Skip to content

Commit

Permalink
Make the Adding Nodes guide more usable
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@ptgott
ptgott committed Jun 2, 2022
1 parent f79eb4b commit bcd26d6
Showing 1 changed file with 73 additions and 68 deletions.
141 changes: 73 additions & 68 deletions docs/pages/setup/admin/adding-nodes.mdx
View file
Original file line number Diff line number Diff line change
@@ -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
---

Expand All @@ -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!)

Expand Down Expand Up @@ -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}')
Expand All @@ -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:
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit bcd26d6

Please sign in to comment.