Upgrading DataCore Puls8

Explore this Page

Overview

DataCore Puls8 supports in-place upgrades to deliver new features, performance enhancements, and stability improvements while preserving existing storage resources and configurations.

The DataCore Puls8 upgrade is a two-phase process:

  • Phase 1: Control-Plane Upgrade (Helm upgrade)
    • Updates the Puls8 control-plane components without interrupting storage I/O.
  • Phase 2: Data-Plane Upgrade (Replicated PV Mayastor io-engine restart)
    • Restarts Replicated PV Mayastor io-engine pods one at a time. After each restart, the DataCore Puls8 upgrade job waits for volume replica rebuilds to complete before proceeding to the next node. This ensures data availability for multi-replica Replicated PV Mayastor volumes.
    • After each io-engine restart:
      • Replica rebuild begins
      • The upgrade waits until the rebuild completes
      • The upgrade proceeds to the next node
    • The upgrade duration depends on:
      • Volume size
      • Number of nodes
      • Storage performance
      • Network performance

This document describes how to upgrade DataCore Puls8 from version 4.3 to version 4.4. It includes upgrade requirements, pre-upgrade validation, upgrade procedure, and post-upgrade verification.

Upgrading to DataCore Puls8 4.4 provides access to the latest features, enhancements, and stability improvements.

Downgrading DataCore Puls8 to a previous version is not supported.

The upgrade follows this sequence:

  • Supported source version:DataCore Puls8 4.3
  • Target version:DataCore Puls8 4.4
  • Downgrade support: Not supported
  • Replicated PV Mayastor single-replica volumes: Temporary downtime during restart
  • Replicated PV Mayastor multi-replica volumes: Remain available, may briefly degrade

Puls8 Plugin Version

The version of the kubectl puls8 plugin determines the DataCore Puls8 version you upgrade to. For example: To upgrade to DataCore Puls8 4.4, install the DataCore Puls8 4.4 plugin.

Copy
Verify kubectl puls8 plugin version
kubectl puls8 -V

You can download the plugin from the DataCore Downloads portal.

Always install the kubectl puls8 plugin version that matches your intended target Puls8 version before starting the upgrade.

Cluster Requirements

  • A healthy Kubernetes cluster running a supported version.
  • DataCore Puls8 4.3 installed using the documented Helm installation process.
  • DiskPools must have sufficient free capacity for replica rebuilds.

Access Requirements

  • Kubernetes cluster administrator privileges.
  • Ability to pull DataCore Puls8 4.4 container images.
  • Permission to install and execute the kubectl puls8 binary.

Network Requirements

Ensure no firewall or network policy restrictions block:

  • Puls8 container image registry
  • Puls8 control-plane communication

If your environment uses a private, custom, or air-gapped container registry, ensure that all Puls8 images required for the target version are available in the registry before starting the upgrade. The upgrade process pulls the required images automatically, and missing images will cause the upgrade to fail.

If a custom registry or repository namespace is used, ensure the Helm configuration and upgrade command reference the correct registry location.

The upgrade follows this sequence:

  1. Install the kubectl puls8 plugin for the target version.
  2. Validate cluster and DataCore Puls8 component health.
  3. Backup existing Helm configuration.
  4. Run upgrade command.
  5. The kubectl puls8 plugin creates the Puls8 upgrade job, which performs the following operations:
    1. Executes the Helm upgrade to update control-plane components.
    2. Waits for replica rebuild operations to complete between each restart.
    3. Completes the upgrade and returns the system to a normal operational state.

DataCore Puls8 automatically performs a rolling upgrade of Replicated PV Mayastorio-engine pods to ensure storage availability and data integrity.

Validate the Puls8 environment to ensure the cluster, storage resources, and workloads are healthy before starting the upgrade. This helps prevent upgrade failures and ensures storage continuity.

  1. Verify currently installed Puls8 version.
    Copy
    Verify Installed Puls8 Version
    helm get metadata <release-name> -n <namespace>
  2. Verify node health.
    Copy
    Verify that all Kubernetes Nodes are in Ready State
    kubectl get nodes
  3. Verify DataCore Puls8 component health.
    Copy
    Confirm that Puls8 Pods are Running and Stable
    kubectl get pods -n <namespace>
  4. Verify DiskPool health.
    Copy
    Ensure all DiskPools are Healthy and Online Before Upgrading
    kubectl get diskpools -n <namespace>
  5. Verify volume health.
    Copy
    Confirm Puls8 Volumes are Healthy and Stable
    kubectl puls8 mayastor get volumes -n <namespace>

    Local Storage operates in kernel space and remain unaffected during Puls8 container restarts.

    StorageImpact
    Replicated PV MayastorTemporary volume unavailability during io-engine restart
    Local PV HostpathNo impact
    Local PV LVMNo impact
    Local PV ZFSNo impact

    Single-replica Replicated PV Mayastor volumes will experience temporary downtime during upgrade. Plan maintenance windows accordingly.

    Volume TypeUpgrade Impact
    2+ replicasRemains available
    1 replicaTemporary downtime (1-3 minutes per node)

  6. Verify Persistent Volume Claims (PVCs).
    Copy
    Verify PVC Status
    kubectl get pvc
  7. Verify VolumeSnapshots.
    Copy
    Verify VolumeSnapshot Status
    kubectl get volumesnapshots

Although DataCore Puls8 upgrades do not alter user data or storage objects, it is recommended to retain backups of key configuration details:

Copy
Backup Existing Helm Values
helm get values <release-name> -n <namespace> > puls8-4.3-values-backup.yaml

Also consider backing up:

  • StorageClass manifests
  • DiskPool manifests
  • Application manifests referencing DataCore Puls8 volumes

Backing up Helm values allows you to restore configuration settings if recovery is required.

Upgrade DataCore Puls8

Upgrade DataCore Puls8 to apply the new version to control-plane and data-plane components. The upgrade is performed as a rolling operation, ensuring storage resources and data remain preserved while the new version is applied.

  1. Verify kubectl puls8 plugin version.
    Copy
    Verify Installed kubectl puls8 Plugin Version
    kubectl puls8 -V

    Ensure plugin version matches desired target version.

  2. Start the DataCore Puls8 upgrade.
    Copy
    Start the Puls8 Upgrade to the Target Version
    kubectl puls8 upgrade -n <namespace>

    This initiates both control-plane and data-plane upgrades.

    The upgrade automatically restarts Replicated PV Mayastor io-engine pods sequentially.

  3. Monitor upgrade progress.
    Copy
    Monitor the Upgrade Process Until it Completes
    kubectl puls8 upgrade status -n <namespace>
  4. View the detailed upgrade logs. (Optional)
    Copy
    View Upgrade Logs
    kubectl logs -n <namespace> job/puls8-upgrade-v4-4-0 -f
  5. Cleanup Upgrade Resources. (Optional)
    Copy
    Remove Upgrade Resources After Successful Completion
    kubectl puls8 upgrade delete -n <namespace>

By default, the Puls8 upgrade performs both control-plane and data-plane upgrades. If required, you can upgrade only the control-plane components without restarting the Replicated PV Mayastorio-engine pods.

Upgrade Control-Plane Only

Copy
Upgrade Control-Plane Only Without Restarting io-engine Pods
kubectl puls8 upgrade -n <namespace> --skip-data-plane-restart

Use when:

  • You want to restart io-engine pods manually later
  • You are scheduling data-plane upgrade separately

By default, the Puls8 upgrade performs both control-plane and data-plane upgrades. If required, you can upgrade only the control-plane components without restarting the Replicated PV Mayastorio-engine pods.

After the upgrade completes, validate the Puls8 environment to ensure all components, storage resources, and workloads remain healthy and operational.

  1. Verify DataCore Puls8 component health.
    Copy
    Verify Puls8 Pods After Upgrade
    kubectl get pods -n <namespace>
  2. Verify DiskPool health.
    Copy
    Verify DiskPool Health After Upgrade
    kubectl get diskpools -n <namespace>
  3. Verify PVCs.
    Copy
    Verify PVC Status After Upgrade
    kubectl get pvc
  4. Verify volume health.
    Copy
    Verify Puls8 Volume Health After Upgrade
    kubectl puls8 mayastor get volumes -n <namespace>
  5. Verify VolumeSnapshots.
    Copy
    Verify VolumeSnapshots After Upgrade
    kubectl get volumesnapshots
  6. Verify installed Puls8 version.
    Copy
    Confirm Upgraded Puls8 Version
    helm get metadata <release-name> -n <namespace>

Basic Syntax

Copy
Puls8 Upgrade Command Syntax
kubectl puls8 upgrade -n <namespace> [OPTIONS]

Common Options

Option Description
-n, --namespace Puls8 namespace
-r, --release-name Helm release name
--set KEY=VALUE Override Helm values
--set-file KEY=PATH Override values from file
--registry Override container registry
--repo-namespace Override image repository namespace

Validation Skip Options

Option Description
--skip-single-replica-volume-validation Skip warning for single-replica volumes
--skip-replica-rebuild Skip rebuild validation
--skip-cordoned-node-validation Skip cordoned node validation

Skipping validations may increase upgrade risk. Use these options only when necessary.

Troubleshooting

Common upgrade issues include:

  • Validation failures during upgrade

    • If the upgrade fails during validation, configuration issues, unhealthy storage resources, or cluster state conditions may be preventing the upgrade from proceeding. DataCore Puls8 waits for rebuild completion before proceeding to ensure data redundancy and consistency.

    Copy
    View Upgrade Job Logs for Validation Errors
    kubectl logs -n <namespace> job/puls8-upgrade-v4-4-0

    Resolve the reported issue before retrying the upgrade.

  • Version mismatch between plugin and installed Puls8 version

    • If the upgrade fails due to a version mismatch, the installed kubectl puls8 plugin version may not match the intended target version or may be older than the installed Puls8 version.

    Copy
    Verify Both Plugin and Installed Puls8 Versions
    # Verify kubectl puls8 plugin version
    kubectl puls8 -V
    # Verify installed Puls8 version
    helm get metadata <release-name> -n <namespace>

    Install the appropriate plugin version before retrying the upgrade.

  • Image pull errors caused by registry access restrictions

    • If the upgrade fails due to container image pull errors, the cluster may not have access to the default container registry or repository. In such cases, explicitly specify the container registry and repository namespace when running the upgrade command using the following options:

    Copy
    Override Container Registry and Repository Namespace for the Upgrade
    --registry <REGISTRY>
        Specify the container registry for the upgrade-job image
    --repo-namespace <REPO_NAMESPACE>
        Specify the container namespace for the upgrade-job image
        (default: datacoresoftware)
  • Namespace discrepancies when running upgrade commands

    • If the upgrade fails due to namespace mismatches, ensure that all kubectl puls8 commands explicitly specify the namespace where DataCore Puls8 is installed. Use the -n <namespace> flag consistently with all upgrade commands, for example:

    Copy
    Example
    kubectl puls8 upgrade -n <namespace>

    Replace <namespace> with the namespace in which DataCore Puls8 is deployed.

  • Upgrade stuck during replica rebuild

    • If the upgrade pauses for an extended period, it may be waiting for volume replica rebuilds to complete. DataCore Puls8 waits for rebuild completion before proceeding to ensure data redundancy and consistency.

    Copy
    Monitor Volume Health and Rebuild Progress
    kubectl puls8 mayastor get volumes -n <namespace>

    Wait until all volumes report a Healthy state and rebuild operations are complete.

  • Cleanup stuck upgrade resources

    • If the upgrade does not complete successfully, the upgrade Kubernetes resources cannot be removed using the standard cleanup command. In such cases, use the force option to forcibly delete the upgrade resources.

    Copy
    Force Cleanup Upgrade Resources
    kubectl puls8 upgrade delete -n <namespace> --force
  • View upgrade logs for debugging

    • To diagnose upgrade failures or monitor upgrade activity, review the upgrade job logs:

    Copy
    Inspect Puls8 Upgrade Job Logs
    kubectl logs -n <namespace> job/puls8-upgrade-v4-4-0 -f

    These logs provide detailed information about upgrade progress, validation failures, and component status.

Best Practices

Follow these best practices to ensure a safe upgrade:

  • Install the correct plugin version first
  • Test upgrade in non-production environment
  • Use multi-replica volumes for critical workloads
  • Schedule maintenance window
  • Notify application owners
  • Monitor rebuild progress
  • Do not interrupt upgrade during rebuild

Learn More