|
This is unreleased documentation for SUSE® Storage 1.9.0 (Dev). |
Important Notes
Please see here for the full release notes.
|
An incorrect Longhorn image tag (v1.8.x-head) was used in the deployment manifest and the Helm chart. The correct tag for Longhorn v1.8.0 images is If you installed or upgraded Longhorn using the deployment manifest or the Helm chart from the main Longhorn repository, perform the following actions to resolve the issue:
This issue does not affect installations and upgrades performed using the charts in the Longhorn Helm repository. For more information, see Install with Helm. |
Removal
Environment Check Script
The environment check script (environment_check.sh), which was deprecated in v1.7.0, has been removed in v1.9.0. Use the Longhorn Command Line Tool to check the Longhorn environment for potential issues.
Orphan Auto-Deletion Setting
The orphan-auto-deletion setting was replaced by the orphan-resource-auto-deletion setting in SUSE Storage v1.9.0. To replicate the previous behavior of orphan-auto-deletion (which often pertained to replica data), ensure that replicaData is included in the value of the orphan-resource-auto-deletion setting. This setting typically accepts a semicolon-separated list of orphan types to auto-delete.
For more information, see Orphaned Data Cleanup and Orphaned Instance Cleanup.
Deprecated Fields in CRDs
Deprecated fields have been removed from the Custom Resource Definitions (CRDs). For details, see Issue #6684.
Deprecation
longhorn.io/v1beta1 API
The 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 cause undesirable behavior. Avoid using longhorn.io/v1beta1 in new code and, if possible, update existing code to exclude this version.
General
Kubernetes Version Requirement
The upgrade of the CSI external snapshotter to version v8.2.0 requires that all clusters run Kubernetes v1.25 or later. Ensure your Kubernetes version meets this requirement before you upgrade to SUSE Storage v1.8.0 or a newer version.
CRD Upgrade Validation
During an upgrade, the Custom Resource Definition (CRD) might be applied after the new Longhorn Manager starts. This order helps prevent the controller from processing objects that contain deprecated data or fields. However, this sequencing can cause the Longhorn Manager to fail during the initial upgrade phase if the CRD is not yet applied.
If the Longhorn Manager crashes during the upgrade, check the logs to determine if the CRD not being applied is the cause of the failure. In such cases, the logs might 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 the Rancher App Marketplace. If a check fails, the upgrade process stops, and the reason for the failure is recorded in an event. For more details, see Upgrading Longhorn Manager.
Manual Checks Before Upgrade
Automated checks are performed only on some upgrade paths, and the pre-upgrade checker might not cover all scenarios. Manual checks, performed using either kubectl or the UI, are recommended for these scenarios. You can then take mitigating actions or defer the upgrade until any identified issues are addressed.
-
Ensure that all V2 Data Engine volumes are detached and their replicas are stopped. The V2 Data Engine currently does not support live upgrades.
-
Avoid upgrading when volumes are in the
"Faulted"status. If all replicas are deemed unusable, they might be deleted, potentially leading to permanent data loss if no usable backups exist. -
Avoid upgrading if a failed
BackingImageexists. For more information, see Backing Image. -
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 if any issues arise during the upgrade.
Backup And Restore
Recurring System Backup
You can create a recurring job for system backup creation. For more information, see Issue #6534.
Replica Rebuilding
Offline Replica Rebuilding
Starting with v1.9.0, Longhorn supports offline replica rebuilding. This feature allows degraded volumes to automatically rebuild replicas while the volumes are detached.
For more information, see Offline replica rebuilding and Issue #8443.
Resilience
Orphaned Instance Deletion
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 Issue #6764.
Performance
Snapshot Checksum Disabled for Single-Replica Volumes
Starting with v1.9.0, Longhorn does not 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. Disabling them helps reduce performance overhead.
For more information, see Issue #10518.
Observability
Improved Metrics for Replica, Engine, and Rebuild Status
Starting with v1.9.0, Longhorn enhances observability by introducing new Prometheus metrics that expose the state and identity of Replica and Engine Custom Resources (CRs), as well as the rebuild status. These improvements make it easier to monitor rebuild events across the entire cluster.
For more information, see Issue #10550 and Issue #10722.