docs: backport

docs/docs-content/clusters/cluster-management/palette-lock-cluster.md

@@ -14,14 +14,81 @@ Palette provides the following platform settings:
 
 ## Pause Platform Updates
 
-Palette supports the **Pause Platform Updates** feature to exclude a cluster or a group of clusters from getting
-upgraded when Palette is upgraded. The use cases of this feature are:
+Palette supports the **Pause Platform Updates** feature to exclude a cluster or a group of clusters from having their
+Palette agent upgraded when Palette is upgraded.
 
-- Pause Updates for Single Cluster
-- Pause Updates for all the Clusters within the Project Scope
-- Pause Updates for all Clusters within the Tenant Scope
+:::info
 
-<br />
+This feature only pauses upgrades for Palette agents, not updates to the clusters themselves.
+
+:::
+
+### Pause Agent Upgrade Scopes
+
+Agent upgrades can be paused and resumed in the following scopes:
+
+- Pause agent upgrades for a single cluster
+- Pause agent upgrades for all clusters within a project
+- Pause agent upgrades for all clusters within a tenant
+
+When determining if the agent upgrades for one cluster is paused or not, you only need to look at the setting for the
+cluster itself. Agent upgrade settings are always applied based on individual cluster settings. Project and tenant agent
+upgrade settings are not inherited - instead cluster level settings are set to match _each time_ project and tenant
+level settings are changed.
+
+Pausing or resuming agent upgrades at a higher-level scope will automatically pause or resume agent upgrades in the
+lower-level scopes. For example, if you pause agent upgrades at the tenant level, then agent upgrades will be paused for
+all projects within that tenant, and all clusters within those projects. Similarly, if you resume upgrades at the
+project level, then all clusters within that project will have their agent upgrades resumed.
+
+This is a one-time change that happens at the moment when you pause or resume upgrades in the project or tenant scope,
+and it does not mandate that the same setting be kept at the lower scopes. If you pause or resume agent upgrades in a
+lower-level scope, it will override the setting from the higher-level scope. For example, even if all agent upgrades are
+paused at the tenant level, you can override the tenant-level pause by resuming upgrades in a specific project or a
+specific cluster.
+
+:::warning
+
+Overrides of agent upgrade settings are not permanent. When the pause agent settings at the project or tenant scope
+change, the agent upgrade setting in the cluster or project scopes will always be set to match the higher-level scope
+setting regardless. If you want to override the project or tenant level agent upgrade setting, you must change the agent
+upgrade setting in the lower scope _after_ the change in the higher scope.
+
+:::
+
+The following table lists some example upgrade configurations and whether the Palette agent will be upgrades in those
+settings. Note that only the settings at the cluster level determines whether the Palette agent will be upgraded.
+
+| Tenant           | Project          | Cluster          | Outcome                                   |
+| ---------------- | ---------------- | ---------------- | ----------------------------------------- |
+| Upgrades paused  | Upgrades paused  | Upgrades enabled | Palette agent will upgrade automatically. |
+| Upgrades enabled | Upgrades enabled | Upgrade paused   | Palette agent upgrades are paused.        |
+
+### Agent Upgrades for PCG and Edge Hosts
+
+Aside from clusters, you can also pause the agent upgrades on Private Cloud Gateways (PCG) and Edge hosts that are
+registered with Palette but are not part of a cluster.
+
+Since PCGs are scoped to tenants, you can pause the agent upgrades on a PCG by pausing agent upgrades on the tenant to
+which the PCG is associated. You can also pause or resume upgrades for a PCG in the PCG details page through **Cluster
+Settings**. Similar to clusters, pausing and resuming upgrades at the tenant level will pause or resume agent upgrades
+for all PCGs in the tenant. Pausing and resuming upgrades for a PCG individually will override the tenant-level setting.
+
+Edge hosts that are part of a cluster have their agent upgrades managed by the settings of their cluster. Edge hosts
+that are not part of a cluster have their agent upgrades managed at the project and tenant level. Similar to clusters,
+pausing or resuming agent upgrades at the tenant level will automatically pause or resume agent upgrades for all
+projects within that tenant. However, you can override the tenant level setting by manually changing the upgrade setting
+at the project level.
+
+The following is a table showing the scopes at which you can pause agent upgrades for different objects. The same
+relationship between the scopes applies: Changing the setting in a higher scope will trigger a one-time change to the
+lower scopes, and changing the setting at the lower scope will override the setting in the higher scope.
+
+|                 | Individual Cluster/PCG | Project | Tenant |
+| --------------- | ---------------------- | ------- | ------ |
+| Cluster         | ✅                     | ✅      | ✅     |
+| PCG             | ✅                     | ❌      | ✅     |
+| Idle Edge hosts | ❌                     | ✅      | ✅     |
 
 ### Pause Updates for Single Cluster