* Promote IAC docs for agents and dynamic resources
Closes#27382Closes#25418Closes#25442
Two aspects of setting up a Teleport cluster are omnipresent in the docs
but never get dedicated treatment:
- Running agents
- Applying dynamic resources
As a result, it is difficult to include discussions about those topics
that are separate from a specific workflow or how-to guide. One glaring
absence has been prominent guidance on using infrastructure-as-code
tools to achieve these tasks.
This change improves the visibility of Teleport's support for
infrastructure-as-code tools by:
- Creating top-level docs sections for running agents and applying
dynamic resources
- Making IAC instructions prominent within these sections
The intention is for readers to become familiar with different methods
of applying dynamic resources and running agents, including how to do
this with IAC, so they can apply this knowledge when reading other parts
of the docs.
As a result, in the docs sidebar, the "Dynamic Resources" section comes
before the section on RBAC, and the "Teleport Agents" section comes
before the sections related to individual Teleport services
("Application Access", "Server Access", etc.).
The new section on dynamic resources also gives us a place to put other
guides to using the Terraform provider and Kubernetes Operator, e.g., if
we add guides to using these tools with popular GitOps platforms.
Likewise, the section on agents gives us a place to put other agent-wide
information, e.g., how to enable an additional Teleport service on an
instance that is already running.
To allow for these changes, I have also made the following, more
tangentially related sidebar changes:
- **Renamed sidebar sections to be noun phrases instead of verb
phrases:** Currently, one half of the sidebar is made of imperative
phrases like "Manage Access" and "Manage your Cluster". This doesn't
really work for the sections on agents and dynamic resources, so I
have renamed these sections for consistency.
- **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I
have arranged the sidebar so more basic topics (i.e., those that new
users and experienced users alike will need to be familiar with) are
on the top and more advanced ones are on the bottom.
The other sections that are currently in the first half of the sidebar
are topics that all Teleport users will need to get familiar with,
while day two operations and self-hosted production deployments are
more advanced topics.
- **Edited the landing page:** I have edited the landing page of the
docs to reflect the new sidebar organization. This also makes the page
shorter, simpler, and more opinionated. It spells out a high-level
sequence for setting up Teleport, then provides a list of advanced
topics for further reading.
Links correspond to sidebar sections--as before, I wanted to describe
the topic of each sidebar section so users would know this information
without having to navigate away from the landing page.
* Move the "Dynamic Configuration" section
Make this a subsection of "Manage your Cluster" since it's not
self-evidently clear as a top-level docs section. Users will probably
need an introduction via the "Manage your Cluster" section intro page.
This also reverts some of the more drastic sidebar changes introduced by
the previous commit.
Responds to xinding33 feedback.
* Make IAC learning tracks prominent/hard to avoid
Closes#27751
Responds to xinding33 feedback
The motivation is to be more opinionated about the course that users
take through the docs. We currently recommend two tracks for
self-service users, i.e., the users expected to make use of the landing
page:
- Setting up a toy self-hosted Teleport cluster
- Setting up a Teleport Team/Enterprise Cloud cluster that can
eventually become production ready
By moving the "Get Started" guide to the landing page, we direct users
immediately on to the first track. This change then gives new users a
way to enter the second track from the docs landing page with a
prominent link to the Teleport Team docs.
This change also edits The landing page to direct users who have
completed the getting started experience to instructions for setting up
a pool of agents on Terraform, helping to make infrastructure-as-code a
first-class citizen of the docs.
This change also removes the menu of links that used to confront users
on the landing page. Since all sidebar sections include introduction
pages, users interested in the content of a sidebar section can visit
the section. By removing links, we make it clearer for users how to
proceed through the docs.
* Fix linter errors
* Incorporate Trivy recommendations
* Respond to alexfornuto feedback
* Restore list of dynamic resources to the reference
* Fix linter warnings
* Remove the ".sh" extension from userdata script
The Terraform module that reads this file does not need the extension,
which was causing trouble for our shellcheck linter.
* Fix Helm chart Join token secret creation
Since #20763 was merged, we lost the ability of the chart reusing the
externally created secrets for join token.
This PR changes the logic and allows to control the secret creation
using the `joinTokenSecret.create` boolean and the secret name with
`joinTokenSecret.name`.
Fixes#20763
* Add changelog
This change makes the experience of getting started with Teleport more
opinionated and more precisely molded around our intended audience. The
assumption is that people who want to go through our getting started
experience are skilled technologists who:
- Are curious about how Teleport works and want to tinker with a toy
cluster
- Need to set up a production cluster in order to protect their
infrastructure, in which case a toy cluster is less important than a
way to get started with the real thing
Promote the "Linux Server" guide
--------------------------------
Make the "Linux Server" guide the definitive introduction to OSS
Teleport by removing other "Try out Teleport" guides and moving this one
to the "Home" section. We want to remove the need for users to decide
which getting started guide to try, and this guide is the only one that
lets users spin up a fully fledged demo cluster besides the Digital
Ocean guide.
To let users know about the DigitalOcean 1-Click droplet, this change
links to our DigitalOcean 1-Click app from within the Linux Server
guide. It also advises users who don't meet the Linux Server guide
prerequisites to sign up for a Teleport Enterprise Cloud free trial.
This change also removes the Docker guide and redirects Docker-related
traffic to the Installation page, since the Docker guide is more of a
Getting Started guide than an integration guide, and our Installation
page already includes Docker setup information.
Edit the Linux Server getting started guide
-------------------------------------------
- Remove Application Service instructions, since it can turn off users
who, for example, don't use Python or don't want to run the
Application Service (plus we already mention it at the end of the
guide for users who do want to run this service).
- Update installation instructions to use our one-liner.
- Make this guide more explicitly focused on the Open Source edition,
removing Enterprise instructions. Users who want to tinker with
Teleport will not be interested in the Enterprise edition.
- Add session recording instructions. Most of the content of the Linux
Server guide has to do with setting up Teleport, rather than seeing
Teleport features, so I wanted to adjust this balance a bit.
- Remove the permission warning. It takes up around 1/4 of the screen
height when viewing the page, and we expect our intended audience to
know this information already.
Change the Enterprise information architecture
----------------------------------------------
- Remove the Enterprise "Getting Started" guide: This guide shows you
how to deploy a demo Teleport Enterprise cluster, which is sort of a
contradiction in terms. Enterprise users expect a production-grade
cluster, which is not what you get in this guide.
- In the Enterprise Introduction page, include instructions to read the
Deployment Guides, which show how to set up a mature HA deployment,
plus a recommendation to use Teleport Enterprise Cloud unless you need
the Enterprise-specific features explained in this guide.
* Change Helm reference `--set` formatting
Closes#9686
Since the `--set` flag examples aren't commands, this change removes the
shell prompts and changes code fence labels from `code` to `text`.
* Remove --set examples from Helm references
Keep the values.yaml examples. Used the following script to generate the
change:
files="$(find docs/pages/reference/helm-reference -name "*.mdx")";
for i in $(echo "$files"); do
tmp=$(awk 'BEGIN{yaml=""}
/<Tabs>/{t=1}
t==1 && /```yaml/{y=1; yaml="`values.yaml` example:\n\n"}
y==1{yaml = (yaml "\n" $0)}
y==1 && /```$/{y=0; print yaml; yaml=""}
t==1 && /<\/Tabs/{t=0; next}
t==0{print $0 }' $i)
echo "$tmp" > $i;
done
* Add docs subsection about joining services
Closes#21851
Also see #21305
Restructure the "Adding Nodes" guide to make joining Teleport processes
via the Proxy Service the default approach. Make it easier for users to
put these instructions in the context of our other joining methods by
creating a separate docs subsection for our joining guides.
This change also updates the previous "Adding Nodes" guide based on
testing.
This also renames "Node" to "Teleport process" and clarifies the
distinction between running a Teleport process and running services on
the process.
* Respond to zmb3 feedback
* Respond to alexfornuto feedback
* Improve the "Join Token" guide descriptionA
Makes this guide consistent with
df3e36e49e
* Move the Kubernetes guide
* Fix spelling
* Linter fixes
In gravitational/docs#238, we will add a linter that lints for incorrect
usage of Teleport terms. This change fixes linter violations to
anticipate this new linter.
Changes include:
- Ensuring that Teleport service names are capitalized
- No longer using the "[Resource] Access" terminology. Instead, talk
about adding resources, using Teleport services, etc.
* 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>
* helm: add updater support to `teleport-kube-agent`
* fixup! helm: add updater support to `teleport-kube-agent`
* Apply suggestions from code review
Co-authored-by: Marco André Dinis <marco.dinis@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* address review feedback
* Fix rebase?
* Fix linter
---------
Co-authored-by: Marco André Dinis <marco.dinis@goteleport.com>
Co-authored-by: Roman Tkachenko <roman@goteleport.com>
* helm: Add support for imagePullSecrets to teleport-cluster chart
This was added to the teleport-kube-agent chart in #6941 but for some reason we never added it to teleport-cluster. This PR rectifies that.
* Add imagePullSecrets to teleport-cluster chart reference
* 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
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>
* 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>
* 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)
```
* 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>
* Update the teleport-kube-agent reference
Fixes#17578
Document values fields and behavior introduced by #13942.
Since the teleport-kube-agent chart now deploys more resources--and
deploys them based on more sophisticated logic--this change lists the
resources deployed by this chart and describes the conditions in which
this chart deploys them.
* Respond to PR feedback
- Fix the legacy behavior description at the top of the refernece. Also
add this to its own H3 since it is getting a bit lengthy.
- Note that *-hook resources are removed after the upgrade finishes.
- Note that `serviceAccountName` is deprecated and expand the
`serviceAccount.name` entry a bit.
- Add a note re: storage not being required to the "New chart
installations" section.
- Clarify `storage.enabled` in relation to upgrades
* format tables
* add br tags to service table
In order to display the service name without a line break mid-word.
* adjust br tag placement
To avoid breaking the first column
Co-authored-by: alexfornuto <alex.fornuto@goteleport.com>
Closes#14578
The Jira Cloud guide applies to all Jira deployments already, so we
don't need to maintain separate guides. This change renames the Jira
Cloud guide so it's about Jira in general.
* Add callouts to docs and Helm values for Kubernetes 1.23+ on EKS
Kubernetes 1.23 introduced a requirement for EKS clusters to use a CSI (container storage interface) driver addon to provision EBS volumes as persistent volumes. Kubernetes 1.23 is now the default for new EKS clusters and since our chart uses persistence in its default mode, it will fail to deploy on EKS without this additional driver being installed.
* Apply suggestions from code review
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Update teleport-kube-agent readme
* Add values.yaml and schema changes for azure dbs
* Add azure discovery helm lint
* Add azure discovery helm tests
* Fix schema and update snapshot
* Update lint
* Update helm chart docs reference
* Update readme
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Isaiah Becker-Mayer <isaiah@goteleport.com>
* Move yaml lint note to include snippet
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Hugo Shaka <hugo.hervieux@goteleport.com>
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Hugo Shaka <hugo.hervieux@goteleport.com>
* Add azureDatabases to list of required resources for db role in docs
* Update readme to link to docs
* Provide complete example yaml for azure db discovery helm chart
* s|dbResources|databaseResources|g in helm chart reference
* Remove --set tabs for aws and azure databases from chart reference
* Update lint to use secret as example too
* Update azure db discovery helm chart snapshot
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Update docs/pages/reference/helm-reference/teleport-kube-agent.mdx
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
* Remove shell vars in readme since we dont provide a command
Co-authored-by: Isaiah Becker-Mayer <isaiah@goteleport.com>
Co-authored-by: Hugo Shaka <hugo.hervieux@goteleport.com>
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
This contribution adds the following feature
- support for `joinParams` value to join using EC2 and IAM tokens
The PR contains the following fixes
- Fix previous secretName documentation that was incorect
- Reword authToken and joinParams documentation to explicit how values interact together
- Add unit test with `joinParams.method = token`
- Add unit tests checking secret creation
- Mark joinParams.method mandatory in JSONSchema
- Always use join_params to pass tokens
* Document requirements for IAM joining
Co-authored-by: Guilherme Sponda <sponda@archlinux.com.br>
Co-authored-by: Guilherme Sponda <guilherme.sponda@audibene.de>
Two links didn't render correctly and preserved the ".mdx" extension,
causing 404s for crawlers. This removes the scope param to get link
rendering to work.
When assigning AWS IAM permissions to Teleport, `eksctl create iamserviceaccount` command manages the ServiceAccount lifecycle.
This PR allows any user to configure an existing Kubernetes ServiceAccount used by the agent.
Part of #11866
Fixes#13129
This PR sets minReadySeconds to 15 by default. During a rollout we still have proxies that don't have tunnels to all agents, but at least agents don't end up with 0 active tunnels.
* Refresh the Enterprise Getting Started guide
Fixes#14249
Edit the Enterprise Getting Started guide based on manual testing to
make the guide up to date and easier to follow.
- Update the architectural description in the introduction
- Structure the guide, following out Linux Server guide for open source
installations, to include Application Access
- Add DNS instructions rather than using the `--insecure` flag
- Add copy-pastable installation instructions
- Flesh out the license file instructions and add a screenshot of the
customer portal
- Simplify the instructions for adding a local user
- Remove the docker-compose instructions, since we want the user to
finish setting up a minimal Teleport cluster by the end of the guide,
and these instructions begin a new step-by-step sequence. We also have
a separate docker-compose guide that users can follow for a local
demo
- Add a "Next steps" section and move relevant content there
* Respond to PR feedback
Provides a solution for #9298
This removes an unnecessary limitation of the Helm chart: `.Values.tls.existingCASecretName` can now be used without `.Values.tls.existingSecretName`. This allows users to trust their own CAs without building custom images.
Context:
- go's x509 library supports loading system certs based on the SSL_CERTS_FILE environment variable
- we are already using this in the chart to trust private CAs (teleport proxy needs to trust its own certs to start)
- users might want to trust custom CAs to
- speak with a S3 backend (minio)
- validate upstream app certs (unlike DB access you can't trust certs per-application)
- trust another cluster
- call an OIDC provider
- teleport-kube-agent chart already has the feature
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
* Add documentation for Jira Helm chart
It includes an updated guide and the reference of the new Helm chart.
* Fixed some minor mistakes in the guides
* Reorganized Helm related examples
* Fixed a few minor mistakes
* Alphabetized jira.* settings
* Renamed Cloud to Executable in Testing
* Extended YAML config example with explanation
* Edit Jira Access Request plugin Helm chart docs
- Edit the configuration instructions so we don't instruct Helm users to
use the `configure` subcommand. Also use the `Tabs` component's
dropdown functionality so we can include both self-hosted and Teleport
Cloud instructions for Helm and VM users.
- Minor style tweaks.
* Add Helm Chart example to Installation section
* Removed confusing (and broken) link
git push
* Fixed wrong default value
Co-authored-by: Paul Gottschling <paul.gottschling@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
Paul Gottschling