Skip to content

Commit

Permalink
[docs] Update how to remove trusted clusters. (#4358)
Browse files Browse the repository at this point in the history 
Co-authored-by: Gus Luxton <[email protected]>
  • Loading branch information
@benarent @webvictim
benarent and webvictim authored Sep 24, 2020
1 parent f920210 commit 616b5f8
Show file tree
Hide file tree
Showing 2 changed files with 164 additions and 301 deletions.
237 changes: 2 additions & 235 deletions docs/4.3/admin-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1056,234 +1056,9 @@ multiple clusters together and establish trust between them. Trusted clusters
allow users of one cluster to seamlessly SSH into the nodes of another cluster
without having to "hop" between proxy servers. Moreover, users don't even need
to have a direct connection to other clusters' proxy servers. Trusted clusters
also have their own restrictions on user access. The user experience looks like
this:
also have their own restrictions on user access.

``` bash
# login using the "main" cluster credentials:
$ tsh login --proxy=main.example.com
# SSH into some host inside the "main" cluster:
$ tsh ssh host
# SSH into the host located in another cluster called "east"
# The connection is established through main.example.com:
$ tsh ssh --cluster=east host
# See what other clusters are available
$ tsh clusters
```

### Selecting the Default Cluster

To avoid using `--cluster` switch with [ `tsh` ](cli-docs.md#tsh) commands, you
can also specify which trusted cluster you want to become the default from the
start:

``` bash
# login into "main" but request "east" to be the default for subsequent
# tsh commands:
$ tsh login --proxy=main.example.com east
```

### Connectivity

The design of trusted clusters allows Teleport users to connect to compute
infrastructure located behind firewalls without any open TCP ports. The real
world usage examples of this capability include:

* Managed service providers (MSP) remotely managing infrastructure of their
clients.

* Device manufacturers remotely maintaining computing appliances deployed on
premises.

* Large cloud software vendors manage multiple data centers using a common
proxy.

Let's take a look at how a connection is established between the "main" cluster
and the "east" cluster:

![Tunnels](img/tunnel.svg)

This setup works as follows:

1. The "east" creates an outbound reverse SSH tunnel to "main" and keeps the
tunnel open.

2. **Accessibility only works in one direction.** The "east" cluster allows
users from "main" to access its nodes but users in the "east" cluster can not
access the "main" cluster.

3. When a user tries to connect to a node inside "east" using main's proxy, the
reverse tunnel from step 1 is used to establish this connection shown as the
green line above.

!!! tip "Load Balancers"

The scheme above also works even if the "main" cluster uses multiple
proxies behind a load balancer (LB) or a DNS entry with multiple values.
This works by "east" establishing a tunnel to _every_ proxy in "main". This
requires that an LB uses round-robin or a similar balancing algorithm. Do
not use sticky load balancing algorithms (a.k.a. "session affinity") with
Teleport proxies.

### Example Configuration

Connecting two clusters together is similar to [adding
nodes](#adding-nodes-to-the-cluster):

1. Generate an invitation token on "main" cluster, or use a pre-defined static
token.

2. On the "east" side, create a trusted cluster [resource](#resources).

**Creating a Cluster Join Token**

Just like with adding nodes, you can use either a static cluster token defined
in `/etc/teleport.yaml` or you can generate an auto-expiring token:

To define a static cluster join token using the configuration file on "main":

``` yaml
# fragment of /etc/teleport.yaml:
auth_service:
enabled: true
tokens: trusted_cluster:secret-token-to-add-new-clusters
```

If you wish to use auto-expiring cluster tokens, execute this CLI command on the
"main" side:

``` bash
$ tctl tokens add --type=trusted_cluster
The cluster invite token: generated-token-to-add-new-clusters
```

**Using a Cluster Join Token**

Now, the administrator of "east" must create the following resource file:

``` yaml
# cluster.yaml
kind: trusted_cluster
version: v2
metadata:
# the trusted cluster name MUST match the 'cluster_name' setting of the
# cluster
name: main
spec:
# this field allows to create tunnels that are disabled, but can be enabled later.
enabled: true
# the token expected by the "main" cluster:
token: secret-token-to-add-new-clusters
# the address in 'host:port' form of the reverse tunnel listening port on the
# "main" proxy server:
tunnel_addr: main.example.com:3024
# the address in 'host:port' form of the web listening port on the
# "main" proxy server:
web_proxy_addr: main.example.com:3080
# the role mapping allows to map user roles from one cluster to another
# (enterprise editions of Teleport only)
role_map:
- remote: "admin" # users who have "admin" role on "main"
local: ["auditor"] # will be assigned "auditor" role when logging into "east"
```

Then, use [ `tctl create` ](cli-docs.md#tctl-create) to add the file:

``` bash
$ tctl create cluster.yaml
```

At this point the users of the main cluster should be able to see "east" in the
list of available clusters.

!!! warning "HTTPS configuration"

If the `web_proxy_addr` endpoint of the main
cluster uses a self-signed or invalid HTTPS certificate, you will get an
error: _"the trusted cluster uses misconfigured HTTP/TLS certificate"_. For
ease of testing the teleport daemon of "east" can be started with
`--insecure` CLI flag to accept self-signed certificates. Make sure to configure
HTTPS properly and remove the insecure flag for production use.

### Using Trusted Clusters

As mentioned above, accessibility is only granted in one direction. So, only
users from the "main" (trusted cluster) can now access nodes in the "east"
(trusting cluster). Users in the "east" cluster will not be able to access the
"main" cluster.

``` bash
# login into the main cluster:
$ tsh --proxy=proxy.main login joe
# see the list of available clusters
$ tsh clusters
Cluster Name Status
------------ ------
main online
east online
# see the list of machines (nodes) behind the eastern cluster:
$ tsh ls --cluster=east
Node Name Node ID Address Labels
--------- ------------------ -------------- -----------
db1.east cf7cc5cd-935e-46f1 10.0.5.2:3022 role=db-leader
db2.east 3879d133-fe81-3212 10.0.5.3:3022 role=db-worker
# SSH into any node in "east":
$ tsh ssh --cluster=east [email protected]
```

### Disabling Trust

To temporarily disable trust between clusters, i.e.to disconnect the "east"
cluster from "main", edit the YAML definition of the trusted cluster resource
and set `enabled` to "false", then update it:

``` bash
$ tctl create --force cluster.yaml
```

If you want to _permanently_ disconnect one cluster from the other:

``` bash
# execute this command on "main" side to disconnect "east":
$ tctl rm tc/east
```

While accessibility is only granted in one direction, trust is granted in both
directions. If you remove "east" from "main", the following will happen:

* Two clusters will be disconnected, because "main" will drop the inbound SSH
tunnel connection from "east" and will not allow a new one.

* "main" will stop trusting certificates issued by "east".
* "east" will continue to trust certificates issued by "main".

If you wish to permanently remove all trust relationships and the connections
between both clusters:

``` bash
# execute on "main":
$ tctl rm tc/east
# execute on "east":
$ tctl rm tc/main
```

### Advanced Configuration

Take a look at [Trusted Clusters Guide](trustedclusters.md) to learn more about
advanced topics:

* Using dynamic cluster join tokens instead of pre-defined static tokens for
enhanced security.

* Defining role-mapping between clusters (Teleport Enterprise only).
To learn more about Trusted Clusters please visit our [Trusted Cluster Guide](trustedclusters.md)

## Github OAuth 2.0

Expand Down Expand Up @@ -1475,14 +1250,6 @@ To check the status of certificate rotation:
$ tctl status
```

!!! danger "Version Warning"

Certificate rotation can only be used with
clusters running version 2.6 of Teleport or newer. If trusted clusters are
used, make sure _all_ connected clusters are running version 2.6+. If one of
the trusted clusters is running an older version of Teleport the
trust/connection to that cluster will be lost.

!!! warning "CA Pinning Warning"

If you are using [CA Pinning](#untrusted-auth-servers) when adding new
Expand Down
Loading

0 comments on commit 616b5f8

Please sign in to comment.