From b206715a1920790b9a6cdcb8a9df92334a11a59b Mon Sep 17 00:00:00 2001
From: Paul Gottschling <paul.gottschling@goteleport.com>
Date: Fri, 6 May 2022 17:18:11 -0400
Subject: [PATCH 1/2] 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.
---
 docs/pages/setup/admin/adding-nodes.mdx | 141 ++++++++++++------------
 1 file changed, 73 insertions(+), 68 deletions(-)

diff --git a/docs/pages/setup/admin/adding-nodes.mdx b/docs/pages/setup/admin/adding-nodes.mdx
index 36078da99a633..3651a56a6377d 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,8 +57,9 @@ by executing [`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate).
     
 </Notice>
 
-Retrieve the CA pin of the Auth Service <ScopedBlock scope="cloud"> by running the following
-command on your local machine</ScopedBlock>:
+On you local machine, retrieve the CA pin of the Auth Service <ScopedBlock
+scope="cloud"> by running the following command on your local
+machine</ScopedBlock>:
 
 ```code
 $ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}')
@@ -77,15 +78,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 <ScopedBlock scope="cloud">on your local
-machine</ScopedBlock> 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 +98,20 @@ $ 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:
+<Details title="Tokens with known values">
+
+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
 ```
 
+</Details>
+
 <Details scope={["oss","enterprise"]} title="An insecure alternative: static tokens" scopeOnly={true} opened>
 <Admonition type="warning">
 Use short-lived tokens instead of long-lived static tokens.
@@ -134,79 +136,56 @@ auth_service:
 
 ### Start your Node with the invite token and CA pin
 
-<Tabs>
-<TabItem scope={["oss", "enterprise"]} scopeOnly={true} label="Self Hosted">
-
-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 your local machine, then copy the output.
 
 ```code
-$ sudo teleport start \
-   --roles=node \
-   --token=(=presets.tokens.first=) \
-   --ca-pin=(=presets.ca_pin=) \
-   --auth-server=10.12.0.6:3025
+$ echo "export CA_PIN=${CA_PIN?}"
+$ echo "export INVITE_TOKEN=${INVITE_TOKEN?}"
 ```
-</TabItem>
-<TabItem scope={["cloud"]} scopeOnly={true} label="Teleport Cloud">
 
-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:
+Paste the output into a terminal on the host where you will run your Node so you
+can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport.
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+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
 ```
 
-</TabItem>
-</Tabs>
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
 
-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 */}
+</ScopedBlock>
 
-<ScopedBlock scope={["oss", "enterprise"]}>
+<Details title="Alternative: Connect to the Proxy Service via Teleport Node Tunneling" scope={["oss", "enterprise"]} scopeOnly opened={false}>
 
-### Teleport Node Tunneling
+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 tunnel.
-This can be useful for IoT applications or for managing a couple of servers in a different network.
+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.
+
+<Notice type="note">
 
-<Admonition type="note">
 We recommend setting up a [Trusted Cluster](../admin/trustedclusters.mdx) if you
 have workloads split across different networks or clouds.
-</Admonition>
-
-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
-```
+</Notice>
 
 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 +221,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.
 </Admonition>
 
-</ScopedBlock>
+</Details>
+
+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 

From efe04b2b566f2a3271555606541ea12df12da8c8 Mon Sep 17 00:00:00 2001
From: Paul Gottschling <paul.gottschling@goteleport.com>
Date: Fri, 20 May 2022 15:00:15 -0400
Subject: [PATCH 2/2] Respond to PR feedback

Also remove some erroneous command output
---
 docs/pages/setup/admin/adding-nodes.mdx | 27 +++++++++++++------------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/docs/pages/setup/admin/adding-nodes.mdx b/docs/pages/setup/admin/adding-nodes.mdx
index 3651a56a6377d..74428405b366e 100644
--- a/docs/pages/setup/admin/adding-nodes.mdx
+++ b/docs/pages/setup/admin/adding-nodes.mdx
@@ -63,11 +63,6 @@ machine</ScopedBlock>:
 
 ```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
@@ -100,7 +95,7 @@ $ tctl tokens ls
 # (=presets.tokens.first=)         Node            25 Sep 18 00:21 UTC
 ```
 
-<Details title="Tokens with known values">
+<Details title="Provide your own token value">
 
 Rather than automatically generating a token, you can create one with a known
 value by using the `--token` flag:
@@ -110,6 +105,14 @@ $ 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
+```
+
 </Details>
 
 <Details scope={["oss","enterprise"]} title="An insecure alternative: static tokens" scopeOnly={true} opened>
@@ -136,16 +139,14 @@ auth_service:
 
 ### Start your Node with the invite token and CA pin
 
-Execute the following commands on your local machine, then copy the output.
+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
-$ echo "export CA_PIN=${CA_PIN?}"
-$ echo "export INVITE_TOKEN=${INVITE_TOKEN?}"
+$ export CA_PIN=$<CA pin>
+$ export INVITE_TOKEN=<invite token>
 ```
 
-Paste the output into a terminal on the host where you will run your Node so you
-can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport.
-
 <ScopedBlock scope={["oss", "enterprise"]}>
 
 Still on the host where you will run your Node, assign the address of your Auth
@@ -253,7 +254,7 @@ dijkstra      c9s93fd9-3333-91d3-9999-c9s93fd98f43     10.1.0.6:3022      distro
 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.
+Proxy Service:
 
 ```code
 $ tctl nodes add --ttl=5m --roles=proxy