* Add steps to create machine-id data dir and systemd enablement
* verbiage update
Co-authored-by: Noah Stride <noah.stride@goteleport.com>
* Change daemon-reload to enable for systemctl
---------
Co-authored-by: Noah Stride <noah.stride@goteleport.com>
An issue with `gravitational/docs` caused the docs linter to stop
catching issues for a period of time. Now that we have addressed the
linter issue, this change addresses warnings/errors flagged by the
linter.
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* 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>
* spag changes
* Use `tctl` partial
* Further readability changes
* "we" -> "you"
* Further succincty
* Adjust referneces
* show format
* Finaly few copy fixes
* missing y
* Update docs/pages/machine-id/guides/github-actions-kubernetes.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Clarify Teleport user privs
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Fix Teleport version
* Update GitHub actions guide with new actions and GHES support
* Fix SPAG
* Add note on ommitting -i
* Changes notes order to make things make more sense
* Apply suggestions from code review
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
* More spag tidying in github actions article and removed some chaff
* Fix SPAG
* Introduce next steps sectionm
* Add missing hyphen
* Move Enterprise instructions to tabbs
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
This addresses some observations from @stevenGravy about a couple places
in the docs where Enterprise-specific installation steps are missing.
- Edit the Machine ID Getting Started guide: Use the `install-linux.mdx`
partial for download instructions, since these include instructiosn
for Enterprise users.
- Add Enterprise instructions to Helm guides that only include OSS
installation instructions.
Closes#9683
To reduce confusion, we should use "set up" as a verb, rather than
"setup", and treat "setup" only as a noun.
Note that one use of the term "setup" as a verb is in the Jira Server
guide, which #17546 intended to remove, but neglected to. This change
removes that instance of "setup" along with the rest of the surrounding
guide.
* Note that GH Actions support includes self-hosted runners
* Update docs/pages/machine-id/guides/github-actions.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Minor tweaks for GitHub Machine ID integration docs
* Update FAQ section on Machine ID CI/CD
* Add handy dandy version warning details
* Fix capitalization of link
* Fix readability of initial sentence
Actual LimitNOFILE varies greatly between the systems as it depends on the
systemd version and the go version used to build Teleport. The goal of this
commit is to run Teleport in the same setup, regardless of the distro nor
Teleport version.
New systemd defaults are 1024:524288, and starting with go 1.19, go process can
increase their soft limit up to the hard limmit dynamically. Old systemd
versions don't suppoprt `soft:hard` notation and old go versions don't
automatically increase up to the hard limit. For this reasons, the most
compatible setting is to set softlimit=hardlimit=524288.
* Add architecture guide for Machine ID
* Adjust indentation per linter rule
* Update docs/pages/machine-id/architecture.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/architecture.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/architecture.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/architecture.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Add section on joining and renewable certificates
* spag
* Add notes on bot creation, user and token.
* Clarify bot destination configuration
* Adjust indentation
* Start fleshing out notes on file permissions
* Finish filesystem permissions section
* Update docs/pages/machine-id/architecture.mdx
Co-authored-by: Tim Buckley <tim@goteleport.com>
* Address Tim's PR comments
* spelling correction
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address a few docs structure comments
* Furth restructure architectural guide
* spag
* Avoid using the "static" terminology in reference to tokens.
* appease linter no-heading-punctuation
* Use paragraphs rather than ordered list for tbot actions
* Add notes on "destinations"
* Improve the way that the tbot section reads
* Add notes on daemon vs oneshot.
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Tim Buckley <tim@goteleport.com>
* 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
* Move Machine ID support matrix into the introduction page
* Link to Machine Id specific guides in support matrix
* Add Machine Id guides to introduction page
* Move machine id guides to includes
* Fix links to guides
* Remove already-answered question from FAQ
* Add Machine ID Kubernetes guide and partial Apps guide
* Small wording tweaks to the k8s guide
* Rename menu titles to match convention
* Fix inaccurate CA cert recommendation on the API access guide
* Tidy up the Kubernetes guide
* Finish up first pass on Apps guide
* Remove empty admonition
* Address review feedback
* Fix doctest lints
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address a batch of review comments
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address further review comments
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Support user traits in impersonated role certificates
* Add param to tctl bots add for specifying logins
* Update comment on desiredAccessInfoForRoleRequest to be mroe accurate
* Update docs for --logins support with Machine ID
* Rearrange bot tests and name them more in-line with standards
* Add test coverage for Server.createBot
* Test role impersonation preserves user traits
* pass traits directly into desiredAccessInfoForRoleRequests
* Drop underscores from test names
* Remove unnecessary initialization of traits
* Address PR comments
* Update docs/pages/machine-id/getting-started.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/getting-started.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/machine-id/getting-started.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
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.
* Add FAQ and Troubleshooting docs for Machine ID
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address feedback on the troubleshooting guide
* Address review feedback
* Resolve doctest failure
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
This changes tbot's configuration to access the token via a
getter/setter instead of a direct property, to allow us to fetch the
token (possibly reading it from a file) when we need it instead of when
the configuration is created.
This also changes the identity fetching logic, to try and read the token
when there is an identity present but not error, allowing for the token
file to have been deleted between restarts. If it can read the token,
it'll check to see if it has changed and refetch the identity if so.
* Added Machine ID and Web Apps Guide.
Co-authored-by: Tim Buckley <tim@goteleport.com>
* Update reference pages with latest v9.3 content
Also, update the mongodb example
* Address review feedback
* Remove unfinished though and fix a few typos
* Tweak wording for the webapps guide
Also, fix broken lints in the go examples.
* Fix Postgres example
* Rename "webapps" guide to "database" guide (with custom app)
* Apply suggestions from code review
Co-authored-by: Noah Stride <noah.stride@goteleport.com>
* Address review feedback
* Fix go.mod issue breaking linter, remove duped postgres library
* Fix broken links
* Rephrase the final sentence a bit.
* Update docs/pages/machine-id/guides.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* First batch of review feedback
* Apply more suggestions from review
* Restore original go.sum / go.mod
* Show different version requirement text for cloud vs OSS/enterprise
* Add small note about `tbot db` limitations
* Add new Machine ID / Database Access diagram
* Fix lint errors
* Fix broken link
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Address review feedback
* Fix whitespace
* Address review feedback
* Update docs/pages/machine-id/guides/databases.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
Co-authored-by: Russell Jones <rjones@gravitational.com>
Co-authored-by: Noah Stride <noah.stride@goteleport.com>
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Add context to "tsh ls" in docs
Fixes#7051
- Create a partial for how the Teleport Auth Service filters Nodes
based on user roles/logins in response to queries.
- Add the partial to provide context for example commands that include
"tsh ls".
- Make our existing text on Teleport's authorization checks clearer
by enumerating the checks in the order they are executed in
services.RoleSet.CheckAccess.
Note that this does not change guides that instruct the user to create
a new user and role, since a user following these guides will see the
correct "tsh ls" output.
* Respond to PR feedback
* Edit the Machine ID getting started guide
Fixes#11806
- Add more scope-specific information to the Prerequisites section
- Add the tctl.mdx partial to make it clearer for each scope how to
connect to the cluster to run tctl commands.
- Add the Cloud tenant address to the "tbot start" example command for
Cloud users.
* Respond to PR feedback
* Fix resource links
Fixes#12839
Some video links still refer to the outdated "/teleport/" path.
This change adds the videos these links refer to to the "img"
directory and updates the links.
Note that two of the three MDX files that are changed here do not
actually render the video. I've changed the links here anyway in
case someone uses these as a reference for the link format.
* Apply suggestions from code review
Co-authored-by: Ben Arent <ben@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
Co-authored-by: Ben Arent <ben@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* 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.
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.
