Refactor cloud-linux page

docs/config.json

@@ -28,6 +28,16 @@
               "title": "Compatibility Overview",
               "slug": "/upgrading/overview/"
             },
+            {
+                "title": "Teleport Cloud Automatic Updates (Linux)",
+                "slug": "/upgrading/cloud-linux-automatic/",
+                "forScopes": ["cloud"]
+            },
+            {
+                "title": "Teleport Cloud Automatic Updates (Kubernetes)",
+                "slug": "/upgrading/cloud-kubernetes-automatic/",
+                "forScopes": ["cloud"]
+            },
             {
               "title": "Teleport Cloud Agents (Linux)",
               "slug": "/upgrading/cloud-linux/",

docs/pages/includes/cloud/install-linux-cloud.mdx

@@ -1,8 +1,6 @@
   <Tabs>
   <TabItem label="Debian 9+/Ubuntu 16.04+ (apt)">
 
-  Add the Teleport repository to your repository list:
-
   ```code
   # Download Teleport's PGP public key
   $ sudo curl https://apt.releases.teleport.dev/gpg \

docs/pages/includes/cloud/tctl-tsh-prerequisite.mdx

@@ -1,3 +1,2 @@
-The `tctl` and `tsh` client tools version >= (=cloud.version=).
-
-You can download these from [Teleport Cloud Downloads](../../choose-an-edition/teleport-cloud/downloads.mdx).
+[Install](../../choose-an-edition/teleport-cloud/downloads.mdx) the `tctl` and
+`tsh` client tools version >= (=cloud.version=).

docs/pages/includes/tctl.mdx

@@ -2,8 +2,6 @@ To check that you can connect to your Teleport cluster, sign in with `tsh login`
 verify that you can run `tctl` commands using your current credentials. 
 `tctl` is supported on macOS and Linux machines.
 
-For example:
-
 ```code
 $ tsh login --proxy=<Var name="teleport.example.com" /> --user=<Var name="[email protected]" />
 $ tctl status

docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx

@@ -1,14 +1,6 @@
-Set up the Teleport Helm repository.
-
-Allow Helm to install charts that are hosted in the Teleport Helm repository:
+Add the Teleport Helm repository and update the cache:
 
 ```code
 $ helm repo add teleport (=teleport.helm_repo_url=)
-```
-
-Update the cache of charts from the remote repository so you can upgrade to all
-available releases:
-
-```code
 $ helm repo update
 ```

docs/pages/upgrading.mdx

@@ -4,44 +4,41 @@ description: Explains how to upgrade Teleport depending on your environment and
 layout: tocless-doc
 ---
 
-The guides in this section show you how to upgrade Teleport to a more recent
-version.
+Teleport components need to be updated regularly to stay up to date with the latest
+features and security updates. Teleport releases a new major version every 4 months.
+See the [Upcoming Releases](./upcoming-releases.mdx) page to view upcoming changes
+and releases.
 
-## Upgrading compatibility overview
+## Upgrading guides
 
-Since Teleport is a distributed system with a number of services that run on
-potentially many hosts, you should take care when upgrading the cluster to
-ensure that all components remain compatible.
+Before starting one of the following guides, please read the [Upgrading Compatibility Overview](./upgrading/overview.mdx)
+to understand how to upgrade components in your Teleport cluster while ensuring compatibility
+between all components.
 
-The [Upgrading Compatibility Overview](./upgrading/overview.mdx) explains how to
-upgrade components in your Teleport cluster to ensure that they communicate as
-expected.
+The Teleport upgrade process is different for cloud-hosted and self-hosted deployments.
+Choose the guide that matches your Teleport edition and the platform where you run
+Teleport services:
 
-## Upgrading guides
+## Cloud-hosted deployments:
 
-After getting familiar with the Compatibility Overview, read one of the
-following guides to upgrade the components in your Teleport cluster. Choose the
-guide that matches your Teleport edition and the platform where you run Teleport
-services:
+Automatic updates is the recommended method for updating Teleport agents.
 
-Teleport Cloud:
+- [Linux Servers](./upgrading/cloud-linux-automatic.mdx) (automatic updates)
+- [Kubernetes](./upgrading/cloud-kubernetes-automatic.mdx) (automatic updates)
 
-- [Linux Servers](./upgrading/cloud-linux.mdx)
+Manual updates are not recommended. If you opt out of automatic updates, you must
+ensure that your Teleport agents are routinely updated, and you must ensure that
+your Teleport agents maintain compatibility with the Teleport Auth Service and Proxy
+Service.
+
+- [Linux Server](./upgrading/cloud-linux.mdx)
 - [Kubernetes](./upgrading/cloud-kubernetes.mdx)
 
-Self-hosted deployments:
+You can find more information regarding the automatic updates architecture in the
+[Agent Update Management](./architecture/agent-update-management.mdx) page.
+
+## Self-hosted deployments:
 
 - [Linux Servers](./upgrading/self-hosted-linux.mdx)
+- [Linux Servers](./upgrading/self-hosted-automatic-agent-updates.mdx) (automatic updates)
 - [Kubernetes](./upgrading/self-hosted-kubernetes.mdx)
-
-## Automatic agent upgrades
-
-We recommend that Teleport users set up automatic agent upgrades, where agents
-query a **version server** in order to determine whether they are out of date
-and need to install a new version of Teleport. 
-
-On Teleport Cloud, the version server is managed for you.
-
-If you are running Teleport Enterprise, read the [Self-Hosted Automatic Agent
-Updates](./upgrading/self-hosted-automatic-agent-updates.mdx) guide to set up
-the version server yourself.

docs/pages/upgrading/cloud-kubernetes-automatic.mdx

@@ -0,0 +1,176 @@
+---
+title: Enable Automatic Updates for Cloud-Hosted Teleport Agents on Kubernetes
+description: Provides instructions for enabling automatic updates for cloud-hosted Teleport agents that run on Kubernetes.
+---
+
+This guide explains how to enable Automatic Updates for Teleport agents on Kubernetes.
+
+## How it works
+
+When automatic updates is enabled, a Teleport updater is deployed along side the
+Teleport agent. The updater communicates with the Teleport Proxy Service to determine
+when an update is available. When an update is available, the updater will update
+the Teleport agent during the next maintenance window. However, if a critical update
+is availble, the Teleport agent will be updated outside the regular maintenance window.
+
+## Prerequisites
+
+- Familiarity with the [Upgrading Compatibility Overview](./overview.mdx) guide,
+  which describes the sequence in which to upgrade components of your cluster.
+
+- (!docs/pages/includes/cloud/tctl-tsh-prerequisite.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+
+## Step 1/2. Find agents to enroll in automatic updates
+
+Use the `tctl inventory ls` command to list connected agents along with their current
+version. Use the `--upgrader=none` flag to list agents that are not enrolled in automatic
+updates.
+
+```code
+$ tctl inventory ls --upgrader=none
+Server ID                            Hostname       Services       Version Upgrader
+------------------------------------ -------------- -------------- ------- --------
+00000000-0000-0000-0000-000000000000 teleport-agent Kube           v14.4.5 none
+...
+```
+
+Note that the `inventory ls` command will also list `teleport-auth` and `teleport-proxy`
+services. These services are managed by the Teleport team, and updates will be performed
+automatically.
+
+## Step 2/2. Enroll agents in automatic updates
+
+This section assumes that the name of your `teleport-kube-agent` release is
+`teleport-agent`, and that you have installed it in the `teleport` namespace.
+
+(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!)
+
+Add the following chart values to your existing agent `values.yaml` to enable
+the automatic updater:
+
+```yaml
+updater:
+    enabled: true
+```
+
+Upgrade the Helm chart release with the new values by running `helm upgrade`:
+
+```code
+$  helm -n <Var name="teleport" /> upgrade <Var name="teleport-agent" /> teleport/teleport-kube-agent  \
+--values=values.yaml \
+--version=<Var name="(=cloud.version=)" />
+```
+
+## GitOps
+
+Automatic updates are incompatible with some GitOps tools used for continuous deployment.
+The `teleport-kube-agent` Helm chart owns the version of the `teleport-agent` resource,
+so when the `teleport-agent-updater` modifies the image version of the `teleport-agent`
+resource, the GitOps tool will detect a drift or a diff in the `teleport-agent` resource.
+
+### ArgoCD deployments
+
+After an automatic update, ArgoCD reports the `teleport-agent` resource as `OutOfSync`.
+As a workaround to this problem use a [Diff Customization](https://argo-cd.readthedocs.io/en/stable/user-guide/diffing/#diffing-customization)
+to ignore the difference in image version. Here is an example deployment using the
+name `teleport-agent` and namespace `teleport`.
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: teleport-agent
+  namespace: teleport
+spec
+  ignoreDifferences:
+  - group: apps
+    kind: StatefulSet
+    name: teleport-agent
+    namespace: teleport
+    jqPathExpressions:
+    - .spec.template.spec.containers[] | select(.name == "teleport").image
+...
+```
+
+### FluxCD deployments
+
+After an automatic update, FluxCD reports a `DriftDetected` event. As a workaround
+to this problem modify the [drift detection](https://fluxcd.io/flux/components/helm/helmreleases/#drift-detection)
+configuration to ignore the difference in image version. Here is an example deployment
+using the name `teleport-agent` and namespace `teleport`.
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta2
+kind: HelmRelease
+metadata:
+  name: teleport-agent
+  namespace: teleport
+spec
+  driftDetection:
+    mode: enabled
+    ignore:
+    - paths: ["/spec/template/spec/containers/0/image"]
+      target:
+        kind: StatefulSet
+        name: teleport-agent
+        namespace: teleport
+...
+```
+
+## Automatic updates with Teleport Community Edition
+
+Automatic updates is not currently supported with the community editions of Teleport.
+Ensure that you are using the Teleport Enterprise edition of the `teleport-kube-agent`
+chart. You should see the following when you query your `teleport-kube-agent` release:
+
+```code
+$ helm -n <Var name="teleport" /> get values <Var name="teleport-agent" /> -o json | jq '.enterprise'
+true
+```
+
+## Troubleshooting
+
+Teleport agents are not updated immediately when a new version of Teleport is released,
+and agent updates can lag behind the cluster by a few days.
+
+If the Teleport agent has not been automatically updating for several weeks, you
+can consult the updater logs to help troubleshoot the problem.
+
+Validate that the updater pod is running:
+
+```code
+$ kubectl -n <Var name="teleport" /> get pods
+NAME                                     READY   STATUS    RESTARTS   AGE
+teleport-agent-0                         1/1     Running   0          14m
+teleport-agent-1                         1/1     Running   0          14m
+teleport-agent-2                         1/1     Running   0          14m
+teleport-agent-updater-d9f97f5dd-v57g9   1/1     Running   0          16m
+```
+
+View its logs:
+
+```code
+$ kubectl -n <Var name="teleport" /> logs deployment/<Var name="teleport-agent" />-updater
+2023-04-28T13:13:30Z	INFO	StatefulSet is already up-to-date, not updating.	{"controller": "statefulset", "controllerGroup": "apps", "controllerKind": "StatefulSet", "StatefulSet": {"name":"teleport-agent","namespace":"teleport"}, "namespace": "teleport", "name": "teleport-agent", "reconcileID": "10419f20-a4c9-45d4-a16f-406866b7fc05", "namespacedname": "teleport/teleport-agent", "kind": "StatefulSet", "err": "no new version (current: \"v12.2.3\", next: \"v12.2.3\")"}
+```
+
+The updater is a controller that periodically reconciles expected Kubernetes
+resources with those in the cluster. The updater executes a reconciliation loop
+every 30 minutes or in response to a Kubernetes event. If you don't want to wait
+until the next reconciliation, you can trigger an event. Any deployment update
+will send an event, so the updater can be triggered by annotating the resource:
+
+```code
+$ kubectl -n <Var name="teleport" /> annotate statefulset/<Var name="teleport-agent" /> 'debug.teleport.dev/trigger-event=1'
+```
+
+To suspend automatic updates for an agent, annotate the agent deployment with
+`teleport.dev/skipreconcile: "true"`, either by setting the
+`annotations.deployment` value in Helm, or by patching the deployment directly
+with `kubectl`.
+
+## Further reading
+
+- [teleport-kube-agent Chart Reference](../reference/helm-reference/teleport-kube-agent.mdx#updater)