#Pre-Upgrade Preparation

Supported upgrade paths:

• From 4.0 → 4.3
• From 4.1 → 4.3
• From 4.2 → 4.3

Before starting, ensure your current platform version is within the supported upgrade range.

#Important Notes

• Ensure the directory /cpaas/minio on the control plane nodes of global cluster has at least 120 GB of free disk space.
• Before upgrading the global tier to ACP 4.3, all workload clusters must remain within the ACP 4.3 Compatible Versions documented in Kubernetes Support Matrix.
• If any workload cluster is outside that compatible range, upgrade that workload cluster first until it enters the ACP 4.3 compatible range before upgrading the global tier.
• A workload cluster can be upgraded only to a Distribution Version that the global tier has already reached.

#Download the Packages for Offline Environments

A production maintenance window typically upgrades Core, the Aligned plugins (cluster plugins and operators released together with the same ACP version), and the in-use Agnostic plugins (independently released cluster plugins and operators) in the same window. Prepare every package the cluster currently uses before the upgrade starts, even when an Agnostic plugin upgrade is technically optional. Holding back an Agnostic plugin during the window often forces a second maintenance window later.

#Step 1: Download the Core Package

From the Customer Portal, download the Core Package. The Core package carries only the Core artifacts that upgrade.sh will prepare for the CVO-driven Core upgrade.

The Core package does not bundle the Aligned plugin packages, even though CVO knows which Aligned plugin versions correspond to the target ACP release. Aligned plugin packages must be downloaded separately from the Customer Portal and pushed with violet; the next step covers that workflow alongside the Agnostic plugins.

#Step 2: Inventory the plugins on every cluster in scope

Cluster plugins and operators are managed by different mechanisms. Both are needed in this step:

• Cluster plugins are global resources. A cluster plugin pushed to the global tier becomes installable and upgradable on every cluster in the platform; you only push each cluster plugin once.
• Operators are scoped to each cluster. Pushing an operator to the global tier is the recommended starting point, but the same operator package must be available on each workload cluster before that cluster's upgrade.

Navigate to the CLI Tools section in the Customer Portal and download the violet tool. violet is required for uploading Aligned and Agnostic plugin packages. For more information about violet, see Upload Packages.

On any machine with network access to the platform endpoint, run violet list to list the plugins (both Aligned and Agnostic) installed in the current environment and export the result to ./apps.yaml:

violet list \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --output-file "./apps.yaml"

Prefer --platform-token over --platform-password to avoid exposing passwords in shell history and process listings (ps aux).

#Step 3: Align the Customer Portal package list

Import the exported apps.yaml file into the Customer Portal to align the package list with what your clusters currently run. The portal then exposes the matching target-version packages — Core, Aligned plugins, and the Agnostic plugins your clusters use — for download.

Download every package you will need so they are all available locally before the upgrade window starts. The next page, Upgrade the global cluster, describes how upgrade.sh and violet push these packages into the platform.

violet push <path/to/directory/only_put_topolvm_plugin_here> \
  --target-catalog-source "platform" \
  --platform-address "https://example.com" \
  --platform-token "<platform_token>" \
  --clusters "cluster-a,cluster-b"