Skip to main content
Version: 26.1

Upgrade PX-CSI

This page provides instructions for upgrading PX-CSI to the latest version. The upgrade process consists of two steps:

  1. Upgrade the Portworx Operator - Update the Operator to the latest version to ensure compatibility with the new PX-CSI version.
  2. Upgrade the StorageCluster - Update the PX-CSI image version based on your current version.
note

The pxctl CLI is removed starting in PX-CSI 25.8.0. Use kubectl, oc, or apply YAML manifests to manage CustomResource objects.

Upgrade the Portworx Operator​

Upgrade the Portworx Operator to the latest version before upgrading the StorageCluster. This step is required for both upgrade paths.

Upgrade the Portworx Operator using the OpenShift web console:

  • OCP version 4.20 or later:
    From the OpenShift UI, go to Ecosystem > Software Catalog, search for Portworx Operator, and upgrade the operator to the latest version.
  • OCP version 4.19 or earlier:
    From the OpenShift UI, go to OperatorHub, search for Portworx Operator, and upgrade the operator to the latest version.

For detailed instructions, see Red Hat documentation on updating installed operators.

Upgrade the StorageCluster​

Choose the upgrade procedure based on your current PX-CSI version:

Upgrade from 25.8.0 or later​

If you are running PX-CSI 25.8.0 or later, upgrade to the latest version by updating the image version in your StorageCluster resource. The Portworx Operator manages the upgrade automatically.

Prerequisites​

Before upgrading, ensure the following requirements are met:

  • Your Kubernetes cluster meets the system requirements.

  • All PX-CSI pods are in a Running state:

    kubectl get pods -n <portworx>

Update the StorageCluster image version​

  1. Retrieve the name of your Portworx StorageCluster:

    oc get storagecluster -n <portworx>
    NAME              CLUSTER UUID          STATUS    VERSION   AGE
    px-cluster-test   *****-****-****-****  Running   25.8.1    4d

  2. Edit the StorageCluster resource to update the image version:

    oc edit storagecluster -n <portworx> <px-cluster-test>

    Find the spec.image field:

    apiVersion: core.libopenstorage.org/v1
    kind: StorageCluster
    metadata:
      name: px-cluster-test
      namespace: <portworx>
    spec:
      image: portworx/px-pure-csi-driver:25.8.1

    Update the image version to the desired version (for example, 26.1.0):

    spec:
      image: portworx/px-pure-csi-driver:26.1.0

  3. Save the changes and verify the upgrade:

    oc get pods -n <portworx>
    oc get storagecluster -n <portworx>
    note

    You can check the upgrade status of nodes at any time by running oc get storagenodes -A, which shows which nodes have been upgraded and the node currently being upgraded.

After a successful upgrade, all PX-CSI pods run on the new version.

Upgrade from 25.6 or earlier​

If you are running PX-CSI 25.6 or earlier, upgrade to the latest version by migrating to the new Kubernetes-native architecture introduced in PX-CSI 25.8.0. This migration removes components such as KVDB and system services, and stores all metadata as Kubernetes custom resources in the cluster's etcd.

important
  • The migration might briefly disrupt the creation of new persistent volume claims (PVCs) or attaching existing volumes to new nodes. Plan this operation during a maintenance window to reduce impact.
  • If the migration process fails with unrecoverable issues, you must contact Portworx Support for assistance.

What changes during migration​

  • KVDB and system services are removed.
  • All metadata is stored as Kubernetes custom resources in the cluster's etcd.
  • A ComponentK8sConfig CR named px-pure-csi-k8s-config is created to configure CPU and memory limits, tolerations, and node affinity. For more information, see Configure resource limits.
  • The image name changes to portworx/px-pure-csi-driver.
  • The pxctl CLI is removed. Use kubectl, oc, or apply YAML manifests to manage CustomResource objects.

Prerequisites​

Ensure the following prerequisites are met:

  • Your Kubernetes cluster meets the system requirements.

  • All Portworx pods including KVDB are in a Running state:

    kubectl get pods -n <portworx>

  • Delete any stale volumes from KVDB before migrating.

Update the StorageCluster image and migrate to the new architecture​

  1. Retrieve the name of your Portworx StorageCluster:

    oc get storagecluster -n <portworx>

  2. Edit the StorageCluster resource to update the image:

    oc edit storagecluster -n <portworx> <px-cluster-name>

    Find the following section:

    apiVersion: core.libopenstorage.org/v1
    kind: StorageCluster
    metadata:
      name: px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-f7ed5df73365
      namespace: <portworx>
    spec:
      image: portworx/oci-monitor:<current-version>

    Change the spec.image value from portworx/oci-monitor to portworx/px-pure-csi-driver with the desired version (for example, 26.1.0):

    spec:
      image: portworx/px-pure-csi-driver:26.1.0

  3. (Optional) If migrating from Portworx Essentials with FlashArray/FlashBlade:

    portworx.io/misc-args: "--oem px-csi"

  4. Save the changes and monitor the migration:

    1. Check the status of migration pods:

      oc get pods -n <portworx> | grep pure-csi-migrator

    2. View the StorageCluster status:

      oc get storagecluster -n <portworx> -o yaml

      Verify that the migration status is complete:

      status:
        clusterName: px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-f7ed5df73365
        clusterUid: xxxxxxxx-xxxx-xxxx-xxxx-415323ca725b
        conditions:
        - lastTransitionTime: "2025-09-03T08:33:13Z"
          message: Pure CSI Driver migration completed successfully
          source: PxCSI
          status: PureCSIMigrationCompleted
          type: PxCSIMigration

    3. Verify that the PureStorageCluster resource was created:

      oc get purestoragecluster -n <portworx>

  5. Verify the migration:

    oc get pods -n <portworx>
    oc get storagecluster -n <portworx>

After a successful migration:

  • Older pods are removed
  • New pods prefixed with px-pure-csi- are created
  • Migrator pods are retained for debugging

Clean up stale files​

After the migration, some stale files, including pxctl, may remain on the nodes. Clean them up using the following command:

rm -rf /opt/pwx
rm -rf /etc/pwx
note

KVDB drives are not automatically deleted after migration. After completing a successful migration, verify that the migration has completed successfully before manually deleting the KVDB drives.

Troubleshooting​

If the migration job fails, it automatically retries every 10 minutes. Migration is performed by the pre-pure-csi-migrator and post-pure-csi-migrator pods.

To investigate issues:

  1. Check the logs of the migrator pods to identify the root cause:

    kubectl logs -n <portworx> <migrator-pod-name>

  2. If needed, manually delete the failed job to trigger a rerun:

    kubectl delete job -n <portworx> <migrator-job-name>