See #36816
The docs are inconsistent in using "automatic updates" vs. "automatic
upgrades". Prefer the former to be consistent with the
`teleport-ent-updater` script.
- Replace "automatic upgrade" with "automatic update" in docs pages.
- Replace "automatic upgrade" uses in the `teleport-kube-agent` chart
and regenerate the docs.
- Catch uses of "automatic upgrade" in the `consistent-terms` Vale rule
* Improve the upgrading documentation
Closes#33817
This change restructures the information architecture of learning how to
upgrade Teleport. Currently, users who want to upgrade Teleport need to
cobble together instructions from pages in various subsections of the
docs site.
With this change, users can navigate to a single subsection of the
"Home" section, "Upgrading", and follow a linear flow for their Teleport
edition (self-hosted or Cloud) and platform (Kubernetes/Linux servers).
The new information architecture replaces the following guides:
- docs/pages/management/admin/upgrading-the-teleport-binary.mdx
- docs/pages/management/operations/enroll-agent-into-automatic-updates.mdx
- docs/pages/management/operations/upgrading.mdx
The compatibility and upgrade sequence information in `upgrading.mdx` is
now in a separate page that readers are expected to be familiar with
before completing the how-to guides in this subsection.
As part of the change, the guide for setting up self-hosted automatic
agent upgrade infrastructure is now in the "Upgrading" subsection. This
guide now includes example Terraform configs for deploying a version
server. Since there are many ways to deploy a static file server, the
intention is to remove decision making to get the user more quickly to
the objective of the guide.
This change also adds an `install-linux-self-hosted.mdx` partial for
guides that only need installation instructions for OSS and Enterprise.
Issues closed by these changes:
- Edit Linux server instructions to include commands for upgrading
Teleport via a package manager, which closes#32553.
- Removes the separation between the "cluster" and "binary" upgrading
docs (closes#31446).
- Organizes the docs by deployment, assuming the user is upgrading an
entire cluster at a time (closes#27672, closes#10917).
- By including package manager instructions already present in partials,
this change makes it clearer how to update a package manager repo to
change major versions (closes#26499).
- Removes the instructions to use SIGUSR2 when upgrading (closes
#33720).
* Partially respond to feedback
- Change titles/descriptions (espadolini)
- Avoid using `awk` in `tctl inventory ls` command (espadolini)
- Simplify `tsh ssh` command (espadolini)
- Remove extra slash (espadolini)
- Add a note re: upgrading trusted clusters one major version at a time
(espadolini)
- Add the `version` flag to the `helm upgrade` command (hugoShaka)
* Replace release/namespace names with Vars
This responds to PR feedback.
* Reorganize the upgrading docs
Responds to hugoShaka feedback.
Move all automatic upgrade instructions from the self-hosted upgrading
guides into a single page. The page includes instructions for setting up
automatic upgrade infrastructure as well as enrolling agents on Linux
and Kubernetes. It uses separate H2s for each compute platform, instead
of tabs, to make each section easier to read, since instructions differ
considerably between platforms.
This change fixes some issues with the Azure VM auto-discovery docs:
- Clarify how Teleport interacts with multiple managed identities.
- Clarify prerequisites for identities on discovered VMs.
- Add extra troubleshooting info.
Paul Gottschling