To configure Longhorn before installing it, see this section for details.
If no other disks exist, create the default disk automatically, only on nodes with the Kubernetes label
If disabled, the default disk will be created on all new nodes when the node is detected for the first time.
This option is useful if you want to scale the cluster but don’t want to use storage on the new nodes, or if you want to customize disks for Longhorn nodes.
Default path to use for storing data on a host.
Can be used with
Create Default Disk on Labeled Nodes option, to make Longhorn only use the nodes with specific storage mounted at, for example,
/opt/longhorn when scaling the cluster.
longhornio/longhorn-engine:varchivesfor Longhorn varchives
The default engine image used by the manager. Can be changed on the manager starting command line only.
Every Longhorn release will ship with a new Longhorn engine image. If the current Longhorn volumes are not using the default engine, a green arrow will show up, indicate this volume needs to be upgraded to use the default engine.
longhornio/longhorn-instance-manager:v1_20200514for Longhorn varchives
The default instance manager image used by the manager. Can be changed on the manager starting command line only.
Upgrade Checker will check for a new Longhorn version periodically. When there is a new version available, it will notify the user in the Longhorn UI.
varchivesfor Longhorn varchives
The latest version of Longhorn available. Automatically updated by the Upgrade Checker.
Only available if
Upgrade Checker is enabled.
The default number of replicas when creating the volume from Longhorn UI. For Kubernetes, update the
numberOfReplicas in the StorageClass
The recommended way of choosing the default replica count is: if you have more than three nodes for storage, use 3; otherwise use 2. Using a single replica on a single node cluster is also OK, but the high availability functionality wouldn’t be available. You can still take snapshots/backups of the volume.
We say a Longhorn volume has data locality if there is a local replica of the volume on the same node as the pod which is using the volume. This setting specifies the default data locality when a volume is created from the Longhorn UI. For Kubernetes configuration, update the dataLocality in the StorageClass
The available modes are:
disabled. This is the default option.
There may or may not be a replica on the same node as the attached volume (workload).
best-effort. This option instructs Longhorn to try to keep a replica on the same node as the attached volume (workload).
Longhorn will not stop the volume, even if it cannot keep a replica local to the attached volume (workload) due to environment limitation, e.g. not enough disk space, incompatible disk tags, etc.
storageClassName is for persistent volumes (PVs) and persistent volume claims (PVCs) when creating PV/PVC for an existing Longhorn volume. Notice that it’s unnecessary for users to create the related StorageClass object in Kubernetes since the StorageClass would only be used as matching labels for PVC bounding purpose. By default ‘longhorn-static’.
The current customer resource’s API version, e.g. longhorn.io/v1beta1. Set by manager automatically.
If enabled, volumes will be automatically salvaged when all the replicas become faulty e.g. due to network disconnection. Longhorn will try to figure out which replica(s) are usable, then use them for the volume.
If enabled, Longhorn will automatically delete the workload pod that is managed by a controller (e.g. deployment, statefulset, daemonset, etc…) when Longhorn volume is detached unexpectedly (e.g. during Kubernetes upgrade, Docker reboot, or network disconnect). By deleting the pod, its controller restarts the pod and Kubernetes handles volume reattachment and remount.
If disabled, Longhorn will not delete the workload pod that is managed by a controller. You will have to manually restart the pod to reattach and remount the volume.
Note: This setting doesn’t apply to the workload pods that don’t have a controller. Longhorn never deletes them.
The Kubernetes Secret name.
Defines the Longhorn action when a Volume is stuck with a Deployment Pod on a failed node.
wait: Longhorn will wait to recover the Volume Attachment until all the terminating pods have passed their deletion grace period.
never: The default Kubernetes behavior of never deleting volume attachments on terminating pods. Longhorn will not recover the Volume Attachment from a failed node.
immediate: Longhorn will recover the Volume Attachment from the failed node as soon as there are pending replacement pods available.
Defines the Longhorn action when a Volume is stuck with a StatefulSet/Deployment Pod on a node that is down.
do-nothingis the default Kubernetes behavior of never force deleting StatefulSet/Deployment terminating pods. Since the pod on the node that is down isn’t removed, Longhorn volumes are stuck on nodes that are down.
delete-statefulset-podLonghorn will force delete StatefulSet terminating pods on nodes that are down to release Longhorn volumes so that Kubernetes can spin up replacement pods.
delete-deployment-podLonghorn will force delete Deployment terminating pods on nodes that are down to release Longhorn volumes so that Kubernetes can spin up replacement pods.
delete-both-statefulset-and-deployment-podLonghorn will force delete StatefulSet/Deployment terminating pods on nodes that are down to release Longhorn volumes so that Kubernetes can spin up replacement pods.
Allows setting additional filesystem creation parameters for ext4. For older host kernels it might be necessary to disable the optional ext4 metadata_csum feature by specifying
Allows engine controller and engine replica to disable revision counter file update for every data write. This improves the data path performance. See Revision Counter for details.
Defines the image Pull Policy of Longhorn system managed pods, e.g. instance manager, engine image, CSI driver, etc. The new image Pull Policy will only apply after the system managed pods restart.
See Kubernetes document on images for more information on the possible choices of the setting.
Longhorn will generate system snapshot during replica rebuild, and if a user doesn’t setup a recurring snapshot schedule, all the system generated snapshots would be left in the replica, and user has to delete them manually, this setting allow Longhorn to automatically cleanup system generated snapshot after replica rebuild.
By default, Longhorn will block
kubectl drain action on a node if the node contains the last healthy replica of a volume.
If this setting is enabled, Longhorn will not block
kubectl drain action on a node even if the node contains the last healthy replica of a volume.
When there is at least one failed replica volume in a degraded volume, this interval in seconds determines how long Longhorn will wait at most in order to reuse the existing data of the failed replicas rather than directly creating a new replica for this volume.
Warning: This wait interval works only when there is at least one failed replica in the volume. And this option may block the rebuilding for a while.
This setting defines the Image Pull Policy of Longhorn system managed pods, e.g. instance manager, engine image, CSI driver, etc.
Notice that the new Image Pull Policy will only apply after the system managed pods restart.
This setting definition is exactly the same as that of in Kubernetes. Here are the available options:
always. Every time the kubelet launches a container, the kubelet queries the container image registry to resolve the name to an image digest. If the kubelet has a container image with that exact digest cached locally, the kubelet uses its cached image; otherwise, the kubelet downloads (pulls) the image with the resolved digest, and uses that image to launch the container.
if-not-present. The image is pulled only if it is not already present locally.
never. The image is assumed to exist locally. No attempt is made to pull the image.
The target used for backup. NFS and S3 are supported. See Setting a Backup Target for details.
The Kubernetes secret associated with the backup target. See Setting a Backup Target for details.
The interval in seconds to poll the backup store for updating volumes’ Last Backup field. Set to 0 to disable the polling. See Setting up Disaster Recovery Volumes for details.
For more information on how the backupstore poll interval affects the recovery time objective and recovery point objective, refer to the concepts section.
If this setting is enabled, Longhorn automatically attaches the volume and takes snapshot/backup when it is the time to do recurring snapshot/backup.
Note that during the time the volume was attached automatically, the volume is not ready for the workload. the workload will have to wait until the recurring job finishes.
When this setting is checked, the Longhorn Manager will allow scheduling on nodes with existing healthy replicas of the same volume.
When this setting is un-checked, the Longhorn Manager will not allow scheduling on nodes with existing healthy replicas of the same volume.
The over-provisioning percentage defines how much storage can be allocated relative to the hard drive’s capacity.
With the default setting of 200, the Longhorn Manager will allow scheduling new replicas only after the amount of disk space has been added to the used disk space (storage scheduled), and the used disk space (Storage Maximum - Storage Reserved) is not over 200% of the actual usable disk capacity.
This value can be lowered to avoid overprovisioning storage. See Multiple Disks Support for details. Also, a replica of volume may take more space than the volume’s size since the snapshots need storage space as well. The users can delete snapshots to reclaim spaces.
With the default setting of 25, the Longhorn Manager will allow scheduling new replicas only after the amount of disk space has been subtracted from the available disk space (Storage Available) and the available disk space is still over 25% of actual disk capacity (Storage Maximum). Otherwise the disk becomes unschedulable until more space is freed up.
See Multiple Disks Support for details.
When this setting is checked, the Longhorn Manager will not schedule replicas on Kubernetes cordoned nodes.
When this setting is un-checked, the Longhorn Manager will schedule replicas on Kubernetes cordoned nodes.
When this setting is checked, the Longhorn Manager will allow scheduling new replicas of a volume to the nodes in the same zone as existing healthy replicas.
When this setting is un-checked, Longhorn Manager will not allow scheduling new replicas of a volume to the nodes in the same zone as existing healthy replicas.
Note: Nodes that don’t belong to any zone will be treated as if they belong to the same zone.
This setting allows user to create and attach a volume that doesn’t have all the replicas scheduled at the time of creation.
Note: It’s recommended to disable this setting when using Longhorn in the production environment. See Best Practices for details.
By setting tolerations for Longhorn then adding taints for the nodes, the nodes with large storage can be dedicated to Longhorn only (to store replica data) and reject other general workloads.
Before modifying toleration setting, all Longhorn volumes should be detached then Longhorn components will be restarted to apply new tolerations. And toleration update will take a while. Users cannot operate Longhorn system during update. Hence it’s recommended to set toleration during Longhorn deployment.
Multiple tolerations can be set here, and these tolerations are separated by semicolon. For example,
See Taint Toleration for details.
Longhorn uses CPU resources on the node to serve the Longhorn Volumes. The Guaranteed Engine CPU option will request Kubernetes to reserve a certain amount of CPU for Longhorn Instance Manager Pods, which contain the running processes. The value is how many CPUs should be reserved for each Engine/Replica Instance Manager Pod created by Longhorn. This will help maintain engine stability during high node workload.
This number only applies to the Engine/Replica Manager Pods created after the setting takes effect.
In order to prevent unexpected volume crash, you can use the following formula to calculate an appropriate value for this setting:
Number of vCPUs = The estimated max Longhorn volume/replica count on a node * 0.1
The result of above calculation doesn’t mean that’s the maximum CPU resources the Longhorn workloads require. To fully exploit the Longhorn volume I/O performance, you can allocate/guarantee more CPU resources via this setting.
If it’s hard to estimate the volume/replica count now, you can leave it with the default value, or allocate 1/8 of total CPU of a node. Then you can tune it when there is no running workload using Longhorn volumes.
Warning: This setting should be changed only when all the volumes on the nodes are detached. Changing the setting will result in all the Instance Manager Pods restarting, which will automatically detach all the attached volumes, and could cause a workload outage.
Since Longhorn exposes the Volume as a block device, it’s critical to ensure the Longhorn Engine processes have enough CPU to satisfy the latency requirement of the Linux system.
The Guaranteed Engine CPU should be set to no more than a quarter of what the node’s available CPU resources, since the allocation is applied to the two Instance Managers on the node (engine and replica), and the future upgraded Instance Managers (another two for engine and replica).
For example, if the setting value is 0.25 or 250m, that means you must have at least 0.25 * 8 = 2 vCPUs per node. Otherwise, the new Instance Manager Pods may fail to start.
There are normally two Instance Manager Pods per node: one for the engine processes, and another one for the replica processes. But when Longhorn is upgrading from an old version of the Instance Manager to a new version, there can be at most four Pods requesting the reserved CPU on the node.
Taking other Kubernetes system components’ CPU reservation request into consideration, we recommend having at least eight times the amount of CPU as the Guaranteed Engine CPU.
By default, Longhorn workloads run with the same priority as other pods in the cluster, meaning in cases of node pressure, such as a node running out of memory, Longhorn workloads will be at the same priority as other Pods for eviction.
The Priority Class setting will specify a Priority Class for the Longhorn workloads to run as. This can be used to set the priority for Longhorn workloads higher so that they will not be the first to be evicted when a node is under pressure.
Warning: This setting should only be changed after detaching all Longhorn volumes, as the Longhorn components will be restarted to apply the setting. The Priority Class update will take a while, and users cannot operate Longhorn system during the update. Hence, it’s recommended to set the Priority Class during Longhorn deployment.
See Priority Class for details.
By disable replica rebuild, there won’t be any new rebuild cross the whole cluster. The Disks or Nodes Eviction Support and Data Locality feature won’t work. But any restore features and currently rebuilding replica would still work as expected.
© 2019-2023 Longhorn Authors | Documentation Distributed under CC-BY-4.0
© 2023 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.