* add version compatibility callout to Cloud section
* consolidate partial usage in various guides
* remove partial consolidated into
* Apply suggestions from code review
* Organize docs guide sections chronologically
This change aims to make docs navigation easier by organizing some docs
sections according to the sequence of steps a user would take to set up
Teleport.
The current docs organization uses a variety of categories and schemes
to organize the docs. For example, there is a "Home" section that
includes the Changelog, Installation page, and Getting Started guides; a
"Setup" section that includes references and admin guides; and
edition-specific sections (Enterprise, Cloud). For a user who is setting
up Teleport--or who has already done some setup work and wants more
advanced instructions--it's difficult to know where in the docs to find
the right information.
This change organizes our how-to guides into the following categories
that describe the process of setting up Teleport:
- Try out Teleport
- Deploy a Cluster (including choosing an edition)
- Configure Access (including SSO, RBAC, and Access Requests)
- Manage your Cluster (admin guides, operations, etc.)
- Use Teleport (this section already exists)
I moved the Reference section after this chronology, since users can
access the reference guides anywhere in the setup process.
As part of the change, I have also moved the content from the
"Enterprise" and "Cloud" sections into "Deploy a Cluster", since this
content has to do with how to deploy a specific edition of Teleport.
Note that this change does _not_ attempt to reorganize our
protocol-specific sections. While adding resources is part of the
Teleport setup process, we have a lot of content in our
protocol-specific sections, and moving it all into a single section
related to adding resources to a cluster would (a) exceed the maximum
depth for subsections in the nav bar and (b) cause more confusion than
it alleviates.
* Respond to PR feedback
- Create a "Compliance Frameworks" section of "Configure Access" with
the FedRAMP and SOC 2 guides
- Rename "Use Teleport" to "Connect your Client"
- Move the database GUI client guide into "Connect your Client"
* Add redirects
* Fix linter issues
If a user installs an agent version that is greater than the control
plane version, the agent will not be able to contact the control plane
(e.g., it will call a gRPC method that the control plane doesn't
recognize). The current partial for installing Teleport on a Linux host
includes only instructions for installing the latest version. Since
Teleport Cloud is behind the latest version, I have added a partial for
installing a Cloud-compatible agent and included it for Cloud users
in guides that require installing a Teleport agent.
While editing guides in certain sections to accommodate Cloud users
(#10631), I introduced some inconsistencies into the way the
Prerequisites sections in these guides provide instructions for users
of Cloud, Open Source, and Enterprise Teleport.
This change adds a partial that provides tabbed instructions to users
of different Teleport editions when a guide requires a running Auth and
Proxy Service. It then includes this partial where relevant in guides
that fall under the scope of #10631.
This helps ensure that cross-edition instructions are consistent in our
guides, and makes it easier to edit additional guides to accommodate
users of different editions.
Caveats:
- Since this change covers a lot of guides, it aims to be as small as
possible. While all of these guides included links in their
Prerequisites sections, for example, replacing these links with full
instructions was out of the scope of this guide. This change should
still make it easier to make further edits, e.g., in response to
#11538.
- We still need to change other elements of some guides to accommodate
Cloud users. The current change only aims to standardize the
Prerequisites section.
* 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
* Mention Cloud compatibility in three guides
Server Access getting started:
- Remove the instructions to install and set up the Auth
Service, and add references to main Getting Started guides
and Cloud signup page.
- Add a prerequisite to have deployed the Auth Service and
Proxy Service.
EC2 joining guide: make it explicit that the Cloud is not
compatible with this. Also make small style tweaks.
App Access getting started page:
- The guide assumes that you are running the Auth Service,
Proxy Service, and App Service via the same binary, which
does not work for Cloud users.
* Respond to PR feedback
- Add newlines after headings
- Use teleport app start instead of teleport start --roles=app
- Fix incorrect Ubuntu version number
- Add a Details box explaining tctl usage for Cloud
- Correctly capitalize "Node"
* Standardize ACME instruction details
Our Getting Started guides often include instructions for
configuring Let's Encrypt and ACME before starting
Teleport, but not all of these instructions have the same
level of detail, and some are missing some context around
how Teleport uses ACME and why you need to open port 443 on
your Proxy Service host. This change adds an include that
spells out these instructions and invokes the include in the
appropriate guides.
The intention was to include as much relevant information within
the guides themselves to prevent the reader from having to
navigate to other pages.
Closes#6448
* Respond to PR feedback
- Substitute "proxy" for "node" where it was incorrectly used
- Some small stylistic fixes
- Clarify that "teleport configure" does not write the config
itself
* Use an apt-key alternative in install instructions
Current installation instructions for Debian/Ubuntu advise using
apt-key, which is deprecated. This change uses the recommended
method of appending a "signed-by" argument to the APT sources
list along with the rest of a repo's information.
Also creates a partial with Linux installation info to avoid
having to repeat changes in our different Linux installation
instructions.
Fixes#9611
* Respond to PR feedback
- Add "sudo" before the installation script
- Add command prompts before commands (not part of PR feedback but
something I noticed was missing)
* Video Banner (#7914)
* Drain off admin guide into setup sections. (#7960)
* Expand daemon section and graceful restarts guide
* Move API section to top
* Move references to setup
Co-authored-by: Ben Arent <ben@goteleport.com>
Alex Fornuto