From 958873409ce2b20170567eb90b37aeb14d58da0d Mon Sep 17 00:00:00 2001
From: Lenny Chen <55669665+lennessyy@users.noreply.github.com>
Date: Thu, 16 Jan 2025 11:48:51 -0800
Subject: [PATCH] docs: add warning about pausing platform upgrades (#5431)

* docs: add warning about pausing platform upgrades

* docs: add limitation on platform upgrades

* docs: copy edit

* docs: emphasize all

* docs: minor edit

* Update docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md

Co-authored-by: Ben Radstone <56587332+benradstone@users.noreply.github.com>

---------

Co-authored-by: Ben Radstone <56587332+benradstone@users.noreply.github.com>
---
 .../pause-platform-upgrades.md                | 23 +++++++++++++------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md b/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md
index eaa2015bbc..38b3acd4b4 100644
--- a/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md
+++ b/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md
@@ -8,13 +8,8 @@ tags: ["clusters", "cluster management"]
 ---
 
 Palette supports the **Pause Agent Upgrades** feature to exclude a cluster or a group of clusters from having their
-Palette agent automatically upgraded when Palette is upgraded.
-
-:::info
-
-This feature only pauses upgrades for Palette agents, not updates to the clusters themselves.
-
-:::
+Palette agent automatically upgraded when Palette is upgraded. This feature only pauses upgrades for Palette agents, not
+updates to the clusters themselves.
 
 ## Pause Agent Upgrade Scopes
 
@@ -83,6 +78,20 @@ lower scopes, and changing the setting at the lower scope will override the sett
 | PCG             | ✅                     | ❌      | ✅     |
 | Idle Edge hosts | ❌                     | ✅      | ✅     |
 
+## Limitations
+
+- Do not pause platform upgrades for clusters if _all_ of the following conditions apply:
+
+  - Your cluster is an Edge cluster.
+  - Your Palette/VerteX instance is on version 4.5.x or later.
+  - Your agent version is older than 4.5.0.
+  - Your Edge cluster has the
+    [local Harbor registry](../../edge/site-deployment/deploy-custom-registries/local-registry.md) enabled.
+
+  Using an agent version older than 4.5.0 with Palette/VerteX versions 4.5.x or later may lead to image download issues,
+  issues with pushing images to the local registry, and cluster deployment issues. Ensure that you enable platform
+  upgrades so your agent can be upgraded to be compatible with Palette/VerteX.
+
 ## Prerequisites
 
 - Cluster admin permissions or Tenant admin permissions when pausing upgrades for all clusters within tenant scope.