* Provide more context in the docs intro page
Closes#22469
The current docs landing page does not include enough context for new
readers. After the general description of Teleport, the rest of the
landing page is series of links, with little guidance for what a new
user should do first (or what an intermediate user should do after
completing the initial setup steps).
This change takes a more narrative approach to the landing page,
briefly describing the content of each top-level docs section and
putting it in context with the rest of the docs. This also helps users
find the right top-level docs section for their needs, since otherwise
the only way to do this is to visit each section.
This change is also more opinionated about which guide new users should
begin with. It recommends the guide to getting started with Teleport
Cloud, since this doesn't require setting up a Teleport cluster and
helps a user register a resource quickly.
The landing page links to the introduction page of each top-level docs
section. If a section does not have an introduction page, this change
adds one.
* Respond to zmb3 feedback
Reorder list items
* Linter fixes
* Respond to alexfornuto PR feedback
* Add GCP Service Account parameter to tctl users add reference
Only applies to master and branch/v12
* Moved azure identities parameter next to other cloud apis ones
Only proxy, node, auth, db, or app are applicable roles. Windows desktop and kube are not supported roles with `teleport start --roles=...`. The default roles if none is specified is proxy, node and auth.
Previously the tokens add would show the command to include these as a role. That was incorrect and has been corrected.
* Reorganize the config reference
Closes#11253
This change breaks up the config reference by moving each Teleport
service's configuration settings into a separate YAML snippet, and
organizing each YAML snippet into a `TabItem` within a `Tabs` with
`dropdownView` enabled. When Teleport Enterprise Cloud doesn't support a
service, this change adds a `Notice` with a message about Teleport
Enterprise Cloud in the relevant `TabItem`.
I thought this approach would be cleaner than alternatives:
- **Including an H2 for each service:** With this approach, the
configuration reference would be even longer than it is now. With the
approach I'm proposing, readers would navigate to "Reference
configurations", then choose a service from a dropdown menu: much less
scrolling for slightly more clicking.
- **Including another set of `TabItem`s for Teleport editions:** I
thought about adding a `Tabs` with a dropdown option for each Teleport
edition and a horizontal `TabItem` for each service, but this would
require horizontal scrolling and doesn't scale very well.
- **Including horizontal tabs for each Teleport edition**, with an inner
dropdown menu for each Teleport service: There is currently no way to
do this without multiple `Tabs` components, which gets messy quickly.
**Note** that this change does not attempt to copy-edit comments/example
values within the configuration snippets. The scope of this change is
limited only to reorganization.
* Respond to PR feedback
* Update docs/pages/includes/config-reference/instance-wide.yaml
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Respond to PR feedback
Use headings instead of `TabItem`s to split up sections of the config
reference.
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Adds `kubernetes_resources` references
This PR adds references to Role `v6` in `Role Versions` and updates the
Terraform docs to include the new Role's field `kubernetes_resources`.
It also fixes a typo in Helm chart guide.
Fixes#21889Fixes#22117
* Update docs/pages/reference/terraform-provider.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update docs/pages/reference/terraform-provider.mdx
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
---------
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* add device spec docs
* format specifics of key
* add yaml tag
* add collected data
* cli ref update
* Update docs/pages/includes/device-spec.mdx
Co-authored-by: Alan Parra <alan.parra@goteleport.com>
* update example
---------
Co-authored-by: Alan Parra <alan.parra@goteleport.com>
* Add more info re: AWS credentials to the docs
Closes#2781
- Add a partial for how to provide credentials to Teleport's AWS client.
Since this includes adding environment variables to the file used by
our systemd service, I also created a partial re: how to configure
Teleport's systemd service and added these two partials to the
relevant guides.
- Removed `Admonition`s that link to the docs re: AWS credentials in
favor of the partial above. (The partial links to the Go SDK for AWS
docs for situations where users have a specific use case.)
- Remove mentions of the AWS credential-related config settings from the
Backends reference. The example config snippets don't actually include
the `access_key` and `secret_key` settings, so these are left over
from an earlier version of the guide. While you can still add these
settings to a config file, I thought it would make sense to leave them
undocumented since using an EC2 instance, environment variables, etc.
is the recommended approach.
- Split the S3/DynamoDB sections of the Backends reference into
subsections so the extra authentication info fits a bit better.
* Respond to PR feedback
* Add new partials to the RDS Proxy guide
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>
* helm: allow to set `initSecurityContext` in `teleport-kube-agent`
* Apply suggestions from code review
Co-authored-by: Gus Luxton <gus@goteleport.com>
* fixup! helm: allow to set `initSecurityContext` in `teleport-kube-agent`
---------
Co-authored-by: Gus Luxton <gus@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>
* helm: disbale PSPs on 1.23 and document PSA usage
In 1.25 Kubernetes removes PSP support, this has 2 consequences:
- Helm will break after upgrading if PSPs are deployed
- We cannot set security policies anymore
This commit documents those two behaviours and makes the chart disable
PSPs on 1.23 and higher to ensure a smooth upgrade path.
* helm: Remove stale 'migrate from legacy charts' guide
* Remove Auth/Proxy instructions from DB guides
Closes#11538
A number of our Database Service guides instruct the user to install the
Auth Service and the Proxy Service. For users who have already set up
these services, these instructions add friction. For users who have
_not_ set up these services, Teleport has existing instructions that
users can follow instead.
This change edits our Database Access guides to require the user to have
a running Teleport cluster as a prerequisite, in line with how-to guides
in other sections of the docs.
Note that, while the issue this change closes is to add Auth/Proxy
Service setup instructions to _more_ places in the docs, this change
follows our style guide recommendation (#20024) to add steps to the
Prerequisites section if we have them documented elsewhere and they
don't directly pertain to the goal of a how-to guide.
* Respond to PR feedback
Change H3s to H2s
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Document Google Cloud CLI access
Closes#17584
- Add a guide to configuring and using Google Cloud CLI access via the
Teleport Application Service.
- Since we now have three guides to setting up secure access to cloud
APIs, create a new subsection of the "Application Access" docs section
related to cloud provider APIs.
* Respond to PR feedback
- Capitalize "JSON Web Tokens"
- Edit the AWS guide's nav bar entry
- Fix garbled section in the App Access intro page
- Improve the service account name we use in the how-to guide
- Clarify the way the App Service uses a service account
- Add new env vars to the `tsh proxy` command output
- Other small changes in response to suggestions/comments
* Edit instructions for starting the VM
Add instructions to launch a new VM with a service account attached.
This addresses feedback on the PR.
* Use more precise terminology for service accounts
This addresses feedback on the PR
* Add information about `tsh gsutil`
This adds to both the Google Cloud API access how-to guide and the CLI
reference.
* Respond to PR feedback
* use nobr tags
* fix multiline command
---------
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* Add device trust documentation
* Link to Device Trust from Access Control pages
* Document `device_trust` authentication section
* Document the `tsh device enroll` command
* Document `tctl devices` commands
* Review: Explain macOS restriction in text
* Review: Address Alex's comments
Indents, markdown style, code block style, punctuation and missing
words.
* Review: Use diff blocks on `tctl edit` example
* Review: Use diff blocks in other examples
* Review: Use standard example names
* Review: Address Alex's comments (2)
Uppercase SERIAL, macOS enroll notice, config example tabs.
* Review: Sort `tctl devices` commands alphabetically
* Review: Use config variables for asset_tag and enroll_token
* Review: Remove '#' from code blocks in cli.mdx
* combine warning and ScopedBlock
A ScopedBlock for OSS will never render on a page not scoped for OSS. This way, it's always visible. Once the feature is out of preview, we can just remove the first line.
* clarify device trust between trusted clusters
This addition dispells any assumptions made by the reader that applying device trust to root clusters would enforece the setting on leaf clusters.
* update enterprise tctl version output
---------
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* docs: remove references to old Teleport versions
With the release of Teleport 12, the oldest supported version of
Teleport will be Teleport 10. This commit removes some references
to Teleport 7 and Teleport 8. The docs for those versions are no
longer available on goteleport.com, so it's safe to assume that
readers are on a more recent version.
* Update docs/pages/management/guides/joining-nodes-aws-ec2.mdx
---------
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
This change adds support for FIDO2/webauthn/hardware tokens by default.
OTP 2fa fill remains functional. This is a major change and should be
part of a major release, even if this should be seamless for most users.
Warning: `webauthn.rp_id` should not change in the cluster life, else
2fa tokens will have to be re-registered.
Users accessing the cluster under a different name than `clusterName`
will have to set rp_id
(`auth.teleportConfig.auth_service.authentication.webauthn.rp_id`) to be
able to register second factors. As we strongly encourage users to have
a resolvable `clusterName` and `publicAddr` support got added recently,
this seems an acceptable edge case.
This commit implements arbitrary configuration passing to Teleport, like what was done for the `teleport-cluster` in https://github.com/gravitational/teleport/pull/18857. This allows users to deploy services or set fields the chart does not support.
The huge snapshot diffs are caused by order changes in the config (the YAML export orders keys alphabetically). I validated that the old and new snapshots were strictly equivalent with the following python snippet:
```python
import yaml
import pathlib
import deepdiff
old = yaml.safe_load(Path("./config-snapshot.old").open())
new = yaml.safe_load(Path("./config-snapshot.new").open())
old_content = { k: yaml.safe_load(yaml.safe_load(v[1])["data"]["teleport.yaml"]) for (k,v) in old.items() }
new_content = { k: yaml.safe_load(yaml.safe_load(v[1])["data"]["teleport.yaml"]) for (k,v) in new.items() }
diff = deepdiff.DeepDiff(old_content, new_content)
print(diff)
```
This commit adds a certificate reloader that periodically reloads proxy
certificates.
Implementation was intentionally kept as simple as possible:
- periodically go through all key pairs and try to load them again
- if any key pair fails to load, then no certificate is updated
- no retry mechanism
- `inotify` is not used
The interval between reloads is configurable by setting
`https_keypairs_reload_interval` to some duration. If not set, or if set
to `0`, then certificates are not reloaded periodically. Thus, this
feature is opt-in and the current behaviour is maintained.
* Update etcd backend docs to include recommendations
- Update links to currently maintained docs
- Include link to hardware recs including mentioning storage
* Describe enabling services in the config reference
Closes#4214
Add a section to the configuration reference indicating which Teleport
services must be enabled/disabled explicitly so they run when Teleport
starts.
The configuration reference wasn't divided into H2s before this, so I
have organized the long Admonition that begins the section into H2s as
well.
* Respond to PR feedback
Co-authored-by: Steven Martin <steven@goteleport.com>
* Add a guide to exporting events to Splunk
Closes#13158
Since there are multiple guides to exporting audit events now, this also
adds a new section of the docs for these guides.
Also fixes a tiny error in the Elastic Stack guide.
* Respond to PR feedback
* Fix linter issues
* Respond to PR feedback
- Use consistent naming
- Mention the `--ttl` flag for `tctl auth sign`
- Mention Machine ID
- Add a quick Troubleshooting section
- Fix `chmod` command
- Add systemd configs (also added this to the Elastic Stack Event
Handler guide. I didn't do this to the Fluentd guide because the
structure of the guide is different from the Splunk guide's).
* Document Azure CLI access
Closes#17583
- Create a guide to Azure CLI access
- Update references to reflect changes to roles, commands, and the file
config
* Respond to alexfornuto feedback
* Add a section to the guide on `tsh proxy azure`
* Respond to smaller feedback items from Tener
* Switch the order of role approaches
Responds to one item of feedback from Tener.
* Respond to zmb3 feedback
* Document new behavior
- Wildcards in `deny` rules
- The `tsh proxy az` alias
* Add SSO instructions for defining a role
* Update env var values
* optimize images
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
* Add a glossary of Teleport terms
Closes#16121Closes#13363
- Create a Core Concepts page based on the Architecture Overview page.
The Overview page is an outline of core concepts, so I thought it
would make a good starting point for the glossary.
- Add the Core Concepts page to the Home section to make it more
prominent for users who are visiting the docs homepage. This should
give it more traffic than leaving it in the Architecture section.
- Move definitions out of the "Definitions" table. Since this table
repeats content from the body sections and comes after them, it makes
sense to condense all content into brief body sections.
- Alphabetize sections
- Bold the first instance of each keyword within a given section. Not
adding links since these are all to the same page. It might get a bit
confusing to click a link and not see a change in view, since the
target section would already be on the page.
- Remove the intro paragraph of the old Overview page, since it's not
strictly related to core concepts.
* Respond to PR feedback and add further edits
- Group definitions into H3-level sections organized into H2s, improving
readability by presenting the more central components first.
- Group "Machine ID" with "Teleport Services" to simplify the glossary.
- Call instances of a Teleport Service an "agent". This is consistent
with our source and informal language about Teleport. This also
removes the "Node" terminology, which is prone to misuse (does it mean
"a Service instance"? An "SSH Service instance"? Both are present in
the docs) and easily confused with the lowercase "node" (i.e., a
host).
- For simplicity, remove the term "Teleport Process" and simply explain
that multiple Teleport Services can run via the same binary.
- Add a section on Teleport's editions, including the terms "Community
Edition", "Enterprise", and "Enterprise Cloud".
- Remove the mention of Teleport Discover, which isn't documented yet.
- Minor wording/readability changes.
* Respond to PR feedback
* Respond to zmb3 feedback
* Update config.mdx
Update permit_user_env config reference comments to indicate that the ~/.tsh/environment file exists on the SSH server and not the client side. This caused confusion with users attempting to pass variables to sessions via the client.
* Update docs/pages/reference/config.mdx
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
* Update config.mdx
* Update docs/pages/reference/config.mdx
Co-authored-by: Gus Luxton <gus@goteleport.com>
Co-authored-by: Zac Bergquist <zac.bergquist@goteleport.com>
Co-authored-by: Gus Luxton <gus@goteleport.com>
- Fix an incorrect link
- Be more specific about what roles/permissions are required
- Remove some text and an image that didn't meaningfully contribute
