Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Convert the Trusted Clusters guide to a tutorial (and edit for different scopes) #10708

Merged
merged 4 commits into from
Jun 6, 2022
Merged

Convert the Trusted Clusters guide to a tutorial (and edit for different scopes) #10708

merged 4 commits into from
Jun 6, 2022

Conversation

ptgott
Copy link
Contributor

@ptgott ptgott commented Mar 1, 2022

See #10633

  • Misc style/grammar/clarity tweaks
  • Turn the Teleport Node Tunneling Admonition into a Details
    box so it can be invisible for Cloud users. In Cloud, Nodes
    must connect via Node Tunneling.
  • Use Tabs components to add Cloud versions of CLI commands
  • Only show the static join token method for self-hosted users
    via Tabs
  • Use a Details box to show content relevant only for Enterprise
    and Cloud users
  • Remove an Admonition that was duplicated in the Troubleshooting
    section

@ptgott ptgott mentioned this pull request Mar 1, 2022
Closed
@github-actions github-actions bot requested review from r0mant, xinding33 and zmb3 March 1, 2022 21:20
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from df22110 to 6c015cc Compare March 7, 2022 22:49
@russjones russjones added the cloud Cloud label Mar 11, 2022
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from 6c015cc to 506b5f8 Compare March 14, 2022 21:16
ulysseskan
ulysseskan approved these changes Mar 16, 2022
View reviewed changes
Copy link
Contributor

@ulysseskan ulysseskan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great!

@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 2 times, most recently from df50c14 to 68236c8 Compare March 18, 2022 21:18
@russjones russjones added cloud-docs and removed cloud Cloud labels Mar 18, 2022
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 2 times, most recently from 8795dac to 9f70eed Compare March 28, 2022 19:46
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 2 times, most recently from 2a9b39c to ba32aa6 Compare April 5, 2022 19:26
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 2 times, most recently from 3166c27 to 0054cce Compare April 11, 2022 20:25
zmb3
zmb3 reviewed Apr 12, 2022
View reviewed changes
docs/pages/setup/admin/trustedclusters.mdx Outdated

## Introduction
If you have a large number of devices on different networks, such as managed
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure the criteria for using tunneling is "a large number of devices."

Technically, node tunneling consumes more resources than direct dial, so your cluster would better handle a large number of devices if you did not use tunneling.

I would recommend we reword this so that networking is the main driver for tunneling.
Something like:

If your nodes are deployed behind a firewall or otherwise not reachable by the Teleport Proxy Service, you can connect your nodes via Teleport Node Tunneling. Instead of connection to the Auth Service directly, ...

docs/pages/setup/admin/trustedclusters.mdx Outdated
## How Trusted Clusters work

Teleport can partition compute infrastructure into multiple clusters. A cluster
is a group of Teleport SSH Nodes connected to the cluster's Auth Service, which
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
is a group of Teleport SSH Nodes connected to the cluster's Auth Service, which
is a group of Teleport resources connected to the cluster's Auth Service, which

Not sure of term (resources, agents, etc), but let's be clear that a cluster is more than SSH nodes and an Auth Service.

docs/pages/setup/admin/trustedclusters.mdx Outdated
- Tries to find a local role that maps to the list of principals found in the certificate.
- Checks if the local role allows the requested identity (UNIX login) to have access.
- Checks if the local role allows the requested identity (Unix login) to have access.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: in the PRs I've reviewed today, we've used all of these interchangeably:

  • Unix login
  • OS login
  • Host login

Should we standardize on a term here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure we need to have a standard for this unless this is a Teleport-specific technical term. We use logins in user/role resource definitions, but the docs also sometimes use the term outside of that context. I'll add it to my list of possible topics to include in a style guide.

@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from 0054cce to dc417d1 Compare April 13, 2022 21:45
@ptgott ptgott requested a review from zmb3 April 13, 2022 21:45
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 2 times, most recently from 7019b0e to 451f720 Compare April 18, 2022 19:37
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 3 times, most recently from d49b6c4 to c4964c6 Compare April 26, 2022 17:12
@ptgott
Copy link
Contributor Author

ptgott commented Apr 26, 2022 •
edited
Loading

Since I need to audit this guide to complete #11841 and this PR has only received one review, I am going to use this branch to make my changes. Turning this into a draft PR until I finish this work.

@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from c4964c6 to be1cc1e Compare April 26, 2022 17:28
@ptgott ptgott marked this pull request as draft April 26, 2022 17:28
@ptgott ptgott mentioned this pull request Apr 26, 2022
Closed
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch 2 times, most recently from ed92701 to 300b93e Compare May 5, 2022 21:39
@ptgott ptgott marked this pull request as ready for review May 5, 2022 21:40
@ptgott ptgott changed the title Edit the Trusted Clusters guide for Cloud Convert the Trusted Clusters guide to a tutorial (and edit for different scopes) May 5, 2022
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from 300b93e to 4da03a4 Compare May 9, 2022 20:01
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from 4da03a4 to 782e81f Compare May 24, 2022 15:38
@ptgott ptgott enabled auto-merge (squash) June 6, 2022 14:28
ptgott added 4 commits June 6, 2022 10:28
@ptgott
Edit the Trusted Clusters guide for Cloud
6196064 
See #10633

- Misc style/grammar/clarity tweaks
- Turn the Teleport Node Tunneling Admonition into a Details
  box so it can be invisible for Cloud users. In Cloud, Nodes
  must connect via Node Tunneling.
- Use Tabs components to add Cloud versions of CLI commands
- Only show the static join token method for self-hosted users
  via Tabs
- Use a Details box to show content relevant only for Enterprise
  and Cloud users
- Remove an Admonition that was duplicated in the Troubleshooting
  section
@ptgott
Respond to PR feedback
7764318
@ptgott
Address PR feedback
9a0f543
@ptgott
Turn the Trusted Clusters guide into a tutorial
1ba5103 
See: #11841

The Trusted Clusters guide is organized as a conceptual introduction,
with configuration/command snippets used as illustrations. To make this
guide easier to follow, I have structured it as a step-by-step tutorial
where a user should be able to copy each command/config snippet on
their own environment, establish trust between clusters, and connect to
a remote Node.

Some more specific changes:

- Remove Details box re: Node Tunneling: This isn't strictly relevant
  to Trusted Clusters, so removing it shortens and simplifies what is
  quite a long guide.

- Make "How Trusted Clusters work" more concise and add the information
  to the introduction.

- Move long explanatory passages into Details boxes. Eventually, it
  would be great to split this guide into multiple guides that explain
  different topics in more depth (e.g., a section of the docs devoted
  to Trusted Clusters). For now, this is the quickest way to organize
  conceptual information without detracting from the tutorial structure.
@ptgott ptgott force-pushed the paul.gottschling/10633-setup-cloud-2 branch from 782e81f to 1ba5103 Compare June 6, 2022 14:28
@ptgott ptgott merged commit 8889781 into master Jun 6, 2022
@ptgott ptgott mentioned this pull request Jun 7, 2022
Merged
ptgott added a commit that referenced this pull request Jun 7, 2022
@ptgott
Convert the Trusted Clusters guide to a tutorial
4fa3d58 
Backports #10708

* Edit the Trusted Clusters guide for Cloud

See #10633

- Misc style/grammar/clarity tweaks
- Turn the Teleport Node Tunneling Admonition into a Details
  box so it can be invisible for Cloud users. In Cloud, Nodes
  must connect via Node Tunneling.
- Use Tabs components to add Cloud versions of CLI commands
- Only show the static join token method for self-hosted users
  via Tabs
- Use a Details box to show content relevant only for Enterprise
  and Cloud users
- Remove an Admonition that was duplicated in the Troubleshooting
  section

* Respond to PR feedback

* Address PR feedback

* Turn the Trusted Clusters guide into a tutorial

See: #11841

The Trusted Clusters guide is organized as a conceptual introduction,
with configuration/command snippets used as illustrations. To make this
guide easier to follow, I have structured it as a step-by-step tutorial
where a user should be able to copy each command/config snippet on
their own environment, establish trust between clusters, and connect to
a remote Node.

Some more specific changes:

- Remove Details box re: Node Tunneling: This isn't strictly relevant
  to Trusted Clusters, so removing it shortens and simplifies what is
  quite a long guide.

- Make "How Trusted Clusters work" more concise and add the information
  to the introduction.

- Move long explanatory passages into Details boxes. Eventually, it
  would be great to split this guide into multiple guides that explain
  different topics in more depth (e.g., a section of the docs devoted
  to Trusted Clusters). For now, this is the quickest way to organize
  conceptual information without detracting from the tutorial structure.
This was referenced Jun 7, 2022
Merged
Open
ptgott added a commit that referenced this pull request Jun 22, 2022
@ptgott
Convert the Trusted Clusters guide to a tutorial
3b44521 
Backports #10708

* Edit the Trusted Clusters guide for Cloud

See #10633

- Misc style/grammar/clarity tweaks
- Turn the Teleport Node Tunneling Admonition into a Details
  box so it can be invisible for Cloud users. In Cloud, Nodes
  must connect via Node Tunneling.
- Use Tabs components to add Cloud versions of CLI commands
- Only show the static join token method for self-hosted users
  via Tabs
- Use a Details box to show content relevant only for Enterprise
  and Cloud users
- Remove an Admonition that was duplicated in the Troubleshooting
  section

* Respond to PR feedback

* Address PR feedback

* Turn the Trusted Clusters guide into a tutorial

See: #11841

The Trusted Clusters guide is organized as a conceptual introduction,
with configuration/command snippets used as illustrations. To make this
guide easier to follow, I have structured it as a step-by-step tutorial
where a user should be able to copy each command/config snippet on
their own environment, establish trust between clusters, and connect to
a remote Node.

Some more specific changes:

- Remove Details box re: Node Tunneling: This isn't strictly relevant
  to Trusted Clusters, so removing it shortens and simplifies what is
  quite a long guide.

- Make "How Trusted Clusters work" more concise and add the information
  to the introduction.

- Move long explanatory passages into Details boxes. Eventually, it
  would be great to split this guide into multiple guides that explain
  different topics in more depth (e.g., a section of the docs devoted
  to Trusted Clusters). For now, this is the quickest way to organize
  conceptual information without detracting from the tutorial structure.
ptgott added a commit that referenced this pull request Jun 22, 2022
@ptgott
[v8] Convert the Trusted Clusters guide to a tutorial (#13251)
33cd77c 
Convert the Trusted Clusters guide to a tutorial

Backports #10708

* Edit the Trusted Clusters guide for Cloud

See #10633

- Misc style/grammar/clarity tweaks
- Turn the Teleport Node Tunneling Admonition into a Details
  box so it can be invisible for Cloud users. In Cloud, Nodes
  must connect via Node Tunneling.
- Use Tabs components to add Cloud versions of CLI commands
- Only show the static join token method for self-hosted users
  via Tabs
- Use a Details box to show content relevant only for Enterprise
  and Cloud users
- Remove an Admonition that was duplicated in the Troubleshooting
  section

* Respond to PR feedback

* Address PR feedback

* Turn the Trusted Clusters guide into a tutorial

See: #11841

The Trusted Clusters guide is organized as a conceptual introduction,
with configuration/command snippets used as illustrations. To make this
guide easier to follow, I have structured it as a step-by-step tutorial
where a user should be able to copy each command/config snippet on
their own environment, establish trust between clusters, and connect to
a remote Node.

Some more specific changes:

- Remove Details box re: Node Tunneling: This isn't strictly relevant
  to Trusted Clusters, so removing it shortens and simplifies what is
  quite a long guide.

- Make "How Trusted Clusters work" more concise and add the information
  to the introduction.

- Move long explanatory passages into Details boxes. Eventually, it
  would be great to split this guide into multiple guides that explain
  different topics in more depth (e.g., a section of the docs devoted
  to Trusted Clusters). For now, this is the quickest way to organize
  conceptual information without detracting from the tutorial structure.
ptgott added a commit that referenced this pull request Jun 22, 2022
@ptgott
Backport #10708 to branch/v9 (#13250)
9f578c8 
* Edit the Trusted Clusters guide for Cloud

See #10633

- Misc style/grammar/clarity tweaks
- Turn the Teleport Node Tunneling Admonition into a Details
  box so it can be invisible for Cloud users. In Cloud, Nodes
  must connect via Node Tunneling.
- Use Tabs components to add Cloud versions of CLI commands
- Only show the static join token method for self-hosted users
  via Tabs
- Use a Details box to show content relevant only for Enterprise
  and Cloud users
- Remove an Admonition that was duplicated in the Troubleshooting
  section

* Respond to PR feedback

* Address PR feedback

* Turn the Trusted Clusters guide into a tutorial

See: #11841

The Trusted Clusters guide is organized as a conceptual introduction,
with configuration/command snippets used as illustrations. To make this
guide easier to follow, I have structured it as a step-by-step tutorial
where a user should be able to copy each command/config snippet on
their own environment, establish trust between clusters, and connect to
a remote Node.

Some more specific changes:

- Remove Details box re: Node Tunneling: This isn't strictly relevant
  to Trusted Clusters, so removing it shortens and simplifies what is
  quite a long guide.

- Make "How Trusted Clusters work" more concise and add the information
  to the introduction.

- Move long explanatory passages into Details boxes. Eventually, it
  would be great to split this guide into multiple guides that explain
  different topics in more depth (e.g., a section of the docs devoted
  to Trusted Clusters). For now, this is the quickest way to organize
  conceptual information without detracting from the tutorial structure.
@sagesyr sagesyr mentioned this pull request Oct 5, 2022
Closed
@ptgott ptgott deleted the paul.gottschling/10633-setup-cloud-2 branch November 3, 2022 21:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ulysseskan ulysseskan ulysseskan approved these changes

@zmb3 zmb3 zmb3 approved these changes

@r0mant r0mant Awaiting requested review from r0mant

@xinding33 xinding33 Awaiting requested review from xinding33

Assignees
No one assigned
Labels
documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@ptgott @zmb3 @ulysseskan @russjones