* Make the Labeling guide easier to follow
See #11841
The current guide is a conceptual introduction to Teleport's labeling
functionality. Since we cover this information in our reference guides,
I wanted to make it possible for readers to follow this guide as a
tutorial and get started labeling resources quickly.
- Introduce labels at the beginning of the guide to set the stage
conceptually before the steps begin.
- Clarify in the Prerequisites section that the instructions in the
guide apply to any Teleport resource, not just Nodes
- Require a host for running a Teleport Node in the Prerequisites and
include instructions for starting the Node. Previously, we included
sample commands/config for applications as well. Requiring a Node
and including setup instructions for that Node will ensure that all
instructions in the guide can be followed easily.
- Add scoped instructions via Tabs and ScopedBlocks.
- Reorganize sections into a series of steps.
- Add commands to verify that labels have been added.
* Respond to PR feedback
* Improve the Labeling guide for self-hosted users
See: #11841
- Edit tctl.mdx: Users of self-hosted Teleport can run tctl commands
from their local machines after logging in to a cluster, just like
they can with Teleport Cloud. I have edited tctl.mdx to instruct self-
hosted users to use tctl remotely. This way, users won't need to
access their Auth Service hosts in order to follow the guides that
use tctl.mdx.
- Add steps for fixing unexpected "tsh ls" output
Also applies PR feedback.
- Add provisions for labeling specific resources as a table near the
top of the page.
- Remove the option to add labels using CLI flags.
- Fix command output spacing
Also misc. clarity tweaks.
* Respond to PR feedback
* Clarify two guides and two intro pages
See #11841
Make the Adding Nodes guide more usable for Cloud
- Add a ca_pin preset
- Clarify that tctl must be run on the local machine for Cloud users
- Structure the guide as a step-by-step tutorial. The guide already
included sequences of sample commands, so all this took was to rename
headings according to the "Step n/d." format and move the CA pinning
section into the section on starting the Node.
- Add environment variables to use for storing a CA pin and invite
token to sample commands, plus piped commands to extract these
strings from the output of tctl commands.
- Use a ScopedBlock to hide the Node Tunneling section for Cloud users
- Indicate that the --auth-server flag in "teleport start" requires a
port.
Add intros to the Admin and Operations menu pages
- Clarify the purpose of the Admin Guides and Operations sections
by adding an intro paragraph to each page. Since these sections are
similar in scope, I added links from one to the other with statements
about how the two sections differ.
- Replace lists of links with Tiles.
GitHub SSO
- Move the step to create an OAuth app out of the Prerequisites and
into its own step. This makes it easier to give the instructions
to use a specific callback URL proper space.
- Be more explicit about the rp_ip value.
- Add explicit instructions for logging in to the cluster after
creating the auth preference, including screenshots of expected
results.
* Fix wording and linter issues following PR review
* Respond to PR feedback
Remove a misleading instruction re: CA pinning. Also move some text
about CA pinning to a more appropriate location.
* Edit two guides for Cloud users
(1) Server Access Getting Started
While this guide mentions Teleport Cloud throughout, I wanted to make
sure that users of one edition wouldn't see scope-irrelevant details.
- Add scoped Tabs to the Prerequisites section
- Add the scoped "tctl.mdx" Details box
- Add ScopedBlocks for minor scope-relevant details like the address
of the Proxy Service
- Edit the tctl.mdx partial to mention when you would use sudo to run
tctl on a local machine, a detail that was added to this guide but
could be included in any guide that uses the tctl.mdx partial.
Also makes misc. style, grammar, and clarity edits.
(2) Edit the OpenSSH guide and spin off a PRM guide
- The Recording Proxy Mode instructions don't apply to Cloud users.
I didn't want to use a ScopedBlock to hide the relevant H2s, since
these still appear within a page's table of contents. Instead, I
separated the Recording Proxy Mode instructions into their own guide,
and added an edition warning for Cloud users at the top of the guide.
I also did some restructuring of the OpenSSH guide to clean it up after
separating the Recording Proxy Mode instructions.
- Used ScopedBlocks to ensure that only scope-relevant information is
shown in the OpenSSH guide.
- Misc grammar/style/clarity tweaks
* Respond to PR feedback
See #10633
Terraform Provider guide
- Add tabbed prerequisites so users only see information relevant to
their scopes.
- Add the impersonation section as an H3 rather than an Admonition. If
users are learning how to use our Terraform provider, they likely
will not have enabled impersonation for the Terraform user, and would
always need to read the Admonition, so this would work better as an
H3.
- Add a scoped Notice indicating which address to use for the cluster
address in the sample Terraform config.
Fluentd plugin guide
- Add tabbed instructions for users of different scopes.
- Move the impersonation Admonition to an H3 so readers can configure
impersonation without running into an error.
- Misc clarity/style edits.
Certificate Authority Rotation
- Add tabbed prerequisites so users of one scope don't see information
intended for other scopes.
* Add Cloud-specific instructions to two guides
Ensure that users of a particular scope don't see irrelevant info
See #10633
GitHub SSO guide
- Edit the tctl partial to show only scope-relevant info.
- Use tabs in the Prerequisites
- Light edits for clarity
Adding Nodes
- Use Tabs for prerequisites
- Move sections specific to self-hosted deployments into Details
boxes that are hidden for Cloud users
- Use Tabs components to offer Cloud-specific alternatives to
examples of commands that presuppose a self-hosted deployment
- Misc clarity edits
* Respond to PR feedback
* Fix linter issues
Paul Gottschling