* 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.
* Add new `tctl bots update` command
This adds a new command to update roles and logins for existing bots,
with flags to both set and append as desired.
changelog: Add new `tctl bots update` command to update bot roles and logins
* Pluralize "add-" flags for consistency
* Add docs for `tctl bots update`
Also merges in some other misc docs changes for `tctl bots ...`
* Fix docs lint
* Fix incorrect example
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Use the bot service's `UpdateBot()` RPC instead of modifying directly
This switches to use the new `UpdateBot()` RPC instead of modifying
the bot user and role directly. Also, tweaks CLI messaging to be a
bit less chatty.
* Update tool/tctl/common/bots_command.go
Co-authored-by: Hugo Shaka <hugo.hervieux@goteleport.com>
* Move set functions into their own reusable package
The set package adds a little extra functionality but is still
missing various important functions, like subset/superset,
difference, intersection, xor/symmetric difference, etc.
This changes the API slightly, so the tctl command is updated to use
the new package.
* Remove duplicate tests
* Reword flag help strings for clarity
* Remove set abstraction
Removes the Set package and unrolls all related function calls in
bots_command.
* Add unit tests for `updateBotLogins()` and `updateBotRoles()`
This also makes a minimal API wrapper interface for mocking.
* Use utils function to convert sets to a string slice
* Update docs/pages/reference/cli/tctl.mdx
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Hugo Shaka <hugo.hervieux@goteleport.com>
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
Closes#21164
The CLI reference is a section of the docs in which each CLI tool has
its own page, so this change sorts each page individually.
The change places H2 sections not related to individual commands (e.g.,
sections for global flags and environment variables) at the top of each
guide, and sorts the sections following these.
In `teleport.mdx`, all commands except for `start` are only documented
in a table at the beignning of the page, so this change sorts the table.
- Fix clashing reference page titles ("Teleport CLI Reference" and
"teleport CLI reference").
- Add missing redirects: The Teleport blog encountered 404s navigating
to three pages. This change adds redirects for these pages in case
other sites link to them as well.
* tsh: Add support for host:port combinations to tsh puttyconfig
* docs: Update PuTTY docs to add instructions for adding OpenSSH nodes
* Add OpenSSH example to tsh puttyconfig CLI reference
* Tidying as suggested by tiago
* Skeleton out docs refactor (#31017)
* Start outlining index pages
* More reshuffling
* Remove old guides index page
* Adjust sidebar config
* Fix redirect
* Fix crosslinks
* Fix changelog links
* Fix more links
* Add short descriptions for platform guides
* Improve some page descriptions/signposting
* Nicer title
* Outline intro page
* Add notes on common usecases
* Remove old sections from introduction
* Start to outline overview topics
* Roughly expand on overview to cover bot user/bot role
* Clarify usecases
* Attempt to break up further reading section to be intelligible
* SPAG
* Add TODOs
* Machine ID Docs Refactor: Kubernetes Platform Guide + some AWS/GCP (#31796)
* Add config files needed for Kubernetes deployment
* Tidy examples under defined headers
* Add namespace to specs
* Add notes on join methods
* Further details on Kubernetes joining
* Document kubernetes rbac resources
* Skeleton out GCP/Linux platform guides
* Add necessary topics to the background for GCP and Linux
* Try and rewrite the blank role mdx to be less rubbish
I'm pulling my hair out over this lol
* Add a todo so I can come back to this part of the description when i can use words
* Further flesh out the background shape and intor shape for the platform guides
* Add more steps to k8s guide
* Fix links to k8s page
* Explain `kubernetes` join method
* Add documentation to the token yaml
* Add reasoning for role
* Document deployment manifest
* Add notes on determining if the deployment is healthy.
* Add token yaml for aws/gcp from my reference notes
* Add token/bot creation step for aws,gcp,linux
* customizing
* Machine ID Docs Refactor: Add `tctl` and `terraform` access guides (#32036)
* Outline `tctl` access doc
* Flesh out Terraform page with an example
* Fill out the copy for the Terraform provider guide
* Add explanation to configure tbot step of Terraform guide
* Add similar explanatory prose to tctl.mdx
* Add example role for tctl guide
* Try to better explain modifying the existing role
* Fix prerequisites
* Note on configuring permissions
* Fix SPAG
* Appease linter
* Expand intro for Terraform
* Please linter with newlines
* Remove spurious newline
* Clarify install/confgiure language
* Update docs/pages/machine-id/access-guides/tctl.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/access-guides/tctl.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/access-guides/tctl.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/access-guides/terraform.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Remove bactics from title
* Make example roles less powerful
* Add example of tctl command to check success
* Correctly say platform guide not access guide
* Be more specific in mentioning `tbot`
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Remove V11 support warnings from platform guides
* Machine ID Docs Refactor: Linux VM based Platform Guides (#32472)
* Add pre-requisites
* Add example systemd service
* Notes on oneshot mode
* Offer daemon or oneshot mode docs
* Hide one-shot mode from `token` join based Linux
* Clarify Linux user for access
* Use variables for the token and explain commands
* Explain creating systemd service
* Explain when to prefer one-shot mode
* Add skeleton for Azure
* Document azure join token fields
* Add intros for guides
* Explain why we protect the directory
* Add install instructions
* Remove step regarding writing token to a seperate file
* Move coinfigure outputs to template
* Signify each step as local machine or target host
* Explain gcp/azure join methods
* Explain token and iam join methods
* Remove no longer recommended host certs guide
* Add next step
* Correct list of supported join methods
* Machine ID Docs Refactor: Rewrite GitLab and CircleCI guides (#32834)
* Start reshaping the circleic guide
* Make some changes to the GitLab side as well
* Add role creation to GitLab guide
* Add role creation step to CircleCI guide
* Adjust token file name
* Make sure anonymous telemetry advice is included
* Machine ID Docs Refactor: GitHub Actions docs (#32854)
* Start restructuring GHA guides
* Copy in Kubernetes Action example
* Add example DIY workflow
* Adjust examples with replacement steps
* Link off to the action github pages
* Tidy up introduction for GHA guide
* Explain GHA examples better and more searchably
* Improved title
* Add example role modifications
* Machine ID Docs Refactor: Ansible Access Guide (#32741)
* Rework Ansible with Server Access guide
* SPAG and consistency suggested changes
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Clarify intro and use the variable throughout
* suggested fixes
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Clarify configuring bot rbac
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Machine ID Docs Refactor: Application Access (#32745)
* Rework Application Access docs
* Code review suggestions
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Clarify RBAC
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Machine ID Docs Refactor: SSH Access guide (#32735)
* Add prereqs for ssh access guide
* Outline steps and output config
* Add guidance on tsha nd OpenSSH
* Guidance on other tools
* Simplify guidance on other tools
* Link to ansible guide
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Reorganise RBAC section
* Fix miscopied sentence
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Machine ID Docs Refactor: Architecture and Introduction (#32901)
* Rewrite getting started guide next steps
* Rewrite introduction introduction to focus on tangible machine ID benefits
* Overview
* Add todo markers
* Rewrite overview
* Rewrite some of the architecture page
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Rearrange "overview" to act as "concepts"
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Machine ID Docs Refactor: Database Access (#32743)
* Rewrite database access guide
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Clarify that systemd should be used rather than exercise for reader
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Machine ID Docs Refactor: Kubernetes Access (#32744)
* Rewrite Kubernetes access guide
* Code review suggestions
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Explain need for kubectl on both client machine and machine id host
* spag
* Fix `kubernetes_resources` example
* Further clarify `kubernetes_resources`
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Edit the Machine ID docs refactor (#33596)
* Edit the Machine ID docs refactor
- **Rename the new guides:** Use the "Connect a Bot" and "Deploy Machine
ID" language instead of "Access Guides" and "Platform Guides" to
connect these guides more explicitly to the language we use in the
"Concepts" discussion of the Machine ID landing page.
- **Add context to the deployment guide index page**: Reduce repetition
and provide information about each deployment method to help users get
more context about how Machine ID runs and joins a cluster, as well as
to help users choose a deployment guide.
- **Make links more visible on the Machine ID intro page:** Use a video
banner for the Machine ID intro so it takes up less space on the page.
Shorten some sections and add more specific H2s for the links.
- **Streamline some deployment guides:** Where guides include
"Background" and "Guide" H2s, blend the introductory information with
the guide so we can promote the "Step" H2s to H3s and direct the reader
to the step-by-step instructions more quickly.
- **Add new pages to the docs table of contents.**
* Respond to zmb3 feedback
- List cloud platforms before CI/CD platforms on the sidebar
- Recommend using platform-signed identity documents in the deployment
guide intro page.
- Edit language introducing join tokens.
* Respond to strideynet feedback
- Edit wording in the deployment guide index page, including renaming a
section heading and adding language re: renewable certs in the static
token join method.
- Change GitHub Actions link.
- Rename the Access Guides back to "Access Guides"
* Fix spelling
* Appease linter
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* docs: Add WinSCP to PuTTY client instructions
* Restore validity section
* Restore validity section
* Formatting tweaks
* Merge lists
* Change title
* Fix docs link title to match page
* Bump tsh version for WinSCP support
* Whitelist WinSCP in spellcheck
* putty.mdx -> putty-winscp.mdx
* Reduce the use of capitalized trusted clusters and a few other fixes
* fix a typo
* Modify the description of trusted clusters in core concepts
* Lower case cluster, add root and leaf to the description for self-hosted
* OpenSSH split into two topics
* Add Access List documentation.
Access List documentation has been added, providing a reference for Access
Lists for Teleport v14.
* Reword things, clarify unclear things, remove copy paste error.
* Migrate CLI docs.
* Show user creation via the GUI.
* Make the dumper app the concrete example in the access list guide.
* Remove references to running resources in prerequisites.
* Update docs/pages/access-controls/access-lists/reference.mdx
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* Add in admonition about audit reviews not being in Teleport yet.
* Remove language surrounding missed audit reviews leading to expired access.
* Apply suggestions from code review
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
* Make the requirements fields more clear.
* Correct typo.
---------
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
Fixes#27817
Move our guidance on the `tsh` config files to the `tsh` guide in the
"Connect your Client" section and out of the CLI reference. This is
because the CLI reference focuses on commands, while the general `tsh`
guide covers a number of topics, making it a more appropriate place for
the config file guide.
* Replace multi-line ScopedBlocks with Tabs
Contributes to #30268
The documentation scope switcher tends to confuse users, and the
ScopedBlock component hides docs content based on the scope switcher. To
help remove ScopedBlocks from the docs site, this change replaces
multi-line ScopedBlocks with Tabs components if they include variations
for different scopes.
While most multi-line ScopedBlocks function like Tabs, there are a few
edge cases, which this change addresses individually.
Note that this change does not intend to remove all ScopedBlocks that
are placed inline within a paragraph. That will be the goal of a
separate change.
* Remove more ScopedBlocks (#30623)
This builds on the work done in #30616 and contributes to #30616.
Fixes#29957
Improves the page load performance of our CLI reference documentation by
splitting up the long CLI reference page. This also has other benefits,
including:
- **SEO**: Users don't need to search for the Teleport CLI reference
(and don't need to know that this page exists), but can search for a
specific tool they want reference docs for.
- **In-page search:** Users searching within a specific page will get
results for the tool they are researching, not all of Teleport's CLI
tools.
Paul Gottschling