Edit Helm installation instructions

Backports #11177 While addressing #10636, I noticed that the Details box that appears for Cloud users when they visit some of our Helm guides is in a slightly odd location, in the middle of a Prerequisites item. I have moved this to the top of each guide instead. I have also refactored the helm-install.mdx partial to split it into multiple partials, which allows us to use the "Step n/d" format in our Helm guides. Also adds a Cloud warning to the Digital Ocean Helm guide.
gravitational · Mar 23, 2022 · ed3e299 · ed3e299
1 parent dc41ba5
commit ed3e299
Show file tree

Hide file tree

Showing 11 changed files with 112 additions and 71 deletions.
diff --git a/docs/pages/kubernetes-access/helm/guides/aws.mdx b/docs/pages/kubernetes-access/helm/guides/aws.mdx
@@ -6,9 +6,21 @@ description: Install and configure an HA Teleport cluster using an AWS EKS clust
 In this guide, we'll go through how to set up a High Availability Teleport cluster with multiple replicas in Kubernetes
 using Teleport Helm charts and AWS products (DynamoDB and S3).
 
-(!docs/pages/kubernetes-access/helm/includes/helm-install.mdx!)
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx!)
 
-## Step 3. Set up AWS IAM configuration
+## Prerequisites
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx!)
+
+## Step 1/7. Install Helm
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-install.mdx!)
+
+## Step 2/7. Add the Teleport Helm chart repository
+
+(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
+
+## Step 3/7. Set up AWS IAM configuration
 
 For Teleport to be able to create the DynamoDB tables, indexes, and the S3 storage bucket it needs,
 you'll need to configure AWS IAM policies to allow access.
@@ -153,7 +165,7 @@ You'll need to replace these values in the policy example below:
 }
 ```
 
-## Step 4. Install and configure cert-manager
+## Step 4/7. Install and configure cert-manager
 
 Reference: [`cert-manager` docs](https://cert-manager.io/docs/)
 
@@ -216,7 +228,7 @@ $ kubectl create namespace teleport
 $ kubectl --namespace teleport create -f aws-issuer.yaml
 ```
 
-## Step 5. Set values to configure the cluster
+## Step 5/7. Set values to configure the cluster
 
 There are two different ways to configure the `teleport-cluster` Helm chart to use `aws` mode - using a `values.yaml` file, or using `--set`
 on the command line.
@@ -300,7 +312,7 @@ $ kubectl --namespace teleport get all
 # replicaset.apps/teleport-5cf46ddf5f   2         2         2       4m21s
 ```
 
-## Step 6. Set up DNS
+## Step 6/7. Set up DNS
 
 You'll need to set up a DNS `A` record for `teleport.example.com`. In our example, this record is an alias to an ELB.
 
@@ -368,7 +380,7 @@ $ aws route53 get-change --id "${CHANGEID?}" | jq '.ChangeInfo.Status'
 # "INSYNC"
 ```
 
-## Step 7. Create a Teleport user
+## Step 7/7. Create a Teleport user
 
 Create a user to be able to log into Teleport. This needs to be done on the Teleport auth server,
 so we can run the command using `kubectl`:

diff --git a/docs/pages/kubernetes-access/helm/guides/custom.mdx b/docs/pages/kubernetes-access/helm/guides/custom.mdx
@@ -9,9 +9,21 @@ config file using Teleport Helm charts.
 This setup can be useful when you already have an existing Teleport cluster and would like to start running it in Kubernetes, or when
 migrating your setup from a legacy version of the Helm charts.
 
-(!docs/pages/kubernetes-access/helm/includes/helm-install.mdx!)
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx!)
 
-## Step 3. Setting up a Teleport cluster with Helm using a custom config
+## Prerequisites
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx!)
+
+## Step 1/4. Install Helm
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-install.mdx!)
+
+## Step 2/4. Add the Teleport Helm chart repository
+
+(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
+
+## Step 3/4. Setting up a Teleport cluster with Helm using a custom config
 
 In `custom` mode, the `teleport-cluster` Helm chart does not create a `ConfigMap` containing a `teleport.yaml` file for you, but
 expects that you will provide this yourself.
@@ -130,7 +142,7 @@ $ kubectl --namespace teleport get all
 # replicaset.apps/teleport-5c56b4d869   1         1         1       5h8m
 ```
 
-## Step 4. Create a Teleport user (optional)
+## Step 4/4. Create a Teleport user (optional)
 
 If you're not migrating an existing Teleport cluster, you'll need to create a user to be able to log into Teleport. This needs to be done on the
 Teleport auth server, so we can run the command using `kubectl`:

diff --git a/docs/pages/kubernetes-access/helm/guides/digitalocean.mdx b/docs/pages/kubernetes-access/helm/guides/digitalocean.mdx
@@ -5,6 +5,8 @@ description: How to get started with Teleport on DigitalOcean Kubernetes
 
 This guide will show you how to get started with Teleport on DigitalOcean Kubernetes. 
 
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx!)
+
 ## Prerequisites
 - DigitalOcean account.
 - Your workstation configured with [kubectl](https://kubernetes.io/docs/tasks/tools/), [Helm](https://helm.sh/docs/intro/install/), [doctl](https://docs.digitalocean.com/reference/doctl/how-to/install/), and the Teleport [tsh](https://goteleport.com/docs/installation/) client.

diff --git a/docs/pages/kubernetes-access/helm/guides/gcp.mdx b/docs/pages/kubernetes-access/helm/guides/gcp.mdx
@@ -6,7 +6,19 @@ description: Install and configure an HA Teleport cluster using a Google Cloud G
 In this guide, we'll go through how to set up a High Availability Teleport cluster with multiple replicas in Kubernetes
 using Teleport Helm charts and Google Cloud Platform products (Firestore and Google Cloud Storage).
 
-(!docs/pages/kubernetes-access/helm/includes/helm-install.mdx!)
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx!)
+
+## Prerequisites
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx!)
+
+## Step 1/7. Install Helm
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-install.mdx!)
+
+## Step 2/7. Add the Teleport Helm chart repository
+
+(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
 
 <Admonition
   type="note"
@@ -15,7 +27,7 @@ using Teleport Helm charts and Google Cloud Platform products (Firestore and Goo
   The steps below apply to Google Cloud Google Kubernetes Engine (GKE) Standard deployments.
 </Admonition>
 
-## Step 3: Google Cloud IAM configuration
+## Step 3/7. Google Cloud IAM configuration
 
 For Teleport to be able to create the Firestore collections, indexes, and the Google Cloud Storage bucket it needs,
 you'll need to configure a Google Cloud service account with permissions to use these services.
@@ -187,7 +199,7 @@ $ kubectl --namespace teleport create secret generic teleport-gcp-credentials --
  The credentials file stored in any secret used must have the key name `gcp-credentials.json`.
 </Admonition>
 
-## Step 4: Install and configure cert-manager
+## Step 4/7. Install and configure cert-manager
 
 Reference the [cert-manager docs](https://cert-manager.io/docs/).
 
@@ -255,7 +267,7 @@ After you have created the `Issuer` and updated the values, add it to your clust
 $ kubectl --namespace teleport create -f gcp-issuer.yaml
 ```
 
-## Step 5: Set values to configure the cluster
+## Step 5/7. Set values to configure the cluster
 
 <Admonition type="note">
   If you are installing Teleport in a brand new GCP project, make sure you have enabled the
@@ -344,7 +356,7 @@ $ kubectl --namespace teleport get all
 # replicaset.apps/teleport-b64dd8849    2         2         2       7m16s
 ```
 
-## Step 6. Set up DNS
+## Step 6/7. Set up DNS
 
 You'll need to set up a DNS `A` record for `teleport.example.com`.
 
@@ -370,7 +382,7 @@ $ gcloud dns record-sets transaction describe --zone="${MYZONE?}"
 $ gcloud dns record-sets transaction execute --zone="${MYZONE?}"
 ```
 
-## Step 7. Create a Teleport user
+## Step 7/7. Create a Teleport user
 
 Create a user to be able to log into Teleport. This needs to be done on the Teleport auth server,
 so we can run the command using `kubectl`:

diff --git a/docs/pages/kubernetes-access/helm/guides/migration.mdx b/docs/pages/kubernetes-access/helm/guides/migration.mdx
@@ -13,9 +13,21 @@ to use the newer `teleport-cluster` Helm chart instead.
   consider [following a different guide](../guides.mdx) and storing your cluster's data in AWS DynamoDB or Google Cloud Firestore.
 </Admonition>
 
-(!docs/pages/kubernetes-access/helm/includes/helm-install.mdx!)
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx!)
 
-## Step 3. Get the Teleport configuration file from your existing cluster
+## Prerequisites
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx!)
+
+## Step 1/6. Install Helm
+
+(!docs/pages/kubernetes-access/helm/includes/teleport-cluster-install.mdx!)
+
+## Step 2/6. Add the Teleport Helm chart repository
+
+(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
+
+## Step 3/6. Get the Teleport configuration file from your existing cluster
 
 <Admonition type="tip" title="Teleport storage in AWS or GCP">
   If your Teleport cluster's database is currently stored in AWS DynamoDB or Google Cloud Firestore rather than
@@ -81,7 +93,7 @@ $ kubectl --namespace teleport-cluster create configmap teleport --from-file=tel
 # configmap/teleport created
 ```
 
-## Step 4. Extracting the contents of Teleport's database
+## Step 4/6. Extracting the contents of Teleport's database
 
 <Admonition type="note" title="Note on namespacing">
   If you migrate your existing data, the `cluster_name` which is configured in `teleport.yaml` must stay the same.
@@ -112,7 +124,7 @@ Add the backup to your new `teleport-cluster` namespace as a secret:
 $ kubectl --namespace teleport-cluster create secret generic bootstrap --from-file=backup.yaml
 ```
 
-## Step 5. Start the new cluster with your old config file and backup
+## Step 5/6. Start the new cluster with your old config file and backup
 
 We will start the new cluster and bootstrap it using the backup of your cluster's data. Once this step is complete and the cluster is working,
 we'll modify the deployment to remove references to the backup data, and remove it from Kubernetes for security.
@@ -185,7 +197,7 @@ $ kubectl --namespace teleport-cluster get all
   browser to view the page successfully.
 </Admonition>
 
-## Step 6. Remove the bootstrap data and update the chart deployment
+## Step 6/6. Remove the bootstrap data and update the chart deployment
 
 Once you've tested your new Teleport cluster and you're confident that your data has been migrated successfully,
 you should redeploy the chart without your backup data mounted for security.

diff --git a/docs/pages/kubernetes-access/helm/includes/helm-install.mdx b/docs/pages/kubernetes-access/helm/includes/helm-install.mdx
diff --git a/docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx b/docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx
@@ -0,0 +1,11 @@
+To allow Helm to install charts that are hosted in the Teleport Helm repository, use `helm repo add`:
+
+```code
+$ helm repo add teleport (=teleport.helm_repo_url=)
+```
+
+To update the cache of charts from the remote repository, run `helm repo update`:
+
+```code
+$ helm repo update
+```
diff --git a/docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx b/docs/pages/kubernetes-access/helm/includes/teleport-cluster-cloud-warning.mdx
@@ -0,0 +1,10 @@
+<Details scopeOnly={true} scope={["cloud"]} title="Teleport Cloud warning">
+This guide shows you how to install the `teleport-cluster` Helm chart, which is intended to help you get started with Teleport by deploying the Auth Service and 
+Proxy Service in a Kubernetes cluster so you can access that cluster via the Kubernetes Service.
+
+Since the Auth and Proxy Services are fully managed in Teleport Cloud, you should install our `teleport-kube-agent` chart, which is intended for deployments where the Auth Service and Proxy Service run outside your Kubernetes cluster.
+
+You can use the `teleport-kube-agent` chart to enable the Application Service and Database Service in addition to the Kubernetes Service.
+
+For more information, see our [Helm chart reference](../reference.mdx#teleport-kube-agent).
+</Details>
diff --git a/docs/pages/kubernetes-access/helm/includes/teleport-cluster-install.mdx b/docs/pages/kubernetes-access/helm/includes/teleport-cluster-install.mdx
@@ -0,0 +1,12 @@
+Teleport's charts require the use of Helm version 3. You can [install Helm 3 by following these instructions](https://helm.sh/docs/intro/install/).
+
+Throughout this guide, we will assume that you have the `helm` and `kubectl` binaries available in your `PATH`:
+
+```code
+$ helm version
+# version.BuildInfo{Version:"v(=helm.version=)"}
+
+$ kubectl version
+# Client Version: version.Info{Major:"(=kubernetes.major_version=)", Minor:"(=kubernetes.minor_version=)+"}
+# Server Version: version.Info{Major:"(=kubernetes.major_version=)", Minor:"(=kubernetes.minor_version=)+"}
+```
diff --git a/docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx b/docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx
@@ -0,0 +1,6 @@
+- [Kubernetes](https://kubernetes.io) >= v(=kubernetes.major_version=).(=kubernetes.minor_version=).0
+- [Helm](https://helm.sh) >= v(=helm.version=)
+
+Verify that Helm and Kubernetes are installed and up to date.
+
+(!docs/pages/includes/permission-warning.mdx!)
diff --git a/docs/pages/kubernetes-access/helm/reference.mdx b/docs/pages/kubernetes-access/helm/reference.mdx
@@ -539,7 +539,7 @@ cluster deployed in HA mode.
   You must install and configure `cert-manager` in your Kubernetes cluster yourself.
 
   See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/kubernetes/#option-2-install-crds-as-part-of-the-helm-release)
-  and the relevant sections of the [AWS](./guides/aws.mdx#step-4-install-and-configure-cert-manager) and [GCP](./guides/gcp.mdx#step-4-install-and-configure-cert-manager) guides for more information.
+  and the relevant sections of the [AWS](./guides/aws.mdx#step-47-install-and-configure-cert-manager) and [GCP](./guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information.
 </Admonition>
 
 ### `highAvailability.certManager.addCommonName`
@@ -554,7 +554,7 @@ Setting `highAvailability.certManager.addCommonName` to `true` will instruct `ce
   You must install and configure `cert-manager` in your Kubernetes cluster yourself.
 
   See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/kubernetes/#option-2-install-crds-as-part-of-the-helm-release)
-  and the relevant sections of the [AWS](./guides/aws.mdx#step-4-install-and-configure-cert-manager) and [GCP](./guides/gcp.mdx#step-4-install-and-configure-cert-manager) guides for more information.
+  and the relevant sections of the [AWS](./guides/aws.mdx#step-47-install-and-configure-cert-manager) and [GCP](./guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information.
 </Admonition>
 
 <Tabs>
@@ -588,7 +588,7 @@ Sets the name of the `cert-manager` `Issuer` or `ClusterIssuer` to use for issui
   You must install configure an appropriate `Issuer` supporting a DNS01 challenge yourself.
 
   Please see the [cert-manager DNS01 docs](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers) and the relevant sections
-  of the [AWS](./guides/aws.mdx#step-4-install-and-configure-cert-manager) and [GCP](./guides/gcp.mdx#step-4-install-and-configure-cert-manager) guides for more information.
+  of the [AWS](./guides/aws.mdx#step-47-install-and-configure-cert-manager) and [GCP](./guides/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information.
 </Admonition>
 
 <Tabs>