Replace mermaid diagram, add guided instructions, remove includes wit… #33554

lsgunn-teleport · 2023-10-16T23:18:55Z

…h the get context command

I'm not a Kubernetes expert (or even a novice), so this might have a lot of errors. The main goals here are:

Replace the Mermaid diagram with one that uses the new LucidChart library.
Add guided enrollment instructions.

Remove misleading instruction: Run the following command to get the Kubernetes user for your current context:

kubectl config view \
-o jsonpath="{.contexts[?(@.name==\"$(kubectl config current-context)\")].context.user}"

See #18495

Simplify steps based on a minikube and using the UI example.

Maybe manual enrollment should be a separate topic?

…h the get context command

github-actions · 2023-10-16T23:32:35Z

🤖 Vercel preview here: https://docs-r9bxjt9s0-goteleport.vercel.app/docs/ver/preview

github-actions · 2023-10-17T17:22:08Z

🤖 Vercel preview here: https://docs-2f7dbpmt5-goteleport.vercel.app/docs/ver/preview

github-actions · 2023-10-17T17:28:24Z

🤖 Vercel preview here: https://docs-o0996fat5-goteleport.vercel.app/docs/ver/preview

zmb3 · 2023-10-17T18:01:28Z

docs/img/k8s/enroll-kubernetes.png

What is the purple "Kubernetes" box meant to indicate here?

Teleport Kubernetes Service, I assume.
https://lucid.app/lucidchart/3bf626af-1189-433f-8f33-558812766f24/edit?invitationId=inv_dc4bd6e8-1001-47a4-83a7-1ab649f21f3d&page=0_0#

docs/pages/kubernetes-access/getting-started.mdx

zmb3 · 2023-10-17T18:06:37Z

docs/pages/kubernetes-access/getting-started.mdx

+   After you click Next, Teleport generates a script to configure and enroll the 
+   Kubernetes cluster as a resource in the Teleport cluster.
+
+1. Copy the command displayed in the Teleport Web UI and run it on the server running 


Kubernetes clusters typically consist of several servers. Does this command have to be run on a Kubernetes node or can it run anywhere?

That makes sense, but I'm not really sure what a real-world scenario would be like. I ran through the steps using a single computer minikube installation.

In the minikube case, Helm would be making requests to the Kubernetes API server running on minikube, which would be running in a container or VM on your workstation. In a real-life scenario, the Kubernetes API server would be running remotely, e.g., as part of an EKS control plane.

docs/pages/kubernetes-access/getting-started.mdx

…sing.

github-actions · 2023-10-17T18:49:27Z

🤖 Vercel preview here: https://docs-lzvdovih0-goteleport.vercel.app/docs/ver/preview

docs/img/k8s/enroll-kubernetes.png

ptgott · 2023-10-17T20:39:18Z

docs/img/k8s/test-k8s-connection.png

Should the namespace we set here be one the user would understand?

I was happy to have it work, so I didn't consider editing it. I'm not sure it's hard to understand, but the default is "default" and that would be a "recognizable" namespace identifier but it didn't work for me.

ptgott · 2023-10-17T20:48:00Z

docs/pages/kubernetes-access/getting-started.mdx

+Kubernetes cluster—and information you specify, such as the Kubernetes namespace,
+users, and groups to grant access to.
+
+If you can't use the Teleport Web UI or want to run commands and edit file manually,


When would a user be unable to use the Web UI? If there aren't any situations where this would be impossible, would it make sense to use only the guided enrollment step in this guide?

Since this is a getting started guide, I think it would make sense to remove Step 1 and "Enroll Kubernetes manually", and have all readers follow Step 2. Then we can use the "Next steps" section to link the reader to the Kubernetes Discovery guides or Registering Kubernetes Clusters with Teleport for their more advanced use cases.

How does that sound?

docs/pages/kubernetes-access/getting-started.mdx

ptgott · 2023-10-17T20:54:25Z

docs/pages/kubernetes-access/getting-started.mdx

+1. Type all or part of **Kubernetes** in the Search field to filter the resource types 
+   displayed, then click **Kubernetes**.
+
+1. Copy the command to add the `teleport-agent` chart to your charts repository and paste 


Is this the teleport-kube-agent chart? https://goteleport.com/docs/reference/helm-reference/teleport-kube-agent/

From the UI, it says:

Add teleport-agent chart to your charts repository
and

Generate a command to automatically configure and install the teleport-agent namespace

I'm not sure, but I think teleport-kube-agent is an example chart, but I'm not sure it's exactly what gets added here (I'm guessing that this step adds a boilerplate to the charts repo and that your settings in the UI fill in the details, making it "different" from the teleport-kube-agent chart as defined in the reference section.)

It looks like the command shown in the source, helm install teleport-agent teleport/teleport-kube-agent, installs the teleport-kube-agent chart but names the release teleport-agent.

ptgott · 2023-10-17T20:56:06Z

docs/pages/kubernetes-access/getting-started.mdx

+   After you click Next, Teleport generates a script to configure and enroll the 
+   Kubernetes cluster as a resource in the Teleport cluster.
+
+1. Copy the command displayed in the Teleport Web UI and run it on a server in 


How does the script enroll the Kubernetes cluster? If it deploys the Teleport Kubernetes Service via the teleport-kube-agent chart, would you be running the script on your workstation instead of on a Kubernetes node?

As far as I can tell based on the original diagram, text, and my test with minikube, the assumption is that you are running this on a server that's part of the cluster. Otherwise, wouldn't it be the same as the standalone cluster with a separate Linux host?
@tigrato Can you clarify the scenario?

ptgott · 2023-10-17T20:59:50Z

@lsgunn-teleport Are we backporting this, or is it v15 behavior?

…unning commands

github-actions · 2023-10-18T22:02:05Z

🤖 Vercel preview here: https://docs-3ydjo06w9-goteleport.vercel.app/docs/ver/preview

github-actions · 2023-10-18T22:11:08Z

🤖 Vercel preview here: https://docs-k5jaw5hxa-goteleport.vercel.app/docs/ver/preview

github-actions · 2023-10-18T22:57:21Z

🤖 Vercel preview here: https://docs-poxsrb2c9-goteleport.vercel.app/docs/ver/preview

lsgunn-teleport · 2023-10-20T22:11:36Z

I find the Kubernetes setup options rather confusing:

Getting started manual instructions (are they covered by one of the other topics? it doesn't seem like it)
Kubernetes Discovery
- AWS
- Azure
- Google Cloud
Manual Cluster Registration
- Register a Cluster with Static kubeconfigs
- Register a Cluster with IAM Joining
- Register Clusters Dynamically

Might be worth revisiting the section holistically to clarify what they use cases are and how they differ.

ptgott · 2023-10-26T17:41:50Z

docs/pages/kubernetes-access/getting-started.mdx

+1. Type all or part of **Kubernetes** in the Search field to filter the resource types 
+   displayed, then click **Kubernetes**.
+
+1. Copy the command to add the `teleport-agent` chart repository and paste 


Suggested change

1. Copy the command to add the `teleport-agent` chart repository and paste

1. Copy the command to add the Teleport chart repository and paste

teleport-agent is the name of the release

public-teleport-github-review-bot · 2023-10-26T18:37:08Z

@lsgunn-teleport See the table below for backport results.

Branch	Result
branch/v14	Create PR

Replace mermaid diagram, add guided instructions, remove includes wit…

e26b10c

…h the get context command

lsgunn-teleport temporarily deployed to vercel October 16, 2023 23:19 — with GitHub Actions Inactive

github-actions bot added documentation size/md labels Oct 16, 2023

github-actions bot requested review from ptgott, r0mant, xinding33 and zmb3 October 16, 2023 23:19

lsgunn-teleport temporarily deployed to vercel October 17, 2023 17:10 — with GitHub Actions Inactive

Change strings to pass linter

2dbb5e5

lsgunn-teleport temporarily deployed to vercel October 17, 2023 17:16 — with GitHub Actions Inactive

zmb3 reviewed Oct 17, 2023

View reviewed changes

Update diagram text, collapse sign in steps, add Kubernetes where mis…

c08f702

…sing.

lsgunn-teleport temporarily deployed to vercel October 17, 2023 18:37 — with GitHub Actions Inactive

ptgott reviewed Oct 17, 2023

View reviewed changes

lsgunn-teleport added the backport/branch/v14 label Oct 18, 2023

Remove manual enrollment, add new next steps, modify wording around r…

1f75f29

…unning commands

lsgunn-teleport temporarily deployed to vercel October 18, 2023 21:53 — with GitHub Actions Inactive

Rename Getting Started to Enroll s Kubernetes Cluster

d89e815

lsgunn-teleport temporarily deployed to vercel October 18, 2023 22:01 — with GitHub Actions Inactive

Change link to registering clusters toppic

3184eee

lsgunn-teleport temporarily deployed to vercel October 18, 2023 22:47 — with GitHub Actions Inactive

lsgunn-teleport requested review from zmb3 and ptgott October 20, 2023 22:13

lsgunn-teleport added the no-changelog Indicates that a PR does not require a changelog entry label Oct 23, 2023

zmb3 approved these changes Oct 26, 2023

View reviewed changes

ptgott approved these changes Oct 26, 2023

View reviewed changes

public-teleport-github-review-bot bot removed request for r0mant and xinding33 October 26, 2023 17:43

lsgunn-teleport added this pull request to the merge queue Oct 26, 2023

Merged via the queue into master with commit b1eb339 Oct 26, 2023

lsgunn-teleport deleted the LG/k8s-getting-started branch October 26, 2023 18:35

ptgott mentioned this pull request Dec 15, 2023

[v14] Replace mermaid diagram, add guided instructions, remove includes wit… #35804

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace mermaid diagram, add guided instructions, remove includes wit… #33554

Replace mermaid diagram, add guided instructions, remove includes wit… #33554

lsgunn-teleport commented Oct 16, 2023 •

edited

Loading

github-actions bot commented Oct 16, 2023

github-actions bot commented Oct 17, 2023

github-actions bot commented Oct 17, 2023

zmb3 Oct 17, 2023

lsgunn-teleport Oct 17, 2023

zmb3 Oct 17, 2023

lsgunn-teleport Oct 17, 2023

ptgott Oct 23, 2023

github-actions bot commented Oct 17, 2023

ptgott Oct 17, 2023

lsgunn-teleport Oct 17, 2023

ptgott Oct 17, 2023

ptgott Oct 17, 2023

lsgunn-teleport Oct 18, 2023 •

edited

Loading

ptgott Oct 23, 2023

ptgott Oct 17, 2023

lsgunn-teleport Oct 18, 2023

ptgott commented Oct 17, 2023

github-actions bot commented Oct 18, 2023

github-actions bot commented Oct 18, 2023

github-actions bot commented Oct 18, 2023

lsgunn-teleport commented Oct 20, 2023

ptgott Oct 26, 2023

public-teleport-github-review-bot bot commented Oct 26, 2023

	1. Copy the command to add the `teleport-agent` chart repository and paste
	1. Copy the command to add the Teleport chart repository and paste

Replace mermaid diagram, add guided instructions, remove includes wit… #33554

Replace mermaid diagram, add guided instructions, remove includes wit… #33554

Conversation

lsgunn-teleport commented Oct 16, 2023 • edited Loading

github-actions bot commented Oct 16, 2023

github-actions bot commented Oct 17, 2023

github-actions bot commented Oct 17, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Oct 17, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lsgunn-teleport Oct 18, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ptgott commented Oct 17, 2023

github-actions bot commented Oct 18, 2023

github-actions bot commented Oct 18, 2023

github-actions bot commented Oct 18, 2023

lsgunn-teleport commented Oct 20, 2023

Choose a reason for hiding this comment

public-teleport-github-review-bot bot commented Oct 26, 2023

lsgunn-teleport commented Oct 16, 2023 •

edited

Loading

lsgunn-teleport Oct 18, 2023 •

edited

Loading