From bbc4656b72f93bcb15c12f08f7a1136b200959ca Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Fri, 3 Jun 2022 09:34:37 -0400 Subject: [PATCH] Backport #12504 to branch/v7 (#13114) * Make the Adding Nodes guide more usable See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide. * Respond to PR feedback Also remove some erroneous command output --- docs/pages/setup/admin/adding-nodes.mdx | 152 ++++++++++++------------ 1 file changed, 79 insertions(+), 73 deletions(-) diff --git a/docs/pages/setup/admin/adding-nodes.mdx b/docs/pages/setup/admin/adding-nodes.mdx index 36078da99a633..74428405b366e 100644 --- a/docs/pages/setup/admin/adding-nodes.mdx +++ b/docs/pages/setup/admin/adding-nodes.mdx @@ -1,5 +1,5 @@ --- -title: Adding Nodes to the Cluster +title: Adding Nodes to your Cluster description: How to add Nodes to your Teleport cluster --- @@ -9,7 +9,7 @@ This guide explains how to add Teleport Nodes to your cluster. (!docs/pages/includes/edition-prereqs-tabs.mdx!) -- A Linux server that you will use to host your Teleport Node +- A Linux server that you will use to host your Teleport Node. (!docs/pages/includes/tctl.mdx!) @@ -57,16 +57,12 @@ by executing [`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate). -Retrieve the CA pin of the Auth Service by running the following -command on your local machine: +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}') - -# Cluster staging.example.com -# User CA never updated -# Host CA never updated -# CA pin (=presets.ca_pin=) ``` ### Generate a token @@ -77,15 +73,14 @@ 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: -`auth`, `proxy`, `node`, `app`, `kube`, or `db`. +An invite token also defines which role a new host can assume within a cluster +(e.g., `auth`, `proxy`, `node`, or `kube`). Administrators can generate tokens as they are needed. A token can be used multiple times until its time to live (TTL) expires. -Use the `tctl` tool on your local -machine to generate a new token. In the following example, a new -token is created with a TTL of five minutes: +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: @@ -98,18 +93,28 @@ $ tctl tokens ls # Token Type Expiry Time # ------------------------ ----------- --------------- # (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC - -# ... or revoke an invite token before it's used: -$ tctl tokens rm (=presets.tokens.first=) ``` -If you want to provide your own token, you can do so using the `--token` flag: +
+ +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. @@ -134,79 +139,54 @@ auth_service: ### Start your Node with the invite token and CA pin - - - -Execute one of the following commands on a new Node to add it to a cluster. -Supply the invite token and CA pin you retrieved earlier: +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 -$ sudo teleport start \ - --roles=node \ - --token=(=presets.tokens.first=) \ - --ca-pin=(=presets.ca_pin=) \ - --auth-server=10.12.0.6:3025 +$ export CA_PIN=$ +$ export INVITE_TOKEN= ``` - - -Execute the following command on a new Node to add it to a cluster. Replace -`mytenant.teleport.sh` with the domain name of your Teleport Cloud tenant. -Supply the invite token and CA pin you retrieved earlier: + + +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 -$ sudo teleport start \ - --roles=node \ - --token=(=presets.tokens.first=) \ - --ca-pin=(=presets.ca_pin=) \ - --auth-server=https://mytenant.teleport.sh:443 +$ export ADDR=teleport.example.com:3025 ``` - - + + -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: +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 -$ 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 +$ export ADDR=mytenant.teleport.sh:443 ``` -{/* TODO: This lengthy Details box should be a subsection. Using the Details box -as a workaround until we have a way to control the visibility of subsections -using the scope switcher */} + - +
+ +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 +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. -Teleport Node Tunneling lets you add a remote Node to an existing Teleport Cluster through a tunnel. -This can be useful for IoT applications or for managing a couple of servers in a different network. + - We recommend setting up a [Trusted Cluster](../admin/trustedclusters.mdx) if you have workloads split across different networks or clouds. - - -To connect a Node to your cluster via Node Tunneling, use `tctl` to create a -single-use token for a Node. Instead of supplying the IP of the Auth Service for -the `--auth-server` flag, you will use the URL of the Proxy Service. -In the example below, we've replaced the auth server IP with the Proxy's web -endpoint `teleport-proxy.example.com:3080`. - -```code -$ tctl tokens add --type=node | grep -oP '(?<=token:\s).*' > token.file - -# This will save the token to a file. -# Run this on the new node to join the cluster: -$ sudo teleport start --roles=node --token=/path/to/token.file --auth-server=teleport-proxy.example.com:3080 -``` + 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 @@ -242,13 +222,39 @@ DEBU [PROC:1] Setup Proxy: Reverse tunnel proxy and web proxy listen on the s 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 to create a token for a new Proxy Service. +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