Version: 14.x

Configure Teleport to Automatically Enroll EC2 instances

The Teleport Discovery Service can connect to Amazon EC2 and automatically discover and enroll EC2 instances matching configured labels. It will then execute an install script on these discovered instances using AWS Systems Manager that will install Teleport, start it and join the cluster.

In this scenario, Teleport Discovery Service uses an IAM invite token with a long time-to-live (TTL), so that new instances can be discovered and added to the Teleport cluster for the lifetime of the token.

Prerequisites

A running Teleport cluster version 14.3.33 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
The tctl admin tool and tsh client tool.

Visit Installation for instructions on downloading tctl and tsh.

AWS account with EC2 instances and permissions to create and attach IAM policies.
EC2 instances running Ubuntu/Debian/RHEL/Amazon Linux 2/Amazon Linux 2023 and SSM agent version 3.1 or greater if making use of the default Teleport install script. (For other Linux distributions, you can install Teleport manually.)
To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines. For example:
```
$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  teleport.example.com
# Version  14.3.33
# CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/7. Create an EC2 invite token

When discovering EC2 instances, Teleport makes use of IAM invite tokens for authenticating joining Nodes.

Create a file called token.yaml:

# token.yaml
kind: token
version: v2
metadata:
  # the token name is not a secret because instances must prove that they are
  # running in your AWS account to use this token
  name: aws-discovery-iam-token
spec:
  # use the minimal set of roles required (e.g. Node, App, Kube, DB, WindowsDesktop)
  roles: [Node]

  # set the join method allowed for this token
  join_method: iam

  allow:
  # specify the AWS account which Nodes may join from
  - aws_account: "123456789"

Assign the aws_account field to your AWS account number. Add the token to the Teleport cluster with:

$ tctl create -f token.yaml

Step 2/7. Define an IAM policy

The teleport discovery bootstrap command will automate the process of defining and implementing IAM policies required to make auto-discovery work. It requires only a single pre-defined policy, attached to the EC2 instance running the command:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:GetPolicy",
                "iam:TagPolicy",
                "iam:ListPolicyVersions",
                "iam:CreatePolicyVersion",
                "iam:CreatePolicy",
                "ssm:CreateDocument",
                "iam:DeletePolicyVersion",
                "iam:AttachRolePolicy",
                "iam:PutRolePermissionsBoundary"
            ],
            "Resource": "*"
        }
    ]
}

Create this policy and apply it to the Node (EC2 instance) that will run the Discovery Service.

Step 3/7. Install Teleport on the Discovery Node

tip

If you plan on running the Discovery Service on the same Node already running another Teleport service (Auth or Proxy, for example), you can skip this step.

Install Teleport on the EC2 instance that will run the Discovery Service:

Select an edition, then follow the instructions for that edition to install Teleport.

Teleport Community Edition
Teleport Enterprise
Teleport Enterprise Cloud

The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

$ curl https://cdn.teleport.dev/install-v14.3.33.sh | bash -s 14.3.33

# Download Teleport's PGP public key
$ sudo curl https://apt.releases.teleport.dev/gpg \
-o /usr/share/keyrings/teleport-archive-keyring.asc
# Source variables about OS version
$ source /etc/os-release
# Add the Teleport APT repository for v14. You'll need to update this
# file for each major release of Teleport.
$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \
| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

$ sudo apt-get update
$ sudo apt-get install teleport-ent