* Provide more context in the docs intro page
Closes#22469
The current docs landing page does not include enough context for new
readers. After the general description of Teleport, the rest of the
landing page is series of links, with little guidance for what a new
user should do first (or what an intermediate user should do after
completing the initial setup steps).
This change takes a more narrative approach to the landing page,
briefly describing the content of each top-level docs section and
putting it in context with the rest of the docs. This also helps users
find the right top-level docs section for their needs, since otherwise
the only way to do this is to visit each section.
This change is also more opinionated about which guide new users should
begin with. It recommends the guide to getting started with Teleport
Cloud, since this doesn't require setting up a Teleport cluster and
helps a user register a resource quickly.
The landing page links to the introduction page of each top-level docs
section. If a section does not have an introduction page, this change
adds one.
* Respond to zmb3 feedback
Reorder list items
* Linter fixes
* Respond to alexfornuto PR feedback
* Explain Kubernetes RBAC more comprehensively
Closes#18230
This change explains Teleport's RBAC system in relation to the Teleport
Kubernetes Service. The docs didn't leave me with a readily available
place to put this information, since explanations of Kubernetes-related
role fields are scattered in asides throughout various pages.
As a result, I have added a more comprehensive, focused explanation of
Teleport's Kubernetes RBAC system in two places:
- A new how-to guide for setting up Kubernetes RBAC with Teleport using
a local `minikube` cluster.
- A reference guide that explains the Kubernetes-related fields within a
Teleport role as well as the logic that the Kubernetes Service uses to
evaluate these fields. This replaces the existing Kubernetes Access
Controls guide.
To make room for the RBAC how-to guide, I've reorganized the other
guides into a logical sequence: enabling auto-discovery, manually
registering clusters, and setting up access controls.
I've also edited the Resource Access Requests guides to explain role
fields for the different resources you can restrict access to via
`search_as_roles`, including `pods`.
* Partially respond to PR feedback
- Add `kubernetes_labels` to example snippets
- Rename a misleading H5 in the Resource Requests guide
- Make the description of impersonation more accurate in the Access
Controls guide
- Move a Notice in the Access Controls guide
- Add an example role to the warning re: namespace restrictions in the
Access Controls guide
- Make resource filtering info more accurate in the CLI reference
* Change the RBAC how-to guide
Use Deployments in the demo cluster instead of Pods, showcasing the use
of regular expressions in per-pod RBAC.
This responds to PR feedback.
* Provide an example of internal traits
This responds to PR feedback
* Add notes about regex support
Responds to PR feedback
* Explain multiple values in labels
Responds to PR feedback
* Document progressively enabling access to pods
In response to PR feedback
* unbreak redirect
* copy edits
* more copy edits
* Respond to alexfornuto feedback
---------
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* Add a glossary of Teleport terms
Closes#16121Closes#13363
- Create a Core Concepts page based on the Architecture Overview page.
The Overview page is an outline of core concepts, so I thought it
would make a good starting point for the glossary.
- Add the Core Concepts page to the Home section to make it more
prominent for users who are visiting the docs homepage. This should
give it more traffic than leaving it in the Architecture section.
- Move definitions out of the "Definitions" table. Since this table
repeats content from the body sections and comes after them, it makes
sense to condense all content into brief body sections.
- Alphabetize sections
- Bold the first instance of each keyword within a given section. Not
adding links since these are all to the same page. It might get a bit
confusing to click a link and not see a change in view, since the
target section would already be on the page.
- Remove the intro paragraph of the old Overview page, since it's not
strictly related to core concepts.
* Respond to PR feedback and add further edits
- Group definitions into H3-level sections organized into H2s, improving
readability by presenting the more central components first.
- Group "Machine ID" with "Teleport Services" to simplify the glossary.
- Call instances of a Teleport Service an "agent". This is consistent
with our source and informal language about Teleport. This also
removes the "Node" terminology, which is prone to misuse (does it mean
"a Service instance"? An "SSH Service instance"? Both are present in
the docs) and easily confused with the lowercase "node" (i.e., a
host).
- For simplicity, remove the term "Teleport Process" and simply explain
that multiple Teleport Services can run via the same binary.
- Add a section on Teleport's editions, including the terms "Community
Edition", "Enterprise", and "Enterprise Cloud".
- Remove the mention of Teleport Discover, which isn't documented yet.
- Minor wording/readability changes.
* Respond to PR feedback
* Respond to zmb3 feedback
* 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
Reorganize our Access Request guides
Fixes#13696
Most guides to Access Requests are currently not listed on the sidebar,
and the guides that are listed are available for Cloud as well as
Enterprise. This change makes it easier to find our Access Requests
guides by moving them to the Access Controls section and listing all
guides on the sidebar. It adds the "Access Requests" and "Access Request
Plugins" subsections to "Access Controls".
Since the Access Controls section includes one subsection, called
"Guides", this change also renames that subsection--and adds a
descriptive intro paragraph to the section's menu page--in order to
accommodate the Access Requests and Access Request Plugins subsections.
Move some guides into "Access Requests"
* Edit the Slack access request plugin guide
Fixes#14581
- Flesh out the intro a bit
- Fix the directory name used in the `mv` command in the installation
step. Also fix the name of the binary generated by the `make` command.
- Add a step to test the installation
- Edit the rbac.mdx and impersonations.mdx partials to provide more
context and restructure the instructions so users can follow them step
by step.
- Add context around other existing steps
- Add more comprehensive role mapping instructions. The guide included
an example role mapping, but did not spell out the general logic of
the role mapping bheavior, e.g., that the "*" key is required.
- Move the step re: inviting the bot to after the user configures role
mapping so they know which channels to invite the bot to.
- Add a section on creating roles to enable Access Requests so it is
eassier to follow this guide linearly. Otherwise, users will need to
do more work to match the configuration instructions with the
specifics of their RBAC setup.
- Capitalize "Access Request" in this and other guides, since we're
adding more emphasis on this as a product.
- Turn the "Audit Log" section into an Admonition and make the
instructions there more accurate.
- Add context to the "identity-export.mdx" partial. This is a pretty
confusing part of the Access Request setup process, so I added context
to explain why different identity file formats are used.
* Apply suggestions from code review
Co-authored-by: Nic Klaassen <nic@goteleport.com>
* Respond to PR review
Co-authored-by: Nic Klaassen <nic@goteleport.com>
Fixes#10976
This change helps to remedy two issues with the documentation:
- Much of the documentation was written when Teleport's services
consisted of the Auth Service, Proxy Service, and Nodes/SSH Service.
There are some places in the docs where a reader can mistake the
Node Service to mean "any resource service."
- Users often associate the term "agent" with a daemon that must run on
every host in their infrastructure, and usage of this term can make
Teleport seem more resource intensive than it actually is.
This change corrects mentions of "Node" that stand in for "any service
that access resources in your infrastructure" to account for Teleport's
other resource services. It also replaces mentions of the term "agent"
with "instance," the name of a resource service, or simply "Teleport."
Also edits the "agentless" question in the FAQ to include more detailed
information about each of Teleport's resource services.
This change also does some light copy-editing to correct the
capitalization of service names. It doesn't aim to be comprehensive,
though, since the main purpose of this change is to fix potentially
misleading mentions of "Node" and "agents".
Finally, this change deletes the production.mdx guide, as there is
no way to access this guide due to redirects. This guide includes
some outdated usage of "Nodes".
Our architecture section was written almost 5 years ago
and was completely obsolete.
I refactored all of it to be up to date, added Kuberentes
and other resource type references, replaced and created new diagrams.
* Make the OpenSSH guide more usable
See #11841
- Add a Prerequisites section and divide the instructions into steps via
H2 headings.
- Use ScopedBlocks to add instructions for Cloud users.
- Fill in missing instructions (e.g., adding host_cert permissions for
Cloud users and editing the file permission of the host key/cert)
- Since all supported versions of Teleport now include "tsh config,"
remove the manual OpenSSH configuration option. This makes the guide
much simpler to follow.
- Add a Details box explaining "tsh config" The original OpenSSH guide
included some technical details about the proxy subsystem, but
without enough context to understand the configuration generated by
tsh config. I've moved the technical details into a Details box, and
expanded them, so readers interested in how the local SSH config they
generate via "tsh config" works.
- Indicate that you need to specify the SSH port when connecting to an
OpenSSH host via configuration generated by tsh config.
* Respond to PR feedback
* Edit tctl instructions to clarify remote login
Closes#11464
- Ensure that all example tctl commands are accompanied either by
instructions to log in to the cluster or the tctl.mdx partial.
- Edit the guides in the Architecture section to remove notes that
tctl can only be used locally to the Auth Service.
- Edit the user-client-rereqs partial to mention tctl for all
editions, since you can log in to tctl remotely for all editions.
Not editing guides where:
- tctl is run via kubectl exec
- tctl is not mentioned in a code block, i.e., only in passing, and
a reader isn't expected to run the command on their own while
following the guide.
- The user is already expected to run tctl on the Auth Service. The
docker-compose Getting Started guide is an example of this.
* Respond to PR feedback
- Provide more context on authenticating with tctl in the CLI reference
- Update the link to more information re: tctl in the architecture
overview, and indicate that tctl users must authenticate.
- Minor tweaks.
* Respond to PR feedback
- Rephrase the authentication paragraph in the Architecture Overview.
* 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
Add the WebAuthn Access Control guide and tweak various pages that mention U2F
to either refer to WebAuthn or use more generic terms.
* Added `/docs/access-controls/guides/webauthn/` (branched from u2f.mdx)
* Added `webauthn` section to reference configuration (`u2f` kept unchanged)
* U2F access control guide moved under the "References" section and removed
from the index / navigation menu
* Cloud guides removed (U2F was the last guide, now deleted)
* WebAuthn access control guide
* Update access controls pages
Update links to WebAuthn and changes lingo to refer to either WebAuthn,
MFA, "second factor hardware token" and "second factor authenticator",
where appropriate.
U2F is moved to the references sections and WebAuthn is favored as the
guide to be followed in regards to MFA hardware tokens. Generic language
is used whenever possible, excluding places where we reference server
configuration or protocol support.
* WebAuthn cloud guide
* Update cloud pages
* WebAuthn config reference
* Update references to U2F in various pages
* Link to the WebAuthn guide in from the Authentication reference page
Incorporates ibeckermayer's suggestion from
https://github.com/gravitational/teleport/pull/8703.
* Rephrase sentences according to reviewer feedback
* Replace explicit <h2> with `##`
* Move "Migrating from U2F" section to the bottom
* Use numbered steps
* Include tabs for Cloud in config examples
* Add tctl as a prerequisite for WebAuthn setup
* Remove Cloud guides
U2F and WebAuthn were the last remaining items.
* Make linter happy
This adds documentation for using tsh on Windows, along with a guide
for using VS Code Remote Development with Teleport hosts.
Related PRs:
* #7848: Support Windows with `tsh config`
* #7790: Support Windows with `tsh ssh` (and `scp`, `join`, `play`, etc)
* Cleanup docs on users and roles
- Updates roles to use v4
- Moves users to a separate guide
- Creates up to date reference for users and roles resources
* Update docs/pages/setup/reference/resources.mdx
Co-authored-by: Roman Tkachenko <roman@gravitational.com>
Co-authored-by: Roman Tkachenko <roman@gravitational.com>
Co-authored-by: Roman Tkachenko <roman@gravitational.com>
* 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>
* Open Sources Access Controls Docs (#6188)
Moves RBAC to a separate access controls section,
adds a couple of guides and prepares
the structure for more content.
* Fix href links
Paul Gottschling