Important Notes
This page lists important notes for Longhorn v1.9.0. Please see here for the full release note.
The environment check script (environment_check.sh
), which was deprecated in v1.7.0, has been removed from v1.9.0. Use the Longhorn Command Line Tool to check the Longhorn environment for potential issues.
The orphan-auto-deletion
setting has been replaced by orphan-resource-auto-deletion
in v1.9.0. To replicate the previous behavior (orphan-auto-deletion
), include replicaData
in the orphan-resource-auto-deletion
value.
For more information, see Orphaned Data Cleanup and Orphaned Instance Cleanup.
Deprecated fields have been removed from the CRDs. For details, see #6684.
longhorn.io/v1beta1
APIThe v1beta1
version of the Longhorn API is deprecated in v1.9.0 and will be removed in v1.10.0. During Longhorn system upgrades, custom resources using longhorn.io/v1beta1
are automatically migrated to longhorn.io/v1beta2
.
Deprecated APIs are no longer served and may therefore cause unexpected or unwanted behavior. Avoid using longhorn.io/v1beta1 in new code and, if possible, rewrite existing code to exclude this version.
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.
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"
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.
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.
Starting with Longhorn v1.9.0, you can create a recurring job for system backup creation.
For more information, see #6534
Starting with v1.9.0, Longhorn supports offline replica rebuilding, allowing degraded volumes to automatically rebuild replicas while detached.
For more information, see Offline replica rebuilding and #8443.
Starting with Longhorn v1.9.0, Longhorn includes the capability to track the orphaned instances. These orphaned instances can be removed either automatically or manually.
For more information, see #6764.
Starting with v1.9.0, Longhorn won’t calculate snapshot checksums by default for single-replica v1 volumes. Since snapshot checksums are primarily used for ensuring data integrity and speeding up replica rebuilding, they are unnecessary in single-replica setups and disabling them helps reduce performance overhead.
For more information, see #10518.
Starting with v1.9.0, Longhorn enhances observability by introducing new Prometheus metrics that expose the state and identity of Replica and Engine CRs, as well as the rebuild status. These improvements make it easier to monitor rebuild events across the entire cluster.
For more information, see #10550 and #10722.
Longhorn currently does not support live upgrading of V2 volumes. Ensure that all V2 volumes are detached before initiating the upgrade process.
© 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.