diff --git a/docs/config.json b/docs/config.json index de77f2ff3a340..37964ed5ec588 100644 --- a/docs/config.json +++ b/docs/config.json @@ -461,13 +461,38 @@ "slug": "/management/introduction/" }, { - "title": "Admin Guides", - "slug": "/management/admin/", + "title": "Joining Teleport Services", + "slug": "/management/join-services-to-your-cluster/", "entries": [ { - "title": "Adding Nodes", - "slug": "/management/admin/adding-nodes/" + "title": "Via AWS EC2", + "slug": "/management/join-services-to-your-cluster/aws-ec2/", + "forScopes": ["oss", "enterprise"] + }, + { + "title": "Via AWS IAM", + "slug": "/management/join-services-to-your-cluster/aws-iam/" + }, + { + "title": "Via Azure", + "slug": "/management/join-services-to-your-cluster/azure/" + }, + { + "title": "Joining Services via Kubernetes ServiceAccount", + "slug": "/management/join-services-to-your-cluster/kubernetes/", + "forScopes": ["oss", "enterprise"] }, + + { + "title": "Via a Join Token", + "slug": "/management/join-services-to-your-cluster/join-token/" + } + ] + }, + { + "title": "Admin Guides", + "slug": "/management/admin/", + "entries": [ { "title": "Trusted Clusters", "slug": "/management/admin/trustedclusters/" @@ -567,24 +592,6 @@ "title": "EC2 Tags", "slug": "/management/guides/ec2-tags/" }, - { - "title": "Joining Nodes via AWS IAM", - "slug": "/management/guides/joining-nodes-aws-iam/" - }, - { - "title": "Joining Nodes via AWS EC2", - "slug": "/management/guides/joining-nodes-aws-ec2/", - "forScopes": ["oss", "enterprise"] - }, - { - "title": "Joining Nodes via Azure", - "slug": "/management/guides/joining-nodes-azure/" - }, - { - "title": "Joining Services via Kubernetes ServiceAccount", - "slug": "/management/guides/joining-services-kubernetes-serviceaccount/", - "forScopes": ["oss", "enterprise"] - }, { "title": "Using Teleport's CA with GitHub", "slug": "/management/guides/ssh-key-extensions/" @@ -1695,7 +1702,7 @@ }, { "source": "/setup/guides/joining-nodes-aws/", - "destination": "/management/guides/joining-nodes-aws-iam/", + "destination": "/management/join-services-to-your-cluster/aws-iam/", "permanent": true }, { @@ -2045,7 +2052,7 @@ }, { "source": "/setup/admin/adding-nodes/", - "destination": "/management/admin/adding-nodes/", + "destination": "/management/join-services-to-your-cluster/join-token/", "permanent": true }, { @@ -2100,12 +2107,12 @@ }, { "source": "/setup/guides/joining-nodes-aws-ec2/", - "destination": "/management/guides/joining-nodes-aws-ec2/", + "destination": "/management/join-services-to-your-cluster/aws-ec2/", "permanent": true }, { "source": "/setup/guides/joining-nodes-aws-iam/", - "destination": "/management/guides/joining-nodes-aws-iam/", + "destination": "/management/join-services-to-your-cluster/aws-iam/", "permanent": true }, { @@ -2442,6 +2449,31 @@ "source": "/contributing/", "destination": "/contributing/documentation/", "permanent": true + }, + { + "source": "/management/guides/joining-nodes-aws-ec2/", + "destination": "/management/join-services-to-your-cluster/aws-ec2/", + "permanent": true + }, + { + "source": "/management/guides/joining-nodes-aws-iam/", + "destination": "/management/join-services-to-your-cluster/aws-iam/", + "permanent": true + }, + { + "source": "/management/admin/adding-nodes/", + "destination": "/management/join-services-to-your-cluster/join-token/", + "permanent": true + }, + { + "source": "/management/guides/joining-nodes-azure/", + "destination": "/management/join-services-to-your-cluster/azure/", + "permanent": true + }, + { + "source": "/management/guides/joining-services-kubernetes-serviceaccount/", + "destination": "/management/join-services-to-your-cluster/kubernetes/", + "permanent": true } ] } diff --git a/docs/pages/access-controls/compliance-frameworks/soc2.mdx b/docs/pages/access-controls/compliance-frameworks/soc2.mdx index 9f9d116f5003d..46f998acedc00 100644 --- a/docs/pages/access-controls/compliance-frameworks/soc2.mdx +++ b/docs/pages/access-controls/compliance-frameworks/soc2.mdx @@ -56,7 +56,7 @@ Each principle has many “Points of Focus” which will apply differently to di | CC6.1 - Manages Points of Access | Points of access by outside entities and the types of data that flow through the points of access are identified, inventoried, and managed. The types of individuals and systems using each point of access are identified, documented, and managed. | [Label Nodes to inventory and create rules](../../management/admin/labels.mdx)

[Create Labels from AWS Tags](../../management/guides/ec2-tags.mdx)

Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time. | | CC6.1 - Restricts Access to Information Assets | Combinations of data classification, separate data structures, port restrictions, access protocol restrictions, user identification, and digital certificates are used to establish access-control rules for information assets. | [Teleport uses Certificates to grant access and create access control rules](../../core-concepts.mdx) | | CC6.1 - Manages Identification and Authentication | Identification and authentication requirements are established, documented, and managed for individuals and systems accessing entity information, infrastructure, and software. | Teleport makes setting policies for SSH requirements easy since it works in the cloud and on premise with the same authentication security standards. | -| CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../management/admin/adding-nodes.mdx) | +| CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../management/join-services-to-your-cluster/join-token.mdx) | | CC6.1 - Uses Encryption to Protect Data | The entity uses encryption to supplement other measures used to protect data at rest, when such protections are deemed appropriate based on assessed risk. | Teleport Audit logs can use DynamoDB encryption at rest. | | CC6.1 - Protects Encryption Keys | Processes are in place to protect encryption keys during generation, storage, use, and destruction. | Teleport acts as a Certificate Authority to issue SSH and x509 user certificates that are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically | | CC6.2 - Controls Access Credentials to Protected Assets | Information asset access credentials are created based on an authorization from the system's asset owner or authorized custodian. | [Request Approval from the command line](../../reference/cli.mdx#tctl-request-approve)

[Build Approval Workflows with Access Requests](../../access-controls/access-requests.mdx)

[Use Plugins to send approvals to tools like Slack or Jira](../../access-controls/access-requests.mdx) | diff --git a/docs/pages/architecture/authentication.mdx b/docs/pages/architecture/authentication.mdx index 88f01f9a7429f..7a66f3c2546c9 100644 --- a/docs/pages/architecture/authentication.mdx +++ b/docs/pages/architecture/authentication.mdx @@ -143,7 +143,7 @@ services and rotates SSH and X.509 certificates. Teleport internal services - Auth, Proxy and Nodes use certificates to identify themselves within a cluster. To join proxies and nodes to the cluster and receive certificates, admins should use -[short-lived tokens or cloud identity services](../management/admin/adding-nodes.mdx). +[short-lived tokens or cloud identity services](../management/join-services-to-your-cluster/join-token.mdx). Unlike users and services, internal services receive long-lived certificates. diff --git a/docs/pages/choose-an-edition/teleport-cloud/faq.mdx b/docs/pages/choose-an-edition/teleport-cloud/faq.mdx index 64689a5b91f3b..b88e24125b189 100644 --- a/docs/pages/choose-an-edition/teleport-cloud/faq.mdx +++ b/docs/pages/choose-an-edition/teleport-cloud/faq.mdx @@ -48,8 +48,8 @@ See our documentation on [data retention](./architecture.mdx#data-retention). ## How do I add Nodes to Teleport Enterprise Cloud? -You can connect servers, Kubernetes clusters, databases and applications -using [reverse tunnels](../../management/admin/adding-nodes.mdx). +You can connect servers, Kubernetes clusters, databases and applications using +[reverse tunnels](../../management/join-services-to-your-cluster.mdx). There is no need to open any ports on your infrastructure for inbound traffic. @@ -122,7 +122,7 @@ $ tctl tokens add --type=node ## Are dynamic node tokens available? After [connecting](#how-can-i-access-the-tctl-admin-tool) `tctl` to Teleport Enterprise Cloud, users can generate -[dynamic tokens](../../management/admin/adding-nodes.mdx): +[dynamic tokens](../../management/join-services-to-your-cluster/join-token.mdx): ```code $ tctl nodes add --ttl=5m --roles=node,proxy --token=$(uuid) diff --git a/docs/pages/database-access/guides/aws-dynamodb.mdx b/docs/pages/database-access/guides/aws-dynamodb.mdx index 7d39468054a52..4794ca2ee581a 100644 --- a/docs/pages/database-access/guides/aws-dynamodb.mdx +++ b/docs/pages/database-access/guides/aws-dynamodb.mdx @@ -159,8 +159,9 @@ many instances, consider alternative methods for joining new EC2 instances runni Teleport: - [Configure Teleport to Automatically Enroll EC2 instances (Preview)](../../server-access/guides/ec2-discovery.mdx) -- [Joining Nodes via AWS IAM Role](../../management/guides/joining-nodes-aws-iam.mdx) -- [Joining Nodes via AWS EC2 Identity Document](../../management/guides/joining-nodes-aws-ec2.mdx) +- [Joining Nodes via AWS IAM + Role](../../management/join-services-to-your-cluster/aws-iam.mdx) +- [Joining Nodes via AWS EC2 Identity Document](../../management/join-services-to-your-cluster/aws-ec2.mdx) diff --git a/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx b/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx index 923af1fdd1d73..5033956779b54 100644 --- a/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx +++ b/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx @@ -730,7 +730,8 @@ To add new nodes/EC2 servers that you can "SSH into" you'll need to: - [Install the Teleport binary on the Server](../../installation.mdx) - [Run Teleport - we recommend using systemd](../../management/admin/daemon.mdx) - [Set the correct settings in /etc/teleport.yaml](../../reference/config.mdx) -- [Add Nodes to the Teleport cluster](../../management/admin/adding-nodes.mdx) +- [Add Nodes to the Teleport + cluster](../../management/join-services-to-your-cluster.mdx) ### Getting the CA pin hash @@ -752,7 +753,7 @@ $ aws ssm get-parameter --region ${TF_VAR_region} --name "/teleport/${TF_VAR_clu # 992a9725-0a64-428d-8e5e-308e6877743d ``` -You can also generate a Node join token using `tctl tokens add --type=node` [as detailed here in our admin guide](../../management/admin/adding-nodes.mdx). +You can also generate a Node join token using `tctl tokens add --type=node` [as detailed here in our admin guide](../../management/join-services-to-your-cluster/join-token.mdx). ### Joining Nodes via the Teleport Auth Service @@ -773,7 +774,7 @@ auth_server: example-cluster-auth-c5b0fc2764ee015b.elb.us-east-1.amazonaws.com:3 ### Joining Nodes via Teleport IoT/Node tunneling To join Teleport Nodes from outside the same VPC, you will either need to investigate VPC peering/gateways (out of scope -for this document) or join your nodes using [Teleport's node tunneling](../../management/admin/adding-nodes.mdx) functionality. +for this document) or join your nodes using [Teleport's node tunneling](../../management/join-services-to-your-cluster/join-token.mdx) functionality. With this method, you can join the nodes using the public facing proxy address - `teleport.example.com:443` for our example. diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx index 5904a6b5a4030..0122d3a7e88d2 100644 --- a/docs/pages/faq.mdx +++ b/docs/pages/faq.mdx @@ -53,7 +53,8 @@ behind-firewall clusters refer to our Yes. When running a Teleport agent, use the `--auth-server` flag to point to the Proxy Service address (this would be `public_addr` and `web_listen_addr` in your file configuration). For more information, see -[Adding Nodes to the Cluster](./management/admin/adding-nodes.mdx). +[Adding Nodes to the +Cluster](./management/join-services-to-your-cluster/join-token.mdx). ## Can Nodes use a single port for reverse tunnels? diff --git a/docs/pages/management/admin.mdx b/docs/pages/management/admin.mdx index 8fd43553d55f8..fb2348be856bd 100644 --- a/docs/pages/management/admin.mdx +++ b/docs/pages/management/admin.mdx @@ -21,8 +21,6 @@ environment without configuring TLS certificates. ## Manage users and resources -- [GitHub SSO](../access-controls/sso/github-sso.mdx): Set up single sign-on with GitHub. -- [Adding Nodes](./admin/adding-nodes.mdx): Add Nodes to your Teleport cluster. - [Trusted Clusters](./admin/trustedclusters.mdx): Connect multiple Teleport clusters using Trusted Clusters. - [Labels](./admin/labels.mdx): Manage resource metadata with labels. - [Local Users](./admin/users.mdx): Manage local user accounts. diff --git a/docs/pages/management/admin/adding-nodes.mdx b/docs/pages/management/admin/adding-nodes.mdx deleted file mode 100644 index 92041e9374ed6..0000000000000 --- a/docs/pages/management/admin/adding-nodes.mdx +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: Adding Nodes to your Cluster -description: This guide shows you how to join a Teleport instance to your cluster in order to proxy access to resources in your infrastructure. ---- - -This guide explains how to add Teleport Nodes to your cluster. - -## Prerequisites - -(!docs/pages/includes/edition-prereqs-tabs.mdx!) - -- A Linux server that you will use to host your Teleport Node. -- (!docs/pages/includes/tctl.mdx!) - -## Step 1/3. Install Teleport on your Node - -On the host where you will run your Teleport Node, follow the instructions for -your environment to install Teleport. - -(!docs/pages/includes/install-linux.mdx!) - -## Step 2/3. Join your Node to the cluster - -In this section, we will join your Node to the Teleport cluster by: - -- Obtaining information stored on the Auth Service -- Starting Teleport on your Node with the information we obtained - -### Obtain a CA pin - -In a zero-trust environment, you must assume that an attacker can hijack the IP -address of the Auth Service. - -To prevent this from happening, you need to supply every new Node with -information about the Auth Service. This technique is called **CA pinning**. It -works by asking the Auth Service to produce a CA pin, a hash value of the SPKI -header in a certificate. This way, an attacker cannot easily forge a matching -private key. - -If a CA pin is not provided, the Teleport Node will join a cluster but it will -print a warning message. - - - -The CA pin becomes invalid if a Teleport administrator performs the CA rotation -by executing [`tctl auth rotate`](../../reference/cli.mdx#tctl-auth-rotate). - - - -On you local machine, retrieve the CA pin of the Auth Service by running the following command on your local -machine: - -```code -$ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}') -``` - -### Generate a token - -Teleport only allows access to Nodes that have joined the cluster. - -Once a Node joins, it receives a host certificate signed by the cluster's -Auth Service. To receive a host certificate upon joining a cluster, a new -Teleport host must present an **invite token**. - -An invite token also defines which role a new host can assume within a cluster: - -- `proxy` -- `node` -- `auth` -- `app` -- `db` -- `kube` -- `windowsdesktop` - -Administrators can generate tokens as they are needed. A token can be used -multiple times until its time to live (TTL) expires. - -On your local machine, use the `tctl` tool to generate a new token. In the -following example, a new token is created with a TTL of five minutes: - -```code -# Generate a short-lived invite token for a new node: -$ export INVITE_TOKEN=$(tctl tokens add --ttl=5m --type=node --format=text) -$ echo $INVITE_TOKEN -# (=presets.tokens.first=) - -# You can also list all generated non-expired tokens: -$ tctl tokens ls -# Token Type Expiry Time -# ------------------------ ----------- --------------- -# (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC -``` - -
- -Rather than automatically generating a token, you can create one with a known -value by using the `--token` flag: - -```code -$ tctl nodes add --ttl=5m --roles=node,proxy --token=secret-value -# The invite token: secret-value -``` - -The value of `--token` should be cryptographically secure. For example, you can -create an SHA256 hash to reduce the risk that a malicious actor will produce -a token with the same value as yours: - -```code -$ head -n 1 /dev/random | sha256sum -``` - -
- -
- -Use short-lived tokens instead of long-lived static tokens. -Static tokens are easier to steal, guess, and leak. - - -Static tokens are defined ahead of time by an administrator and stored in the -auth server's config file: - -```yaml -# Config section in `/etc/teleport.yaml` file for the auth server -auth_service: - enabled: true - tokens: - # This static token allows new hosts to join the cluster as "proxy" or "node" - - "proxy,node:secret-token-value" - # A token can also be stored in a file. In this example the token for adding - # new auth servers are stored in /path/to/tokenfile - - "auth:/path/to/tokenfile" -``` -
- -### Start your Node with the invite token and CA pin - -Execute the following commands on the host where you will run your Node so you -can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport. - -```code -$ export CA_PIN= -$ export INVITE_TOKEN= -``` - - - -Still on the host where you will run your Node, assign the address of your Auth -Service to an environment variable, including the domain name (or IP address) -and port: - -```code -$ export ADDR=teleport.example.com:3025 -``` - - - - -Still on the host where you will run your Node, assign the address of your -Teleport Cloud tenant to an environment variable, including the domain name (or -IP address) and port `443`: - -```code -$ export ADDR=mytenant.teleport.sh:443 -``` - - - -
- -If you plan to use Teleport Node Tunneling, which we will explain below, set -`ADDR` to the domain name (or IP address) and `web_listen_addr` port of your -Teleport Proxy Service. - -Teleport Node Tunneling lets you add a remote Node to an existing Teleport -Cluster through a reverse tunnel. This is useful when the Auth Service is -inaccessible from the network where the Node is running, e.g., for IoT -applications. - - - -We recommend setting up a [Trusted Cluster](../admin/trustedclusters.mdx) if you -have workloads split across different networks or clouds. - - - -Using the ports in Teleport's default configuration, the Node needs to be able -to talk to ports `3080` and `3024` on the Proxy Service. Port `3080` is used to -initially fetch the credentials (SSH and TLS certificates) and for discovering -the reverse tunnel. Port `3024 `is used to establish a connection to the Auth -Service through the Proxy. - -For those using ACME, port `443` is also required. - -To enable multiplexing so only one port is used, simply set the -`tunnel_listen_addr` to the same value as `web_listen_addr` within the -`proxy_service` section of your configuration file. Teleport will automatically -recognize that the Proxy Service is using the same port for both addresses and -enable multiplexing. - -If your log setting is set to DEBUG, you will see multiplexing enabled in the -server log. - -```txt -DEBU [PROC:1] Setup Proxy: Reverse tunnel proxy and web proxy listen on the same port, multiplexing is on. service/service.go:1944 -``` - - - - The setup above also works even if the cluster uses multiple Proxy Service - instances behind a load balancer (LB) or a DNS entry with multiple values. In - this case, the Node establishes a tunnel to every proxy. - - This requires that an LB - uses a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (a.k.a. "session affinity") with Teleport Proxy Service instances. - - -
- -Execute the following command on your Node to add it to a cluster: - -```code -$ sudo teleport start \ - --roles=node \ - --token=${INVITE_TOKEN?} \ - --ca-pin=${CA_PIN?} \ - --auth-server=${ADDR?} -``` - -As new Nodes come online, they start sending ping requests every few seconds to -the Auth Service. This allows users to explore cluster membership and size. - -Run the following command on your local machine to see all of the Teleport Nodes -in your cluster: - -```code -$ tctl nodes ls - -Node Name Node ID Address Labels ---------- ------- ------- ------ -turing d52527f9-b260-41d0-bb5a-e23b0cfe0f8f 10.1.0.5:3022 distro:ubuntu -dijkstra c9s93fd9-3333-91d3-9999-c9s93fd98f43 10.1.0.6:3022 distro:debian -``` - -## Step 3/3. Revoke an invitation - -Tokens used for joining Nodes to a cluster can be revoked before they are used. - -Run the following command on your local machine to create a token for a new -Proxy Service: - -```code -$ tctl nodes add --ttl=5m --roles=proxy -# The invite token: (=presets.tokens.first=). -# This token will expire in 5 minutes. -# -# Run this on the new node to join the cluster: -# -# > teleport start \ -# --roles=proxy \ -# --token=(=presets.tokens.first=) \ -# --ca-pin=(=presets.ca_pin=) \ -# --auth-server=123.123.123.123:3025 -# -# Please note: -# -# - This invitation token will expire in 5 minutes -# - 123.123.123.123 must be reachable from the new node -``` - -Next, run the following command to see a list of outstanding tokens: - -``` -$ tctl tokens ls - -# Token Role Expiry Time (UTC) -# ----- ---- ----------------- -# (=presets.tokens.first=) Proxy never -# (=presets.tokens.second=) Node 17 May 16 03:51 UTC -# (=presets.tokens.third=) Signup 17 May 16 04:24 UTC -``` - - - -The output of `tctl tokens ls` includes tokens used for adding users alongside -tokens used for adding Nodes to your cluster. - - - -In this example, the first token has a `never` expiry date because it is a -static token configured via a config file. - -The token with the `Node` role was generated to invite a new Node to this -cluster. And the third token was generated to invite a new user to sign up. - -Tokens created via `tctl` can be deleted (revoked) via the `tctl tokens del` -command. Run the following command to delete a token: - -```code -$ tctl tokens del (=presets.tokens.first=) -# Token (=presets.tokens.first=) has been deleted -``` diff --git a/docs/pages/management/admin/trustedclusters.mdx b/docs/pages/management/admin/trustedclusters.mdx index 79bcb3b8e2f38..43eb25444489e 100644 --- a/docs/pages/management/admin/trustedclusters.mdx +++ b/docs/pages/management/admin/trustedclusters.mdx @@ -27,7 +27,7 @@ A leaf cluster always creates an outbound reverse SSH tunnel to the root cluster Individual nodes and proxies can create reverse tunnels to proxy services without creating a new cluster. You don't need to set up a trusted cluster just to connect a couple of servers, kubernetes clusters or -databases behind a firewall. For more information, see [Adding Nodes to the Cluster](./adding-nodes.mdx). +databases behind a firewall. For more information, see [Adding Nodes to the Cluster](../join-services-to-your-cluster/join-token.mdx). When a user tries to connect to any resource inside the leaf cluster using the root's proxy @@ -62,8 +62,8 @@ This guide will explain how to: - A Teleport Node that is joined to one of your clusters. We will refer to this cluster as the **leaf cluster** throughout this guide. - See [Adding Nodes](adding-nodes.mdx) for how to launch a Teleport Node in - your cluster. + See [Adding Nodes](../join-services-to-your-cluster.mdx) for how to launch a + Teleport Node in your cluster. @@ -117,8 +117,8 @@ how to set up this cluster, see one of our - A Teleport Node that is joined to one of your clusters. We will refer to this cluster as the **leaf cluster** throughout this guide. - See [Adding Nodes](adding-nodes.mdx) for how to launch a Teleport Node in - your cluster. + See [Adding Nodes](../join-services-to-your-cluster.mdx) for how to launch a + Teleport Node in your cluster. diff --git a/docs/pages/management/guides.mdx b/docs/pages/management/guides.mdx index b3be7a7651b9c..637d6467f3124 100644 --- a/docs/pages/management/guides.mdx +++ b/docs/pages/management/guides.mdx @@ -8,11 +8,4 @@ layout: tocless-doc - [Terraform Provider](./guides/terraform-provider.mdx). How to configure Teleport Cloud, Open Source, and Enterprise with the Terraform Provider for Teleport. - [Docker](./guides/docker.mdx). Getting started with Teleport Open Source using Docker. - [EC2 tags as Teleport Nodes](./guides/ec2-tags.mdx). How to set up Teleport Node labels based on EC2 tags. - - [Joining Nodes via AWS IAM Role](./guides/joining-nodes-aws-iam.mdx). Use the IAM join method to add Nodes to your Teleport cluster on AWS. - - - [Joining Nodes via AWS EC2 Identity Document](./guides/joining-nodes-aws-ec2.mdx). Use the EC2 join method to add Nodes to your Teleport cluster on AWS. - - [Joining Services via Kubernetes ServiceAccount](./guides/joining-services-kubernetes-serviceaccount.mdx). - Use Kubernetes ServiceAccount tokens to join services running in the same Kubernetes cluster as the Auth Service. - - - [Joining Nodes via Azure](./guides/joining-nodes-azure.mdx) Use the Azure join method to add Nodes to your Teleport cluster on Azure. - [Using Teleport's Certificate Authority with GitHub](./guides/ssh-key-extensions.mdx). Use Teleport's short-lived certificates with GitHub's Certificate Authority. diff --git a/docs/pages/management/guides/ec2-tags.mdx b/docs/pages/management/guides/ec2-tags.mdx index fd59a783ea959..94e90b40879bf 100644 --- a/docs/pages/management/guides/ec2-tags.mdx +++ b/docs/pages/management/guides/ec2-tags.mdx @@ -28,7 +28,7 @@ fakehost.example.com 127.0.0.1:3022 env=example,hostname=ip-172-31-53-70,aws/Nam (!docs/pages/includes/edition-prereqs-tabs.mdx!) - One Teleport Node running on an Amazon EC2 instance. See - [Adding Nodes](../admin/adding-nodes.mdx) for how to set up a Teleport Node. + [Adding Nodes](../join-services-to-your-cluster.mdx) for how to set up a Teleport Node. ## Enable tags in instance metadata diff --git a/docs/pages/management/guides/joining-nodes-aws-iam.mdx b/docs/pages/management/guides/joining-nodes-aws-iam.mdx deleted file mode 100644 index 7c3638dbefe8b..0000000000000 --- a/docs/pages/management/guides/joining-nodes-aws-iam.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Joining Nodes via AWS IAM Role -description: Use the IAM join method to add Nodes to your Teleport cluster on AWS ---- - -This guide will explain how to use the **IAM join method** to configure Teleport -Nodes and Proxy Service instances to join your Teleport cluster without sharing -any secrets when they are running in AWS. - -The IAM join method is available to any Teleport service 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. - -
- -There are two additional methods you can use to join your Nodes to a Teleport -cluster. - -The **EC2 join method** is available in self-hosted versions of Teleport. -It is available to any Teleport service instance running on an EC2 instance. -Only one Teleport service instance 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 Nodes or -Proxies. - -You can also configure Nodes running in AWS to join a cluster via **secret tokens**, -which is useful when you don't want to rely on AWS-specific APIs. -Read more in the following guide: -[Adding Nodes to the cluster](../admin/adding-nodes.mdx) - -
-
- -You can also configure Nodes running in AWS to join a cluster via **secret tokens**, -which is useful when you don't want to rely on AWS-specific APIs. -Read more in the following guide: -[Adding Nodes to the cluster](../admin/adding-nodes.mdx) - -
- - - -The IAM join method will not work if TLS is terminated at a load balancer in -front of your Teleport Proxy Service unless the Node using this method is -connecting directly to the Auth Service. - - - -## Prerequisites - -(!docs/pages/includes/edition-prereqs-tabs.mdx!) - -- An AWS EC2 instance to act as a Teleport Node, with the Teleport binary - installed. -- (!docs/pages/includes/tctl.mdx!) - -## Step 1/4. Set up AWS IAM credentials - -Every Node or Proxy using the IAM method to join your Teleport cluster needs AWS -IAM credentials in order to call the `sts:GetCallerIdentity` API. No specific -IAM policy or permissions are needed. Any IAM user or role can call this API. - -If running your Node on an EC2 instance, it is sufficient to attach any IAM -role to the instance. To attach an IAM role from the EC2 dashboard, select -`Actions > Security > Modify IAM role`. -It is not necessary for the role to have any attached IAM policies at all. -If your instance does not otherwise need AWS credentials, it is preferred to -create and attach an empty role with no attached policies. - -You can also provide the IAM credentials to Teleport through a shared -configuration file or environment variables. For details, see the following guide: - -[Specifying Credentials](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials) - -## Step 2/4. Create the AWS Node joining token -Under the hood, Nodes will prove that they are running in your AWS account by -sending a pre-signed `sts:GetCallerIdentity` request to the Teleport Auth Server. The -Node's identity must match 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 ARN that your Node's identity must match. - -``` -# 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: iam-token -spec: - # use the minimal set of roles required - 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: "111111111111" - # multiple allow rules are supported - - aws_account: "222222222222" - # aws_arn is optional and allows you to restrict the IAM role of joining Nodes - - aws_account: "333333333333" - aws_arn: "arn:aws:sts::333333333333:assumed-role/teleport-node-role/i-*" -``` - -The token name `iam-token` is just an example and can be any value you want to -use, as long as you use the same value for `join_params.token_name` in Step 3. - -The optional `aws_arn` field in the allow rules supports wildcard characters: -- `*` to match any combination of characters -- `?` to match any single character - -See the -[IAM docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html) -for more details on the ARN format. - -You can check what your AWS identity looks like by running -`aws sts get-caller-identity` on the -[AWS CLI](https://aws.amazon.com/cli/). - -Run `tctl create -f token.yaml` to create the token. - -## Step 3/4. Configure your Nodes -The IAM join method can be used for Teleport services running the SSH, Proxy, -Kubernetes, Application, or Database Service. - -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: iam` as shown in the following example config: - -``` -# /etc/teleport.yaml -version: v3 -teleport: - join_params: - token_name: iam-token - method: iam - proxy_server: https://teleport.example.com:443 -ssh_service: - enabled: yes -auth_service: - enabled: no -proxy_service: - enabled: no -``` - -## Step 4/4. Launch your Teleport Node - -(!docs/pages/includes/aws-credentials.mdx!) - -(!docs/pages/includes/start-teleport.mdx!) - -Once you have started Teleport, confirm that your Node is able to connect to and -join your cluster. diff --git a/docs/pages/management/introduction.mdx b/docs/pages/management/introduction.mdx index 3565402119878..c6cc95f160702 100644 --- a/docs/pages/management/introduction.mdx +++ b/docs/pages/management/introduction.mdx @@ -7,19 +7,14 @@ layout: tocless-doc In this section, you can find guides on managing a Teleport cluster after deploying it. -## Export audit events +## Join Teleport services to your cluster -Teleport's Auth Service maintains an audit log that tracks events in your -cluster, such when a user begins an SSH session or attempts to authenticate. You -can get insight into how users are interacting with your Teleport cluster by -exporting audit events to your log management solution. See how in the -[Exporting Audit Events](./export-audit-events.mdx) guides. - -## Security - -While Teleport is designed with security in mind, there are steps you can take -to ensure that your cluster is as secure as possible. Read about these in the -[Security](./security.mdx) section. +Protect resources in your infrastructure with Teleport by joining Teleport +services to proxy those resources. To do this, start a Teleport process that +runs one or more services. The Teleport process establishes a trust relationship +with your Teleport cluster through a variety of methods. Read [Joining Teleport +Services to a Cluster](./join-services-to-your-cluster.mdx) for a detailed +explanation of each method. ## Admin guides @@ -33,6 +28,12 @@ The [Operations](./operations.mdx) section describes how to perform critical, infrequent tasks such as achieving scalability, upgrading a cluster, and rotating Teleport's certificate authority. +## Security + +While Teleport is designed with security in mind, there are steps you can take +to ensure that your cluster is as secure as possible. Read about these in the +[Security](./security.mdx) section. + ## Integrations Teleport integrates with third-party software in order to enable secure access @@ -45,3 +46,10 @@ To get visibility into the performance of the Teleport services running in your infrastructure, you can use Teleport's built-in metrics, traces, and profiling. Learn more in the [Diagnostics](./diagnostics.mdx) section. +## Export audit events + +Teleport's Auth Service maintains an audit log that tracks events in your +cluster, such when a user begins an SSH session or attempts to authenticate. You +can get insight into how users are interacting with your Teleport cluster by +exporting audit events to your log management solution. See how in the +[Exporting Audit Events](./export-audit-events.mdx) guides. diff --git a/docs/pages/management/join-services-to-your-cluster.mdx b/docs/pages/management/join-services-to-your-cluster.mdx new file mode 100644 index 0000000000000..a5a540091d9f8 --- /dev/null +++ b/docs/pages/management/join-services-to-your-cluster.mdx @@ -0,0 +1,21 @@ +--- +title: Join Services to your Teleport Cluster +description: How to register the Proxy Service, Database Service, and other Teleport services with your cluster. +--- + +A **Teleport service** manages access to resources in your infrastructure, such +as Kubernetes clusters, Windows desktops, internal web applications, and +databases. A single **Teleport process** can run multiple Teleport services. + +There are multiple methods you can use to join a Teleport process to your +cluster in order to run Teleport services, including an instance of the Proxy +Service. Choose the method that best suits your infrastructure: + +|Method|Description|When to use| +|------|-----------|-----------| +|[EC2 Identity Document](./join-services-to-your-cluster/aws-ec2.mdx)|A Teleport process running on an EC2 instance authenticates to your cluster via a signed EC2 instance identity document.|Your Teleport process will run on EC2.| +|[AWS IAM](./join-services-to-your-cluster/aws-iam.mdx)|A Teleport process uses AWS credentials to join the cluster, whether running on EC2 or not.|At least some of your infrastructure runs on AWS and your Teleport cluster is self hosted.| +|[Azure Managed Identity](./join-services-to-your-cluster/azure.mdx)|A Teleport process demonstrates that it runs in your Azure subscription by sending a signed attested data document and access token to the Teleport Auth Service.|Your Teleport process will run on Azure.| +|[Kubernetes ServiceAccount](./join-services-to-your-cluster/kubernetes.mdx)|A Teleport process uses a Kubernetes-signed proof to establish a trust relationship with your Teleport cluster.|Your Teleport process will run on Kubernetes.| +|[Join Token](./join-services-to-your-cluster/join-token.mdx)|A Teleport process presents a join token provided when starting the service.|There is no other supported method for your cloud provider.| + diff --git a/docs/pages/management/guides/joining-nodes-aws-ec2.mdx b/docs/pages/management/join-services-to-your-cluster/aws-ec2.mdx similarity index 62% rename from docs/pages/management/guides/joining-nodes-aws-ec2.mdx rename to docs/pages/management/join-services-to-your-cluster/aws-ec2.mdx index 8a967cebf4edc..99f192dabbe19 100644 --- a/docs/pages/management/guides/joining-nodes-aws-ec2.mdx +++ b/docs/pages/management/join-services-to-your-cluster/aws-ec2.mdx @@ -1,46 +1,46 @@ --- -title: Joining Nodes via AWS EC2 Identity Document -description: Use the EC2 join method to add Nodes to your Teleport cluster on AWS +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 -Nodes and Proxy Service instances to join your Teleport cluster without sharing -any secrets when they are running in AWS. +processes to join your Teleport cluster without sharing any secrets when they +are running in AWS. -The EC2 join method is not available in Teleport Cloud. Teleport Cloud customers -can use the [IAM join method](./joining-nodes-aws-iam.mdx) or -[secret tokens](../admin/adding-nodes.mdx). +The EC2 join method is not available in Teleport Enterprise Cloud. Teleport +Enterprise Cloud customers can use the [IAM join method](./aws-iam.mdx) or +[secret tokens](join-token.mdx). -The EC2 join method is available to any Teleport service running on an EC2 instance. -Only one Teleport service per EC2 instance may use the EC2 join method. +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 Nodes or -Proxy Service instances. +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.
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 service running anywhere with access to -IAM credentials, such as an EC2 instance with an attached IAM role. No specific +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 Nodes running in AWS to join a cluster via **secret -tokens**, which is useful when you don't want to rely on AWS-specific APIs. Read -more in the following guide: -[Adding Nodes to the cluster](../admin/adding-nodes.mdx) +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.
@@ -49,9 +49,11 @@ more in the following guide: (!docs/pages/includes/edition-prereqs-tabs.mdx!) - (!docs/pages/includes/tctl.mdx!) -- An AWS EC2 instance to act as a Teleport Node, with the Teleport binary - installed. The Node should not have an existing data dir (`/var/lib/teleport` by default). - Remove the data directory if this instance has previously joined a Teleport cluster. + +- An AWS EC2 instance to host a Teleport process, with the Teleport binary + installed. The host should not have an existing data dir (`/var/lib/teleport` + by default). Remove the data directory if this instance has previously joined + a Teleport cluster. ## Step 1/4. Set up AWS IAM credentials @@ -79,13 +81,13 @@ your account: ### Step 1.2. Attach the IAM policy -If your Teleport Auth Server is running on an EC2 instance and already has an +If your Teleport Auth Service 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. +policy and attach it to your EC2 instance running the Teleport Auth Service. -If you are running your Teleport Auth Server outside of AWS you can attach +If you are running your Teleport Auth Service outside of AWS you can attach the `teleport-DescribeInstances-policy` directly to an IAM user which Teleport will use to authenticate. @@ -94,14 +96,14 @@ file or environment variables. See [Specifying Credentials](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials) for details. -## Step 2/4. Create the AWS Node joining token +## Step 2/4. Create the AWS 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. +Configure your Teleport Auth Service with a special dynamic token which will +allow services from your AWS account to join your Teleport cluster. -Under the hood, Nodes will prove that they are running in your AWS account by +Under the hood, services 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. +configured in your AWS 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. @@ -126,7 +128,7 @@ spec: # the risk of stolen EC2 Instance Identity Documents being used to join your # cluster. # - # When launching your first Node using the EC2 join method, you may need to + # When launching your first Teleport process using the EC2 join method, you may need to # temporarily configure a higher `aws_iid_ttl` value 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. @@ -141,14 +143,14 @@ spec: Run `tctl create token.yaml` to create the token. -## Step 3/4. Configure your Nodes +## Step 3/4. Configure your services -The EC2 join method can be used for Teleport services running SSH, Proxy, -Kubernetes, Application, Database, or Windows desktop 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). +The EC2 join method can be used for Teleport processes running the SSH, Proxy, +Kubernetes, Application, Database, or Windows Desktop Services. The Teleport +process 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 +Configure your Teleport process 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: @@ -168,25 +170,28 @@ proxy_service: enabled: no ``` -## Step 4/4. Launch your Teleport Node +## Step 4/4. Launch your Teleport process + The data directory (`/var/lib/teleport` by default) must be empty prior to - launching the Node. If this Node had previously joined by another method (e.g. - token or IAM) the host UUID will not match the expected name (`-`) and will not be allowed to join. + launching the Teleport process. If this Teleport process had previously joined + by another method (e.g. token or IAM) the host UUID will not match the + expected name (`-`) and will not be allowed + to join. + -Start Teleport on the Node and confirm that it is able to connect to and join +Start Teleport on the host and confirm that it is able to connect to and join your cluster. You're all set! -## Configuring the EC2 join method for Multiple AWS Accounts +## Configuring the EC2 join method 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 +In order for Teleport processes to join from EC2 instances in AWS accounts other +than the account in which your Teleport Auth Service is running, Teleport must have permissions to assume an IAM role in each of those accounts and call `ec2:DescribeInstances` in the foreign account. @@ -195,15 +200,15 @@ 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. + the account where your Teleport Auth Service 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. + the account where your Teleport Auth Service is running. Attach the `teleport-DescribeInstances-policy` to the role. -In the AWS account where your Teleport Auth Server is running: +In the AWS account where your Teleport Auth Service is running: 1. Create an IAM policy named `teleport-AssumeRole-policy` with an `AssumeRole` statement for each foreign account: @@ -226,10 +231,10 @@ In the AWS account where your Teleport Auth Server is running: } ``` -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). +2. Attach this `teleport-AssumeRole-policy` to the IAM role your Teleport Auth + Service 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 +When creating the AWS joining token, include an allow rule for each foreign account and specify the AWS ARN for the foreign `teleport-DescribeInstances-role`. diff --git a/docs/pages/management/join-services-to-your-cluster/aws-iam.mdx b/docs/pages/management/join-services-to-your-cluster/aws-iam.mdx new file mode 100644 index 0000000000000..a8c74a3191a03 --- /dev/null +++ b/docs/pages/management/join-services-to-your-cluster/aws-iam.mdx @@ -0,0 +1,135 @@ +--- +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 +processes to join your Teleport cluster without sharing any secrets when they +are running in AWS. + +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. + + + +The IAM join method will not work if TLS is terminated at a load balancer in +front of your Teleport Proxy Service unless the service using this method is +connecting directly to the Auth Service. + + + +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!) + +- An AWS EC2 instance to host a Teleport service, with the Teleport binary + installed. + +(!docs/pages/includes/tctl.mdx!) + +## Step 1/4. Set up AWS IAM credentials + +Every Teleport process using the IAM method to join your Teleport cluster needs +AWS IAM credentials in order to call the `sts:GetCallerIdentity` API. No +specific IAM policy or permissions are needed. Any IAM user or role can call +this API. + +If running Teleport on an EC2 instance, it is sufficient to attach any IAM role +to the instance. To attach an IAM role from the EC2 dashboard, select `Actions > +Security > Modify IAM role`. It is not necessary for the role to have any +attached IAM policies at all. If your instance does not otherwise need AWS +credentials, it is preferred to create and attach an empty role with no attached +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. + +``` +# 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: iam-token +spec: + # use the minimal set of roles required + roles: [Node] + + # set the join method allowed for this token + join_method: iam + + allow: + # specify the AWS account which Teleport processes may join from + - aws_account: "111111111111" + # multiple allow rules are supported + - aws_account: "222222222222" + # aws_arn is optional and allows you to restrict the IAM role of joining + # Teleport processes + - aws_account: "333333333333" + aws_arn: "arn:aws:sts::333333333333:assumed-role/teleport-node-role/i-*" +``` + +The token name `iam-token` is just an example and can be any value you want to +use, as long as you use the same value for `join_params.token_name` in Step 3. + +The optional `aws_arn` field in the allow rules supports wildcard characters: +- `*` to match any combination of characters +- `?` to match any single character + +Run the following command to create the token: + +```code +$ tctl create -f token.yaml +``` + +## Step 3/4. Configure your services + +The IAM join method can be used for Teleport processes running the SSH, Proxy, +Kubernetes, Application, or Database Service. + +Configure your Teleport service with a custom `teleport.yaml` file. Use the +`join_params` section with `token_name` matching your token created in Step 2 +and `method: iam` as shown in the following example config: + +``` +# /etc/teleport.yaml +version: v3 +teleport: + join_params: + token_name: iam-token + method: iam + proxy_server: teleport.example.com:443 +ssh_service: + enabled: yes +auth_service: + enabled: no +proxy_service: + enabled: no +``` + +In the `teleport.proxy_server` field, replace the value with the host and web +port of your Teleport Proxy Service or Teleport Enterprise Cloud tenant, e.g., +`mytenant.teleport.sh:443`. + +## Step 4/4. Launch your Teleport process + +(!docs/pages/includes/aws-credentials.mdx!) + +(!docs/pages/includes/start-teleport.mdx!) + +Once you have started Teleport, confirm that your service is able to connect to and +join your cluster. diff --git a/docs/pages/management/guides/joining-nodes-azure.mdx b/docs/pages/management/join-services-to-your-cluster/azure.mdx similarity index 85% rename from docs/pages/management/guides/joining-nodes-azure.mdx rename to docs/pages/management/join-services-to-your-cluster/azure.mdx index 2f60a619620ec..96fd8b5eded4e 100644 --- a/docs/pages/management/guides/joining-nodes-azure.mdx +++ b/docs/pages/management/join-services-to-your-cluster/azure.mdx @@ -1,6 +1,6 @@ --- -title: Joining Nodes via Azure Managed Identity -description: Use the Azure join method to add Nodes to your Teleport cluster on Azure +title: Joining Services via Azure Managed Identity +description: Use the Azure join method to join Teleport services to your Teleport cluster on Azure --- This guide will explain how to use the **Azure join method** to configure @@ -8,46 +8,35 @@ Teleport instances to join your Teleport cluster without sharing any secrets when they are running in an Azure Virtual Machine. The Azure join method is available in Teleport 12.1+. It is available to any -Teleport service running in an Azure Virtual Machine. - -
- -You can also configure Nodes running in Azure to join a cluster via **secret tokens**, -which is useful when you don't want to rely on Azure-specific APIs. -Read more in the following guide: -[Adding Nodes to your Cluster](../admin/adding-nodes.mdx) - -
+Teleport process running in an Azure Virtual Machine. The Azure join method will not work if TLS is terminated at a load balancer in -front of your Teleport Proxy Service unless the Node using this method is -connecting directly to the Auth Service. +front of your Teleport Proxy Service unless the Teleport process using this +method is connecting directly to the Auth Service. +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!) -- An Azure Virtual Machine to act as a Teleport Node, with the Teleport binary - installed. The Virtual Machine must have a - [Managed Identity](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) +- An Azure Virtual Machine running Linux with the Teleport binary installed. The + Virtual Machine must have a [Managed + Identity](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) assigned to it with permission to read virtual machine info. - (!docs/pages/includes/tctl.mdx!) ## Step 1/4. Set up a Managed Identity -Every virtual machine hosting a Node or Proxy using the Azure method to join -your Teleport cluster needs a Managed Identity assigned to it. The identity -requires the `Microsoft.Compute/virtualMachines/read` permission so Teleport -can look up the virtual machine. No other permissions are required. +Every virtual machine hosting a Teleport process using the Azure method to join +your Teleport cluster needs a Managed Identity assigned to it. The identity +requires the `Microsoft.Compute/virtualMachines/read` permission so Teleport can +look up the virtual machine. No other permissions are required. @@ -328,14 +317,15 @@ Use the value of `CLIENT_ID` in Step 3. -## Step 2/4. Create the Azure Node joining token -Under the hood, Nodes will prove that they are running in your Azure subscription -by sending a signed attested data document and access token to the Teleport Auth -Service. The Node's identity must match an allow rule configured in your Azure -Node joining token. +## Step 2/4. Create the Azure joining token + +Under the hood, Teleport processes will prove that they are running in your +Azure subscription by sending a signed attested data document and access token +to the Teleport Auth Service. The VM's identity must match an allow rule +configured in your Azure joining token. Create the following `token.yaml` with an `allow` rule specifying your Azure -subscription and the resource group that your Node's identity must match. +subscription and the resource group that your VM's identity must match. ```yaml # token.yaml @@ -351,12 +341,12 @@ spec: join_method: azure azure: allow: - # specify the Azure subscription which Nodes may join from + # specify the Azure subscription which Teleport processes may join from - subscription: 11111111-1111-1111-1111-111111111111 # multiple allow rules are supported - subscription: 22222222-2222-2222-2222-222222222222 # resource_groups is optional and allows you to restrict the resource group of - # joining Nodes + # joining Teleport processes - subscription: 33333333-3333-3333-3333-333333333333 resource_groups: ["group1", "group2"] ``` @@ -370,11 +360,12 @@ Run the following command to create the token: $ tctl create -f token.yaml ``` -## Step 3/4. Configure your Nodes -The Azure join method can be used for Teleport services running the SSH, Proxy, +## Step 3/4. Configure your Teleport process + +The Azure join method can be used for Teleport processes running the SSH, Proxy, Kubernetes, Application, Database, or Desktop Service. -Configure your Teleport Node with a custom `teleport.yaml` file. Use the +Configure your Teleport process with a custom `teleport.yaml` file. Use the `join_params` section with `token_name` matching your token created in Step 2 and `method: azure` as shown in the following example config: @@ -397,7 +388,11 @@ proxy_service: enabled: no ``` -## Step 4/4. Launch your Teleport Node +## Step 4/4. Launch your Teleport process + +Start Teleport on the Azure VM. + +(!docs/pages/includes/start-teleport.mdx!) -Start Teleport on the Node and confirm that it is able to connect to and join -your cluster. You're all set! +Confirm that your Teleport process is able to connect to and join your cluster. +You're all set! diff --git a/docs/pages/management/join-services-to-your-cluster/join-token.mdx b/docs/pages/management/join-services-to-your-cluster/join-token.mdx new file mode 100644 index 0000000000000..d4ab0145c92d6 --- /dev/null +++ b/docs/pages/management/join-services-to-your-cluster/join-token.mdx @@ -0,0 +1,338 @@ +--- +title: Join Services with a Secure Token +description: This guide shows you how to join a Teleport instance to your cluster using a join token in order to proxy access to resources in your infrastructure. +--- + +In this guide, we will show you how to register a Teleport process running one +or more services to your cluster by presenting a **join token**. + +In this approach, you declare your intention to register a new Teleport process, +and Teleport generates a secure token that the process uses to establish a trust +relationship with the Teleport cluster. + +## Prerequisites + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- A Linux server that you will use to host your Teleport process, e.g., a + virtual machine or Docker container with an image based on a Linux + distribution. + + In this guide, we will show you how to register a Teleport SSH Service + instance. This approach also applies to other Teleport services, like the + Proxy Service, Kubernetes Service, Database Service, and other services for + accessing resources in your infrastructure. + +
+ + The join token method works if a cluster includes a single Proxy Service + instance as well as multiple Proxy Service instances behind a load balancer + (LB) or a DNS entry with multiple values. If there are multiple Proxy Service + instances, a Teleport process joining the cluster establishes a tunnel to + every Proxy Service instance. + + If you are using a load balancer, it must use a round-robin or a similar + balancing algorithm. Do not use sticky load balancing algorithms (i.e., + "session affinity") with Teleport Proxy Service instances. + +
+ + + + If you are are using a Docker container, note that this guide assumes that + your Linux host has `curl` and `sudo` installed. + + + +(!docs/pages/includes/tctl.mdx!) + +## Step 1/3. Install Teleport + +Install Teleport on your Linux host. + +(!docs/pages/includes/install-linux.mdx!) + +## Step 2/3. Join your Teleport process to the cluster + +In this section, we will join your Teleport process to your cluster by: + +- Obtaining a join token +- Running your Teleport process with the join token + +### Generate a token + +Teleport only allows access to resources in your infrastructure via Teleport +processes that that have joined the cluster. + +On your local machine, use the `tctl` tool to generate a new token. In the +following example, a new token is created with a TTL of five minutes: + +```code +# Generate a short-lived invite token for a new Teleport SSH Service instance: +$ tctl tokens add --ttl=5m --type=node +The invite token: (=presets.tokens.first=) +This token will expire in 5 minutes. + +Run this on the new node to join the cluster: + +> teleport start \ + --roles=node \ + --token=(=presets.tokens.first=) \ + --ca-pin=(=presets.ca_pin=) \ + --auth-server=192.0.2.0:3025 + +Please note: + + - This invitation token will expire in 5 minutes + - 192.0.2.0:3025 must be reachable from the new node +``` + +In this command, we assigned the token the `node` type, indicating that it will +belong to an SSH Service instance. + +Copy the token so you can use it later in this guide. You can ignore the rest of +the `tctl tokens add` output. + +
+ +Here are all the values we support for `--type` flag when creating a join token: + +|Role|Teleport Service| +|---|---| +|`app`|Application Service| +|`auth`|Auth Service| +|`bot`|Machine ID| +|`db`|Database Service| +|`discovery`|Discovery Service| +|`kube`|Kubernetes Service| +|`node`|SSH Service| +|`proxy`|Proxy Service| +|`windowsdesktop`|Windows Desktop Service| + +
+ +Administrators can generate tokens as they are needed. A Teleport process can +use a token multiple times until its time to live (TTL) expires, with the +exception of tokens with the `bot` type, which are used by Machine ID. + +To list all of the tokens you have generated, run the following command: + +```code +$ tctl tokens ls +Token Type Labels Expiry Time (UTC) +-------------------------------- ---- ------ -------------------------- +(=presets.tokens.first=) Node 30 Mar 23 18:15 UTC (2m8s) +``` + +
+ + +Use short-lived tokens instead of long-lived static tokens. +Static tokens are easier to steal, guess, and leak. + + +Static tokens are defined ahead of time by an administrator and stored in the +Auth Service's config file: + +```yaml +# Config section in `/etc/teleport.yaml` file for the Auth Service +auth_service: + enabled: true + tokens: + # This static token allows new hosts to join the cluster as "proxy" or "node" + - "proxy,node:secret-token-value" + # A token can also be stored in a file. In this example the token for adding + # new Auth Service instances are stored in /path/to/tokenfile + - "auth:/path/to/tokenfile" +``` +
+ +### Start your Teleport process with the invite token + +Execute the following command on the host running your new Teleport process to +add it to a cluster. Assign to the token you generated +earlier and to the host and web port of your +Teleport Proxy Service or Teleport Enterprise Cloud tenant (e.g., +`teleport.example.com:443`): + +```code +$ sudo teleport configure \ + --roles=node \ + --token= \ + --proxy= \ + -o file +``` + + + +For SSH Service instances, you can also run `teleport node configure` instead of +`teleport configure`. This way, you can exclude the `--roles=node` flag from the +command. + + + +
+ +So far, this guide has assumed that you are joining your new Teleport process to +your cluster by connecting it to the Proxy Service. (This is the only +possibility in Teleport Enterprise Cloud.) Depending on the design of your +infrastructure, you may need to connect your new Teleport process directly to +the Auth Service. + + + +Only connect Teleport processes directly to the Auth Service if no other join +methods are suitable, as we recommend exposing the Auth Service to as few +sources of ingress traffic as possible. + + + +The Teleport process joining the cluster must also establish trust with the Auth +Service in order to prevent an attacker from hijacking the address of your Auth +Service host. + +To do this, you supply your new Teleport process with a secure hash value +generated by the Auth Service's certificate authority, called a **CA pin**. This +way, an attacker cannot easily forge a private key to trick your Teleport +process into communicating with a malicious service. + +### Obtain a CA pin + +On you local machine, retrieve the CA pin of the Auth Service: + +```code +$ tctl status +Cluster teleport.example.com +Version 12.1.1 +host CA never updated +user CA never updated +db CA never updated +openssh CA never updated +jwt CA never updated +saml_idp CA never updated +CA pin (=presets.ca_pin=) +``` + +Copy the CA pin and assign it to the value of . + + + +The CA pin becomes invalid if a Teleport administrator performs the CA rotation +by executing [`tctl auth rotate`](../../reference/cli.mdx#tctl-auth-rotate). + + + +### Configure your Teleport process with the join token and CA pin + +Run the following command to configure your Teleport process instead of the +`teleport configure` command we showed you earlier. Assign to the host and gRPC port of your Auth Service host, e.g., +`teleport.example.com:3025`. + +```code +$ sudo teleport configure \ + --roles=node \ + --token= \ + --auth-server= \ + -o file +``` + +Next, edit the Teleport configuration file, `/etc/teleport.yaml`, assigning the +CA pin (the `teleport.ca_pin` field) to the one you copied earlier: + +```code +$ sudo sed -i 's| ca_pin: ""| ca_pin: " />"|' /etc/teleport.yaml +``` + +
+ +(!docs/pages/includes/start-teleport.mdx!) + +
+ +If you followed this guide with a local Docker container, execute the following +command within your container to run your new Teleport process in the foreground: + +```code +$ teleport start +``` + +
+ +As new services come online, they start sending heartbeat requests every few +seconds to the Auth Service. This allows users to explore cluster membership and +size. + +Run the following command on your local machine to see all of the Teleport SSH +Service instances in your cluster: + +```code +$ tctl nodes ls +Host UUID Public Address Labels Version +------------- --------------------- -------------- ---------------------- ------- +1f58429134c4 6805dda3-779e-493b... hostname=1f58429134c4 (=teleport.version=) +``` + + +## Step 3/3. Revoke an invitation + +You can revoke a join token to prevent a Teleport process from using it. + +Run the following command on your local machine to create a token for a new +Proxy Service: + +```code +$ tctl nodes add --ttl=5m --roles=proxy +# The invite token: (=presets.tokens.first=). +# This token will expire in 5 minutes. +# +# Run this on the new node to join the cluster: +# +# > teleport start \ +# --roles=proxy \ +# --token=(=presets.tokens.first=) \ +# --ca-pin=(=presets.ca_pin=) \ +# --auth-server=123.123.123.123:443 +# +# Please note: +# +# - This invitation token will expire in 5 minutes +# - 123.123.123.123 must be reachable from the new node +``` + +Next, run the following command to see a list of outstanding tokens: + +```code +$ tctl tokens ls +Token Type Labels Expiry Time (UTC) +-------------------------------- ----- ------ --------------------------- +(=presets.tokens.first=) Node 30 Mar 23 18:20 UTC (36s) +(=presets.tokens.second=) Proxy 30 Mar 23 18:24 UTC (4m39s) +``` + + + +The output of `tctl tokens ls` includes tokens used for adding users alongside +tokens used for adding Teleport processes to your cluster. + + + +You generated the token with the `Node` role earlier in this guide to invite a +new Teleport process to this cluster. The second token is the one you generated +for a Proxy Service instance. + +Tokens created via `tctl` can be deleted (revoked) via the `tctl tokens rm` +command. Copy the second token from the output above and run the following +command to delete it, assigning the token to . + +```code +$ tctl tokens rm +# Token (=presets.tokens.first=) has been deleted +``` + +## Next steps + +- If you have workloads split across different networks or clouds, we recommend + setting up Trusted Clusters. Read how to get started in our [Trusted Clusters + guide](../admin/trustedclusters.mdx). diff --git a/docs/pages/management/guides/joining-services-kubernetes-serviceaccount.mdx b/docs/pages/management/join-services-to-your-cluster/kubernetes.mdx similarity index 100% rename from docs/pages/management/guides/joining-services-kubernetes-serviceaccount.mdx rename to docs/pages/management/join-services-to-your-cluster/kubernetes.mdx diff --git a/docs/pages/management/operations/ca-rotation.mdx b/docs/pages/management/operations/ca-rotation.mdx index 1b218f77fcc59..eb4c852d83a12 100644 --- a/docs/pages/management/operations/ca-rotation.mdx +++ b/docs/pages/management/operations/ca-rotation.mdx @@ -13,7 +13,7 @@ description: How to rotate Teleport's certificate authority This section will show you how to implement certificate rotation in practice. -If you are using [CA Pinning](../admin/adding-nodes.mdx#obtain-a-ca-pin) +If you are using [CA Pinning](../join-services-to-your-cluster/join-token.mdx#obtain-a-ca-pin) when adding new nodes, the CA pin will change after the rotation. Make sure you use the *new* CA pin when adding nodes after rotation. diff --git a/docs/pages/reference/helm-reference/teleport-kube-agent.mdx b/docs/pages/reference/helm-reference/teleport-kube-agent.mdx index 87b561a9a8347..f952679337d2a 100644 --- a/docs/pages/reference/helm-reference/teleport-kube-agent.mdx +++ b/docs/pages/reference/helm-reference/teleport-kube-agent.mdx @@ -321,8 +321,10 @@ These sub-values must be configured for the agent to connect to a cluster. `joinParams.method` defines which join method will be used to join the Teleport cluster. Possible values are `token`, `iam` and `ec2`. -- For `iam`, see [Joining Nodes Via AWS IAM Role](../../management/guides/joining-nodes-aws-iam.mdx). -- For `ec2`, see [Joining Nodes Via AWS IAM Role](../../management/guides/joining-nodes-aws-ec2.mdx). +- For `iam`, see [Joining Nodes Via AWS IAM + Role](../../management/join-services-to-your-cluster/aws-iam.mdx). +- For `ec2`, see [Joining Nodes Via AWS IAM + Role](../../management/join-services-to-your-cluster/aws-ec2.mdx). - For `token` (default value), the token must be provided through `joinParams.tokenName` or [through an existing Kubernetes Secret](#secretName). @@ -816,7 +818,7 @@ See [this link for information on Community Docker image versions](../../managem When `caPin` is set, the Teleport pod will use its values to check the Auth Service's identity when first joining a cluster. This enables a more secure way of adding new Teleport instances to a cluster. See -["Adding Nodes to the Cluster"](../../management/admin/adding-nodes.mdx). +["Adding Nodes to the Cluster"](../../management/join-services-to-your-cluster/join-token.mdx). Each list element can be the pin itself (recommended, works out of the box), or a path to a file containing the pin. For the latter it is your diff --git a/docs/pages/server-access/guides/azure-discovery.mdx b/docs/pages/server-access/guides/azure-discovery.mdx index 11664b17d1318..f8d43a3141787 100644 --- a/docs/pages/server-access/guides/azure-discovery.mdx +++ b/docs/pages/server-access/guides/azure-discovery.mdx @@ -340,7 +340,7 @@ for more information. ## Next steps -- Read [Joining Nodes via Azure Managed Identity](../../management/guides/joining-nodes-azure.mdx) +- Read [Joining Nodes via Azure Managed Identity](../../management/join-services-to-your-cluster/azure.mdx) for more information on Azure tokens. - Full documentation on Azure discovery configuration can be found through the [ config file reference documentation](../../reference/config.mdx). diff --git a/docs/pages/server-access/guides/ec2-discovery.mdx b/docs/pages/server-access/guides/ec2-discovery.mdx index 8e3ed83a668f1..dbf8bab38312e 100644 --- a/docs/pages/server-access/guides/ec2-discovery.mdx +++ b/docs/pages/server-access/guides/ec2-discovery.mdx @@ -388,7 +388,8 @@ Select the instance-id of the Target to review Errors. ## Next steps -- Read [Joining Nodes via AWS IAM Role](../../management/guides/joining-nodes-aws-iam.mdx) +- Read [Joining Nodes via AWS IAM + Role](../../management/join-services-to-your-cluster/aws-iam.mdx) for more information on IAM Invite Tokens. - Information on IAM best practices on EC2 instances managed by Systems Manager can be found for in the [AWS Cloud Operations & Migrations Blog