opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-09-24 16:17:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Reduce the use of capitalized trusted clusters and a few other fixes (#32432)

Browse Source 
* 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
This commit is contained in:
lsgunn-teleport
2023-10-04 19:40:44 +00:00
committed by GitHub
parent 061b5690f4
commit c33b8484e5
20 changed files with 61 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pages/access-controls/guides/ip-pinning.mdx
+1 -1
View File
@@ -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.
docs/pages/access-controls/reference.mdx
+1 -1
View File
@@ -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<br/>and logins from a root cluster. <br/><br/>For local users, Teleport will substitute this with the<br/>"allowed logins" parameter used in the<br/>`tctl users add [user] <allowed logins>` command. <br/><br/>If the role is within a leaf cluster in a [Trusted Cluster](../management/admin/trustedclusters.mdx),<br/>Teleport will substitute the logins from the root cluster<br/>whether the user is a local user or from an SSO provider. <br/><br/>As an example, if the user has the `ubuntu` login in the root<br/>cluster, then `ubuntu` will be substituted in the leaf<br/>cluster with this variable. |
| `{{internal.logins}}` | Substituted with a value stored in Teleport's local user database<br/>and logins from a root cluster. <br/><br/>For local users, Teleport will substitute this with the<br/>"allowed logins" parameter used in the<br/>`tctl users add [user] <allowed logins>` command. <br/><br/>If the role is within a leaf cluster in a [trusted cluster](../management/admin/trustedclusters.mdx),<br/>Teleport will substitute the logins from the root cluster<br/>whether the user is a local user or from an SSO provider. <br/><br/>As an example, if the user has the `ubuntu` login in the root<br/>cluster, then `ubuntu` will be substituted in the leaf<br/>cluster with this variable. |
| `{{external.xyz}}` | Substituted with a value from an external [SSO provider](https://en.wikipedia.org/wiki/Single_sign-on).<br/>If using SAML, this will be expanded with "xyz" assertion value.<br/>For OIDC, this will be expanded a value of "xyz" claim. |
Both variables above are there to deliver the same benefit: they allow Teleport
docs/pages/agents/join-services-to-your-cluster/join-token.mdx
+1 -2
View File
@@ -334,5 +334,4 @@ $ tctl tokens rm <Var name="token-to-delete"/>
## 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).
docs/pages/architecture/session-recording.mdx
+4 -4
View File
@@ -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.
<Admonition type="note">
docs/pages/architecture/tls-routing.mdx
+2 -2
View File
@@ -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.
docs/pages/connect-your-client/teleport-connect.mdx
+2 -2
View File
@@ -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.
docs/pages/connect-your-client/tsh.mdx
+4 -4
View File
@@ -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).
<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
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
docs/pages/core-concepts.mdx
+12 -12
View File
@@ -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).
docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx
+2 -2
View File
@@ -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
docs/pages/faq.mdx
+2 -3
View File
@@ -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!)
docs/pages/includes/role-spec.mdx
+1 -1
View File
@@ -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
docs/pages/kubernetes-access/manage-access.mdx
+1 -1
View File
@@ -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
docs/pages/kubernetes-access/manage-access/federation.mdx
+10 -8
View File
@@ -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.
<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
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 `<cluster>` 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
</TabItem>
<TabItem scope={["cloud","team"]} label="Cloud-Hosted">
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 `<cluster>` 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.
docs/pages/machine-id/faq.mdx
+2 -3
View File
@@ -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?
docs/pages/management/admin.mdx
+1 -1
View File
@@ -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.
docs/pages/management/operations/upgrading.mdx
+2 -2
View File
@@ -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.
</TabItem>
<TabItem scope={["cloud","team"]} label="Cloud-Hosted">
@@ -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.
</TabItem>
</Tabs>
docs/pages/reference/cli/tctl.mdx
+1 -1
View File
@@ -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
docs/pages/server-access/guides/openssh/openssh-manual-install.mdx
+5 -5
View File
@@ -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.
</Admonition>
@@ -512,10 +512,10 @@ host's SSH port.
</Details>
<Details title="Using Trusted Clusters?">
<Details title="Using trusted clusters?">
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}
docs/pages/server-access/guides/openssh/openssh.mdx
+5 -5
View File
@@ -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.
</Admonition>
@@ -326,10 +326,10 @@ host's SSH port.
</Details>
<Details title="Using Trusted Clusters?">
<Details title="Using trusted clusters?">
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}
docs/pages/server-access/rbac.mdx
+2 -2
View File
@@ -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.