Customizing Default Settings

You may customize Longhorn’s default settings when deploying it. You may specify, for example, Create Default Disk With Node Labeled and Default Data Path before starting Longhorn.

This default setting is only for a Longhorn system that hasn’t been deployed. It has no impact on an existing Longhorn system. The settings for any existing Longhorn system should be modified using the Longhorn UI.

The default settings can be customized in the following ways:

Using the Rancher UI

From the project view in Rancher, go to Apps > Launch > Longhorn and edit the settings before launching the app.

Using the Longhorn Deployment YAML File

  1. Download the longhorn repo:

    git clone
  2. Modify the config map named longhorn-default-setting in the yaml file longhorn/deploy/longhorn.yaml. For example:

    apiVersion: v1
    kind: ConfigMap
      name: longhorn-default-setting
      namespace: longhorn-system
      default-setting.yaml: |-
        backup-target: s3://backupbucket@us-east-1/backupstore
        backup-target-credential-secret: minio-secret
        create-default-disk-labeled-nodes: true
        default-data-path: /var/lib/longhorn-example/
        replica-soft-anti-affinity: false
        storage-over-provisioning-percentage: 600
        storage-minimal-available-percentage: 15
        upgrade-checker: false
        default-replica-count: 2
        default-data-locality: disabled
        guaranteed-engine-cpu: 0.25
        default-longhorn-static-storage-class: longhorn-static-example
        backupstore-poll-interval: 500
        taint-toleration: key1=value1:NoSchedule; key2:NoExecute
        registry-secret: registry-secret
        auto-salvage: false
        disable-scheduling-on-cordoned-node: false
        replica-zone-soft-anti-affinity: false
        volume-attachment-recovery-policy: never
        node-down-pod-deletion-policy: do-nothing
        mkfs-ext4-parameters: -O ^64bit,^metadata_csum

Using Helm

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

  • Helm 2

    helm install longhorn/longhorn \
      --name longhorn \
      --namespace longhorn-system \
      --set defaultSettings.taintToleration="key1=value1:NoSchedule; key2:NoExecute"
  • Helm 3

    helm install longhorn longhorn/longhorn \
      --namespace longhorn-system \
      --create-namespace \
      --set defaultSettings.taintToleration="key1=value1:NoSchedule; key2:NoExecute"

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:

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

      backupTarget: s3://backupbucket@us-east-1/backupstore
      backupTargetCredentialSecret: minio-secret
      createDefaultDiskLabeledNodes: true
      defaultDataPath: /var/lib/longhorn-example/
      replicaSoftAntiAffinity: false
      storageOverProvisioningPercentage: 600
      storageMinimalAvailablePercentage: 15
      upgradeChecker: false
      defaultReplicaCount: 2
      defaultDataLocality: disabled
      guaranteedEngineCPU: 0.25
      defaultLonghornStaticStorageClass: longhorn-static-example
      backupstorePollInterval: 500
      taintToleration: key1=value1:NoSchedule; key2:NoExecute
      registrySecret: registry-secret
      autoSalvage: false
      disableSchedulingOnCordonedNode: false
      replicaZoneSoftAntiAffinity: false
      volumeAttachmentRecoveryPolicy: never
      nodeDownPodDeletionPolicy: do-nothing
      mkfsExt4Parameters: -O ^64bit,^metadata_csum
  3. Run Helm with values.yaml:

    • Helm 2
      helm install longhorn/longhorn \
        --name longhorn \
        --namespace longhorn-system \
        --values values.yaml
    • Helm 3
      helm install longhorn longhorn/longhorn \
        --namespace longhorn-system \
        --create-namespace \
        --values values.yaml

For more info about using helm, see the section about installing Longhorn with Helm


Original feature request

Available since v0.6.0

© 2019-2024 Longhorn Authors | Documentation Distributed under CC-BY-4.0

© 2024 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.