Skip to main content
Version: 3.3

Upgrade an Air-Gapped Portworx 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 Portworx 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.

caution

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.

Prerequisites​

  • 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 are currently using, query your existing StorageCluster by running the following command:

STORAGECLUSTER_NAME=$(kubectl -n <px-namespace> get storagecluster -o jsonpath='{.items[0].metadata.name}')
kubectl get stc -n <px-namespace> $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:

    PXVER=<portworx-version>
    note

    For the latest Portworx version, see Portworx Release Notes.

  3. On an internet-connected host with the same architecture and OS version as the Kubernetes cluster nodes intended for Portworx installation, download the air-gapped installation bootstrap script for the specified Kubernetes and Portworx versions:

    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.yaml "https://install.portworx.com/$PXVER/version?kbver=$KBVER"

  2. Update (deleting/recreating) the px-versions configmap from the downloaded version manifest:

    kubectl -n <px-namespace> delete configmap px-versions
    kubectl -n <px-namespace> create configmap px-versions --from-file=versions.yaml

Upgrade Portworx installation​

note

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

  • If using configmap, update the version manifest for Portworx Operator. Otherwise, you might not see the expected image versions.

  • If you override the default PodDisruptionBudget in GKE environments, ensure that the maxUnavailable is less than the storage-pdb-min-available value for a balanced speed and disruption. Portworx by Pure Storage recommends using the following configurations for surge upgrades:

    • maxSurge=1
    • maxUnavailable=0

  1. Log in to the custom container registry using your JFrog credentials.
    The registry automatically creates the following sample config.json file:

    cat /root/.docker/config.json
    {
            "auths": {
                    <custom registry name>: {
                "auth": <Base 64 version of Jfrog username: Jfrog token>
                    }
            }
    }

    Replace custom registry name with the name of the custom registry and Base 64 version of Jfrog username: Jfrog token with the base 64 version of your jfrog username and token.

  2. Use the config.json file, and create a registry secret to pull container images from the custom container registry:

    kubectl create secret generic regcred -n portworx \
    --from-file=.dockerconfigjson=/root/.docker/config.json \
    --type=kubernetes.io/dockerconfigjson

    After creating the regcred registry secret, add the registry secret in the Kubernetes Docker Registry Secret field.

  3. Retrieve the name of your Portworx StorageCluster within the appropriate namespace:

    kubectl get storagecluster -n <px-namespace>
    NAME                                            STATUS   VERSION   AGE
    px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Online   2.10.3    43d

    If your cluster is installed in a different namespace, specify it using the -n flag.

  4. Modify the StorageCluster resource to update Portworx to the desired version:

    kubectl edit storagecluster -n <px-namespace> <storagecluster-name>

    In the editor, make the following changes in the StorageCluster:

    • Update the spec.image field to your desired Portworx version.
    • (optional) For smart upgrade, ensure that the spec.updateStrategy.rollingUpdate.disruption.allow parameter is set to false and the maximum number of nodes that can be upgraded at a time is set using the spec.updateStrategy.rollingUpdate.maxUnavailable parameter.
    apiVersion: core.libopenstorage.org/v1
    kind: StorageCluster
    metadata:
       name: portworx
       namespace: <px-namespace>
    spec:
       image: portworx/oci-monitor:<desired-version>
       # For smart upgrades, ensure that the below lines are uncommented and `disruption.allow` is set to false. You can use the `maxUnavailable` field to control the maximum number of Portworx nodes that can be upgraded at a time.
       #updateStrategy:
       #   type: RollingUpdate
       #   rollingUpdate:
       #      maxUnavailable: 5
       #      minReadySeconds: 0
       #      disruption:
       #         allow: false
    note
    • If there are any component images configured in the StorageCluster, such as the spec.stork.image or spec.autopilot.image fields, you need to update the image fields to the latest version.
    • To look up recent versions, refer to the following release notes:

  5. Verify that the upgrade is complete by checking the Portworx version on the nodes:

    kubectl get storagenodes -n <px-namespace> -l name=portworx
    NAME       ID                                     STATUS   VERSION          AGE
    node-1-1   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   Online   <desired-version>   10d