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"
+```