* 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
This change replaces all `Tile`s in the docs with lists of links. This
achieves two things:
- Helps us move toward a more text-focused look and feel for the docs.
See gravitational/docs#93.
- Makes it easier to reorganize the docs. Currently, there's no linting
for internal links in `Tile` hrefs (See gravitational/docs#100).
I used this script to edit each docs page, invoking the script for all
MDX files in docs/pages:
```
gawk '
BEGIN{inopentag=0; indesc=0; desc=""; title=""; href="";}
/<\/?TileSet>/{next;}
/<Tile/ {
inopentag=1;
}
inopentag==1 && /title=/{
title=gensub(/.*title="([^"]+)".*/, "\\1", "g", $0);
}
inopentag==1 && /href=/{
href=gensub(/.*href="([^"]+)".*/, "\\1", "g", $0);
}
inopentag==1 && />/ {
inopentag=0;
indesc=1;
next;
}
indesc==1 && !/<\/Tile/{
gsub(/(\n|\t|\s{2,})/," ",$0);
desc=desc ($0);
next;
}
/<\/Tile/{
print "- [" title "](" href "):" desc;
indesc=0;
desc="";
title="";
href="";
next;
}
inopentag==0 && indesc==0{ print $0 }
' $1 > "$1.tmp";
cat "$1.tmp" > "$1";
rm "$1.tmp";
```
I then cleaned up each file changed by the script and fixed any
incorrect URLs.
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 API getting started guide includes a go snippet that ends with
"EOF," which is not a Go keyword. If the reader isn't familiar with
Go but wants to follow this guide, the Go compiler will return a syntax
error.
This change removes the line.
* Add Cloud compatibility notes to guides
Add Details boxes to some guides that do not mention Teleport
Cloud, indicating how each guide relates to Teleport Cloud users.
* Respond to PR feedback
Removes Details boxes unless necessary to warn users of
incompatibility with Teleport Cloud.
Also makes minor stylistic tweaks.
* 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>
Paul Gottschling