[v13] docs: document the updater

docs/config.json

@@ -726,6 +726,21 @@
               "forScopes": [
                 "enterprise"
               ]
+            },
+            {
+              "title": "Self-hosted automatic updates",
+              "slug": "/management/operations/self-hosted-automatic-agent-updates/",
+              "forScopes": [
+                "enterprise"
+              ]
+            },
+            {
+              "title": "Enroll agent in automatic updates",
+              "slug": "/management/operations/enroll-agent-into-automatic-updates/",
+              "forScopes": [
+                "enterprise",
+                "cloud"
+              ]
             }
           ]
         },
@@ -1586,6 +1601,11 @@
         {
           "title": "Proxy Peering (Preview)",
           "slug": "/architecture/proxy-peering/"
+        },
+        {
+          "title": "Agent Update Management",
+          "slug": "/architecture/agent-update-management/",
+          "forScopes": ["enterprise", "cloud"]
         }
       ]
     },

docs/cspell.json

@@ -508,6 +508,7 @@
     "nameid",
     "nameidentifier",
     "nameserver",
+    "namespacedname",
     "navin",
     "ndots",
     "netcat",
@@ -623,6 +624,7 @@
     "setspn",
     "sharded",
     "signup",
+    "skipreconcile",
     "slacktokenfromsecret",
     "snowsql",
     "splunkd",

docs/pages/architecture/agent-update-management.mdx

@@ -0,0 +1,95 @@
+---
+title: Agent Update Management (Preview)
+description: This chapter explains how Teleport agent automatic update is working.
+---
+
+While many Teleport resources [support agentless
+mode](../faq.mdx#can-teleport-be-deployed-in-agentless-mode), agent deployments
+are sometimes simpler and more convenient. However, large Teleport deployments
+can create an additional burden: updating all agents.
+
+Starting with version 13, Teleport supports automatic agent updates for systemd-based
+Linux distributions using `apt` or `yum` package managers, and Kubernetes clusters.
+
+## Update logic and failure modes
+
+An updater is a piece of software deployed next to an agent which is responsible
+for updating it. Updating multiple agents requires multiple updaters.
+
+We designed the updater to be as decoupled from Teleport as possible. The
+updater can update agents even when they cannot join the Teleport cluster.
+Pushing a broken version can happen, but a rollback/roll-forward must always
+be possible without manually connecting to the resource and fixing the agent.
+
+The updater recurrently fetches the target version from a version server and
+updates the agent to the target version. Because restarting the agent can
+disrupt currently open sessions, it will only update the agent in two cases:
+during a maintenance window or when the agent is unhealthy.
+
+When enrolled in a cluster with automatic updates, the agent will retrieve
+its maintenance schedule from the Teleport cluster and save it. When a
+maintenance schedule is available, the updater will honour it. However, if
+the updater cannot find the maintenance schedule, it will consider the agent
+unhealthy and perform updates as soon as possible. Similarly, if the updater
+detects the agent is unhealthy, it immediately applies any pending update to
+try to recover from a degraded state.
+
+We implemented an additional failsafe: the critical maintenance toggle.
+The version server can specify that an update is critical. Critical updates are
+applied even if the updater is outside its regular maintenance window.
+
+## Security
+
+When updating the agent, the updater will ensure the new version's authenticity
+before deploying it. On Linux distributions using `apt` or `yum`, it relies on
+the existing package signature system. On Kubernetes-based environments, it
+validates the OCI image signature (using [cosign's signature
+](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md)).
+
+## Version server and source of truth
+
+The agent version is subject to the following constraints:
+
+- the agent must never exceed the Proxy or Auth Service version,
+- the agent must always be no more than one major version below the Proxy or Auth
+  Service version.
+
+The best practice is to always align the agent version with the Proxy and Auth
+ones. To upgrade Auth and Proxy, follow [the Teleport Cluster upgrade guide
+](../management/operations/upgrading.mdx).
+
+For this reason, all updaters must subscribe to a release channel targeting
+versions that are compatible with their Teleport cluster. Teleport Cloud users
+must use the Teleport Cloud version server with the `stable/cloud` release
+channel. Self-hosted Teleport users must host their own version server and
+updater their release channel each time they update their Auth and Proxy
+instances.
+
+### Teleport Cloud
+
+Teleport Cloud users can use Teleport Cloud's version server only if their
+instance is enrolled in automatic updates. This version server will always
+target the best version from a feature, compatibility, security and stability
+point of view.
+
+Teleport Cloud users whose control plane is not automatically updated must not use
+automatic agent updates. This is because their Teleport instance version might
+differ from the other Teleport Cloud instances and might not yet support the
+latest agent version.
+
+### Self-hosted Teleport
+
+Self-hosted Teleport users can set up automatic agent updates. They must host
+their version server and choose their target version. They are responsible for
+ensuring the targeted version is compatible with their current auth/proxy
+versions. They must also monitor the agent's health and rollout status to
+ensure every agent is healthy and running the correct version.
+
+## Next steps
+
+Self-hosted users must first [set up self-hosted automatic agent update
+](../management/operations/self-hosted-automatic-agent-updates.mdx).
+
+If you're a Teleport Cloud user or self-hosting with automatic update
+configured, you can [enroll your agents into automatic updates
+](../management/operations/enroll-agent-into-automatic-updates.mdx).

docs/pages/architecture/introduction.mdx

@@ -9,9 +9,10 @@ works.
 
 - [Authentication](./authentication.mdx)
 - [Authorization](./authorization.mdx)
+- [Automatic Agent Update](./agent-update-management.mdx)
 - [The Teleport Proxy Service](./proxy.mdx)
+- [Trusted Clusters](./trustedclusters.mdx)
 - [Teleport Nodes](./nodes.mdx)
 - [Session Recording](./session-recording.mdx)
 - [TLS Routing](./tls-routing.mdx)
 - [Proxy Peering](./proxy-peering.mdx)
-- [Trusted Clusters](./trustedclusters.mdx)

docs/pages/includes/cluster-maintenance-config-spec.mdx

@@ -0,0 +1,16 @@
+```yaml
+kind: cluster_maintenance_config
+spec:
+  agent_upgrades:
+    # Maintenance window start hour in UTC.
+    # The maintenance window lasts 1 hour.
+    utc_start_hour: 2
+    # Week days when maintenance is allowed
+    # Possible values are:
+    # - Short names: Sun, Mon, Tue, Wed, Thu, Fri, Sat
+    # - Long names: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
+    weekdays:
+      - Mon
+      - Wed
+      - Fri
+```

docs/pages/management/operations.mdx

@@ -16,3 +16,5 @@ the [Cluster Administration Guides](./admin.mdx) section.
 - [CA Rotation](./operations/ca-rotation.mdx): Rotating Teleport certificate authorities.
 - [TLS Routing Migration](./operations/tls-routing.mdx): Migrating your Teleport cluster to single-port TLS routing mode.
 - [Proxy Peering Migration](./operations/proxy-peering.mdx): Migrating your Teleport cluster to Proxy Peering mode.
+- [Setup automatic agent updates for self-hosted Teleport](./operations/self-hosted-automatic-agent-updates.mdx)
+- [Enroll agent into automatic updates](./operations/enroll-agent-into-automatic-updates.mdx)