Important Notes

Edit this page

This page lists important notes for Longhorn v1.10.0. Please see here for the full release note.

Removal

longhorn.io/v1beta1 API

The v1beta1 version of the Longhorn API is removed since Longhorn v1.10.0.

For more details, see Issue #10249.

General

Kubernetes Version Requirement

Due to the upgrade of the CSI external snapshotter to version v8.2.0, ensure that all clusters are running Kubernetes v1.25 or later before upgrading to Longhorn v1.8.0 or any newer version.

CRD Upgrade Validation

During the upgrade process, the Custom Resource Definition (CRD) may be applied after the new Longhorn manager has started. This sequencing ensures that the controller does not process objects with deprecated data or fields. However, this can result in the Longhorn manager failing during the initial upgrade phase if the CRD has not been applied yet.

If the Longhorn manager crashes during the upgrade, check the logs to determine if the failure is due to the CRD not being applied. In such cases, the logs may contain error messages similar to the following:

time="2025-03-27T06:59:55Z" level=fatal msg="Error starting manager: upgrade resources failed: BackingImage in version \"v1beta2\" cannot be handled as a BackingImage: strict decoding error: unknown field \"spec.diskFileSpecMap\", unknown field \"spec.diskSelector\", unknown field \"spec.minNumberOfCopies\", unknown field \"spec.nodeSelector\", unknown field \"spec.secret\", unknown field \"spec.secretNamespace\"" func=main.main.DaemonCmd.func3 file="daemon.go:94"

Upgrade Check Events

Longhorn performs a pre-upgrade check when upgrading with Helm or Rancher App Marketplace. If a check fails, the upgrade will stop and the reason for the check’s failure will be recorded in an event. For more detail, see Upgrading Longhorn Manager.

Manual Checks Before Upgrade

Automated checks are only performed on some upgrade paths, and the pre-upgrade checker may not cover some scenarios. Manual checks, performed using either kubectl or the UI, are recommended for these schenarios. You can take mitigating actions or defer the upgrade until issues are addressed.

  • Ensure that all V2 Data Engine volumes are detached and the replicas are stopped. The V2 Data Engine currently does not support live upgrades.
  • Avoid upgrading when volumes are in the “Faulted” status. If all the replicas are deemed unusable, they may be deleted and data may be permanently lost (if no usable backups exist).
  • Avoid upgrading if a failed BackingImage exists. For more information, see Backing Image.
  • It is recommended to create a Longhorn system backup before performing the upgrade. This ensures that all critical resources, such as volumes and backing images, are backed up and can be restored in case any issues arise.

Consolidation of Longhorn Settings

Longhorn settings have been consolidated to improve manageability and user experience for V1 and V2 Data Engines. Each setting supports only one of the following formats, depending on its definition. The supported format determines which Data Engines can be configured and whether their values can differ.

  • Single value for all supported Data Engines
    • Format: Non-JSON string (e.g., 1024)
    • The value applies to all supported Data Engines and must be the same across them.
    • Data-engine-specific values are not allowed.
  • Data-engine-specific values for V1 and V2 Data Engines
    • Format: JSON object (e.g., {"v1": "value1", "v2": "value2"})
    • Allows specifying different values for V1 and V2 Data Engines.
  • Data-engine-specific values for V1 Data Engine only
    • Format: JSON object with v1 key only (e.g., {"v1": "value1"})
    • Only the V1 Data Engine can be configured; the V2 Data Engine is not affected.
  • Data-engine-specific values for V2 Data Engine only
    • Format: JSON object with v2 key only (e.g., {"v2": "value1"})
    • Only the V2 Data Engine can be configured; the V1 Data Engine is not affected.

For more information, see Longhorn Settings.

Backup and Restore

Configurable Backup Block Size

Starting in Longhorn v1.10.0, users can configure the backup block size when creating a volume. This feature offers greater flexibility, allowing the block size to be adjusted based on different needs and cost considerations to balance performance, efficiency, and transmission cost.

For more information, see Create Longhorn Volumes.

V1 Data Engine

IPv6 Support

Longhorn v1.10.0 and later version support usage of V1 volumes in single-stacked IPv6 Kubernetes cluster. For more information, see Issue #2259.

Warning: Dual-stack Kubernetes clusters and V2 volumes are not supported at this version.

V2 Data Engine

Longhorn System Upgrade

Longhorn currently does not support live upgrading of V2 volumes. Ensure that all V2 volumes are detached before initiating the upgrade process.

Newly Introduced Functionalities since Longhorn v1.10.0

V2 Data Engine Without Hugepage Support

Longhorn v1.10.0 allows running the V2 Data Engine without Hugepage by setting data-engine-hugepage-enabled to {"v2":"false"}. This reduces memory pressure on low‑spec nodes and increases deployment flexibility, though performance may be lower than with Hugepage.

V2 Data Engine Interrupt Mode Support

Adds interrupt mode to the V2 Data Engine to help reduce CPU usage. This feature is especially beneficial for clusters with idle or low I/O workloads, where conserving CPU resources is more important than minimizing latency.

While interrupt mode lowers CPU consumption, it may introduce slightly higher I/O latency compared to polling mode. In addition, the current implementation uses a hybrid approach, which still incurs a minimal, constant CPU load even when interrupts are enabled.

For more information, see Interrupt Mode for more information.

© 2019-2025 Longhorn Authors | Documentation Distributed under CC-BY-4.0


© 2025 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.