Fork me on GitHub
Teleport

Joining Node and Proxies in AWS

Improve

This section will explain how to set up Teleport Nodes and Proxies to join your Teleport cluster with the EC2 join method. The EC2 join method enables you to allow Teleport nodes to join your Teleport cluster from EC2 instances in your AWS account without sharing any secrets.

Prerequisites

  • Teleport v7.3.2 Open Source or Enterprise.
  • A running self-hosted Teleport cluster.
  • AWS EC2 instance with Teleport installed.

Step 1/4. Setup AWS permissions for your Auth server

Teleport Auth needs permission to call ec2:DescribeInstances in order to check that the EC2 instances attempting to join your cluster are legitimate and currently running.

Step 1.1. Create the IAM policy

Create the following AWS IAM policy named teleport-DescribeInstances-policy in your account:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": "ec2:DescribeInstances",
           "Resource": "*"
       }
   ]
}

Step 1.2. Attach the IAM policy

If your Teleport auth server is running on an EC2 instance and already has an attached "IAM role for Amazon EC2", add the above teleport-DescribeInstances-policy to the existing role. If the instance does not already have an attached role, create an IAM role with the above policy and attach it to your EC2 instance running the Teleport auth server.

If you are running your Teleport auth server outside of AWS you can attach the teleport-DescribeInstances-policy directly to an IAM user which Teleport will use to authenticate. You can provide the IAM credentials to teleport through a shared configuration file or environment variables, see https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials for details.

Step 2/4. Create the AWS Node Joining Token

Configure your Teleport auth server with a special dynamic token which will allow nodes from your AWS account to join your Teleport cluster. Nodes will prove that they are running in your AWS account by sending a signed EC2 Instance Identity Document which matches an allow rule configured in your AWS Node Joining Token.

Create the following token.yaml with an allow rule specifying your AWS account and the AWS regions in which your EC2 instances will run.

# 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: ec2-token
  # set a long expiry time, the default for tokens is only 30 minutes
  expires: "3000-01-01T00:00:00Z"
spec:
  # use the minimal set of roles required
  roles: [Node]

  # aws_iid_ttl is the amount of time after the EC2 instance is launched during
  # which it should be allowed to join the cluster. Use a short TTL to decrease
  # the risk of stolen EC2 Instance Identity Documents being used to join your
  # cluster.
  aws_iid_ttl: 5m

  allow:
  - aws_account: "111111111111" # your AWS account ID
    aws_regions: # use the minimal set of AWS regions required
    - us-west-1
    - us-west-2

Run tctl create token.yaml to create the token on the auth server.

Step 3/4. Configure your Nodes

The EC2 join method can be used for Teleport services running SSH, Proxy, Kubernetes, Application, or Database roles. The service should be run directly on an AWS EC2 instance and must have network access to the AWS EC2 IMDSv2 (enabled by default for most EC2 instances).

Configure your Teleport node with a custom teleport.yaml file. Use the join_params section with token_name matching your token created in Step 2 and method: ec2 as shown in the following example config:

# /etc/teleport.yaml
teleport:
  join_params:
    token_name: ec2-token
    method: ec2
  auth_servers:
  - https://teleport.example.com:443
ssh_service:
  enabled: yes
auth_service:
  enabled: no
proxy_service:
  enabled: no

Step 4/4. Launch your Teleport Node

When launching your first Node, you may need to temporarily configure a higher aws_iid_ttl value in the AWS Node Joining token so that you have time to get Teleport set up and configured. This feature works best once Teleport is configured in an EC2 AMI to start automatically on launch. You can edit the aws_iid_ttl value by editing the token yaml file and re-running tctl create -f token.yaml.

Start Teleport on the node and confirm that it is able to connect to and join your cluster. You're all set!

Next Steps

Configuring AWS Node Joining for Multiple AWS Accounts

In order for Teleport nodes to join from EC2 instances in AWS accounts other than the account in which your Teleport auth server is running, Teleport must have permissions to assume an IAM role in each of those accounts and call ec2:DescribeInstances in the foreign account.

In each AWS account where your EC2 instances will be running:

  1. Create the teleport-DescribeInstances-policy from Step 1.1.

  2. Create an IAM role teleport-DescribeInstances-role that can be assumed from the account where your Teleport auth server is running.

    Go to the AWS IAM Console, select Create Role, and for "Select type of trusted entity" select "Another AWS account" and enter the AWS Account ID of the account where your Teleport auth server is running.

    Attach the teleport-DescribeInstances-policy to the role.

In the AWS account where your Teleport auth server is running:

  1. Create an IAM policy named teleport-AssumeRole-policy with an AssumeRole statement for each foreign account:
{
   "Version": "2012-10-17",
   "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::222222222222:role/teleport-DescribeInstances-role"
        },
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::333333333333:role/teleport-DescribeInstances-role"
        }
   ]
}
  1. Attach this teleport-AssumeRole-policy to the IAM role your Teleport auth server has credentials for, see Step 1.2.

When creating the AWS Node Joining token, include an allow rule for each foreign account and specify the AWS ARN for the foreign teleport-DescribeInstances-role.

# token.yaml
kind: token
version: v2
metadata:
  name: ec2-multiaccount-token
  expires: "3000-01-01T00:00:00Z"
spec:
  roles: [Node]
  aws_iid_ttl: 5m
  allow:
  - aws_account: "222222222222"
    aws_regions:
    - us-west-1
    - us-west-2
    aws_role: "arn:aws:iam::222222222222:role/teleport-DescribeInstances-role"
  - aws_account: "333333333333"
    aws_regions:
    - us-west-1
    - us-west-2
    aws_role: "arn:aws:iam::333333333333:role/teleport-DescribeInstances-role"
Have a suggestion or can’t find something?
IMPROVE THE DOCS