We are standardizing docs guides to add a `page_type` frontmatter field,
with values for how-to guides, references, etc. We can then use this
field to apply linting rules that ensure each guide type follows
type-specific docs site conventions. The first convention is that each
docs page must have an outcome statement, the structure of which depends
on the guide's type. Human and AI agent readers can determine from the
outcome statement whether to continue reading the guide or not.
This change assigns the `page_type` frontmatter field to 47 guides.
Where an outcome statement is missing or incorrect, this change adds or
corrects it. Changes include:
- Landing pages: added `page_type: landing`, with no outcome statement
required
- Guides with entirely new outcome statements
- Already-compliant guides: intro paragraphs already matched the
required pattern, so this adds `page_type` only
- Editing outcome statements to use compliant phrasing: a sentence in
the introduction mostly matched the expected pattern, but required a
small phrasing change
* Begin restructuring installation docs
See RFD 246
The documentation in the Installation section is currently organized by
platform while documentation for deploying Teleport components is
organized elsewhere. This creates confusion for users, who visit the
Installation docs far more often than any other section, missing
critical instructions.
This change modifies the Installation section to include four children:
- Deploying Teleport Agents
- Installing Teleport on a single machine
- Uninstalling Teleport
- An external link to the Download page, the fastest way to download
Teleport client tools.
Implementation details:
- Remove the `amazon-ec2.mdx` installation guide. This has to do with
cluster installation, not single-machine installation. Move AMI
information into the EC2 Terraform guides, which a separate change
will add to the Installation section. Also remove `helm.mdx` from the
single-machine section, where it does not belong. A separate change
will add our Helm guides to the Installation section.
- Move `amazon-ecs.mdx` to the `agents` directory. It's a guide for
deploying Teleport Agents.
- Remove `windows.mdx`, which only pertains to clients, in favor of
making the Download page more visible in the Installation section.
This change also adds some structural improvements to the `linux.mdx`
guide:
- Organize section introductiosn to create a clearer hierarchy between
more general and more specific information. Readers now read more general
information first.
- Move the item re: recommending Cloud to the top of the page.
- Rework the control plane section. Remove the tab for Teleport Cloud,
which is unnecessary since the section isn't for cloud customers. Add
stepped instructions to consolidate the text a bit.
- Include clearer branching in the TAR and package download section
between self-hosted and agent use cases. Move the branching between
FIPS and standard installations higher in the section for clarity.
* Fix links after reorganizing installation docs
* Clean up installation instructions
Responds to **GavinFrazar** feedback:
- Make the Installation section description more precise.
- Extract the Teleport AMI list into a partial.
* Fix clarity issues in the Installation section
- In the landing page, provide a clearer route for users interested in
self-hosting Teleport Community Edition.
- Restore the Windows guide so we have consistent installation
instructions for all supported platforms. Accordingly, update the
`docs/pages/installation/single-machine` landing page to indicate that
this section also pertains to client tools.
- Place the Amazon EC2 guide in the Single Machine subsection and
include the partial that lists AMIs. Replace the single H2 with an
Admonition for clarity. Fix redirects accordingly.
- Move "Downloads" to the end of the Installation sidebar section.
Clarify the purpose of the link.
- Include `fdpass-teleport` in the table of installed binaries.
- Use "control plane" instead of "cluster" to describe the Auth Service
and Proxy Service in the single-machine.mdx index page.
Closes#57908
Move content out of the Admin Guides and Operations sections, which are
ambiguous. There is content throughout the docs on performing admin
tasks and operations on a cluster. Each guide in these sections has a
more thematically specific home in the docs with related guides in the
same subsection.
Reorganize the following guides:
| Guide | New Location | Reasoning |
|---------------------|--------------|------------------------------|
| AWS OIDC | Cloud APIs | Contains `integration` info |
| Backup/restore | Self-Hosting | Only for self-hosting |
| CA Rotation | Security | About securing a cluster |
| Datadog Integration | Diagnostics | About monitoring a cluster |
| GitHub integration | Cloud APIs | Contains `integration` info |
| Local Users | RBAC Intro | Beginner-level RBAC guide |
| Proxy Peering | Self-Hosting | Only for self-hosting |
| Scaling | Reference | Conceptual and re: deploying |
| Self-Signed Certs | Self-Hosting | Only for self-hosting |
| Troubleshooting | Diagnostics | Related to introspection |
| Trusted Clusters | Self-Hosting | Only for self-hosting |
| Uninstall Teleport | Installation | Relevant to installation |
Also shorten sidebar labels in order to reduce noise for readers. Remove
the `trusted-cluster-address-lookup.mdx` page, since we include the same
instructions in how-to guides throughout the docs, and this is too short
to be a guide of its own.
Move the daemon guide to the top level of Management, since the Admin
section is now gone. Unlike other guides in `management/admin`, this
guide does not have another more appropriate home.
Revamps the Getting Started experience into a concise, four-step guide:
1. Deploy a Teleport cluster
2. Connect infrastructure
3. Set up access controls
4. Configure audit logging
This guide is designed as a multi-page, flowing overview that links to more in-depth documentation (if needed), rather than a long one-page tutorial.
Replaces:
- Existing single-page Getting Started guide (Teleport Enterprise Cloud)
- Linux Demo guide (Teleport Community Edition)
Links in other pages have been updated to point to these new locations and sidebar has been updated as well.
Replace the `labels` frontmatter field with one called `tags`.
Docusaurus supports tag-based navigation out of the box with the `tags`
field. The original plan was to implement a separate system that allows
for filtering by multiple tags - which Docusaurus does not - but it
makes sense to enable the default approach as a first iteration.
* Move Access Controls to ZTA
The guides in Access Controls describe ZTA features, and we are
organizing the docs so that all pages fall under a product-focused
category.
* Move some Management content to ZTA
The guides in the `admin-guides/management` section describe ZTA
features, and we are organizing the docs so that all pages fall under a
product-focused category.
Paul Gottschling