DPF Operator Upgrade Guide

DPF Operator Version Migration Guides

This document describes the process of upgrading between different versions of the DPF Operator.

Prerequisites

Before starting the upgrade process, ensure you have the following Helm Prerequisites installed and configured.

Further prerequisites include:

• All DPF Operator components MUST be in a ready state

• All DPUs MUST be in a ready and healthy state

• Always review the release notes for the version you are upgrading to

• Release notes contain critical information about:

  • New features and capabilities

  • Bug fixes and improvements

  • Breaking changes and migration requirements

  • Known issues and workarounds

  • Configuration changes that may be required

Verifying Readiness

You can verify the readiness of your DPF Operator and DPUs using dpfctl or kubectl:

Using dpfctl (recommended):

# Check overall DPF Operator status
dpfctl describe all --show-resources=dpfoperatorconfig

# Check all conditions for troubleshooting
dpfctl describe all --show-resources=dpfoperatorconfig --show-conditions=all

The dpfctl tool provides a more user-friendly view of the DPFOperatorConfig status and all related conditions, making it easier to identify validation issues.

Using kubectl:

kubectl get dpfoperatorconfig -o yaml

All status conditions in the status section should be True, and the version field should match the current DPF Operator version.

DPF Operator Lifecycle

When a new major version is released:

• New major version is supported

• Previous major version enters EOL (end-of-life)

Supported Upgrade Path (n-1 Policy)

Important: DPF Operator follows an n-1 upgrade policy with the version pattern year.month.patchVersion. You can upgrade from the previous release version to the current release version. Patch-level upgrades within the same minor version are always allowed.

✅ Supported:

• v25.7.0 → v25.10.0

• v25.7.0 → v25.7.1

❌ Not Supported:

• v25.4 → v25.7 (unsupported version upgrade)

• v25.7 → next GA release (skipping version v25.10)

Why this matters: Skipping versions can lead to:

• Failed upgrades due to missing intermediate API changes

• Data corruption or loss

• Incompatible resource states

• Unsupported configuration combinations

BlueField BFB Support Matrix

For the full BFB version compatibility matrix, see the BlueField BFB Support Matrix in the Platform Support documentation.

Prevalidation

Before the DPF Operator upgrades any components, the system performs prevalidation checks to ensure the cluster is in a safe state for the upgrade. These validations are automatically executed and must pass before the upgrade can continue.

• Version Compatibility Validation

  • DPF Version Check: Validates that the current DPF version is compatible with the target version

  • Supported Upgrade Path: Ensures you are upgrading from a supported version (n-1 policy)

• System Components Readiness

  • The operator validates that all critical system components are ready for upgrade

• DPU State Validation

  • DPU Readiness: All DPUs must be in a ready state

  • DPF Version Compatibility: Each DPU's DPF version must be compatible with the upgrade

  • DPU Health: All DPUs must be healthy and operational

Validation Failure Handling

If any validation fails:

• Upgrade Blocked: The upgrade process is automatically halted

• Status Updates: The DPFOperatorConfig status reflects the validation failure

Performing the Upgrade

Upgrade the DPF Operator using Helm. This assumes the DPF Helm repository is already configured as described in the Getting Started Guide (repo setup, OCI registry variants, and Helm prerequisites are covered there).

helm repo update
helm upgrade --install -n dpf-operator-system dpf-operator \
  dpf-repository/dpf-operator --version=$TAG --reset-then-reuse-values

Replace $TAG with the target DPF Operator version (e.g. v26.4.0).

Alternatively, re-apply the original values file explicitly with -f values.yaml. If the file is no longer available, the currently deployed values can be retrieved from the release:

helm get values dpf-operator -n dpf-operator-system > values.yaml

Validate the Upgrade

Verify the controller has rolled out:

kubectl -n dpf-operator-system rollout status deployment dpf-operator-controller-manager

Confirm that DPFOperatorConfig reports the new version in its status (status.version should match $TAG):

kubectl -n dpf-operator-system get dpfoperatorconfig dpfoperatorconfig -o jsonpath='{.status.version}'

Or, using dpfctl:

dpfctl describe all --show-resources=dpfoperatorconfig

What to Do Next

After completing your DPF Operator upgrade, follow these steps to ensure everything is working correctly:

1. Update to Supported BFB and DPUFlavor: Create the new BFB object and DPUFlavor object according to the new guide. Review and update your DPUDeployment/DPUSet resources as needed to reference those objects to make the system compatible with the new operator version.

2. Update DPUServices: Review and update your DPUDeployment/DPUService resources to use services that are compatible with BFB version and operator version.

3. Monitor the Upgrade: Use dpfctl describe all to monitor the reconciliation process and ensure all resources reach ready state.

Last updated: June 24, 2026