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 or by kubectl. Reference to the knowledge base doc for the details.

The default settings can be customized in the following ways:

Deploy

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:

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

    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:
    10. backup-target-credential-secret:
    11. allow-recurring-job-while-volume-detached:
    12. create-default-disk-labeled-nodes:
    13. default-data-path:
    14. replica-soft-anti-affinity:
    15. storage-over-provisioning-percentage:
    16. storage-minimal-available-percentage:
    17. upgrade-checker:
    18. default-replica-count:
    19. default-data-locality:
    20. guaranteed-engine-cpu:
    21. default-longhorn-static-storage-class:
    22. backupstore-poll-interval:
    23. taint-toleration:
    24. system-managed-components-node-selector:
    25. priority-class:
    26. auto-salvage:
    27. auto-delete-pod-when-volume-detached-unexpectedly:
    28. disable-scheduling-on-cordoned-node:
    29. replica-zone-soft-anti-affinity:
    30. node-down-pod-deletion-policy:
    31. allow-node-drain-with-last-healthy-replica:
    32. mkfs-ext4-parameters:
    33. disable-replica-rebuild:
    34. replica-replenishment-wait-interval:
    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. guaranteed-engine-manager-cpu:
    42. guaranteed-replica-manager-cpu:
    43. ---

Using Helm

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

  • Helm 2

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

    1. helm install longhorn longhorn/longhorn \
    2. --namespace longhorn-system \
    3. --create-namespace \
    4. --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:

    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:

    1. defaultSettings:
    2. backupTarget: s3://backupbucket@us-east-1/backupstore
    3. backupTargetCredentialSecret: minio-secret
    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. guaranteedEngineCPU:
    13. defaultLonghornStaticStorageClass: longhorn-static-example
    14. backupstorePollInterval: 500
    15. taintToleration: key1=value1:NoSchedule; key2:NoExecute
    16. systemManagedComponentsNodeSelector: "label-key1:label-value1"
    17. priority-class: high-priority
    18. autoSalvage: false
    19. disableSchedulingOnCordonedNode: false
    20. replicaZoneSoftAntiAffinity: false
    21. volumeAttachmentRecoveryPolicy: never
    22. nodeDownPodDeletionPolicy: do-nothing
    23. mkfsExt4Parameters: -O ^64bit,^metadata_csum
    24. guaranteed-engine-manager-cpu: 15
    25. guaranteed-replica-manager-cpu: 15
  3. Run Helm with values.yaml:

  • Helm 2

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

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

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

Upgrade

Using the Longhorn UI

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

Using Kubectl

If you prefer to use the command line to update the setting, you could use kubectl. But please be aware this will bypass Longhorn backend validation.

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

Using Script

If you’re using Rancher UI or Helm to upgrade the setting, but found that the customized setting does not apply to the cluster. You could run the below script to update the Longhorn Setting CR according to the longhorn-default-setting ConfigMap. But please be aware this will bypass Longhorn backend validation.

  1. kubectl -n longhorn-system get configmap longhorn-default-setting -ojsonpath="{.data['default-setting\.yaml']}" | awk '{if ($2) print $0;}' | while read key val; do kubectl -n longhorn-system patch settings ${key%:} --type='json' -p='[{"op": "replace", "path": "/value", "value": "'${val}'"}]'; done

History

Original feature request

Available since v0.6.0