* Add a guide to writing an Access Request plugin
Closes#22227
This guide uses a minimal working example of an Access Request plugin to
demonstrate some of the key libraries that Teleport makes available to
plugin developers. The guide is based on a 270-line plugin that manages
Access Requests using Google Sheets.
* Respond to hugoShaka feedback
* Respond to zmb3 feedback
* Add some minor tweaks
- Update the line of code count in the demo program
- Mention Machine ID
* Respond to alexfornuto PR 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
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>
* 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