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.
Closes#23277
Document the `types`, `skip-event-types`, and `skip-session-types` event
handler configuration fields. The `finish-event-handler-config.mdx`
partial is the most appropriate place for this, since it already
includes instructions for tailoring the user's event handler
configuration.
Closes#43181
Address inconsistent information between the Event Handler README and
step-by-step guides by using the information in the step-by-step guides,
which is more in line with our current recommendations.
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.
- Remove the `team` scope from config.json.
- Edit the Edition comparison table to remove the "Team" column.
- Change the Teleport Team getting started guide to a Teleport
Enterprise Cloud getting started guide.
- Remove other Teleport Team mentions from the docs.
* Fix the access list reminder pagination loop.
On error in the access list reminder pagination loop, the loop now breaks
instead of continuing, which is the intended behavior. A test has been added
to exercise this. This test will time out with the previous behavior. A light
refactoring has been done to make it easier to mock the ListAccessLists
response.
Users running their own Slack plugins (outside of cloud) were running into an
issue here due to the plugin user not having permissions to read access lists.
On cloud tenants, the plugins should have this access, so the impact there is
minimal.
Additionally, the docs have been updated to include the access list
permissions.
* Test fixes.
* Tests are more consistent.
* Update docs/pages/includes/plugins/rbac-with-friendly-name.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Add in initial duration/trigger.
* Output migration instructions, add jitter back in.
* Don't return error when no recipients.
* Tune the error return.
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Include Machine ID instructions in plugin guides
Closes#15062
This change incorporates Machine ID instructions into how-to guides for
Teleport plugins.
The alternative was to write a separate guide for using Machine ID with
plugins. However, the current how-to guides assume that the user is
providing long-lived credentials via `tctl`, so it makes sense to modify
the instructions in these guides. Otherwise, a user would need to get
familiar with the Machine ID guide, then work out for themselves which
parts of the how-to guides are relevant or not.
- Use a partial for the initial plugin config as well as for a Machine
ID prerequisite.
- Add partial for providing identity files via Machine ID.
- Edit impersonation partials to mention Machine ID.
- Add a `refresh-plugin-identity.mdx` partial for configuring plugins to
periodically refresh their identities.
- Make Access Request plugin guides more consistent with how they use
the identity-export.mdx partial.
* Fix "susceptible" usage
Responds to zmb3 feedback
* Respond to strideynet feedback
Change Event Handler instructions to mention the
`teleport-refresh-enabled` flag instead of a config option.
* Fix spelling issue
Make the Event Handler guides more consistent so it's easier to add
Machine ID instructions in subsequent changes (to resolve#15062):
- Extract partials for editing the config and creating an Event Handler
impersonator role, as well as starting the Event Handler.
- Add a `secret` parameter to the `identity-export.mdx` partial so we
can reuse the `kubectl` secret generation instructions across the
Event Handler guides.
* Update diagrams in the docs
Closes#31324
We introduced a new Lucidchart library for adding diagrams to docs
pages. This change:
- Replaces all MermaidJS diagrams with ones that use the new library,
which enables us to phase out the `remark-mermaid` plugin.
- Replaces some other diagrams with the new library.
* Minor tweaks to diagram images
Responds to strongeron feedback
* Add permissions for friendly names
* Only show updated permissions for Slack
* Remove duplicate impersonation instructions
* Use preview_as_roles for access plugin permissions
* Capitalize Access Requests
* Add hosted Access Request plugin docs
See #29979
For the most part, the documentation for the Teleport Access Request
plugins assumes that a user is self-hosting their plugins, and contains
information for installing and configuring the plugin that is not
relevant to a user of hosted plugins.
This change edits the menu page of the Access Request plugin subsection
of the docs to add instructions for enrolling hosted Access Request
plugins. It also adds a note to the top of each guide for an Access
Request plugin with a hosted counterpart that a user can enable the
hosted version of that plugin. This anticipates a separate change to add
more detailed instructions to the hosted Access Request plugin
enrollment workflow within the Web UI.
* Update docs/pages/application-access/okta/guide.mdx
Co-authored-by: Isaiah Becker-Mayer <isaiah@goteleport.com>
---------
Co-authored-by: Isaiah Becker-Mayer <isaiah@goteleport.com>
* Add Docker to the access request plugin partial and Discord section
* Update another partial for Docker
* Restore variable to teleport.plugin.version
* Update docs/pages/includes/plugins/install-access-request.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Use partial for Access Request plugin install docs
The Access Request plugin installation instructions are _almost_
standard. Make the instructions more consistent and easier to edit by
replacing them with a partial. Use our partial parameter substitution
syntax to supply the name of each plugin.
* Respond to alexfornuto feedback
* Add a missing `sudo`
Partially responds to stevenGravy feedback
* Add consistent Helm details
Ensure all Access Request plugin guides include the same Helm-related
steps. Excluding the Jira plugin because that guide is out of date and
will be addressed in a separate change.
Also removes the "Feedback" section from each Access Request plugin
guide. These are out of step with the rest of the docs, which don't
include a feedback section, and do not reflect the current location of
the Access Request plugin source.
* Spelling and linter fixes
unlike `tctl auth sign ... --ttl` that can take a golang duration formatted string, the `--ttl` argument for tsh is an integer in the number of minutes.
This was mainly an experiment to see how we could use partial parameters
with Mermaid diagrams, but also ensures that Access Request plugin
docs have a diagram for easier architectural understanding.
The Jira plugin works differently than the rest, so I did not include
the diagram partial.
* docs: make consistent helm configuration and instructions
* Language updates and identity file fix
* fix identity file refs
* label as Teleport Enterprise Cloud, not Teleport Cloud
See #21305
In order to standardize the docs around connecting Teleport services to
the Proxy Service, rather than the Auth Service, change Event Handler
guides to remove instructions for connecting to the Auth Service.
This includes modifying partials used by the Access Request plugin
guides so they work for the Event Handler guides as well.
* Edit cluster joining info in Access Request docs
See #21305
Edit Access Request plugin guides to remove the options to connect to
the Auth Service directly. This simplifies the guides and helps us
standardize the docs around connecting services via the Proxy Service.
Also make the Jira guide more consistent with other Access Request
plugin guides (this is not an attempt to refresh the guide, which is
still out of date, but will help us refresh the guide when the time
comes).
* Fix linter issues
* Respond to PR feedback
* 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
* 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>
We will be adding a linter rule that prohibits Details boxes that lack
titles, letting us implement the ability to link directly to a Details
box. In some places in the docs, Details boxes are used purely to
adjust the visibility of Markdown based on scope. Now that we have a
ScopedBlock component, we can use this instead.
* Edit four Access Controls guides for Cloud users
See #10638
Per-session MFA
- Add scoped Tabs to the Prerequisites section
- Add a ScopedBlock so Cloud users don't see the option to enable
per-session MFA via static config
- Minor copy-edits and organization edits. For example, turn a section
that refers to an example in another section into an Admonition.
Dual Authorization
- Add scoped Tabs to the Prerequisites
- Use a scoped Notice for the edition warning
- Style/clarity/grammar edits
- Hide the Troubleshooting section for Cloud users
Moderated Sessions
- Change the edition warning to a scoped Notice. Since this guide
is a conceptual guide rather than a step-by-step tutorial, there's no
other scope-irrelevant information to hide.
Impersonation
- Add scoped Tabs to the Prerequisites
- Used ScopedBlocks to hide minor scope-irrelevant details
- Minor style/grammar/clarity edits
* Respond to PR feedback
* Respond to PR feedback
Paul Gottschling