General Updates and Refactors to Helm Docs (#21656)

* update helm docs Signed-off-by: Evan Freed <evan.freed@goteleport.com> * fix links Signed-off-by: Evan Freed <evan.freed@goteleport.com> --------- Signed-off-by: Evan Freed <evan.freed@goteleport.com>
gravitational · Jun 20, 2023 · e1c1d2e · e1c1d2e
1 parent 817b9a6
commit e1c1d2e
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 37 deletions.
diff --git a/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx b/docs/pages/deploy-a-cluster/helm-deployments/aws.mdx
@@ -3,8 +3,7 @@ title: Running an HA Teleport cluster using AWS, EKS, and Helm
 description: Install and configure an HA Teleport cluster using an AWS EKS cluster
 ---
 
-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).
+In this guide, we'll use Teleport Helm charts to set up a high-availability Teleport cluster that runs on AWS EKS.
 
 <Admonition type="tip" title="Have an existing Teleport cluster?">
 If you are already running Teleport on another platform, you can use your
@@ -19,23 +18,18 @@ cluster to Teleport.
 
 (!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
+## Step 1/6. Add the Teleport Helm chart repository
 
 (!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
 
-## Step 3/7. Set up AWS IAM configuration
+## Step 2/6. Set up AWS IAM configuration
 
 For Teleport to be able to manage the DynamoDB tables, indexes, and the S3
 storage bucket it needs, you'll need to configure AWS IAM policies to allow
 access.
 
 <Admonition type="note">
-  These IAM policies should be added to your AWS account, then granted to the instance role associated with the
-  EKS nodegroups which are running your Kubernetes nodes.
+  Add these IAM policies to your AWS account and then grant it to the role associated with your EKS node group(s).
 </Admonition>
 
 ### DynamoDB IAM policy
@@ -46,7 +40,7 @@ access.
 
 (!docs/pages/includes/s3-iam-policy.mdx!)
 
-## Step 4/7. Configure TLS certificates for Teleport
+## Step 3/6. Configure TLS certificates for Teleport
 
 The `teleport-cluster` chart deploys a Kubernetes `LoadBalancer` to handle incoming connections to the Teleport Proxy Service.
 
@@ -261,7 +255,7 @@ Edit your `values.yaml` file to refer to the name of your secret:
 </TabItem>
 </Tabs>
 
-## Step 5/7. Set values to configure the cluster
+## Step 4/6. Set values to configure the cluster
 
 <ScopedBlock scope="enterprise">
 
@@ -430,7 +424,7 @@ replicaset.apps/teleport-auth-57989d4cbd   2         2         2       22h
 replicaset.apps/teleport-proxy-c6bf55cfc   2         2         2       22h
 ```
 
-## Step 6/7. Set up DNS
+## Step 5/6. 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.
 
@@ -498,7 +492,7 @@ $ aws route53 get-change --id "${CHANGEID?}" | jq '.ChangeInfo.Status'
 # "INSYNC"
 ```
 
-## Step 7/7. Create a Teleport user
+## Step 6/6. 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`:
@@ -621,4 +615,4 @@ users and setting up RBAC.
 
 See the [high availability section of our Helm chart reference](../../reference/helm-reference/teleport-cluster.mdx#highavailability) for more details on high availability.
 
-Read the [`cert-manager` documentation](https://cert-manager.io/docs/).
+Read the [`cert-manager` documentation](https://cert-manager.io/docs/).
diff --git a/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx b/docs/pages/deploy-a-cluster/helm-deployments/custom.mdx
@@ -28,15 +28,11 @@ of this page to choose the correct version.
 
 (!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
+## Step 1/3. 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
+## Step 2/3. Setting up a Teleport cluster with Helm using a custom config
 
 `teleport-cluster` deploys two sets of pods: one for the Proxy Service and one for the Auth Service. You can provide two configurations, one for each pod type.
 
@@ -208,7 +204,7 @@ replicaset.apps/teleport-auth-57989d4cbd   1         1         1       22h
 replicaset.apps/teleport-proxy-c6bf55cfc   2         2         2       22h
 ```
 
-## Step 4/4. Create a Teleport user (optional)
+## Step 3/3. 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

diff --git a/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx b/docs/pages/deploy-a-cluster/helm-deployments/gcp.mdx
@@ -17,11 +17,7 @@ cluster to Teleport.
 
 (!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
+## Step 1/6. Add the Teleport Helm chart repository
 
 (!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
 
@@ -32,7 +28,7 @@ cluster to Teleport.
   The steps below apply to Google Cloud Google Kubernetes Engine (GKE) Standard deployments.
 </Admonition>
 
-## Step 3/7. Google Cloud IAM configuration
+## Step 2/6. 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.
@@ -207,7 +203,7 @@ secret/teleport-gcp-credentials created
  The credentials file stored in any secret used must have the key name `gcp-credentials.json`.
 </Admonition>
 
-## Step 4/7. Install and configure cert-manager
+## Step 3/6. Install and configure cert-manager
 
 Reference the [cert-manager docs](https://cert-manager.io/docs/).
 
@@ -275,7 +271,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/7. Set values to configure the cluster
+## Step 4/6. Set values to configure the cluster
 
 <Details title="License Secret" scopeOnly={false} scope={"enterprise"} opened={true}>
 
@@ -388,7 +384,7 @@ replicaset.apps/teleport-auth-57989d4cbd   2         2         2       22h
 replicaset.apps/teleport-proxy-c6bf55cfc   2         2         2       22h
 ```
 
-## Step 6/7. Set up DNS
+## Step 5/6. Set up DNS
 
 You'll need to set up a DNS `A` record for `teleport.example.com`.
 
@@ -414,7 +410,7 @@ $ gcloud dns record-sets transaction describe --zone="${MYZONE?}"
 $ gcloud dns record-sets transaction execute --zone="${MYZONE?}"
 ```
 
-## Step 7/7. Create a Teleport user
+## Step 6/6. 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/includes/teleport-cluster-prereqs.mdx b/docs/pages/kubernetes-access/helm/includes/teleport-cluster-prereqs.mdx
@@ -1,6 +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/kubernetes-access/helm/includes/teleport-cluster-install.mdx!)
 
-(!docs/pages/includes/permission-warning.mdx!)
+(!docs/pages/includes/permission-warning.mdx!)
diff --git a/docs/pages/reference/helm-reference/teleport-cluster.mdx b/docs/pages/reference/helm-reference/teleport-cluster.mdx
@@ -996,7 +996,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](../../deploy-a-cluster/helm-deployments/aws.mdx#step-47-configure-tls-certificates-for-teleport) and [GCP](../../deploy-a-cluster/helm-deployments/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information.
+  and the relevant sections of the [AWS](../../deploy-a-cluster/helm-deployments/aws.mdx#step-36-configure-tls-certificates-for-teleport) and [GCP](../../deploy-a-cluster/helm-deployments/gcp.mdx#step-36-install-and-configure-cert-manager) guides for more information.
 </Admonition>
 
 ### `highAvailability.certManager.addCommonName`
@@ -1011,7 +1011,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](../../deploy-a-cluster/helm-deployments/aws.mdx#step-47-configure-tls-certificates-for-teleport) and [GCP](../../deploy-a-cluster/helm-deployments/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information.
+  and the relevant sections of the [AWS](../../deploy-a-cluster/helm-deployments/aws.mdx#step-36-configure-tls-certificates-for-teleport) and [GCP](../../deploy-a-cluster/helm-deployments/gcp.mdx#step-36-install-and-configure-cert-manager) guides for more information.
 </Admonition>
 
 `values.yaml` example:
@@ -1036,7 +1036,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](../../deploy-a-cluster/helm-deployments/aws.mdx#step-47-configure-tls-certificates-for-teleport) and [GCP](../../deploy-a-cluster/helm-deployments/gcp.mdx#step-47-install-and-configure-cert-manager) guides for more information.
+  of the [AWS](../../deploy-a-cluster/helm-deployments/aws.mdx#step-36-configure-tls-certificates-for-teleport) and [GCP](../../deploy-a-cluster/helm-deployments/gcp.mdx#step-36-install-and-configure-cert-manager) guides for more information.
 </Admonition>
 
 `values.yaml` example: