* Reorganize two Access Controls sections
Partially addresses #37558
- Remove the Kubernetes Federation guide. This is more of a side note
about `tsh login` with trusted clusters, and gets very little traffic.
Consolidate it with the trusted cluster guide, which is more popular.
This allows us to remove the "Manage Access" subsection of "Kubernetes
Access", which only contains this and the RBAC how-to guide.
- Collapse the Kubernetes RBAC how-to guide into "Manage Access" to make
it more discoverable.
- Collapse the "Configuring Access" guide for databases into "RBAC". The
section contains a single guide, so this makes the content more
discoverable.
* Respond to tigrato feedback
- Add `tsh kube login` instructions to the trusted cluster guide
changes.
* Fix linter issues
* Add a Discovery Service section
Closes#38741
Add a dedicated sidebar section for the Teleport Discovery Service.
Since the Discovery Service is a separate agent service from the SSH
Service, Kubernetes Service, etc., it makes sense to add a dedicated
section for this service. In the future, we can include configuration
guides, architecture guides, etc. in this section.
To create the new section, this change moves existing auto-discovery
guides from other sections of the docs.
* Respond to hugoShaka feedback
- Move the Kubernetes application discovery docs
- Edit the "Kubernetes Access" intro to include a link to Kubernetes
auto-discovery
* 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 template vars/functions reference
* Update docs/pages/access-controls/reference.mdx
* replace details blocks with headers
With unopened details blocks the headers cannot be directly linked to, negating their usefullness as H4s
* partial updates
* Clarify predicate language contexts
Teleport roles make use of different but similar predicate languages.
Clarify these languages by giving each one a section within the Access
Controls reference.
This also clarifies other aspects of predicates in Teleport roles:
- Explain the dot vs. bracket syntax in `external` variables
- Add a note re: OIDC claim data types
To make room for the new organization, this also changes other aspects
of the page's structure:
- Some paragraphs in the introductory section were more appropriate in
the section re: managing access to Teleport RBAC resources.
- Make the intro and title more readable.
- Move an out-of-place H3 regarding SAML to the `external` trait
section.
* Respond to lsgunn-teleport feedback
- Readability improvements.
* Respond to zmb3 feedback
- Replace "predicate" uses with more suitable terms.
- Clarify wording.
- Move the section that explains `app_labels` below the one that
explains `app_labels_expression`.
* Respond to nklaassen feedback
Restore the original label expressions H3
* Linter fixes
---------
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* Add docs to Kubernetes per-Resource RBAC
This PR adds documentation for the Kubernetes per-Resource RBAC and
supported verbs introduced in Teleport 14.
Signed-off-by: Tiago Silva <tiago.silva@goteleport.com>
* initial review
* fix lint
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* fix bad reference
* Restructure the Resource Requests guide (#31637)
Move the subsection on requesting access to Kubernetes resources to an
H3. This way, we can avoid an unslightly H6 heading. Also, since this
section relates to requesting access, not restricting access, it's more
discoverable in a separate H3.
---------
Signed-off-by: Tiago Silva <tiago.silva@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update default roles for kube-agent chart in guides/documentation to be 'kube,app,discovery'
We want users to not have problems with feature discovery of Kuberentes app discovery,
so we're making sure by default our guides tell users to enable it.
* Add missing backslash
* Add enabling of App and Discovery roles when generating token for Kube
We want users to not have problems with enabling Kuberneetes App discovery by default.
* Add test checking that we provide correct '--set roles' text in command print out.
Fix messed up spelling
add missing punctuation, fir wording
Docs: Ordered and unordered list changes for lint update (#29094)
* Ordered and unordered list chnages for lint update
* Fixes from Alex's review
Docs: numbering lint warnings batch 2 (#29093)
* Change ordered and unordered lists to squash lint warnings
* Change ordered and unordered lists to squash lint warnings
* Changes for lint update
additional lint fixes
Additional fixes for linter
* Use the examples directory for example plugin code
Also edit the Access Request plugin API guide to use this directory,
rather than having the reader copy/paste individual code snippets. This
makes the guide easier to follow, and users will have a compilable
example before they proceed through the guide.
* Run make fix-license
* Run make fix-imports
* Fix spelling
* Run go mod tidy
* Extract Access Request plugin example to partials
This way, we can reuse the actual program in the Access Request plugin
API guide and avoid unintended discrepancies and drift.
* Use types.Events.NewWatcher instead of watcherjob
Need to test this out, but it compiles
* Remove outdated information
- Types that are no longer reachable via public interfaces
- The description of the demo implementation that used the old
`watcherjob` package
* Update text to reflect new `run` logic
* Make the example program more modular
Respond to Joerger feedback
* Respond to alexfornuto feedback
* Apply suggestions from code review
Co-authored-by: Brian Joerger <bjoerger@goteleport.com>
* Respond to zmb3 feedback
- Split up "types.go". Reserve a single file for configuration values so
these are visible in a single place within the guide.
- Return an error on an unsuccessful HTTP request when creating or
updating a row
- Simplify requestStates lookup
- Clearly mark values that a user must change
- Update the text of the guide to match changes to the program
* Spell fixes
* Respond to zmb3 feedback
---------
Co-authored-by: Brian Joerger <bjoerger@goteleport.com>
Machine ID is often a better option than `tctl auth sign` when
Teleport certificates are required for automation purposes.
This commit mentions Machine ID as an option in several areas
where we currently recommend the tctl approach.
In the future, we should update some of these guides (or make new
ones) to list Machine ID as the primary approach, but that's a larger
change and I wanted to get something out that can highlight Machine ID
as an option right away.
* update tctl partial format
* standardize cloud warning in cluster guides
* standardize prereqs in machine id guides
Also uncomments a video block that was never made available once the video was created
* cleanup partial
* standardize prereq partial use throughout
* add partials to more guides
* linter fixes
* Support spellchecking in docs content
In gravitational/docs#261, we will add a script that checks the spelling
of each version of the docs. This change edits one version of the docs
content to support this, including:
- A cspell configuration file
- A new step in the GitHub Actions in the "Lint (Docs)" workflow that
runs the spellcheck script we will add in `gravitational/docs`
- Fix mispellings so this passes the lint job. The mispellings are in a
file that we generated automatically, but there are few enough of
them, and we haven't merged the auto-generation script yet, that I
think it makes sense to fix them in the generated file for now.
* Respond to PR feedback
- Remove misspellings from the ignore list
- Sort the ignore list (and format it via prettier)
* Use the new yarn spellcheck command
* Spelling fixes
* spell fixes and add words to cspell.json
---------
Co-authored-by: Steven Martin <steven@goteleport.com>
* Add a guide to creating Teleport roles via the API
See #19716
This guide uses a small demo application to show how to create Teleport
roles based on an external RBAC system. The demo revolves around a local
`minikube` cluster. I chose this approach because Teleport works well
with Kubernetes RBAC, and Kubernetes RBAC resources are pretty
straightforward to set up locally.
* Based the guide on a program in the examples dir
* Respond to zmb3 PR feedback
* Run make fix-license
* Respond to PR feedback
* Respond to alexfornuto feedback
* Add a guide to using the API for auto-discovery
See #19716
Adding resources is a popular use of Teleport's API, so I have added a
guide to using the API for syncing resources to a service discovery API
using an example of a local Docker setup.
* Respond to zmb3 feedback
* Use the examples directory for the code
This way, users can have a compilable example before they start working
through the guide.
* Respond to alexfornuto feedback
* Respond to PR feedback
* Run make fix-license
* 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
Our API module is not currently versioned to align with Teleport
major versions, but it's important for developers building integrations
to use a verison of the API that is compatible with their cluster.
Include a short snippet that can be used to identify the correct
version string to place in go.mod given a particular tag.
* Reorganize early-stage docs sections
Closes#18127
Currently, there are two sections of the docs related to the earliest
stages of setting up Teleport, "Try out Teleport" and "Deploy a
Cluster". While the organization of our top-level docs sections attempts
to correspond to the stages a user goes through when setting up
Teleport, these combine some tasks that should probably be separated:
- **Choosing an edition and deploying a production cluster**: While the
"Deploy a Cluster" section includes our deployment guides as well as
our edition guides, user will likely commit to setting up Teleport
Cloud, Open Source, or Enterprise before they plan a full HA
production deployment.
- **Deploying a production cluster and deploying a small-scale Teleport
cluster:** While the "Deploy a Cluster" section includes the Linux
Server and Digital Ocean 1-Click guides, these two guides are more for
small-scale deployments than full production clusters.
This change improves the early-stage docs experience for new Teleport
users by:
Splitting the "Deploy a Cluster" section
----------------------------------------
The "Deploy a Cluster" section includes subsections related to choosing
a Teleport edition as well as subsections related to deploying a
production cluster. The problem with this approach is that it leaves no
room for adding introductory guides to help users with these two
purposes.
By splitting the "Deploy a Cluster" section into two top-level sections,
one related to choosing an edition and the other to dpeloying to
production, we can add introductory pages that put the subsections of
these sections in context.
_This change accompanies the work on #16751 to write a general guide to
HA Teleport deployments, since the new guide will have a prominent
place in the reorganized "Deploy a Cluster" section._
Adding introductory pages
-------------------------
Sections related to getting started with Teleport, "Try out Teleport"
and "Deploy a Cluster", were missing introductory pages. This change
adds them, and also adds one to the new "Choose an Edition" section.
Moving the Linux Server and Digital Ocean guides
------------------------------------------------
Move these to "Try out Teleport". The Digital Ocean guide didn't fit
with the rest of the deployment guides, since it's not about
architecting an HA deployment.
This is also a better home for the "Linux Server" guide, so this change
moves that as well.
Removing the "getting-started.mdx" page
---------------------------------------
This page is not reachable via the navigation menu.
* Respond to PR feedback
* Respond to PR feedback
Also minor text tweaks
* 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>
Gavin Frazar