Refresh the teleport-cluster Helm guide #25287

ptgott · 2023-04-27T20:23:26Z

Closes #13853

Updated the guide while testing it for v13.

The goals of this change are to:

Update the guide for v13 (these are very minor changes consisting of editing example outputs)
Simplify the guide
Make the guide easier to use

Updating the guide:

Remove the video, which is two years old.

Simplifying the guide:

Some Tabs components differ only in mentioning an Enterprise-specific namespace instead of an OSS-specific namespace. By using the same namespace for both editions, we can remove these tabs.
Add tsh as a prerequisite so we don't need to install it midway through the guide.
Remove the SSO instructions: The SSO instructions rely on following other guides to complete, so these aren't really appropriate for this step-by-step guide. The only difference the SSO instructions in this guide offer from other guides is is running tctl on the Auth Service pod via kubectl exec. Since this isn't actually necessary, we can remove these instructions.
Refactor out common instructions in the OSS/Enterprise installation tabs
Remove the command to get the Proxy Service's load balancer IP, since the get services command already shows this

Make the guide easier to use:

Add more specific Enterprise installation steps, including showing how to get the license file.
Make the DNS instructions more specific.
Add guidance in the Prerequisites for ensuring that your cluster supports Persistent Volumes.
Add a warning re: system:masters
Add Var components to code snippets so they are easier to copy/paste.

Stray edits:

Adjust line widths for easier reviews.
Recommend the local Kubenetes guide in the first Admonition, rather than the Docker Compose guide, since readers will already be interested in Kubernetes.

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

hugoShaka · 2023-04-27T20:57:33Z

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

+  <Details title="Launching a fresh EKS cluster with eksctl?" open="false">
+
+  If you are using [eksctl](https://eksctl.io/) to launch a fresh Amazon Elastic
+  Kubernetes Service cluster in order to follow this guide, the following
+  example configuration sets up the EBS CSI driver add-on. Update the cluster
+  name, version, node group size, and region as required:
+
+  ```yaml
+    apiVersion: eksctl.io/v1alpha5
+    kind: ClusterConfig
+    metadata:
+      name: my-cluster
+      region: us-east-1
+      version: "1.23"
+
+    iam:
+      withOIDC: true
+
+    addons:
+    - name: aws-ebs-csi-driver
+      version: v1.11.4-eksbuild.1
+      attachPolicyARNs:
+      - arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy
+
+    managedNodeGroups:
+      - name: managed-ng-2
+        instanceType: t3.medium
+        minSize: 2
+        maxSize: 3
+    ```
+
+  </Details>


(non-blocking)

I'm not sure putting eksctl in the hands of unsuspecting new users is good. The tool creates a lot of resources, has complex behaviour when things are going wrong. Cleaning up after eksctl is quite complex.

Do we really want to be in the business of teaching users how to deploy the EKS cluster Rube Goldberg machine?

I added this because I found it helpful when spinning up a quick demo cluster via eksctl, and didn't want users in a similar boat as me to spend as much time as I did going through the AWS docs. I get what you're saying, though. Maybe we can add a red Notice box at the top of this Details box indicating that:

This is for demo clusters only

You should already be experienced with eksctl

ptgott · 2023-04-28T21:34:08Z

@alexfornuto This should be ready for copy review

alexfornuto

Generally 👍 but with some suggestions.

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

alexfornuto · 2023-05-04T17:34:32Z

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

+<Admonition title="No cloud provider?" type="tip">
+
+Teleport also supports Kubernetes in on-premise and air-gapped environments. If
+you would like to try out Teleport on your local machine, we recommend following
+our [local Kubernetes guide](../../try-out-teleport/local-kubernetes.mdx).

-<Admonition title="Local-only setups" type="tip">
-Teleport also supports Kubernetes in on-premise and air-gapped environments. If you would like to try out Teleport on your local machine, we recommend following our [Docker Compose guide](../../try-out-teleport/docker-compose.mdx).
 </Admonition>


This admonition breaks the indent flow of the prerequisites section. I suggest moving it under the "A Kubernetest cluster..." bullet point and indenting it.

I'll remove this Admonition since we have removed the local Kubernetes guide. I'm guessing that orgs interested in Kubernetes in air-gapped environments will be sophisticated enough that removing this message will put them off Teleport.

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

alexfornuto · 2023-05-04T17:56:36Z

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

+|Record Type|Domain Name|Value|
+|---|---|---|
+|A|teleport.example.com|The IP address of your load balancer|
+|A|*.teleport.example.com|The IP address of your load balancer|
+
+</TabItem>
+<TabItem label="Domain Name">
+
+|Record Type|Domain Name|Value|
+|---|---|---|
+|CNAME|teleport.example.com|The domain name of your load balancer|
+|CNAME|*.teleport.example.com|The domain name of your load balancer|


The tables seem like a bit of overkill, since in both tabs they are either A or CNAME records and all have the same value.

I could use prose instead to make this more compact, but I'm not sure this needs to be more compact. For me, having a table makes things easier to keep track of when (for example) I'm in the Route 53 console.

docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx

Updated the guide while testing it for v13. The goals of this change are to: - Update the guide for v13 (these are very minor changes consisting of editing example outputs) - Simplify the guide - Make the guide easier to use Updating the guide: - Remove the video, which is two years old. Simplifying the guide: - Some `Tabs` components differ only in mentioning an Enterprise-specific namespace instead of an OSS-specific namespace. By using the same namespace for both editions, we can remove these tabs. - Add tsh as a prerequisite so we don't need to install it midway through the guide. - Remove the SSO instructions: The SSO instructions rely on following other guides to complete, so these aren't really appropriate for this step-by-step guide. The only difference the SSO instructions in this guide offer from other guides is is running `tctl` on the Auth Service pod via `kubectl exec`. Since this isn't actually necessary, we can remove these instructions. - Refactor out common instructions in the OSS/Enterprise installation tabs - Remove the command to get the Proxy Service's load balancer IP, since the `get services` command already shows this Make the guide easier to use: - Add more specific Enterprise installation steps, including showing how to get the license file. - Make the DNS instructions more specific. - Add guidance in the Prerequisites for ensuring that your cluster supports Persistent Volumes. - Add a warning re: `system:masters` - Add `Var` components to code snippets so they are easier to copy/paste. Stray edits: - Adjust line widths for easier reviews. - Recommend the local Kubenetes guide in the first Admonition, rather than the Docker Compose guide, since readers will already be interested in Kubernetes.

public-teleport-github-review-bot · 2023-05-11T15:28:34Z

@ptgott See the table below for backport results.

Branch	Result
branch/v13	Failed

Backports #25287 * Refresh the teleport-cluster Helm guide Updated the guide while testing it for v13. The goals of this change are to: - Update the guide for v13 (these are very minor changes consisting of editing example outputs) - Simplify the guide - Make the guide easier to use Updating the guide: - Remove the video, which is two years old. Simplifying the guide: - Some `Tabs` components differ only in mentioning an Enterprise-specific namespace instead of an OSS-specific namespace. By using the same namespace for both editions, we can remove these tabs. - Add tsh as a prerequisite so we don't need to install it midway through the guide. - Remove the SSO instructions: The SSO instructions rely on following other guides to complete, so these aren't really appropriate for this step-by-step guide. The only difference the SSO instructions in this guide offer from other guides is is running `tctl` on the Auth Service pod via `kubectl exec`. Since this isn't actually necessary, we can remove these instructions. - Refactor out common instructions in the OSS/Enterprise installation tabs - Remove the command to get the Proxy Service's load balancer IP, since the `get services` command already shows this Make the guide easier to use: - Add more specific Enterprise installation steps, including showing how to get the license file. - Make the DNS instructions more specific. - Add guidance in the Prerequisites for ensuring that your cluster supports Persistent Volumes. - Add a warning re: `system:masters` - Add `Var` components to code snippets so they are easier to copy/paste. Stray edits: - Adjust line widths for easier reviews. - Recommend the local Kubenetes guide in the first Admonition, rather than the Docker Compose guide, since readers will already be interested in Kubernetes. * Respond to hugoShaka feedback * Linter fixes * Respond to alexfornuto feedback

github-actions bot requested review from alexfornuto, r0mant, xinding33 and zmb3 April 27, 2023 20:23

github-actions bot added documentation size/sm labels Apr 27, 2023

This was referenced Apr 27, 2023

Update/improve the "kubernetes-cluster" guide #20779

Closed

Teleport 13 Test Plan #24576

Closed

hugoShaka approved these changes Apr 27, 2023

View reviewed changes

alexfornuto approved these changes May 4, 2023

View reviewed changes

alexfornuto mentioned this pull request May 4, 2023

Docs: replace DNS partial with generic instructions for kubernetes #24930

Closed

ptgott added 3 commits May 11, 2023 10:30

Respond to hugoShaka feedback

3be51d5

Linter fixes

32427d0

ptgott force-pushed the paul.gottschling/2023-04-teleport-cluster branch from 79430fc to cfbb399 Compare May 11, 2023 14:51

public-teleport-github-review-bot bot removed request for r0mant, zmb3 and xinding33 May 11, 2023 14:51

Respond to alexfornuto feedback

db4585d

ptgott force-pushed the paul.gottschling/2023-04-teleport-cluster branch from cfbb399 to db4585d Compare May 11, 2023 14:58

ptgott enabled auto-merge May 11, 2023 14:58

ptgott added the backport/branch/v13 label May 11, 2023

ptgott added this pull request to the merge queue May 11, 2023

Merged via the queue into master with commit a954bad May 11, 2023

ptgott deleted the paul.gottschling/2023-04-teleport-cluster branch May 11, 2023 15:27

alexfornuto mentioned this pull request May 11, 2023

Fix DNS instructions in the Kubernetes cluster guide #15930

Closed

ptgott mentioned this pull request May 12, 2023

[v13] Refresh the teleport-cluster Helm guide #26172

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refresh the teleport-cluster Helm guide #25287

Refresh the teleport-cluster Helm guide #25287

ptgott commented Apr 27, 2023 •

edited

Loading

hugoShaka Apr 27, 2023 •

edited

Loading

ptgott Apr 28, 2023

ptgott commented Apr 28, 2023

alexfornuto left a comment

alexfornuto May 4, 2023

ptgott May 11, 2023

alexfornuto May 4, 2023

ptgott May 11, 2023

public-teleport-github-review-bot bot commented May 11, 2023

Refresh the teleport-cluster Helm guide #25287

Refresh the teleport-cluster Helm guide #25287

Conversation

ptgott commented Apr 27, 2023 • edited Loading

hugoShaka Apr 27, 2023 • edited Loading

Choose a reason for hiding this comment

ptgott Apr 28, 2023

Choose a reason for hiding this comment

ptgott commented Apr 28, 2023

alexfornuto left a comment

Choose a reason for hiding this comment

alexfornuto May 4, 2023

Choose a reason for hiding this comment

ptgott May 11, 2023

Choose a reason for hiding this comment

alexfornuto May 4, 2023

Choose a reason for hiding this comment

ptgott May 11, 2023

Choose a reason for hiding this comment

public-teleport-github-review-bot bot commented May 11, 2023

ptgott commented Apr 27, 2023 •

edited

Loading

hugoShaka Apr 27, 2023 •

edited

Loading