Upgrade Portworx (or Kubernetes) on an air-gapped cluster

During installation on an internet-connected Kubernetes cluster, Portworx fetches the resources necessary for installation from the internet automatically. However, while installing Portworx on an air-gapped cluster, you would have to perform an extra step to pre-stage these resources within the air-gapped environment.

Similarly, to upgrade your Portwiorx installation on an air-gapped cluster, you will fetch updated container images, and then pre-stage them within the air-gapped cluster.

Since, Portworx leverages a component of the Kubernetes control plane to make enhanced Kubernetes scheduling decisions based on storage layout. Therefore, these steps are also required if your cluster’s Kubernetes/control plane is updated as well.

WARNING: If you do not perform these pre-staging steps before upgrading either Portworx or Kubernetes on an air-gapped cluster, your pods can enter crash loops and cause service disruptions.

Follow the instructions on this page to get the updated container images, pre-stage them within the air-gapped cluster, and then proceed to upgrade your Portworx installation.


  • You must have an existing Portworx Kubernetes cluster that is healthy and operational.
  • You should be using the same internal or private container registry as used during the installation.

NOTE: To check what registry you’re currently using, query your existing StorageCluster by running the following command:

STORAGECLUSTER_NAME=$(kubectl -n kube-system get storagecluster -o jsonpath='{.items[0].metadata.name}')
kubectl get stc -n kube-system $STORAGECLUSTER_NAME -o jsonpath='{.spec.image}{"\n"}'

Get the updated container images

  1. Set an environment variable for the Kubernetes version that you are using:

    KBVER=$(kubectl version --short 2>/dev/null | awk -F'[v+_-]' '/Server Version: / {print $3}')
  2. Set an environment variable to the latest major version of Portworx:

    NOTE: For the latest Portworx version, see Portworx Release Notes.
  3. On an internet-connected host, fetch the same air-gapped-install bootstrap script used during installation, for the Kubernetes and Portworx versions that you specified:

    curl -o px-ag-install.sh -L "https://install.portworx.com/$PXVER/air-gapped?kbver=$KBVER"
  4. Pull the container images required for the specified versions:

    sh px-ag-install.sh pull
  5. Log in to the container registry using the docker command:

    docker login <your-private-registry>
  6. Push the container images to the same private container registry that is accessible to your air-gapped nodes. Do not include http:// in your private registry path:

    sh px-ag-install.sh push <your-registry-path>

    For example:

    sh px-ag-install.sh push myregistry.net:5443

    For example, to push the new images to a specific repo (consult your StorageCluster definition as per the note in the Prerequisites):

    sh px-ag-install.sh push myregistry.net:5443/px-images

Create a version manifest configmap for Portworx Operator

  1. Download the Portworx version manifest:

    curl -o versions "https://install.portworx.com/$PXVER/version?kbver=$KBVER"
  2. Update (deleting/recreating) the px-versions configmap from the downloaded version manifest:

    kubectl -n kube-system delete configmap px-versions
    kubectl -n kube-system create configmap px-versions --from-file=versions

Upgrade Portworx installation

NOTE: Skip this section if you are upgrading only the Kubernetes control plane version.

Follow the steps in the Upgrade Portworx section to upgrade the Portworx StorageCluster spec.

Last edited: Tuesday, May 9, 2023