* Add a top-level MWI section to the docs
Move how-to guides related to Machine & Workload Identity into a
dedicated top-level documentation sidebar section so readers are aware
of this product as a top-level offering. This is part of a broader
initiative to add a top-level documentation section for each Teleport
product.
* Rename the mwi docs directory
Change the name to machine-workload-identity.
Responds to strideynet feedback
* docs: explain awsic plugin install flag
* expand the use system credential sentence
* Update docs/pages/admin-guides/management/guides/aws-iam-identity-center/migrating-identity-center-from-okta-to-teleport.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Add cdocumentation for `workload-identity-aws-ra` service
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Adjust name to be full roles anywhere
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
See gravitational/docs-website#91
Docusaurus uses semantic HTML tags instead of a custom Details
component. Replace instances of our Details component with the
`<details>` and `<summary>` tags so we do not need to perform a
conversion when building the docs website.
* Machine ID: Document `kubernetes/v2` service
This adds initial documentation for the new `kubernetes/v2` service.
This only includes reference documentation for now, since this
service was added partway through v17; the existing Kubernetes guide
will be updated in a separate PR for v18 and won't be backported to
v17.
Partially fixes#52412
* Review feedback, and add an FAQ entry about the new service
* Add more detailed version note
* Fix broken link
Use Docusaurus syntax for admonitions so the docs engine does not need
to replace these. This is one step toward removing the
`remark-update-tags` plugin. See: gravitational/docs-website#94
Relevant commands are included below to make reproducing this work
easier.
1. Replace all `Notice` tags with `Admonition` tags.
2. Add `type="info"` if an Admonition is missing a type.
To find instances:
```
find docs/pages -name "*.mdx" -exec awk '
BEGIN{a=0}
a==0 && /<Admonition/{ a = 1 }
a==1 && /type/{t = 1}
a==1 && />/{ a = 0; if(t == 0) print FILENAME ":" FNR }' {} \;
```
3. Replace `type="notice"` with `type="note"`.
To find instances:
```
find docs/pages -name "*.mdx" -exec awk '
BEGIN{a=0}
a==0 && /<Admonition/{ a = 1 }
a==1 && /type="notice"/{t = 1}
a==1 && />/{ a = 0; if(t == 1) print FILENAME ":" FNR }' {} \;
```
- Fix "Auth Service" variations.
- Fix some AWS product naming violations.
- Ignore some false positives.
- Fix capitalization warnings.
- Address warnings re: outdated product names.
Some of the warning categories above include auto-generated pages. This
change does not touch the generators in order to simplify things.
* Stable user UID addition to the host user creation guide
* tctl stable-unix-users-ls docs
* CAP resource reference
* auth service reference
* Uncomment defaulted field in fileconf
* Clarify conditions for stable uids
* Add CLI reference
* Start fleshing out pages for new docs
* Link out to Terraform provider information
* Start putting together workload-identiyt-api svc reference
* Minor adjustments
* Keep hacking on reference for resource
* Keep hacking on reference
* Add to list of templating supported fields
* Add TOC
* Add rules to the example yaml
* Flesh out workload-identity-api docs page
* Add some todos
* Add skeleton of attributes page
* ADd comments
* Cross page links
* Retitle page
* Link one reference to another
* Add template for selector
* SPAG
* Fix link
* Fix TODO link
* ADd tbot start workload-identity-jwt to cli reference
* Add `workload-identity-x509` to config reference
* Start documenting join attributes
* Finish last batch of join attrs
* Add some short exsplanations/summaries
* Start explaining rules
* Shorter explanation
* Add opener to Workload Identity API and Workload Attestationreference
* SPAG
* Add docs for selector
* Fill out migration guide
* rename/reorg
* Add short note on SPIFFE Workload API
* SPAG
* Fix links
* Machine ID: Update documentation to reflect tbot CLI changes
This updates the tbot documentation to reflect the new UX changes
for v17, including the new `tbot start` subcommands and runtime ACL
management.
* Add `tctl bots instances` subcommand reference docs
Also tweaks troubleshooting steps to reference the new tctl
subcommands for simpler instance creation.
* Fix a few docs lints
* Small wording fix
* Linter appeasement
* More linter appeasement
* Update docs/pages/reference/cli/tbot.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Adjust wording to explicitly state "example" is the bot name
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Closes#10574
- Present the examples with a correct use of the `logins` flag
- Since the current examples overlap, just use one
The remaining issues identified by #10574 are already resolved or out of
date.
Docusaurus [sidebar
generation](https://docusaurus.io/docs/next/sidebar/autogenerated)
expects category index pages to have one of three file path conventions:
- `section/index.mdx`
- `section/README.mdx`
- `section/section.mdx`
This change standardizes category index paths on the third convention so
Docusaurus sidebar generation succeeds. We can then add checks to the
current docs site to prevent additional menu pages from violating this
convention.
This change also adds redirects to the new category index pages, and
updates internal links to pages that were moved.
Note that this change does not move all relevant menu pages. We still
need to reorganize the `reference/terraform-provider` section. Since
this section is automatically generated, we need another approach to
restructuring it.
* docs: use code instead of shell
* docs: revert generated file
* docs: update shell styling for generated file
---------
Co-authored-by: Steven Martin <stevenmartin@Stevens-MBP.fios-router.home>
Currently, the agentless OpenSSH guide does not appear on the sidebar.
This is because the sidebar generator expects menu pages to be named
after their corresponding subdirectory and to exist at either (a) the
same level as the subdirectory or (b) within the subdirectory. Since a
page exists at both locations called `openssh.mdx`, the sidebar
generator only shows one of these.
This change edits the OpenSSH guide to be called `openssh-agentless.mdx`
so it appears on the sidebar.
Provide a less overwhelming documentation experience for users by
condensing sidebar sections into five, organized loosely around
different audiences of the documentation:
- **Get Started:** new Teleport users, as well as users of all levels
who want to quickly look up key, frequently changing information, such
as the changelog and upcoming release information.
- **Admin Guides:** intermediate users completing a specific task. This
includes all how-to guides in the docs except those in "Get Started"
and "Enroll Resources".
- **Enroll Resources:** Admin Guides, but for our extensive library of
how-to guides for protecting infrastructure resources with Teleport.
- **References:** Advanced users looking for comprehensive reference
information and architecture guides. This includes all reference
guides in the docs.
- **User Guides:** Guides for end users looking to access resources.
Related changes:
- **Move Helm reference partials**. Use the `docs/pages/includes`
directory so we can generate the sidebar from `docs/pages/reference`.
- **Move the Architecture sidebar section** into "References", and move
architecture guides across the documentation into "Architecture".
- **Remove "Documentation Overview"** as this is out of date. Now, top-level
sidebar sections are more self explanatory.
- **Remove "Choose an Edition"**, since we want to elevate Teleport
Enterprise (Cloud), making Teleport Enterprise (Self-Hosted) available
for certain use cases.
- **Add an infrastructure as code section** to Admin Guides.
* Add `tbot install systemd` to CLI reference
* Switch systemd unit file creation to new `tbot install systemd`
* Remove unused machine-id-service include
The number of sections on the left sidebar makes the documentation
difficult to navigate. This change reduces the number of sidebar
sections by creating an "Enroll Resources" section from sidebar sections
related to protecting infrastructure resources with Teleport.
This change configures the sidebar for the Enroll Resources section to
be automatically generated. Since the generator expects each
subdirectory of a section to have a corresponding table of contents
page, this change also adds missing table of contents pages.
In some cases, we can repurpose an existing section introduction page
for a section's table of contents page. In other cases, the introduction
spends too much time on providing context to make for a useful table of
contents, so this change adds a separate table of contents page. Table
of contents pages use the `(!toc!)` syntax to list links automatically
based on the file system.
This change also adds redirects based on mentions of Teleport docs URLs
in the Web UI source, and removes all other redirects to avoid exceeding
the maximum number of routes in Vercel.
* Refactor agent architecture guides into one
See #37558
The Teleport documentation has two guides that explain the architecture
of Teleport agents:
- The Database Access Architecture guide
(`docs/pages/database-access/architecture.mdx`)
- The SSH Nodes guide (`docs/pages/architecture/nodes.mdx`)
While these guides are framed around describing the architecture of
specific agent services, most of the information in these guides applies
to Teleport agents in general.
This change refactors these two guides into a single Teleport agent
architecture guide that applies to all agent services. Where agents
differ, the guide users tables to explain differences. It also links to
more specific guides where applicable.
As an alternative, we could create a separate architecture guide for
each agent service. This change avoids this approach because:
- The purpose of this change is to refactor existing information for
discoverability, and adds minimal new information.
- Agent services differ substantially in how they proxy traffic to
specific resources. As of #40115, we expect how-to guides to contain a
"How it works" section to explain the architecture of enrolling a
specific resource (#39979 includes an example that edits database
guides). This approach is cleaner than using a single guide to
describe the architecture of connecting to every single resource an
agent can proxy.
- The convention of having a separate `[Resource] Access` section of the
docs per agent service reflects legacy messaging that we are moving
away from.
More specific changes:
- Remove `docs/pages/database-access/architecture`.
- Combine information from the Database Architecture and SSH Nodes
guides into an Agent Architecture guide in
`docs/pages/architecture/agents.mdx`.
- Move session secording information from the SSH Nodes guide to
the Session Recording architecture guide, where it is more
appropriate.
- Remove "Cluster State" from the SSH Nodes guide, since this
information is present in the backends reference.
- Briefly document direct dial mode for agents, but frame the new guide
around the assumption that users will/should enroll agents via the
Teleport Proxy Service.
- Add a new architecture diagram and moves the original one to the
Database Access Introduction page.
* Respond to greedy52 feedback
- Edit list of database protocols.
- Note additional commands that retreive certificates.
- Add information re: `tsh apps login` to the client cert table.
- Fix Desktop Service introduction mistake.
- Mention the Discovery Service after the list of agent services.
- List the Discovery Service as one that does not require a reverse
tunnel.
- Mention HTTP apps in the local proxy table.
* Partially respond to feedback
- Use a clearer first paragraph and replace "proxy" where possible when
talking about agents.
- Use more accurate column heading in service table.
- Clarify where agents can run and their relationship to services.
- Other accuracy/clarity fixes, including incorporating suggested
wording.
- Describe example agent-to-resource authentication methods for
resources besides databases.
- Mention Teleport Connect.
- Remove the mention of agent ping message payloads.
* Edit the agent architecture guide
Flatten the heading structure, organizing the guide according to
connections between components, merging the "Retrieving credentials"
sections into sections related to communication between components.
Also clarify the process in which the Proxy Service forwards traffic to
an agent over a reverse tunnel.
* Edit the intro paragraph
* Fix spelling
* Fix linter errors
- Update link target paths
- Add the "Cluster state" H2 from the original "Nodes" architecture
guide to the Backend Reference so the latter doesn't need to link to a
missing section.
* refactor(docs): update docs to include debug service usage
* docs: code review suggestions
* docs: update debug service intro definitions
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* docs(diagnostics): move teleport-debug-config section up in the guide
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Add TPM to join method reference page
* Skeleton out the Linux/TPM guide
* Add yaml for join token
* Flesh out TPM joining guide
* Try var
* Add note on FIPS 140-2 compliance
* Add more vars
* ADd more background to how TPM joining works
* Clarify statement on most secure
* Add `tbot tpm identify` to cli reference
* Rename background to `how it works`
* Update docs/config.json
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/includes/tpm-joining-background.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/includes/tpm-joining-background.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/includes/tpm-joining-background.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/deployment/linux-tpm.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Use Create A Bot template
* Expand TPM
* Reword tpm joining background
* Fix trailing ,
* Mention enterprise licensing
* cspell
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Document Azure CLI setup for AKS with Entra Workload ID
* add How it works section
* address review comments from Tener
* address comments from Paul
* try to fix lint and add version info
* Modify `tbot` docs to show `--proxy-server`/`proxy_server` in preference to `--auth-server`
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/deployment/kubernetes.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Fix an incorrect sitemap link. The Teleport docs engine generates the
sitemap based on the contents of `docs/pages`. This directory tree
included a file called `docs/pages/server-access/guides/openssh.mdx`,
but the `config.json` for the docs content included a redirect from this
page to `docs/pages/server-access/guides/openssh/openssh.mdx`, meaning
that a page in the sitemap became inaccessible.
This change fixes the `/server-access` section of the docs to resolve
the sitemap issue. To do so, it creates the `server-access/openssh`
directory and moves OpenSSH guides into this directory. It updates
`config.json` and the Server Access menu page accordingly.
This change also adds a missing meta description to the self-hosted
Access Graph guide.
Paul Gottschling