From c33b8484e58a7386d825bd678f67ec5d7b98dc4e Mon Sep 17 00:00:00 2001 From: lsgunn-teleport <136391445+lsgunn-teleport@users.noreply.github.com> Date: Wed, 4 Oct 2023 12:40:44 -0700 Subject: [PATCH] docs: Reduce the use of capitalized trusted clusters and a few other fixes (#32432) * Reduce the use of capitalized trusted clusters and a few other fixes * fix a typo * Modify the description of trusted clusters in core concepts * Lower case cluster, add root and leaf to the description for self-hosted * OpenSSH split into two topics --- .../access-controls/guides/ip-pinning.mdx | 2 +- docs/pages/access-controls/reference.mdx | 2 +- .../join-token.mdx | 3 +-- docs/pages/architecture/session-recording.mdx | 8 +++---- docs/pages/architecture/tls-routing.mdx | 4 ++-- .../connect-your-client/teleport-connect.mdx | 4 ++-- docs/pages/connect-your-client/tsh.mdx | 8 +++---- docs/pages/core-concepts.mdx | 24 +++++++++---------- .../deployments/aws-terraform.mdx | 4 ++-- docs/pages/faq.mdx | 5 ++-- docs/pages/includes/role-spec.mdx | 2 +- .../pages/kubernetes-access/manage-access.mdx | 2 +- .../manage-access/federation.mdx | 18 +++++++------- docs/pages/machine-id/faq.mdx | 5 ++-- docs/pages/management/admin.mdx | 2 +- .../pages/management/operations/upgrading.mdx | 4 ++-- docs/pages/reference/cli/tctl.mdx | 2 +- .../guides/openssh/openssh-manual-install.mdx | 10 ++++---- .../server-access/guides/openssh/openssh.mdx | 10 ++++---- docs/pages/server-access/rbac.mdx | 4 ++-- 20 files changed, 61 insertions(+), 62 deletions(-) diff --git a/docs/pages/access-controls/guides/ip-pinning.mdx b/docs/pages/access-controls/guides/ip-pinning.mdx index eea09b51a11..f920d29c7f6 100644 --- a/docs/pages/access-controls/guides/ip-pinning.mdx +++ b/docs/pages/access-controls/guides/ip-pinning.mdx @@ -31,7 +31,7 @@ access will be denied. This means that if you enable IP pinning for some role, a order to regenerate their certificates. A client's observed IP will be propagated internally between Teleport services if needed, so Teleport performs the IP pinning check against the correct IP. -IP pinning can work across Trusted Clusters, but be aware that if a user tries to access a leaf cluster's resources through the root cluster, and their +IP pinning can work across trusted clusters, but be aware that if a user tries to access a leaf cluster's resources through the root cluster, and their mapped role on the leaf cluster has IP pinning enabled, they should also have IP pinning enabled on their root cluster roles. Otherwise, their certificates will not contain pinned IP information. diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx index aa2a2883667..60e9602dfda 100644 --- a/docs/pages/access-controls/reference.mdx +++ b/docs/pages/access-controls/reference.mdx @@ -68,7 +68,7 @@ The following variables can be used with `logins` and `windows_desktop_logins` f | Variable | Description | | - | - | -| `{{internal.logins}}` | Substituted with a value stored in Teleport's local user database
and logins from a root cluster.

For local users, Teleport will substitute this with the
"allowed logins" parameter used in the
`tctl users add [user] ` command.

If the role is within a leaf cluster in a [Trusted Cluster](../management/admin/trustedclusters.mdx),
Teleport will substitute the logins from the root cluster
whether the user is a local user or from an SSO provider.

As an example, if the user has the `ubuntu` login in the root
cluster, then `ubuntu` will be substituted in the leaf
cluster with this variable. | +| `{{internal.logins}}` | Substituted with a value stored in Teleport's local user database
and logins from a root cluster.

For local users, Teleport will substitute this with the
"allowed logins" parameter used in the
`tctl users add [user] ` command.

If the role is within a leaf cluster in a [trusted cluster](../management/admin/trustedclusters.mdx),
Teleport will substitute the logins from the root cluster
whether the user is a local user or from an SSO provider.

As an example, if the user has the `ubuntu` login in the root
cluster, then `ubuntu` will be substituted in the leaf
cluster with this variable. | | `{{external.xyz}}` | Substituted with a value from an external [SSO provider](https://en.wikipedia.org/wiki/Single_sign-on).
If using SAML, this will be expanded with "xyz" assertion value.
For OIDC, this will be expanded a value of "xyz" claim. | Both variables above are there to deliver the same benefit: they allow Teleport diff --git a/docs/pages/agents/join-services-to-your-cluster/join-token.mdx b/docs/pages/agents/join-services-to-your-cluster/join-token.mdx index 026ab247dae..7b3e32ff0b0 100644 --- a/docs/pages/agents/join-services-to-your-cluster/join-token.mdx +++ b/docs/pages/agents/join-services-to-your-cluster/join-token.mdx @@ -334,5 +334,4 @@ $ tctl tokens rm ## 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](../../management/admin/trustedclusters.mdx). + setting up trusted clusters. Read how to get started in [Configure Trusted Clusters](../../management/admin/trustedclusters.mdx). diff --git a/docs/pages/architecture/session-recording.mdx b/docs/pages/architecture/session-recording.mdx index 6de3e1f8e77..f5543ff757b 100644 --- a/docs/pages/architecture/session-recording.mdx +++ b/docs/pages/architecture/session-recording.mdx @@ -61,10 +61,10 @@ This results in 4 possible session recording configurations: This is a cluster-wide configuration option and applies to the entire Teleport cluster. It can be configured by setting `session_recording` -in the `auth_service` section of your `teleport.yaml`, or dynamically via -the the `session_recording_config` resource. If you need to apply different -recording configuration to different sets of resources, we recommend setting up -[Trusted Clusters](../management/admin/trustedclusters.mdx) with their own +in the `auth_service` section of your `teleport.yaml`, or dynamically using +the `session_recording_config` resource. If you need to apply different +recording configurations to different sets of resources, you can set up +[trusted clusters](../management/admin/trustedclusters.mdx) with their own recording configurations. diff --git a/docs/pages/architecture/tls-routing.mdx b/docs/pages/architecture/tls-routing.mdx index 7be9f3e3f08..417903e6f1e 100644 --- a/docs/pages/architecture/tls-routing.mdx +++ b/docs/pages/architecture/tls-routing.mdx @@ -90,8 +90,8 @@ how it's configured. ## Reverse tunnels -Reverse tunnel workers within the Teleport Node, Application and Database -Services, as well as for Trusted Clusters, open a TLS tunnel to the cluster's +Reverse tunnel workers within the Teleport SSH, Application, and Database +Services, as well as for trusted clusters, open a TLS tunnel to the cluster's Proxy Service with the `teleport-reversetunnel` ALPN protocol. The workers then dial SSH over the tunnel, establishing a secure connection. diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx index ab99fff346a..c2b761d2086 100644 --- a/docs/pages/connect-your-client/teleport-connect.mdx +++ b/docs/pages/connect-your-client/teleport-connect.mdx @@ -56,7 +56,7 @@ The top bar of Teleport Connect consists of: between them. - The **search bar** (in the middle), which allows you to search for resources across clusters. - The **cluster selector** (to the left of the search bar), which shows up only if you have set up - Trusted Clusters and there are leaf clusters connected to the root cluster. It lets you browse + trusted clusters and there are leaf clusters connected to the root cluster. It lets you browse leaf cluster resources. Also, the "Open new terminal" action will bind new terminal tabs to the selected cluster. - The **additional actions menu** (to the left of the profile selector), containing options such as opening a config file or creating an access request in an Enterprise cluster. @@ -85,7 +85,7 @@ this by setting the environment variables `TELEPORT_PROXY` and `TELEPORT_CLUSTER Additionally, Teleport Connect prepends the `PATH`/`Path` environment variable in the session with the directory containing the tsh binary, even if [tsh is not globally available](#using-tsh-outside-of-teleport-connect). -When using [Trusted Clusters](../management/admin/trustedclusters.mdx), the cluster selector allows +When using [trusted clusters](../management/admin/trustedclusters.mdx), the cluster selector allows you to determine which cluster the shell session will be bound to. The selected cluster will be reflected in both the tab title and the status bar. diff --git a/docs/pages/connect-your-client/tsh.mdx b/docs/pages/connect-your-client/tsh.mdx index 86d53511e1b..ac3edba5958 100644 --- a/docs/pages/connect-your-client/tsh.mdx +++ b/docs/pages/connect-your-client/tsh.mdx @@ -697,14 +697,14 @@ Teleport supports creating clusters of servers located behind firewalls **without any open listening TCP ports**. This works by creating reverse SSH tunnels from behind-firewall environments into a Teleport Proxy Service you have access to. -These features are called **Trusted Clusters**. Refer to [the Trusted Clusters guide](../management/admin/trustedclusters.mdx) -to learn how a Trusted Cluster can be configured. +To learn more about setting up a trust relationship between clusters behind firewalls, see +[Configure Trusted Clusters](../management/admin/trustedclusters.mdx). -Assuming the Teleport Proxy Server called `work` is configured with a few Trusted -Clusters, a user may use the `tsh clusters` command to see a list of all Trusted Clusters on the server: +Assuming the Teleport Proxy Server called `work` is configured with a few trusted +clusters, you can use the `tsh clusters` command to see a list of all the trusted clusters on the server: ```code $ tsh --proxy=work clusters diff --git a/docs/pages/core-concepts.mdx b/docs/pages/core-concepts.mdx index 0be02a56038..247027ee3bf 100644 --- a/docs/pages/core-concepts.mdx +++ b/docs/pages/core-concepts.mdx @@ -214,17 +214,17 @@ authenticate to Teleport via a Single Sign-On (SSO) solution. See our guide to [Authentication Options](./reference/authentication.mdx). -### Trusted Cluster +### Trusted clusters -A **Trusted Cluster** is a remote **Teleport cluster** joined to your own -cluster via a trust relationship. Users in your Teleport cluster can access -resources in a Trusted Cluster. +Teleport allows you to configure a **trusted cluster relationship** between a +**root cluster** and one or more **leaf clusters** that trust the root cluster +certificate authority. The trust relationship between the root and leaf clusters +enables users authenticated in the root cluster to access resources +in leaf cluster. The root and leaf cluster operate independently with their own +users, roles, and resources, but the trust relationship allows users with certain roles +in the root cluster to be mapped to roles and permissions defined in the leaf cluster. -In a Trusted Cluster relationship, the remote cluster is called a **leaf -cluster**. Your cluster, if you are adding a leaf cluster to it, is called a -**root cluster**. - -Read our [Trusted Clusters architecture -guide](./architecture/trustedclusters.mdx) for how Trusted Clusters work and our -[how-to guide](./management/admin/trustedclusters.mdx) for how to configure -Trusted Clusters. +For more information about how to configure a trust relationship between clusters, +see [Configure Trusted Clusters](./management/admin/trustedclusters.mdx). +For an overview of the architecture used in a trusted cluster relationship, see +[Trusted Cluster Architecture]](./architecture/trustedclusters.mdx). diff --git a/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx b/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx index 8841c9a0005..d330bc7b026 100644 --- a/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx +++ b/docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx @@ -827,9 +827,9 @@ example. proxy_server: teleport.example.com:443 ``` -### Trusted Clusters +### Trusted clusters -To add a Trusted Cluster, you'll need the hostname of the proxy load balancer. You can get it using this command: +To add a trusted cluster, you'll need the hostname of the proxy load balancer. You can get it using this command: ```code $ aws elbv2 describe-load-balancers --names "${TF_VAR_cluster_name}-proxy" --query "LoadBalancers[*].DNSName" --output text diff --git a/docs/pages/faq.mdx b/docs/pages/faq.mdx index 47a6e3615aa..b9c779fe7ca 100644 --- a/docs/pages/faq.mdx +++ b/docs/pages/faq.mdx @@ -31,11 +31,10 @@ functionality without a net addition of an agent on your system. Yes, this question comes up often and is related to the previous one. Take a look at [Using OpenSSH Guide](./server-access/guides/openssh.mdx). -## Can I connect to Nodes behind a firewall? +## Can I connect to nodes behind a firewall? Yes, Teleport supports reverse SSH tunnels out of the box. To configure -behind-firewall clusters refer to our -[Trusted Clusters](./management/admin/trustedclusters.mdx) guide. +behind-firewall clusters, see [Configure Trusted Clusters](./management/admin/trustedclusters.mdx). ## Should we use Teleport Enterprise or Teleport Community Edition for connecting resources to our Teleport cluster? (!docs/pages/includes/ent-vs-community-faq.mdx!) diff --git a/docs/pages/includes/role-spec.mdx b/docs/pages/includes/role-spec.mdx index 0a830a76493..1cef8d3dd2e 100644 --- a/docs/pages/includes/role-spec.mdx +++ b/docs/pages/includes/role-spec.mdx @@ -385,7 +385,7 @@ spec: # saml - connector resource # github - GitHub connector resource # - # trusted_cluster - Trusted Cluster resource + # trusted_cluster - Trusted cluster resource # remote_cluster - remote cluster resource # # access_request - Access Request resource diff --git a/docs/pages/kubernetes-access/manage-access.mdx b/docs/pages/kubernetes-access/manage-access.mdx index e2dbc576e65..e44be1e143d 100644 --- a/docs/pages/kubernetes-access/manage-access.mdx +++ b/docs/pages/kubernetes-access/manage-access.mdx @@ -1,6 +1,6 @@ --- title: Managing Access to Kubernetes Clusters -description: Use Teleport's sophisticated RBAC and Trusted Clusters to ensure that your teams have the correct access to your Kubernetes clusters. +description: Use Teleport's sophisticated RBAC and trusted clusters to ensure that your teams have the correct access to your Kubernetes clusters. --- Once you register a Kubernetes cluster with Teleport, you can apply diff --git a/docs/pages/kubernetes-access/manage-access/federation.mdx b/docs/pages/kubernetes-access/manage-access/federation.mdx index 69d73207cbb..61ec4dba7bd 100644 --- a/docs/pages/kubernetes-access/manage-access/federation.mdx +++ b/docs/pages/kubernetes-access/manage-access/federation.mdx @@ -1,26 +1,27 @@ --- title: Federated Kubernetes Access with Trusted Clusters -description: Federated Access using Teleport Trusted Clusters. +description: Federated Access using Teleport trusted clusters. --- There are cases when you have Kubernetes clusters that have to operate independently, for example, they are part of a different organization or have intermittent connectivity. -You can take advantage of [Trusted Clusters](../../management/admin/trustedclusters.mdx) +You can take advantage of [trusted clusters](../../management/admin/trustedclusters.mdx) to federate trust across Kubernetes clusters. -When multiple Trusted Clusters are present behind the Teleport Proxy Service, the +When multiple trusted clusters are present behind the Teleport Proxy Service, the `kubeconfig` generated by [tsh login](../../reference/cli/tsh.mdx#tsh-login) will contain the Kubernetes API endpoint determined by the `` argument to [tsh login](../../reference/cli/tsh.mdx#tsh-login). For example, consider the following setup: -- There are three Teleport/Kubernetes clusters: `main`, `east`, and `west`. These are the names set in `cluster_name` setting in their configuration files. -- The clusters `east` and `west` are Trusted Clusters for `main`. +- There are three Teleport/Kubernetes clusters: the root cluster named `main` and the leaf clusters + `east` and `west` specified in the `cluster_name` setting in each cluster's configuration file. +- The clusters `east` and `west` are trust the `main` root cluster certificate authority. - Users always authenticate against `main` but use their certificates to access SSH nodes and the Kubernetes API in all three clusters. - The DNS name of the main Proxy Service is `main.example.com`. @@ -44,15 +45,16 @@ $ tsh --proxy=main.example.com login east -When multiple Trusted Clusters are present behind the Teleport Proxy Service, the +When multiple trusted clusters are present behind the Teleport Proxy Service, the `kubeconfig` generated by [tsh login](../../reference/cli/tsh.mdx#tsh-login) will contain the Kubernetes API endpoint determined by the `` argument to [tsh login](../../reference/cli/tsh.mdx#tsh-login). For example, consider the following setup: -- There are two Teleport/Kubernetes clusters, `east` and `west`. These are the names set in `cluster_name` setting in their configuration files. -- The clusters `east` and `west` are Trusted Clusters for a Teleport Team or Enterprise Cloud tenant, `mytenant.teleport.sh`. +- There are two Teleport/Kubernetes clusters: `east` and `west`. + These are the names set in `cluster_name` setting in their configuration files. +- The clusters `east` and `west` are trusted clusters for a Teleport Team or Enterprise Cloud tenant, `mytenant.teleport.sh`. - Users always authenticate against `mytenant.teleport.sh` but use their certificates to access SSH nodes and the Kubernetes API in all three clusters. diff --git a/docs/pages/machine-id/faq.mdx b/docs/pages/machine-id/faq.mdx index 1cce1ea350b..9e4335b4bf5 100644 --- a/docs/pages/machine-id/faq.mdx +++ b/docs/pages/machine-id/faq.mdx @@ -20,11 +20,10 @@ runs. ## Can Machine ID be used with Trusted Clusters ? -From Teleport 12.2, Trusted Cluster support for SSH Access has been included in -Machine ID. +From Teleport 12.2, you can use Machine ID for SSH Access in trusted leaf clusters. We currently do not support access to applications, databases, or Kubernetes -clusters in Trusted Clusters configured as leaf clusters. +clusters in leaf clusters. ## Should I define allowed logins as user traits or within roles? diff --git a/docs/pages/management/admin.mdx b/docs/pages/management/admin.mdx index fb2348be856..81c3931c8ee 100644 --- a/docs/pages/management/admin.mdx +++ b/docs/pages/management/admin.mdx @@ -21,7 +21,7 @@ environment without configuring TLS certificates. ## Manage users and resources -- [Trusted Clusters](./admin/trustedclusters.mdx): Connect multiple Teleport clusters using Trusted Clusters. +- [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/operations/upgrading.mdx b/docs/pages/management/operations/upgrading.mdx index b3b9ce47387..a272d16af76 100644 --- a/docs/pages/management/operations/upgrading.mdx +++ b/docs/pages/management/operations/upgrading.mdx @@ -89,7 +89,7 @@ When upgrading multiple clusters: - Upgrade the root cluster—that is, the cluster that other clusters trust—first. - Verify the upgrade was successful. -- Upgrade the Trusted Clusters. +- Upgrade the trusted leaf clusters. @@ -102,7 +102,7 @@ When upgrading multiple clusters: - Upgrade the root cluster—that is, the cluster that other clusters trust—first. - Verify the upgrade was successful. -- Upgrade the Trusted Clusters. +- Upgrade the trusted leaf clusters. diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx index ada2a1b459a..b52277bd7bb 100644 --- a/docs/pages/reference/cli/tctl.mdx +++ b/docs/pages/reference/cli/tctl.mdx @@ -7,7 +7,7 @@ description: Comprehensive reference of subcommands, flags, and arguments for th in a cluster, including nodes, users, tokens, certificates, and devices. `tctl` can also be used to modify the dynamic configuration of the cluster, such as -creating new user roles or connecting Trusted Clusters. +creating new user roles or connecting to trusted clusters. ## Authentication diff --git a/docs/pages/server-access/guides/openssh/openssh-manual-install.mdx b/docs/pages/server-access/guides/openssh/openssh-manual-install.mdx index 47edeb479bb..2e821a2348f 100644 --- a/docs/pages/server-access/guides/openssh/openssh-manual-install.mdx +++ b/docs/pages/server-access/guides/openssh/openssh-manual-install.mdx @@ -371,7 +371,7 @@ order to make it easier to clean up, but you can append the output of Teleport implements an SSH server that includes several **subsystems**, or predefined commands that are run when the server handles a connection. The Proxy Service implements a `proxy` subsystem that forwards SSH traffic to remote hosts -and Trusted Clusters. +and trusted clusters. Here is a brief explanation of the configuration that `tsh config` generates: @@ -443,7 +443,7 @@ are using an OpenSSH client and have hosts with uppercase letters in their hostn If you switch between multiple Teleport Proxy Servers, you'll need to re-run `tsh config` for each to generate the cluster-specific configuration. - Similarly, if Trusted Clusters are added or removed, be sure to re-run + Similarly, if trusted clusters are added or removed, be sure to re-run `tsh config` and replace the previous configuration. @@ -512,10 +512,10 @@ host's SSH port. -
+
-You can log in to a host in a Trusted Cluster by placing the name of the cluster -between the name of the node and the name of your root Teleport cluster: +You can log in to a host in a trusted leaf cluster by placing the name of the cluster +between the name of the node and the name of your root cluster: ```code $ ssh -F ssh_config_teleport ${USER?}@node2.leafcluster.${CLUSTER} diff --git a/docs/pages/server-access/guides/openssh/openssh.mdx b/docs/pages/server-access/guides/openssh/openssh.mdx index a2d994d5869..2992492c2a2 100644 --- a/docs/pages/server-access/guides/openssh/openssh.mdx +++ b/docs/pages/server-access/guides/openssh/openssh.mdx @@ -185,7 +185,7 @@ order to make it easier to clean up, but you can append the output of Teleport implements an SSH server that includes several **subsystems**, or predefined commands that are run when the server handles a connection. The Proxy Service implements a `proxy` subsystem that forwards SSH traffic to remote hosts -and Trusted Clusters. +and trusted clusters. Here is a brief explanation of the configuration that `tsh config` generates: @@ -257,7 +257,7 @@ are using an OpenSSH client and have hosts with uppercase letters in their hostn If you switch between multiple Teleport Proxy Servers, you'll need to re-run `tsh config` for each to generate the cluster-specific configuration. - Similarly, if Trusted Clusters are added or removed, be sure to re-run + Similarly, if trusted clusters are added or removed, be sure to re-run `tsh config` and replace the previous configuration. @@ -326,10 +326,10 @@ host's SSH port.
-
+
-You can log in to a host in a Trusted Cluster by placing the name of the cluster -between the name of the node and the name of your root Teleport cluster: +You can log in to a host in a trusted leaf cluster by placing the name of +the leaf cluster between the name of the node and the name of the root cluster: ```code $ ssh -F ssh_config_teleport ${USER?}@node2.leafcluster.${CLUSTER} diff --git a/docs/pages/server-access/rbac.mdx b/docs/pages/server-access/rbac.mdx index 261398123fa..81bf7e056bb 100644 --- a/docs/pages/server-access/rbac.mdx +++ b/docs/pages/server-access/rbac.mdx @@ -95,8 +95,8 @@ spec: ``` The `{{internal.logins}}` variable applies to local users -and works with Teleport Trusted Clusters. Trusted Clusters allow -connecting via a root Teleport cluster to resources connected to other Teleport clusters. +and works with Teleport trusted clusters. Trusted clusters allow +connecting from a root Teleport cluster to resources connected to other Teleport clusters. Those Teleport clusters, identified as leaf clusters, allow the connection by trusting the root Teleport cluster.