You may customize Longhorn’s default settings while installing or upgrading. You may specify, for example, and Default Data Path before starting Longhorn.

The default settings can be customized in the following ways:

From the project view in Rancher, go to Apps && Marketplace > Longhorn > Install > Next > Edit Options > Longhorn Default Settings > Customize Default Settings and edit the settings before installing the app.

Using the Longhorn Deployment YAML File

  1. Download the longhorn repo:

  2. Modify the config map named longhorn-default-setting in the yaml file longhorn/deploy/longhorn.yaml.

    In the below example, users customize the default settings, backup-target, backup-target-credential-secret, and default-data-path. When the setting is absent or has a leading # symbol, the default setting will use the default value in Longhorn or the customized values previously configured.

    1. ---
    2. apiVersion: v1
    3. kind: ConfigMap
    4. metadata:
    5.   name: longhorn-default-setting
    6.   namespace: longhorn-system
    7. data:
    8.   default-setting.yaml: |-
    9.     backup-target: s3://backupbucket@us-east-1/backupstore
    10.     backup-target-credential-secret: minio-secret
    11.     #create-default-disk-labeled-nodes:
    12.     default-data-path: /var/lib/longhorn-example/
    13.     #replica-soft-anti-affinity:
    14.     #replica-auto-balance:
    15.     #storage-over-provisioning-percentage:
    16.     #storage-minimal-available-percentage:
    17.     #upgrade-checker:
    18.     #default-replica-count:
    19.     #default-data-locality:
    20.     #default-longhorn-static-storage-class:
    21.     #backupstore-poll-interval:
    22.     #taint-toleration:
    23.     #system-managed-components-node-selector:
    24.     #priority-class:
    25.     #auto-salvage:
    26.     #auto-delete-pod-when-volume-detached-unexpectedly:
    27.     #disable-scheduling-on-cordoned-node:
    28.     #replica-zone-soft-anti-affinity:
    30.     #allow-node-drain-with-last-healthy-replica:
    31.     #mkfs-ext4-parameters:
    32.     #disable-replica-rebuild:
    33.     #replica-replenishment-wait-interval:
    34.     #concurrent-replica-rebuild-per-node-limit:
    35.     #disable-revision-counter:
    36.     #system-managed-pods-image-pull-policy:
    37.     #allow-volume-creation-with-degraded-availability:
    38.     #auto-cleanup-system-generated-snapshot:
    39.     #concurrent-automatic-engine-upgrade-per-node-limit:
    40.     #backing-image-cleanup-wait-interval:
    41.     #backing-image-recovery-wait-interval:
    42.     #guaranteed-engine-manager-cpu:
    43.     #guaranteed-replica-manager-cpu:
    44.     #kubernetes-cluster-autoscaler-enabled:
    45.     #orphan-auto-deletion:
    46.     #storage-network:
    47.     #recurring-successful-jobs-history-limit:
    48.     #recurring-failed-jobs-history-limit:
    49. ---

Using Helm

Use the Helm command with the --set flag to modify the default settings. For example:

  • Helm 3

You can also provide a copy of the values.yaml file with the default settings modified to the --values flag when running the Helm command:

  1. Obtain a copy of the values.yaml file from GitHub:

    1. curl -Lo values.yaml https://raw.githubusercontent.com/longhorn/charts/master/charts/longhorn/values.yaml

  2. Modify the default settings in the YAML file. The following is an example snippet of values.yaml:

    When the setting is absent or has a leading # symbol, the default setting will use the default value in Longhorn or the customized values previously configured.

    1. defaultSettings:
    2.   backupTarget: s3://backupbucket@us-east-1/backupstore
    4.   createDefaultDiskLabeledNodes: true
    5.   defaultDataPath: /var/lib/longhorn-example/
    6.   replicaSoftAntiAffinity: false
    7.   storageOverProvisioningPercentage: 600
    8.   storageMinimalAvailablePercentage: 15
    9.   upgradeChecker: false
    10.   defaultReplicaCount: 2
    11.   defaultDataLocality: disabled
    12.   defaultLonghornStaticStorageClass: longhorn-static-example
    13.   backupstorePollInterval: 500
    14.   taintToleration: key1=value1:NoSchedule; key2:NoExecute
    15.   systemManagedComponentsNodeSelector: "label-key1:label-value1"
    16.   priorityClass: high-priority
    17.   autoSalvage: false
    18.   disableSchedulingOnCordonedNode: false
    19.   replicaZoneSoftAntiAffinity: false
    20.   volumeAttachmentRecoveryPolicy: never
    21.   nodeDownPodDeletionPolicy: do-nothing
    22.   mkfsExt4Parameters: -O ^64bit,^metadata_csum
    23.   guaranteedEngineManagerCpu: 15
    24.   guaranteedReplicaManagerCpu: 15
    25.   orphanAutoDeletion: false

  3. Run Helm with values.yaml:

  • Helm 2

  • Helm 3

    1. helm install longhorn longhorn/longhorn \
    2.   --namespace longhorn-system \
    3.   --create-namespace \

We recommend using the Longhorn UI to change Longhorn setting on the existing cluster. It would make the setting persistent.

Using the Rancher UI

From the project view in Rancher, go to Apps && Marketplace > Longhorn > Upgrade > Next > Edit Options > Longhorn Default Settings > Customize Default Settings and edit the settings before upgrading the app to the current Longhorn version.

Using Kubectl

If you prefer to use the command line to update the setting, you could use kubectl.

  1. kubectl edit settings <SETTING-NAME> -n longhorn-system

Modify the default settings in the YAML file as described in Fresh Installation > Using Helm and then update the settings using

Using the Rancher UI

From the project view in Rancher, go to Apps && Marketplace > Longhorn > Upgrade > Next > Edit Options > Longhorn Default Settings > Customize Default Settings and edit the settings before upgrading the app.

Using the Longhorn Deployment YAML File

Modify the config map named longhorn-default-setting in the yaml file longhorn/deploy/longhorn.yaml as described in Fresh Installation > Using the Longhorn Deployment YAML File and then upgrade the Longhorn system using kubectl.

Modify the default settings in the YAML file as described in Fresh Installation > Using Helm and then upgrade the Longhorn system using helm upgrade.

Available since v1.3.0 (Reference)