Consolidate updating guides (#43425)

Backports #41160

* Consolidate updating guides

Include a how-to guide for the fast path we want most users to move to:
using cloud-hosted Teleport Enterprise and enrolling agents in automatic
updates. For other use cases and edge cases, include a general Updating
Reference.

* Respond to hugoShaka feedback

- Fix step numbering.
- Add cloud prerequisite and mention cloud-hosted clusters in the
  introduciton.

* Respond to bernardjkim feedback

- Remove unintentionally preserved text about release channels for
  Teleport v14.
- Add instructions for determining the Teleport version to install.

* Add an intro paragraph with a recommendation

Urge users to enroll their agents in automatic upgrades per feedback
from bernardjkim.

* Add check for the Enterprise teleport-kube-agent

Incorporates #41132

* Respond to r0mant feedback

- Include self-hosted instructions in the how-to guide
- Include a journalctl command to check logs
- Edit the upgrading menu page and intro of the how-to guide to provide
  stronger language re: using automatic agent upgrades in cloud
  accounts.

* Add `helm repo update` step

* Fix linter errors

* Respond to r0mant feedback

docs/config.json

@@ -29,29 +29,12 @@
               "slug": "/upgrading/overview/"
             },
             {
-              "title": "Teleport Cloud Agents (Linux)",
-              "slug": "/upgrading/cloud-linux/",
-              "forScopes": ["cloud"]
-            },
-            {
-              "title": "Teleport Cloud Agents (Kubernetes)",
-              "slug": "/upgrading/cloud-kubernetes/",
-              "forScopes": ["cloud"]
-            },
-            {
-              "title": "Self-Hosted Linux",
-              "slug": "/upgrading/self-hosted-linux/",
-              "forScopes": ["enterprise", "oss"]
-            },
-            {
-              "title": "Self-Hosted Kubernetes",
-              "slug": "/upgrading/self-hosted-kubernetes/",
-              "forScopes": ["enterprise", "oss"]
+                "title": "Set up Automatic Agent Updates",
+                "slug": "/upgrading/automatic-agent-updates/"
             },
             {
-              "title": "Self-Hosted Automatic Upgrades",
-              "slug": "/upgrading/self-hosted-automatic-agent-updates/",
-              "forScopes": ["enterprise"]
+                "title": "Updating Reference",
+                "slug": "/upgrading/reference/"
             }
           ]
         },
@@ -2710,7 +2693,7 @@
     },
     {
       "source": "/management/operations/self-hosted-automatic-agent-updates/",
-      "destination": "/upgrading/self-hosted-automatic-agent-updates/",
+      "destination": "/upgrading/",
       "permanent": true
     },
     {

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

@@ -88,7 +88,7 @@ ensure every agent is healthy and running the correct version.
 ## Next steps
 
 Self-hosted users must first [set up self-hosted automatic agent upgrades
-](../upgrading/self-hosted-automatic-agent-updates.mdx).
+](../upgrading/automatic-agent-updates.mdx).
 
 After that, you can set enroll agents in automatic updates as part of the
 [upgrading procedure](../upgrading.mdx).

docs/pages/choose-an-edition/teleport-cloud/faq.mdx

@@ -190,14 +190,10 @@ Teleport Cloud version server for automatic agent updates. With automatic agent
 updates, agents periodically check the version server for new releases and
 update the software when new versions are found.
 
-If you enroll in automatic agent updates, Teleport agents are automatically 
-updated after your Teleport cluster is updated during your scheduled maintenance 
-period. For more information, read one of the following guides:
-
-- [Upgrading Teleport Cloud Agents on
-  Kubernetes](../../upgrading/cloud-kubernetes.mdx)
-- [Upgrading Teleport Cloud Agents on
-  Linux Servers](../../upgrading/cloud-linux.mdx)
+If you enroll in automatic agent updates, Teleport agents are automatically
+updated after your Teleport cluster is updated during your scheduled maintenance
+period. For more information, read the [Automatic Agent
+Updates](../../upgrading/automatic-agent-updates.mdx) guide.
 
 ### How can I find version information on connected agents?
 

docs/pages/includes/server-access/custom-installer.mdx

@@ -71,7 +71,7 @@ connect to.
 Has format `<channel>/<version>` e.g. stable/v(=teleport.major_version=). See [installation](../../installation.mdx#linux) for more details.
 - `{{ .AutomaticUpgrades }}`: indicates whether Automatic Updates are enabled or disabled.
   Its value is either `true` or `false`. See
-  [self-hosted automatic agent updates](../../upgrading/self-hosted-automatic-agent-updates.mdx)
+  [Automatic Agent Updates](../../upgrading/automatic-agent-updates.mdx)
   for more information.
 - `{{ .TeleportPackage }}`: the Teleport package to use.
   Its value is either `teleport-ent` or `teleport` depending on whether the

docs/pages/upgrading.mdx

@@ -1,47 +1,23 @@
 ---
 title: Upgrading Teleport
 description: Explains how to upgrade Teleport depending on your environment and edition.
-layout: tocless-doc
 ---
 
 The guides in this section show you how to upgrade Teleport to a more recent
 version.
 
-## Upgrading compatibility overview
+Read the [Upgrading Compatibility Overview](./upgrading/overview.mdx) to
+understand how to upgrade components in your Teleport cluster while ensuring
+compatibility between all components.
 
-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.
+If you have a Teleport Enterprise (Cloud) account, you **must** [set up automatic
+Teleport agent updates](./upgrading/automatic-agent-updates.mdx) to ensure that
+the version of Teleport running on agents is always compatible with that of the
+Teleport cluster. You can also set up automatic agent upgrades in a self-hosted
+cluster.
 
-The [Upgrading Compatibility Overview](./upgrading/overview.mdx) explains how to
-upgrade components in your Teleport cluster to ensure that they communicate as
-expected.
+For more information about upgrading, for example, to upgrade manually, read the
+[Upgrading Reference](./upgrading/reference.mdx).
 
-## Upgrading guides
-
-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:
-
-Teleport Cloud:
-
-- [Linux Servers](./upgrading/cloud-linux.mdx)
-- [Kubernetes](./upgrading/cloud-kubernetes.mdx)
-
-Self-hosted deployments:
-
-- [Linux Servers](./upgrading/self-hosted-linux.mdx)
-- [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.
+You can find more information regarding the automatic updates architecture in the
+[Agent Update Management](./architecture/agent-update-management.mdx) page.