Upgrade Guide: SMCP 5.11 to SMCP 5.12

Prerequisites

Before beginning the upgrade process, ensure the following requirements are met:

1. Minimum Requirements

2. Minimum Kubernetes version for Workload Cluster should be v1.28.

Upgrade Procedure

1. Backup Current System (optional)

Follow the Backup Guide to back up the 5.11 management plane. Before proceeding, verify that the backup was created successfully.

1. Download and Install New Artifacts.

To obtain and install the SMCP 5.12 artifacts:

a. Download the download script:

None

wget https://raw.githubusercontent.com/platform9/support-locker/master/edge-stack/download.sh

b. Make the script executable:

None

chmod u+x download.sh

c. Run the download script:

None

./download.sh <PF9-SHARED-SECRET> v-5.12.1-<airctl_version>

Replace <PF9-SHARED-SECRET> with your Platform9 shared secret.

d. After downloading the artifacts, verify their integrity using the following command:

Bash

curl --user-agent <secret> https://pf9-airctl.s3-accelerate.amazonaws.com/<version>/md5sum.txt | md5sum -c -

Replace <secret> with the same one used to download the airctl build from S3 and <version> with the SMCP version you're installing (e.g., v5.12.0).

e. Run the install.sh script to extract and place the artifacts under /opt/pf9/airctl directory.

Bash

bash install.sh v-5.12.1-<airctl-version>

Refer to the SMCP 5.12 release notes for the exact airctl version used by the install.sh script.

For example, when upgrading to SMCP v5.12.0 :

example

bash install.sh v-5.12.1-3802903

3. Configure New Management Cluster

Update configuration files before deployment:

1. Edit airctl-config.yaml:

   1. Update hostAgentRepo to use SMCP 5.12 images.

   2. dockerRepo to use SMCP 5.12 images.

2. Edit nodelet-bootstrap.yaml:

   1. Update systemImages to use SMCP 5.12 image files

   2. Set userImages to point to SMCP 5.11 image files

   3. Add isAirgapped: true for offline installations

Example airctl-config.yaml and nodelet-bootstrap.yaml snippet:

airctl-config.yaml

hostAgentRepo: /opt/pf9/airctl/hostagent-8-v-5.12.1-3802903.tar.gz
dockerRepo: /opt/pf9/airctl/docker-8-v-5.12.1-3802903.tar.gz

nodelet-bootstrap.yaml

isAirgapped: true
systemImages:
- /opt/pf9/airctl/imgs/kubedu-imgs-v-5.12.1-3802903.tar.gz
- /opt/pf9/airctl/imgs/nodelet-imgs-v-5.12.1-3802903.tar.gz
userImages:
- /opt/pf9/airctl/imgs/kubedu-imgs-v-5.11.1-3501826.tar.gz

4. Upgrade Management Cluster

Starting from the 5.12 release, in-place upgrades are supported. Use the upgrade-mgmt command to perform an in-place upgrade of the management cluster.

Bash

airctl advanced-ddu upgrade-mgmt --verbose

5. Verify DU Status

Check that the DU is in a ready state:

Bash

airctl status
# This command displays the current status of the DU

Wait until all components show as ready before proceeding.

6. Upgrade DU Components

To upgrade the DU components to5.12, follow the upgrade guide.

After upgrade, verify DU status again:

Bash

airctl status
{% endtab %}
{% tab language="none" %}
// Click to edit code

7. Verify Upgrade in GUI

Log in to the management UI and confirm the version is displayed as 5.12.

8. Push New Kubernetes Images

Push images for Kubernetes 1.29, 1.30, and 1.31 to the registry (if applicable):

Bash

sudo airctl advanced-du push-images --img-tar [tar file name]

To push all new images at once:

Bash

ls -1 /opt/pf9/airctl/imgs/k8s* | xargs -I{} sh -c "sudo /opt/pf9/airctl/airctl --config /opt/pf9/airctl/conf/airctl-config.yaml advanced-du push-images --img-tar {}"

NOTE

If the privateRegistryType value is custom, the images must be manually pushed to the custom registry.

9. Upgrade Host Components

Upgrade the host-side components:

NOTE

If the upgrade is performed on Ubuntu, execute the following commands in reverse order: first, run airctl upgrade-hosts, followed by airctl configure-hosts.

Refer to the known issues for more information.

Bash

airctl configure-hosts --reset-pf9-managed-docker-conf --skip-docker-install --skip-docker-img-import --verbose
# This command configures hosts with new settings

airctl hosts-status
# Check the status of hosts before proceeding

airctl upgrade-hosts --verbose
# This command upgrades the host components

10. Verify Status and Version

After upgrading, verify management plane services are ready. At this point all the components have been upgraded to SMCP 5.12. Run the following command to verify.

Bash

airctl status
# Check the status of management plane

airctl version
# The output should be: v-5.12.1-3802903

kubectl get nodes -o wide
# Ensure all the nodes are in Ready state

Now, proceed with the actual workload cluster upgrades either using the GUI or API.