Skip to main content
Version: 25.8

Upgrade PX-CSI

Upgrading to Portworx CSI 25.8.0 introduces a major architectural simplification by removing components such as KVDB and system services.

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

All metadata required for CSI operations is now stored as Kubernetes custom resources in the cluster's etcd. New resource types such as PureVolume and PureSnapshot replace the KVDB-managed state. During the upgrade, the Portworx Operator automatically migrates the existing metadata.

Starting from PX-CSI 25.8.0, a new ComponentK8sConfig custom resource (CR) named px-pure-csi-k8s-config is created by default. This CR instance can be used to configure CPU and memory limits, tolerations, and node affinity across PX-CSI components. For more information, see Configure resource limits, placements, tolerations, and nodeAffinity for PX-CSI components.

This guide walks you through the upgrade process while maintaining application availability and backward compatibility.

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

Prerequisites​

Ensure the following prerequisites are met:

  • Your Kubernetes cluster meets the Portworx system requirements.

  • All Portworx Pods including KVDB are in a Running state.

    Check the cluster status using the following command:

    kubectl get pods -n <portworx>
  • Delete any stale volumes from KVDB before migrating.
  • Verify that API tokens and FlashArray/FlashBlade management endpoints are correct.
  • Remove any tolerations in the StorageCluster that use operator: Exists, as they will block upgrade to version 25.8.0.

Upgrade the Portworx Operator​

Before upgrading the StorageCluster, upgrade the Portworx Operator to the latest version.

  1. Check the current Portworx Operator version:

    kubectl get deployment -n <portworx> portworx-operator -o=jsonpath='{.spec.template.spec.containers[0].image}'

  2. Edit the Operator deployment:

    kubectl edit deployment -n <portworx> portworx-operator

    Update the image to use the latest version:

    containers:
    - name: portworx-operator
      image: portworx/px-operator:<latest-version>

  3. Verify the rollout status:

    kubectl rollout status deployment/portworx-operator -n <portworx>

Upgrade the StorageCluster​

  1. Retrieve the name of your Portworx StorageCluster:

    kubectl get storagecluster -n <portworx>

  2. Modify the spec.image field in the StorageCluster resource to update the image version:

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

    Set the spec.image value to portworx/px-pure-csi-driver:<desired-version>

  3. (Optional) If you are migrating from Portworx Essentials with FlashArray/FlashBlade to PX-CSI, update the portworx.io/misc-args annotation to include:

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

  4. Save the changes and monitor the migration:

    1. Check the status of migration Pods:

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

    2. View the StorageCluster status:

      kubectl get storagecluster -n <portworx> -o yaml

      Verify that the migration 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:

      kubectl get purestoragecluster -n <portworx>

  5. Verify the upgrade:

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

After a successful upgrade:

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

Clean up stale files​

After the upgrade, 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>

  3. In rare cases, when migrating from Portworx version 25.6.0 or earlier, KVDB pods may continuously restart due to tolerations using operator: Exists. If this occurs, edit the StorageCluster specification and remove the affected toleration to allow the migration to proceed. You can add specific key-based tolerations if needed.