This is unreleased documentation for SUSE® Storage 1.12 (Dev).

On-Demand Snapshot Checksum Calculation

SUSE Storage supports on-demand snapshot checksum calculation via CR operation and CLI.

Introduction

Besides periodic snapshot data integrity checks, SUSE Storage provides an on-demand snapshot checksum mechanism. This feature allows users to manually trigger checksum calculation for all user-created snapshots of a volume without waiting for the scheduled cron job.

On-demand checksum is useful when users need immediate calculation of snapshots for speeding up replica rebuilding.

Related Custom Resource Information

Volume

SUSE Storage uses the following fields to trigger an on-demand snapshot checksum calculation request:

  • Spec.SnapshotHashingRequestedAt: SnapshotHashingRequestedAt is the RFC3339 timestamp (for example, "2026-03-16T10:30:00Z") when an on-demand snapshot checksum calculation is requested. When this value is set and is later than LastOnDemandSnapshotHashingCompleteAt, the system calculate checksums for all user snapshots.

    If SnapshotHashingRequestedAt differs from LastOnDemandSnapshotHashingCompleteAt, it indicates that a hashing request is still in progress, and new request is going be rejected.

  • Status.LastOnDemandSnapshotHashingCompleteAt: LastOnDemandSnapshotHashingCompleteAt is the RFC3339 timestamp (for example, "2026-03-16T10:30:00Z") when the most recent on-demand snapshot checksum calculation completed. When this value matches SnapshotHashingRequestedAt, the requested on-demand checksum calculation is considered complete.

Snapshot

Each snapshot records the timestamp of its latest checksum calculation:

  • Status.ChecksumCalculatedAt: ChecksumCalculatedAt is the RFC3339 timestamp indicating when the checksum for this snapshot was last calculated or updated.

How It Works

When a user triggers an on-demand checksum request, SUSE Storage performs the following actions:

1. User issues an on-demand request

The request is initiated through the Longhorn CLI:

./longhornctl checksum volume --name=\<volume-name\> --namespace=longhorn-system
./longhornctl checksum volume --node-id=v\<node-name\> --namespace=longhorn-system
./longhornctl checksum volume --all=true --namespace=longhorn-system

2. Detects a new request

The Volume Controller compares Spec.SnapshotHashingRequestedAt with Status.LastOnDemandSnapshotHashingCompleteAt. If the requested timestamp is newer, SUSE Storage triggers the SnapshotMonitor to calculate checksums for all existing user-created snapshots that are missing checksum data.

3. Calculates snapshot checksums

Performs the checksum calculation using the standard snapshot data integrity logic.

4. VolumeController evaluates completion

SUSE Storage considers the on-demand request completed when all relevant user-created snapshots have a checksum.

5. Completion is recorded

When all snapshots satisfy the criteria above, SUSE Storage updates Volume.Status.LastOnDemandChecksumCompletedAt. This indicates that the on-demand checksum request has been processed.

CLI Usage

SUSE Storage provides a CLI interface to trigger on-demand snapshot checksum operations through the longhornctl command-line tool.

Usage:

longhornctl checksum volume [flags] [options]

Options:

--all: Apply to all volumes (default: false) --name: Name of the Longhorn volume --node-id: Compute snapshots for all volumes on the specified node

This is an asynchronous operation. When the request is marked as complete in the output log, it indicates the trigger was successful. Since there is no dedicated Request CRD, the CLI output confirms the controller has acknowledged the Spec update. Actual computation occurs in the background and duration scales with volume size. You can monitor the progress and check snapshot checksums using kubectl.

Example

Command:

./longhornctl-linux-amd64 checksum volume --all=true

Output:

INFO[2026-03-18T17:04:27+08:00] Triggering on-demand snapshot checksum calculation
INFO[2026-03-18T17:04:27+08:00] Requested on-demand checksum calculation for volume tmp1  volume=tmp1
INFO[2026-03-18T17:04:27+08:00] Requested on-demand checksum calculation for volume tmp2  volume=tmp2
INFO[2026-03-18T17:04:27+08:00] Snapshot checksum calculation may take some time. You can check the snapshot checksum via kubectl.
INFO[2026-03-18T17:04:27+08:00] Checksum request submitted
INFO[2026-03-18T17:04:27+08:00] Cleaning volume on-demand checksum requester
INFO[2026-03-18T17:04:27+08:00] Completed volume on-demand checksum requester

Limitations

  • On-demand snapshot checksum only applies to volumes with at least two replicas, consistent with the behavior of periodic snapshot data integrity checks.

  • The global or per-volume setting snapshot-data-integrity must be set to either enabled or fast-check. The feature is not available when data integrity is disabled.