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.

####

2. Download and Install New Artifacts.

To obtain and install the SMCP 5.12 artifacts:

a. Download the download script:

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

b. Make the script executable:

chmod u+x download.sh

c. Run the download script:

./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:

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 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 :

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:

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

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.

airctl advanced-ddu upgrade-mgmt --verbose

5. Verify DU Status

Check that the DU is in a ready state:

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:

airctl status

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):

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

To push all new images at once:

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 {}"

9. Upgrade Host Components

Upgrade the host-side components:

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.

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.