* 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>
* 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>
* add version compatibility callout to Cloud section
* consolidate partial usage in various guides
* remove partial consolidated into
* Apply suggestions from code review
* Add a guide to GKE Auto-Discovery
Closes#18011
* Respond to PR feedback
* Update the guide while testing it
- Add the `scopes` flag to the `gclodu compute instances
set-service-account command`
- Replace `auth_servers` with `proxy_server` in the config
* Respond to PR feedback
* Improve the Kubernetes Dynamic Registration guide
Some review comments for an earlier PR that edited the Standalone
Kubernetes guide (#18608) also apply to this one:
- Use systemctl to start TAR-based Teleport installations
- Edit the `curl` command that fetches the kubeconfig script so it uses
the Teleport release specified in the docs
* Respond to PR feedback
Closes#18304
- This applies to installing `teleport-cluster`, `teleport-kube-agent`,
and plugins, using the appropriate version variable for each.
- Some pages use the `--teleportVersionOverride` values setting instead
of `--version`. I've replaced this with `--version` for consistency.
Used this `awk` script to find `helm install` instructions that were
missing the `--version` flag:
```awk
find docs/pages -name "*.mdx" -exec awk '
BEGIN{v=0;i=0}
/helm install teleport-/{i++}
/--version \(=/{v++}
END{if(i>0 && i!=v) print FILENAME}' {} \;
```
* Make the Standalone Kubernetes guide easier to use
While following the guide, I edited it so it's easier to complete with a
fresh Linux host. More specifically, this change:
- Adds an introduction to the `kubernetes-access/getting-started.mdx`
guide that describes the setup the guide will include and
distinguishes this setup from the one in `standalone.mdx`. This also
adds a link to `standalone.mdx`.
- Makes the instructions for using `get-kubeconfig.sh` more
copy-pastable and adds context re: what the script is doing.
- Adds instructions for getting a join token.
- Adds the `install-linux.mdx` and `install-agent-cloud.mdx` partials to
the guide, editing the latter so it no longer mentions the Node
Service.
- Updates the configuration instructions.
- Adds instructions for starting the Kubernetes Service.
- Adds instructions for accessing a cluster.
Tested on Teleport Cloud v10, but I think this should work on v11+ as
well.
* Respond to PR feedback
* Respond to PR feedback
* Fix linter issues
* Add a guide to dynamic Kubernetes registration
Closes#17629
* Address PR feedback
- Add to and edit the list of dynamic resources
Closes#16247
- Describe static and dynamic labels in the `kube_cluster` resource
* 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.
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".
Fixes#11774
Ensure that all Kubernetes Access guides that include a `tsh kube`
command also include instructions for assigning a role to your Teleport
user that includes the appropriate fields.
See #12654
The Kubernetes Access section includes guides for using the Kubernetes
Service as well as guides for running the Auth and Proxy Service on
Kubernetes. This is misleading, since (a) you can run the Auth/Proxy
on Kubernetes without using Kubernetes Access and (b) you can use
Kubernetes Access without running the Auth/Proxy on Kubernetes.
This change focuses on our Helm chart references. These are not
exclusive to the Teleport Kubernetes Service, so I am suggesting moving
these guides to the /docs/setup section to make them more discoverable.
Our architecture section was written almost 5 years ago
and was completely obsolete.
I refactored all of it to be up to date, added Kuberentes
and other resource type references, replaced and created new diagrams.
See #12654
The Kubernetes Access section includes guides for using the Kubernetes
Service as well as guides for running the Auth and Proxy Service on
Kubernetes. This is misleading, since (a) you can run the Auth/Proxy
on Kubernetes without using Kubernetes Access and (b) you can use
Kubernetes Access without running the Auth/Proxy on Kubernetes.
This change focuses on our Helm deployment guides. These guides
are not related to the Kubernetes Service, but rather to deploying
the Auth Service and Proxy Service on Kubernetes. I've suggested
moving these guides to a /setup/helm-deployments section for visibility.
See #12654
The Kubernetes Access section includes guides for using the Kubernetes
Service as well as guides for running the Auth and Proxy Service on
Kubernetes. This is misleading, since (a) you can run the Auth/Proxy
on Kubernetes without using Kubernetes Access and (b) you can use
Kubernetes Access without running the Auth/Proxy on Kubernetes.
This change focuses on the pages in:
/docs/pages/kubernetes-access/getting-started/
- Move docs/pages/kubernetes-access/getting-started guides that don't
relate to Kubernetes Access out of this section, and change the
docs/pages/kubernetes-access/getting-started.mdx page to point to
the current "Agent" guide.
- Edit the "docs/pages/getting-started.mdx" menu page to accommodate the
Kubernetes guides. Previously, this page included separate links for
each edition's getting started guide. To add the Kubernetes Cluster
guide, I organized the links in the "Deploy to production" section into
a TabItem for each Teleport edition. There are separate links to the
Kubernetes Cluster guide, one for OSS users and one for Enterprise
users. These links also take users to the appropriate scope.
* Ensure tctl commands include login instructions
See #10192
Add the tctl.mdx partial or a "tsh login" command in some pages that
include example tctl commands. Note that this change does not address
SSO guides, which will be handled separately.
Where a guide requires a complete restructuring to provide full context,
"docs/pages/application-access/guides/connecting-apps.mdx", I've added
"tsh login" instruction above the first tctl command.
* Respond to PR feedback
The PodSecurityPolicy specifies `MustRunAsNonRoot` but the image runs as root.
`Error: container has runAsNonRoot and image will run as root (pod: "<redacted>", container: teleport).`
We expose the securityContext to allow forcing to run as a non-root user such as 99 (nobody) and respect the psp.
Co-authored-by: daquinoaldo <aldd@bendingspoons.com>
* Add S3:AbortMultipartUploads to AWS IAM policies
Searched for all locations where s3:ListBucketMultipartUploads is currently required and added it.
* Fix permission name (it's singular)
* 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.
* Add role notes to the teleport-kube-agent intro
Fixes#10480
Previously, the "Connect a Kubernetes Cluster to Teleport" guide
instructed the user to run "tsh kube login" to a cluster they
may not be authorized to access. This change adds explicit instructions
to authorize your user's Teleport role to interact with your cluster.
* Respond to PR feedback
Use the "view" group instead of "system:masters" in the example role.
See #11383
Help ensure that no visitor to the Teleport docs site sees content that
is irrelevant to their scope (e.g., Cloud, Open Source, or Enterprise) by
hiding scope-irrelevant content from the navigation menu and menu
pages.
For pages that aren't step-by-step guides and are meant to convey
general information about a Teleport edition, show these pages in all
scopes so users who are curious about another scope can get the
information they need.
This PR focuses on the Kubernetes Access section.
It also adds a short note at the top of the teleport-cluter Helm chart
reference that the chart supports custom agent configurations along with
the Auth/Proxy.
* feat(helm): add priorityClassName and extraLabels to kube-agent
Signed-off-by: Roman Tkachenko <roman@goteleport.com>
Co-authored-by: daquinoaldo <aldd@bendingspoons.com>
While editing guides in certain sections to accommodate Cloud users
(#10631), I introduced some inconsistencies into the way the
Prerequisites sections in these guides provide instructions for users
of Cloud, Open Source, and Enterprise Teleport.
This change adds a partial that provides tabbed instructions to users
of different Teleport editions when a guide requires a running Auth and
Proxy Service. It then includes this partial where relevant in guides
that fall under the scope of #10631.
This helps ensure that cross-edition instructions are consistent in our
guides, and makes it easier to edit additional guides to accommodate
users of different editions.
Caveats:
- Since this change covers a lot of guides, it aims to be as small as
possible. While all of these guides included links in their
Prerequisites sections, for example, replacing these links with full
instructions was out of the scope of this guide. This change should
still make it easier to make further edits, e.g., in response to
#11538.
- We still need to change other elements of some guides to accommodate
Cloud users. The current change only aims to standardize the
Prerequisites section.
Travis Rodgers