Important Notes

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

Warning

Unable to Attach Volumes Created Before v1.5.2 and v1.4.4

The Longhorn team has identified a critical issue that affects volume attachment in Longhorn v1.7.0. A fix for this issue will be included in v1.7.1, which is in active development.

Avoid upgrading to v1.7.0 if your Longhorn cluster contains engine resources with the following characteristics:

  • Resource name: The format is <volume name>-e-<8-char random id>.
  • Time of creation: A Longhorn version earlier than v1.5.2 and v1.4.4 was installed on the cluster.

Run the following command to check if you can safely upgrade your Longhorn cluster to v1.7.0:

  1. [ $(kubectl -n longhorn-system get engines.longhorn.io -o name | grep -E '\-e\-[a-z0-9]{8}$' | wc -l) -gt 0 ] && echo "Please hold off on upgrading to v1.7.0 until v1.7.1 is available." || echo "Safe to upgrade to v1.7.0."

Deprecation

Environment Check Script

The functionality of the environment check script (environment_check.sh) overlaps with that of the Longhorn CLI, which is available starting with v1.7.0. Because of this, the script is deprecated in v1.7.0 and is scheduled for removal in v1.8.0.

General

Supported Kubernetes Versions

Please ensure your Kubernetes cluster is at least v1.21 before upgrading to Longhorn v1.7.0 because this is the minimum version Longhorn v1.7.0 supports.

Pod Security Policies Disabled & Pod Security Admission Introduction

  • Longhorn pods require privileged access to manage nodes’ storage. In Longhorn v1.3.x or older, Longhorn was shipping some Pod Security Policies by default, (e.g., link). However, Pod Security Policy has been deprecated since Kubernetes v1.21 and removed since Kubernetes v1.25, link. Therefore, we stopped shipping the Pod Security Policies by default. For Kubernetes < v1.25, if your cluster still enables Pod Security Policy admission controller, please do:

    • Helm installation method: set the helm value enablePSP to true to install longhorn-psp PodSecurityPolicy resource which allows privileged Longhorn pods to start.
    • Kubectl installation method: need to apply the podsecuritypolicy.yaml manifest in addition to applying the longhorn.yaml manifests.
    • Rancher UI installation method: set Other Settings > Pod Security Policy to true to install longhorn-psp PodSecurityPolicy resource which allows privileged Longhorn pods to start.

  • As a replacement for Pod Security Policy, Kubernetes provides a new mechanism, Pod Security Admission. If you enable the Pod Security Admission controller and change the default behavior to block privileged pods, you must add the correct labels to the namespace where Longhorn pods run to allow Longhorn pods to start successfully (because Longhorn pods require privileged access to manage storage). For example, adding the following labels to the namespace that is running Longhorn pods:

    1. apiVersion: v1
    2. kind: Namespace
    3. metadata:
    4.   name: longhorn-system
    5.   labels:
    6.     pod-security.kubernetes.io/enforce: privileged
    7.     pod-security.kubernetes.io/enforce-version: latest
    8.     pod-security.kubernetes.io/audit: privileged
    9.     pod-security.kubernetes.io/audit-version: latest
    10.     pod-security.kubernetes.io/warn: privileged
    11.     pod-security.kubernetes.io/warn-version: latest

Command Line Tool

The Longhorn CLI (binary name: longhornctl), which is the official Longhorn command line tool, was introduced in v1.7.0. This tool interacts with Longhorn by creating Kubernetes custom resources (CRs) and executing commands inside a dedicated pod for in-cluster and host operations. Usage scenarios include installation, operations such as exporting replicas, and troubleshooting. For more information, see Command Line Tool (longhornctl).

Minimum XFS Filesystem Size

Recent versions of xfsprogs (including the version Longhorn currently uses) do not allow the creation of XFS filesystems smaller than 300 MiB. Longhorn v1.7.0 does not allow the following:

  • CSI flow: Volume provisioning if resources.requests.storage < 300 Mi and the corresponding StorageClass has fsType: xfs
  • Longhorn UI: Create PV/PVC with File System: XFS action to be completed on a volume that has spec.size < 300 Mi

However, Longhorn still allows the listed actions when cloning or restoring volumes created with earlier Longhorn versions.

Longhorn PVC with Block Volume Mode

Starting with v1.6.0, Longhorn is changing the default group ID of Longhorn devices from 0 (root group) to 6 (typically associated with the “disk” group). This change allows non-root containers to read or write to PVs using the Block volume mode. Note that Longhorn still keeps the owner of the Longhorn block devices as root. As a result, if your pod has security context such that it runs as non-root user and is part of the group id 0, the pod will no longer be able to read or write to Longhorn block volume mode PVC anymore. This use case should be very rare because running as a non-root user with the root group does not make much sense. More specifically, this example will not work anymore:

  1. apiVersion: v1
  2. kind: PersistentVolumeClaim
  3. metadata:
  4.   name: longhorn-block-vol
  5. spec:
  6.   accessModes:
  7.     - ReadWriteOnce
  8.   volumeMode: Block
  9.   storageClassName: longhorn
  10.   resources:
  11.     requests:
  12.       storage: 2Gi
  13. ---
  14. apiVersion: v1
  15. kind: Pod
  16. metadata:
  17.   name: block-volume-test
  18.   namespace: default
  19. spec:
  20.   securityContext:
  21.     runAsGroup: 1000
  22.     runAsNonRoot: true
  23.     runAsUser: 1000
  24.     supplementalGroups:
  25.     - 0
  26.   containers:
  27.     - name: block-volume-test
  28.       image: ubuntu:20.04
  29.       command: ["sleep", "360000"]
  30.       imagePullPolicy: IfNotPresent
  31.       volumeDevices:
  32.         - devicePath: /dev/longhorn/testblk
  33.           name: block-vol
  34.   volumes:
  35.     - name: block-vol
  36.       persistentVolumeClaim:
  37.         claimName: longhorn-block-vol

From this version, you need to add group id 6 to the security context or run container as root. For more information, see Longhorn PVC ownership and permission

Container-Optimized OS Support

Starting with Longhorn v1.7.0, Longhorn supports Container-Optimized OS (COS), providing robust and efficient persistent storage solutions for Kubernetes clusters running on COS. For more information, see Container-Optimized OS (COS) Support.

Resilience

RWX Volumes Fast Failover

RWX Volumes fast failover is introduced in Longhorn v1.7.0 to improve resilience to share-manager pod failures. This failover mechanism quickly detects and responds to share-manager pod failures independently of the Kubernetes node failure sequence and timing. For details, see RWX Volume Fast Failover.

Note: In rare circumstances, it is possible for the failover to become deadlocked. This happens if the NFS server pod creation is blocked by a recovery action that is itself blocked by the failover-in-process state. If the feature is enabled, and a failover takes more than a minute or two, it is probably stuck in this situation. There is an explanation and a workaround in RWX Volume Fast Failover.

Timeout Configuration for Replica Rebuilding and Snapshot Cloning

Starting with v1.7.0, Longhorn supports configuration of timeouts for replica rebuilding and snapshot cloning. Before v1.7.0, the replica rebuilding timeout was capped at 24 hours, which could cause failures for large volumes in slow bandwidth environments. The default timeout is still 24 hours but you can adjust it to accommodate different environments. For more information, see Long gRPC Timeout.

Data Integrity and Reliability

Support Periodic and On-Demand Full Backups to Enhance Backup Reliability

Since Longhorn v1.7.0, periodic and on-demand full backups have been supported to enhance backup reliability. Prior to v1.7.0, the initial backup was a full backup, with subsequent backups being incremental. If any block became corrupted, all backup revisions relying on that block would also be corrupted. To address this issue, Longhorn now supports performing a full backup after every N incremental backups, as well as on-demand full backups. This approach decreases the likelihood of backup corruption and enhances the overall reliability of the backup process. For more information, see Recurring Snapshots and Backups and Create a Backup.

High Availability of Backing Images

To address the single point of failure (SPOF) issue with backing images, high availability for backing images was introduced in Longhorn v1.7.0. For more information, please see Backing Image.

Scheduling

Volume Locality for RWX Volumes

Longhorn provides new settings that allow you to precisely control the data locality of RWX volumes (through identification of associated Share Manager pods). These granular settings work with related global settings to provide optimal performance, resilience, and adherence to organizational policies or constraints. For more information, see Configuring Volume Locality for RWX Volumes.

Auto-Balance Pressured Disks

The replica auto-balancing feature was enhanced in Longhorn v1.7.0 to address disk space pressure from growing volumes. A new setting, called replica-auto-balance-disk-pressure-percentage, allows you to set a threshold for automatic actions. The enhancements reduce the need for manual intervention by automatically rebalancing replicas during disk pressure, and improve performance by enabling faster replica rebuilding using local file copying. For more information, see replica-auto-balance-disk-pressure-percentage and Issue #4105.

Networking

Storage Network Support for Read-Write-Many (RWX) Volumes

Starting with Longhorn v1.7.0, the storage network supports RWX volumes. However, the network’s reliance on Multus results in a significant restriction.

Multus networks operate within the Kubernetes network namespace, so Longhorn can mount NFS endpoints only within the CSI plugin pod container network namespace. Consequently, NFS mount connections to the Share Manager pod become unresponsive when the CSI plugin pod restarts. This occurs because the namespace in which the connection was established is no longer available.

Longhorn circumvents this restriction by providing the following settings:

  • Storage Network For RWX Volume Enabled: When this setting is disabled, the storage network applies only to RWO volumes. The NFS client for RWX volumes is mounted over the cluster network in the host network namespace. This means that restarting the CSI plugin pod does not affect the NFS mount connections
  • Automatically Delete Workload Pod when The Volume Is Detached Unexpectedly: When the RWX volumes are created over the storage network, this setting actively deletes RWX volume workload pods when the CSI plugin pod restarts. This allows the pods to be remounted and prevents dangling mount entries.

You can upgrade clusters with pre-existing RWX volume workloads to Longhorn v1.7.0. During and after the upgrade, the workload pod must not be interrupted because the NFS share connection uses the cluster IP, which remains valid in the host network namespace.

To apply the storage network to existing RWX volumes, you must detach the volumes, enable the Storage Network For RWX Volume Enabled setting, and then reattach the volumes.

For more information, see Issue #8184.

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.

Enable Both vfio_pci and uio_pci_generic Kernel Modules

According to the SPDK System Configuration User Guide, neither vfio_pci nor uio_pci_generic is universally suitable for all devices and environments. Therefore, users can enable both vfio_pci and uio_pci_generic kernel modules. This allows Longhorn to automatically select the appropriate module. For more information, see this link.

Online Replica Rebuilding

Online replica rebuilding was introduced in Longhorn 1.7.0, so offline replica rebuilding has been removed.

Block-type Disk Supports SPDK AIO, NVMe and VirtIO Bdev Drivers

Before Longhorn v1.7.0, Longhorn block-type disks only supported the SPDK AIO bdev driver, which introduced extra performance penalties. Since v1.7.0, block devices can be directly managed by SPDK NVMe or VirtIO bdev drivers, improving IO performance through a kernel bypass scheme. For more information, see this link.

Filesystem Trim

Filesystem trim is supported since Longhorn v1.7.0. If a disk is managed by the SPDK AIO bdev driver, the Trim (UNMAP) operation is not recommended in a production environment (ref). It is recommended to manage a block-type disk with an NVMe bdev driver.

Linux Kernel on Longhorn Nodes

Host machines with Linux kernel 5.15 may unexpectedly reboot when volume-related IO errors occur. To prevent this, update the Linux kernel on Longhorn nodes to version 5.19 or later. For more information, see Prerequisites. Version 6.7 or later is recommended for improved system stability.

Snapshot Creation Time As Shown in the UI Occasionally Changes

Snapshots created before Longhorn v1.7.0 may change occasionally. This issue arises because the engine randomly selects a replica and its snapshot map each time the UI requests snapshot information or when a replica is rebuilt with a random healthy replica. This can lead to potential time gaps between snapshots among different replicas. Although this bug was fixed in v1.7.0, snapshots created before this version may still encounter the issue. For more information, see this link.

Unable To Revert a Volume to a Snapshot Created Before Longhorn v1.7.0

Reverting a volume to a snapshot created before Longhorn v1.7.0 is not supported due to an incorrect UserCreated flag set on the snapshot. The workaround is to back up the existing snapshots before upgrading to Longhorn v1.7.0 and restore them if needed. The bug is fixed in v1.7.0, and more information can be found here.