Edit four Kubernetes Access guides for Cloud users

See #10636 Introduction - Remove unnecessary mention of Access Requests in a paragraph that is otherwise relevant for all editions. - Minor style/grammar tweaks Standalone Teleport - Add tabbed instructions for different scopes where applicable. - Minor style/grammar tweaks Connect Kubernetes Cluster to Teleport - Use Tabbed instructions and a Notice box so users with one scope do not see instructions for other scopes. - Remove irrelevant details that are specific to self-hosted deployments. Federation - Add a Tabs component to separate instructions for Cloud and Self- Hosted users - Minor style tweaks Multiple Clusters - Add tabbed instructions for Cloud/Self-Hosted users.
gravitational · Mar 16, 2022 · 629efa1 · 629efa1
1 parent 23b0d65
commit 629efa1
Show file tree

Hide file tree

Showing 7 changed files with 377 additions and 59 deletions.
diff --git a/docs/pages/includes/helm.mdx b/docs/pages/includes/helm.mdx
@@ -1,4 +1,4 @@
-Verify that helm and kubernetes are installed and up to date.
+Verify that Helm and Kubernetes are installed and up to date.
 
 ```code
 $ helm version

diff --git a/docs/pages/includes/kubernetes-access/helm-k8s.mdx b/docs/pages/includes/kubernetes-access/helm-k8s.mdx
@@ -1,7 +1,7 @@
 - [Kubernetes](https://kubernetes.io) >= v(=kubernetes.major_version=).(=kubernetes.minor_version=).0
 - [Helm](https://helm.sh) >= (=helm.version=)
 
-Verify that helm and kubernetes are installed and up to date.
+Verify that helm and Kubernetes are installed and up to date.
 
 ```code
 $ helm version

diff --git a/docs/pages/kubernetes-access/getting-started/agent.mdx b/docs/pages/kubernetes-access/getting-started/agent.mdx
@@ -3,67 +3,145 @@ title: Connect a Kubernetes Cluster to Teleport
 description: Connecting a Kubernetes cluster to Teleport
 ---
 
-<Admonition type="notice" title="Editions">
-You can use this guide with Teleport Open Source, Teleport Enterprise, and Teleport Cloud.
-</Admonition>
-
 ## Prerequisites
 
-- Installed and running Teleport cluster, self-hosted or cloud-hosted.
-- Tool `jq` to process `JSON` output.
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+- A running Teleport cluster. For details on how to set this up, see one of our
+  [Getting Started](../../getting-started.mdx) guides. 
+
+- The `jq` tool to process `JSON` output. This is available via common package managers.
+
+- The `tctl` admin tool version >= (=teleport.version=).
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+  See [Installation](../../installation.mdx) for details.
+
+  (!docs/pages/includes/tctl.mdx!)
+
+</TabItem>
+<TabItem
+  scope={["enterprise"]} label="Enterprise">
+
+- A running Teleport cluster. For details on how to set this up, see one of our
+  [Getting Started](../../getting-started.mdx) guides.
+
+- The `jq` tool to process `JSON` output. This is available via common package managers.
+
+- The `tctl` admin tool version >= (=teleport.version=), which you can download
+  by visiting the
+  [customer portal](https://dashboard.gravitational.com/web/login).
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+  (!docs/pages/includes/tctl.mdx!)
+
+</TabItem>
+<TabItem scope={["cloud"]}
+  label="Teleport Cloud">
+
+- A Teleport Cloud account. If you do not have one, visit the
+  [sign up page](https://goteleport.com/signup/) to begin your free trial.
+
+- The `jq` tool to process `JSON` output. This is available via common package
+  managers.
+
+- The Enterprise version of the `tctl` admin tool. To download this, visit
+the [customer portal](https://dashboard.gravitational.com/web/login).
+
+  ```code
+  $ tctl version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
+  ```
+
+  (!docs/pages/includes/tctl.mdx!)
+
+</TabItem>
+</Tabs>
 
 
 (!docs/pages/includes/kubernetes-access/helm-k8s.mdx!)
 
 (!docs/pages/includes/tctl.mdx!)
 
-<Admonition type="notice" title="Enable Kubernetes for Self-Hosted">
-For self-hosted Teleport instances the `kube_listen_addr` setting in the `proxy_service` is required to enable Kubernetes Access.  This is already enabled for Cloud and the Teleport `teleport-cluster` helm chart.
-```yaml
-proxy_service:
-  # ...
-  public_addr: proxy.example.com:3080
+## Deployment overview
 
-  kube_listen_addr: 0.0.0.0:3026  
-  ```  
-</Admonition>
+In this guide, we deploy the Teleport Kubernetes Service, which connects
+Kubernetes cluster `cookie` to Teleport cluster `tele.example.com`:
 
-## Deployment overview
+<Notice type="tip" scope={["cloud"]}>
 
-In this guide, we deploy a Teleport agent that connects kubernetes cluster `cookie` to
-Teleport cluster `tele.example.com`:
+In your Teleport Cloud account, the name of your cluster will be your tenant
+domain name, e.g., `mytenant.teleport.sh`, rather than `teleport.example.com`.
+
+</Notice>
 
 <Figure align="left" bordered caption="Kubernetes agent dialing back to Teleport cluster">
   ![Kubernetes agent](../../../img/k8s/agent.svg)
 </Figure>
 
 ## Step 1/2. Get a join token
 
-Start a lightweight agent in your Kubernetes cluster `cookie` and connect it to `tele.example.com`.
-We would need a join token from `tele.example.com`:
+In order to start the Teleport Kubernetes Service, we will need to request a
+join token from the Teleport Auth Service:
 
 ```code
-# Create a join token for the cluster cookie to authenticate
+# Create a join token for the Teleport Kubernetes Service to authenticate
 $ TOKEN=$(tctl nodes add --roles=kube --ttl=10000h --format=json | jq -r '.[0]')
 $ echo $TOKEN
 ```
 
 ## Step 2/2. Deploy teleport-kube-agent
 
-Switch `kubectl` to the Kubernetes cluster `cookie` and run:
+
+<Tabs>
+<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+
+Switch `kubectl` to the Kubernetes cluster `cookie` and run the following
+commands, assigning `PROXY_ADDR` to the address of your Auth Service or Proxy
+Service.
+
+```code
+# Add teleport-agent chart to charts repository
+$ PROXY_ADDR=tele.example.com:443
+$ helm repo add teleport https://charts.releases.teleport.dev
+$ helm repo update
+
+# Install Kubernetes agent. It dials back to the Teleport cluster at $PROXY_ADDR
+$ CLUSTER='cookie'
+$ helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \
+  --set proxyAddr=${PROXY_ADDR?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent
+```
+
+</TabItem>
+<TabItem scope={["cloud"]} label="Teleport Cloud">
+
+Switch `kubectl` to the Kubernetes cluster `cookie` and run the following
+commands, assigning `PROXY_ADDR` to the address of your Teleport Cloud tenant.
 
 ```code
 # Add teleport-agent chart to charts repository
+$ PROXY_ADDR=mytenant.teleport.sh
 $ helm repo add teleport https://charts.releases.teleport.dev
 $ helm repo update
 
-# Install Kubernetes agent. It dials back to the Teleport cluster tele.example.com.
+# Install Kubernetes agent. It dials back to the Teleport cluster at $PROXY_ADDR
 $ CLUSTER='cookie'
-$ PROXY='tele.example.com:443 - replace me with your cluster'
 $ helm install teleport-agent teleport/teleport-kube-agent --set kubeClusterName=${CLUSTER?} \
-  --set proxyAddr=${PROXY?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent
+  --set proxyAddr=${PROXY_ADDR?} --set authToken=${TOKEN?} --create-namespace --namespace=teleport-agent
 ```
 
+</TabItem>
+</Tabs>
+
 List connected clusters using `tsh kube ls` and switch between
 them using `tsh kube login`:
 
@@ -78,7 +156,7 @@ $ tsh kube ls
 $ tsh kube login cookie
 # Logged into kubernetes cluster "cookie"
 
-# kubectl command executed on `cookie` but is routed through `tele.example.com` cluster.
+# kubectl command executed on `cookie` but is routed through the Teleport cluster.
 $ kubectl get pods
 ```
 

diff --git a/docs/pages/kubernetes-access/guides/federation.mdx b/docs/pages/kubernetes-access/guides/federation.mdx
@@ -1,28 +1,29 @@
 ---
-title: Teleport Kubernetes Access and Trusted Clusters
+title: Federated Kubernetes access with Trusted Clusters
 description: Federated Access using Teleport Trusted Clusters.
 ---
 
-## Federated Kubernetes access with 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](../../setup/admin/trustedclusters.mdx)
 to federate trust across Kubernetes clusters.
 
-When multiple trusted clusters are present behind a Teleport proxy, the
+<Tabs>
+<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+
+When multiple Trusted Clusters are present behind the Teleport Proxy Service, the
 `kubeconfig` generated by [tsh login](../../setup/reference/cli.mdx#tsh-login) will contain the
 Kubernetes API endpoint determined by the `<cluster>` argument to [tsh
 login](../../setup/reference/cli.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`.
+- The clusters `east` and `west` are Trusted Clusters for `main`.
 - Users always authenticate against `main` but use their certificates to access
-  SSH nodes and Kubernetes API in all three clusters.
-- The DNS name of the main proxy server is `main.example.com`
+  SSH nodes and the Kubernetes API in all three clusters.
+- The DNS name of the main Proxy Service is `main.example.com`.
 
 In this scenario, users usually log in using this command:
 
@@ -39,3 +40,37 @@ $ tsh --proxy=main.example.com login east
 # User's `kubeconfig` now contains the entry for the "east" Kubernetes
 # endpoint, i.e. `east.main.example.com`.
 ```
+
+</TabItem>
+<TabItem scope={["cloud"]} label="Teleport Cloud">
+
+When multiple Trusted Clusters are present behind the Teleport Proxy Service, the
+`kubeconfig` generated by [tsh login](../../setup/reference/cli.mdx#tsh-login) will contain the
+Kubernetes API endpoint determined by the `<cluster>` argument to [tsh
+login](../../setup/reference/cli.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 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.
+
+In this scenario, users usually log in using this command:
+
+```code
+# Using login without arguments
+$ tsh --proxy=mytenant.teleport.sh login
+
+# User's `kubeconfig` now contains one entry for the main Kubernetes
+# endpoint, i.e. `mytenant.teleport.sh`.
+
+# Receive a certificate for "east":
+$ tsh --proxy=mytenant.teleport.sh login east
+
+# User's `kubeconfig` now contains the entry for the "east" Kubernetes
+# endpoint, i.e. `east.mytenant.teleport.sh`.
+```
+
+</TabItem>
+</Tabs>