#Upgrade the global cluster

#Sync upgrade artifacts

When: any time before the maintenance window. This step uploads artifacts to the registry and does not change cluster state.

First, record the configured registry address and determine whether the platform uses the built-in or an external registry:

kubectl get productbase base \
  -o jsonpath='{.spec.registry.address}{"\t"}{.spec.registry.external}{"\n"}'

The second value is false for the platform built-in Registry and true for an external registry. The publication command is selected after the target Aligned packages are copied into plugins/.

The Core Package does not contain the Aligned packages from ACP Upgrade to v4.5. Copy each of the eleven separately downloaded packages listed in Pre-Upgrade Preparation into the plugins/ directory of the extracted Core Package. Run the following command once for each package:

cp <path-to-upgrade-extension-package> ./plugins/

Confirm that the directory contains all eleven packages before synchronization:

ls -1 ./plugins/

Publish the staged payload by following the branch that matches the value of ProductBase.spec.registry.external.

For the platform built-in Registry (false), run upgrade.sh in sync-only mode from the extracted Core Package directory:

bash upgrade.sh --only-sync-image

--only-sync-image uploads Core images and the packages that you manually placed in plugins/, without deploying the cluster version operator or changing running applications. The CVO is deployed later, inside the maintenance window — see Deploy the cluster version operator.

For an external registry (true), do not use --only-sync-image as proof of publication. upgrade.sh automatically skips image synchronization. From the target Core Package's installer/ directory, run both res/upload.sh all and res/upload.sh necessary by following Prepare the Target-Version Payload. The modes may run in either order, but both must succeed.

The selected publication path makes the artifacts required by the CVO-based workflow available, including:

For the eleven Aligned applications from ACP Upgrade to v4.5, always stage the packages in plugins/. The built-in Registry path publishes them with upgrade.sh --only-sync-image; the external Registry path publishes them through res/upload.sh all. CVO upgrades an application only when it is already installed; publishing a package for an application that is not installed does not install it.

Use violet push for the other packages downloaded from the violet list inventory:

# Publish another cluster plugin to the global tier
violet push <path-to-other-cluster-plugin-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>"

# Publish another operator to global and each workload cluster that runs it
violet push <path-to-other-operator-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --clusters "global,<workload-cluster-1>,<workload-cluster-2>"

Pushing every operator package to every cluster from the global window is the recommended pattern. If the global window has already passed and you discover a workload cluster missing an operator package, you can still push to that workload cluster before the workload upgrade — see Upgrade workload clusters.

Registry behavior depends on how the environment is configured:

When the target registry is not the platform default, add registry parameters:

To bypass artifact validation when it is known to be redundant, add --skip-check-artifacts.

Before running preflight, confirm that the registry configuration is still correct:

kubectl get productbase base \
  -o jsonpath='{.spec.registry.address}{"\t"}{.spec.registry.external}{"\n"}'

Use successful completion of the selected publication commands and the registry administration interface or API as the Phase 1 evidence. Confirm that the expected target repositories and tags exist, and compare the published Extension set with the installed inventory exported to apps.yaml. Do not use ProductBase.status.artifacts as a zero-output target-version gate: it represents the current catalog and can legitimately contain Absent entries for optional or uninstalled packages.

#Run preflight checks

When: 1–2 weeks before the maintenance window, so there is time to resolve any blocking items before the window opens.

Run upgrade.sh in preflight mode:

bash upgrade.sh --preflight

Preflight is read-only — it validates upgrade readiness and does not change cluster state.

Preflight returns two parts:

The default check set includes:

• ResourcePatchUpgradeable
• ClusterVersionUpgradeable
• AdminAckRequired
• VersionUpgradePath
• KubernetesVersionSupported
• DockerRuntimeUnsupported
• ClusterRunning
• ClusterModuleStable
• ControlPlaneStaticPodsPresent
• CustomEtcdBackupCronJobsAbsent
• CRIUpgradePodsAbsent
• ModuleInfoStable
• PlatformLicense

#Handle preflight blocks

When: before the maintenance window, as soon as preflight reports a block.

A clean first preflight run is not the norm on a customized environment. Treat resolving blocks as part of the preparation phase, not as an exception — that is why preflight is run one to two weeks ahead.

If any check does not pass, do not open the maintenance window. Resolve each block with Upgrade Troubleshooting, which covers:

• ResourcePatchUpgradeable — the most frequent block on a customized environment, and the target-version exemption it requires.
• Other common blocks — KubernetesVersionSupported, VersionUpgradePath, ClusterRunning, DockerRuntimeUnsupported, and module stability.
• Administrator acknowledgement gates — when AdminAckRequired fails.

Do not force an upgrade past a failed check. VersionUpgradePath, KubernetesVersionSupported, and AdminAckRequired gate the supported upgrade path itself. If a block cannot be resolved, contact technical support before continuing.

#Deploy the cluster version operator

When: at the start of the maintenance window.

Run upgrade.sh in skip-sync mode. Synchronization is skipped because the artifacts were already uploaded in Sync upgrade artifacts:

bash upgrade.sh --skip-sync-image

This deploys or updates the cluster version operator (CVO) and completes the remaining preparation. The CVO drives the Core and Aligned plugin upgrade once the upgrade is requested in the next step.

After the command completes, inspect the target ProductManifest before requesting the upgrade:

kubectl get productmanifest v<target-version> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl get productmanifest v<target-version> -o json | jq -r '
  .status.artifacts[] as $artifact
  | $artifact.channels[]
  | select(.artifactStatus != "Ready")
  | [$artifact.name, .channel, .tag, .artifactStatus]
  | @tsv'

The per-artifact output is diagnostic and is not required to be empty. The target manifest can include optional, Agnostic, or uninstalled entries that are legitimately not Ready. Compare the output with the installed Core and Aligned inventory. For an installed Aligned ModulePlugin, inspect the matching target ModulePluginConfig when its channel is not Ready:

kubectl get modulepluginconfig <modulepluginconfig-name> -o yaml

Use the component name and channel tag from the target ProductManifest, or the name reported in the ClusterVersionShadow error, to identify the ModulePluginConfig. The component version in this name is not necessarily the ACP Distribution Version. Do not treat artifactStatus: Absent alone as proof that the registry manifest is missing; use the ModulePluginConfig condition and its .spec.image to distinguish a missing manifest from authentication, CA, network, or package-content failures.

#Request the upgrade

After the cluster version operator is deployed, request the upgrade through one of the following entry points. The entry points are equivalent; pick the one that fits your operating model.

The platform offers two cluster management interfaces in the Web Console. Web Console is the built-in interface that ships with the platform and is the default path. Web Console (Fleet Essentials) is the newer cluster management interface, delivered as a separate cluster plugin that must be installed before it can be used.

# Request upgrade to the highest version currently published in availableUpdates
ac adm upgrade --cluster=global --to-latest

# Request upgrade to a specific target version
ac adm upgrade --cluster=global --to=<target-version>

# Show summary, preflight, and stage progress for the global cluster upgrade
ac adm upgrade status --cluster=global

kubectl patch cvsh global -n cpaas-system --type merge -p '{
  "spec": {
    "desiredUpdate": {
      "version": "<target-version>"
    }
  }
}'

kubectl edit cvsh global -n cpaas-system

spec:
  desiredUpdate:
    version: <target-version>

#Observe execution

Use the following command to inspect the overall status:

kubectl get cvsh -n cpaas-system

Important status fields:

Focus on these conditions first:

If Stalled=True, follow Upgrade Troubleshooting. To observe an individual plugin or operator module, read its ModuleInfo:

# Current version, target, next available version, and phase per installed module on this cluster
kubectl get moduleinfo -l cpaas.io/cluster-name=global \
  -o custom-columns='MODULE:.metadata.labels.cpaas\.io/module-name,CURRENT:.status.version,TARGET:.spec.version,NEW:.status.availableVersions[0].version,PHASE:.status.phase'

# Conditions and any block reasons for one module
kubectl get moduleinfo <name> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

A module has reached its target when status.phase is Running and status.version equals the target version.

#Upgrade Agnostic plugins from Marketplace

CVO drives Core and Aligned plugins. Agnostic plugins are outside CVO's scope and must be upgraded individually after the cluster has reached the target Distribution Version. Whether each Agnostic plugin needs to be upgraded depends on its own Kubernetes compatibility — see the plugin's release notes for compatibility with the target Kubernetes version.

For each in-use Agnostic plugin on the global cluster:

1. In the Web Console, switch to Administrator view.
2. Navigate to Marketplace > Cluster Plugins for Agnostic cluster plugins, or to the operator workflow for Agnostic operators.
3. Select the target plugin or operator and trigger the upgrade. The Marketplace upgrade flow reads the package previously pushed with violet.

If you skipped pushing an Agnostic plugin during pre-upgrade and the Marketplace does not offer the target version, complete the violet push step first and then retry the Marketplace upgrade.