Skip to content

Commit

Permalink
Add context around AWS join methods
Browse files Browse the repository at this point in the history
Closes #26893

Help users determine whether to use the EC2 or IAM join method by:

- Adding a "How it works" section to the top of each method's how-to
  guide explaining how the join method works.
- Ensuring that both guides include a brief discussion of alternative
  possibilities. Currently, only one of these guides does.
  • Loading branch information
ptgott committed Aug 14, 2024
1 parent 984999b commit 36653c9
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 44 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -3,44 +3,37 @@ title: Joining Services via AWS EC2 Identity Document
description: Use the EC2 join method to add services to your Teleport cluster on AWS
---

This guide will explain how to use the **EC2 join method** to configure Teleport
processes to join your Teleport cluster without sharing any secrets when they
are running in AWS.
This guide explains how to use the **EC2 join method** to configure Teleport
processes to join your Teleport cluster without sharing any secrets when they a
re running in AWS.

The EC2 join method is only available in self-hosted Teleport deployments. There
are two other AWS join methods available depending on your use case:

1. The **IAM join method** is available to any Teleport process running anywhere
with access to IAM credentials, such as an EC2 instance with an attached IAM
role (see [documentation](aws-iam.mdx)). No specific permissions or IAM policy
is required: an IAM role with no attached policies is sufficient. No IAM
credentials are required on the Teleport Auth Service.
1. **Tokens not signed by AWS:** You can configure Teleport processes running on
AWS to join a cluster via [Teleport join tokens](join-token.mdx) or, for
Teleport processes running on Kubernetes, [signed ServiceAccount
tokens](kubernetes.mdx). These approaches allow you to join a Teleport
process to a cluster when you don't want to rely on AWS-specific APIs, e.g.,
when adopting a cloud-agnostic approach.

## How it works

The EC2 join method is available to any Teleport process running on an EC2
instance. Only one Teleport process per EC2 instance may use the EC2 join
method.

IAM credentials with `ec2:DescribeInstances` permissions are required on your
Teleport Auth Service. No IAM credentials are required on the Teleport processes
joining the cluster.

<Notice type="warning">

The EC2 join method is not available in Teleport Enterprise Cloud and Teleport
Team. Teleport Enterprise Cloud and Team customers can use the [IAM join
method](./aws-iam.mdx) or [secret tokens](join-token.mdx).

</Notice>

<Details
opened
title="Other AWS joining methods"
>

There are two other AWS join methods available depending on your use case.

The **IAM join method** is available in self-hosted editions of Teleport. It is
available to any Teleport process running anywhere with access to IAM
credentials, such as an EC2 instance with an attached IAM role. No specific
permissions or IAM policy is required: an IAM role with no attached policies is
sufficient. No IAM credentials are required on the Teleport Auth Service.

You can also configure services running in AWS to join a cluster via [join
tokens](join-token.mdx), which is useful when you don't want to rely on
AWS-specific APIs.

</Details>
method. The process presents an [EC2 instance identity
document](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html)
to the Teleport Auth Service.

Meanwhile, the Teleport Auth Service has AWS IAM credentials with
`ec2:DescribeInstances` permissions in order to check that the identity document
belongs to a legitimate EC2 instance. No IAM credentials are required on the
Teleport processes joining the cluster.

## Prerequisites

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,42 @@ title: Joining Services via AWS IAM Role
description: Use the IAM join method to add services to your Teleport cluster on AWS
---

This guide will explain how to use the **IAM join method** to configure Teleport
This guide explains how to use the **IAM join method** to configure Teleport
processes to join your Teleport cluster without sharing any secrets when they
are running in AWS.

There are two other AWS join methods available depending on your use
case:

1. The **EC2 join method**, which is only available for self-hosted Teleport
deployments (see [documentation](aws-ec2.mdx)). A Teleport process running on
an EC2 instance requests a signed EC2 instance identity document and presents
it to the Teleport Auth Service, which queries the EC2 API to verify that the
instance is genuine. This method requires a self-hosted Teleport cluster and
IAM credentials for the Teleport Auth Service.
1. **Tokens not signed by AWS:** You can configure Teleport processes running on
AWS to join a cluster via [Teleport join tokens](join-token.mdx) or, for
Teleport processes running on Kubernetes, [signed ServiceAccount
tokens](kubernetes.mdx). These approaches allow you to join a Teleport
process to a cluster when you don't want to rely on AWS-specific APIs, e.g.,
when adopting a cloud-agnostic approach.

## How it works

The IAM join method is available to any Teleport process running anywhere with
access to IAM credentials, such as an EC2 instance with an attached IAM role.
No specific permissions or IAM policy is required: an IAM role with no attached
policies is sufficient. No IAM credentials are required on the Teleport Auth
Service.

Teleport processes prove that they are running in your AWS account by sending a
pre-signed `sts:GetCallerIdentity` request to the Teleport Auth Service. The
service's identity must match an allow rule configured in your AWS service
joining token.

Support for joining a cluster with the Proxy Service behind a layer 7 load
balancer or reverse proxy is available in Teleport 13.0+.

For other methods of joining a Teleport process to a cluster, see [Joining
Teleport Services to a Cluster](../join-services-to-your-cluster.mdx).

## Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)
Expand All @@ -44,11 +64,6 @@ policies.

## Step 2/4. Create the AWS joining token

Under the hood, services will prove that they are running in your AWS account by
sending a pre-signed `sts:GetCallerIdentity` request to the Teleport Auth
Service. The service's identity must match an allow rule configured in your AWS
service joining token.

Create the following `token.yaml` with an `allow` rule specifying your AWS
account and the ARN that the Teleport process's identity must match.

Expand Down

0 comments on commit 36653c9

Please sign in to comment.