From 920982f2dc7f2b331dd1ca2c879f67fa177fef64 Mon Sep 17 00:00:00 2001 From: Nic Klaassen Date: Fri, 8 Oct 2021 11:59:06 -0700 Subject: [PATCH] Added joining nodes in AWS documentation. --- docs/config.json | 3 +- docs/pages/setup/guides.mdx | 3 + docs/pages/setup/guides/joining-nodes-aws.mdx | 209 ++++++++++++++++++ 3 files changed, 214 insertions(+), 1 deletion(-) create mode 100644 docs/pages/setup/guides/joining-nodes-aws.mdx diff --git a/docs/config.json b/docs/config.json index b1d34b04be6..5e544cdae21 100644 --- a/docs/config.json +++ b/docs/config.json @@ -63,7 +63,8 @@ { "title": "Terraform Provider", "slug": "/setup/guides/terraform-provider/" }, { "title": "Docker", "slug": "/setup/guides/docker/" }, { "title": "Fluentd", "slug": "/setup/guides/fluentd/" }, - { "title": "EC2 tags", "slug": "/setup/guides/ec2-tags/" } + { "title": "EC2 tags", "slug": "/setup/guides/ec2-tags/" }, + { "title": "Joining Nodes in AWS", "slug": "/setup/guides/joining-nodes-aws/" } ] }, { diff --git a/docs/pages/setup/guides.mdx b/docs/pages/setup/guides.mdx index 3eaa8e95b5c..84b47c20288 100644 --- a/docs/pages/setup/guides.mdx +++ b/docs/pages/setup/guides.mdx @@ -17,4 +17,7 @@ layout: tocless-doc
  • [EC2 tags as Teleport Nodes](./guides/ec2-tags.mdx). How to setup Teleport node labels based on EC2 tags.
    • +
  • + [Joining Nodes in AWS](./guides/joining-nodes-aws.mdx). How to join nodes and proxies on EC2. +
    • diff --git a/docs/pages/setup/guides/joining-nodes-aws.mdx b/docs/pages/setup/guides/joining-nodes-aws.mdx new file mode 100644 index 00000000000..8cb04e816bc --- /dev/null +++ b/docs/pages/setup/guides/joining-nodes-aws.mdx @@ -0,0 +1,209 @@ +--- +title: Joining Nodes in AWS +description: How to join nodes and proxies on EC2 +h1: Joining Node and Proxies in AWS +--- + +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 v(=teleport.version=) 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: + +```json +{ + "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](#step-11-create-the-iam-policy). + +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: + +```json +{ + "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" + } + ] +} +``` + +2. Attach this `teleport-AssumeRole-policy` to the IAM role your Teleport auth + server has credentials for, see [Step 1.2](#step-12-attach-the-iam-policy). + +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`. + +```yaml +# 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" +```