Settings

The following is a list of advanced settings that you can use. You can modify the settings.harvesterhci.io custom resource using both the UI and the kubectl command.

General Settings

additional-ca

Definition: Additional trusted CA certificates that enable SUSE® Virtualization to access external services.

Changing this setting might cause single-node clusters to temporarily become unavailable or inaccessible.

Default value: None

Example:

-----BEGIN CERTIFICATE-----
SOME-CA-CERTIFICATES
-----END CERTIFICATE-----

auto-disk-provision-paths [Experimental]

Definition: Setting that allows SUSE® Virtualization to automatically add disks that match the specified glob pattern as VM storage.

This setting only adds formatted disks that are mounted to the system. When specifying multiple patterns, separate values using commas.

This setting is applied to all nodes in the cluster. All data in the storage devices will be destroyed.

Default value: None

Example:

The following example adds disks that match the glob pattern /dev/sd* or /dev/hd*:

/dev/sd*,/dev/hd*

auto-rotate-rke2-certs

Versions: v1.3.0 and later

Definition: Setting that allows you to automatically rotate certificates for RKE2 services. This setting is disabled by default.

Use the field expiringInHours to specify the validity period of each certificate (1 to 8759 hours). The certificate is automatically replaced before the specified period ends.

For more information, see the Certificate Rotation section of the Rancher and RKE2 documentation.

Default value: {"enable":false,"expiringInHours":240}

Example:

{"enable":true,"expiringInHours":48}

backup-target

Definition: Custom backup target used to store VM backups.

For more information, see the Longhorn documentation.

Default value: None

Example:

{
  "type": "s3",
  "endpoint": "https://s3.endpoint.svc",
  "accessKeyId": "test-access-key-id",
  "secretAccessKey": "test-access-key",
  "bucketName": "test-bup",
  "bucketRegion": "us‑east‑2",
  "cert": "",
  "virtualHostedStyle": false
}

cluster-registration-url

Definition: URL used to import the SUSE® Virtualization cluster into Rancher for multi-cluster management.

When you configure this setting, a new pod called cattle-cluster-agent-* is created in the namespace cattle-system for registration purposes. This pod uses the container image rancher/rancher-agent:related-version, which is not packed into the SUSE® Virtualization ISO and is instead determined by Rancher. The related-version is usually the same as the Rancher version. For example, when you register SUSE® Virtualization to Rancher v2.7.9, the image is rancher/rancher-agent:v2.7.9. For more information, see Find the required assets for your Rancher version in the Rancher documentation.

Depending on your settings, the image is downloaded from either of the following locations:

  • SUSE® Virtualization containerd-registry: You can configure a private registry for the cluster.

  • Docker Hub (docker.io): This is the default option when you do not configure a private registry in Rancher.

Alternatively, you can obtain a copy of the image and manually upload it to all nodes.

Default value: None

Example:

https://172.16.0.1/v3/import/w6tp7dgwjj549l88pr7xmxb4x6m54v5kcplvhbp9vv2wzqrrjhrc7c_c-m-zxbbbck9.yaml

containerd-registry

Definition: Configuration of a private registry created for the SUSE® Virtualization cluster.

The value is stored in the registries.yaml file of each node (path: /etc/rancher/rke2/registries.yaml). For more information, see Containerd Registry Configuration in the RKE2 documentation.

For security purposes, SUSE® Virtualization automatically removes the username and password configured for the private registry after those credentials are stored in the registries.yaml file.

Example:

containerd-registry 
{
  "Mirrors": {
    "docker.io": {
      "Endpoints": ["https://myregistry.local:5000"],
      "Rewrites": null
    }
  },
  "Configs": {
    "myregistry.local:5000": {
      "Auth": {
        "Username": "testuser",
        "Password": "testpassword"
      },
      "TLS": {
        "InsecureSkipVerify": false
      }
    }
  }
}

csi-driver-config

Definition: Configuration necessary for using third-party CSI drivers installed in the cluster.

You must configure the following information before using features related to backups and snapshots:

  • Provisioner for the installed third-party CSI driver

  • volumeSnapshotClassName: Name of the VolumeSnapshotClass used to create volume snapshots or VM snapshots.

  • backupVolumeSnapshotClassName: Name of the VolumeSnapshotClass used to create VM backups.

Default value:

{
  "driver.longhorn.io": {
    "volumeSnapshotClassName": "longhorn-snapshot",
    "backupVolumeSnapshotClassName": "longhorn"
  }
}

default-vm-termination-grace-period-seconds

Definition: Number of seconds SUSE® Virtualization waits before forcibly shutting down a VM that was stopped using the UI.

SUSE® Virtualization sends a graceful shutdown signal to any VM that is stopped using the UI. If the graceful shutdown process is not completed within the specified number of seconds, SUSE® Virtualization forcibly shuts down the VM.

Default value: 120

http-proxy

Definition: HTTP proxy used to access external services, including downloading of images and backup to S3 services.

Changing this setting might cause single-node clusters to temporarily become unavailable or inaccessible.

Default value: {}

Supported options and values:

  • Proxy URL for HTTP requests: "httpProxy": "http://<username>:<pswd>@<ip>:<port>"

  • Proxy URL for HTTPS requests: "httpsProxy": "https://<username>:<pswd>@<ip>:<port>"

  • Comma-separated list of hostnames and/or CIDRs: "noProxy": "<hostname | CIDR>"

You must specify key information in the noProxy field if you configured the following options or settings:

Configured option/setting Required value in noProxy Reason

httpProxy and httpsProxy

Node’s CIDR

Not specifying the node’s CIDR can break the cluster.

cluster-registration-url

Host of cluster-registration-url

The host information allows you to access the cluster from Rancher.

SUSE® Virtualization appends necessary addresses to user-specified noProxy values (for example,localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,longhorn-system,cattle-system,cattle-system.svc,harvester-system,.svc,.cluster.local). This ensures that internal traffic flows as expected.

Example:

{
  "httpProxy": "http://my.proxy",
  "httpsProxy": "https://my.proxy",
  "noProxy": "some.internal.svc,172.16.0.0/16"
}

log-level

Definition: Log level for the host.

Default value: info

Supported options and values:

  • panic: Least verbose log level

  • fatal

  • error

  • warn, warning

  • info

  • debug

  • trace: Most verbose log level

Example:

debug

ntp-servers

Definition: NTP servers for time synchronization on nodes.

You can define NTP servers during installation and update the addresses after installation.

Changes to the server address list are applied to all nodes.

Default value: ""

Example:

{
  "ntpServers": [
    "0.suse.pool.ntp.org",
    "1.suse.pool.ntp.org"
  ]
}

overcommit-config

Definition: Percentage of physical compute, memory, and storage resources that can be allocated for VM use.

Overcommitting is used to optimize physical resource allocation, particularly when VMs are not expected to fully consume the allocated resources most of the time. Setting values greater than 100% allows scheduling of multiple VMs even when physical resources are notionally fully allocated.

Default values: { "cpu":1600, "memory":150, "storage":200 }

With the default values, it would be possible to schedule the following:

  • 16x the number of physical CPUs on a host

  • 1.5x the amount of physical RAM on a host

  • 2x the amount of physical storage in Longhorn

A VM that is configured to use 2 CPUs (equivalent to 2,000 milliCPU) can consume the full allocation as long as the resources are available. However, if the host is running heavy workloads and an overcommit value is set (for example, 1600%), SUSE® Virtualization only requests 125 milliCPU from the Kubernetes scheduler (2000/16 = 125 milliCPU).

Example:

{
  "cpu": 1000,
  "memory": 200,
  "storage": 300
}

release-download-url

Definition: URL for downloading the software required for upgrades.

SUSE® Virtualization retrieves the ISO URL and checksum value from the ${URL}/${VERSION}/version.yaml file that is accessible through the configured URL.

Default value: https://releases.rancher.com/harvester

Example (version.yaml):

apiVersion: harvesterhci.io/v1beta1
kind: Version
metadata:
  name: ${VERSION}
  namespace: harvester-system
spec:
  isoChecksum: ${ISO_CHECKSUM}
  isoURL: ${ISO_URL}

server-version

Definition: Version of SUSE® Virtualization that is installed on nodes.

Example:

v1.0.0-abcdef-head

ssl-certificates

Definition: SSL certificates for the UI and API.

Changing this setting might cause single-node clusters to temporarily become unavailable or inaccessible.

Default value: {}

Example:

{
  "ca": "-----BEGIN CERTIFICATE-----\nSOME-CERTIFICATE-ENCODED-IN-PEM-FORMAT\n-----END CERTIFICATE-----",
  "publicCertificate": "-----BEGIN CERTIFICATE-----\nSOME-CERTIFICATE-ENCODED-IN-PEM-FORMAT\n-----END CERTIFICATE-----",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nSOME-PRIVATE-KEY-ENCODED-IN-PEM-FORMAT\n-----END RSA PRIVATE KEY-----"
}

ssl-parameters

Definition: Enabled SSL/TLS protocols and ciphers of the UI and API.

important

If you misconfigure this setting and are unable to access the UI and API, see Troubleshooting.

Default value: None

Supported options and values:

  • protocols: Enabled protocols.

  • ciphers: Enabled ciphers.

For more information about the supported options, see ssl-protocols and ssl-ciphers in the Ingress-Nginx Controller documentation.

If you do not specify any values, SUSE® Virtualization uses TLSv1.2 and ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305.

Example:

{
  "protocols": "TLSv1.2 TLSv1.3",
  "ciphers": "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305"
}

storage-network

Definition: Segregated storage network for Longhorn traffic.

By default, Longhorn uses the management network, which is limited to a single interface and shared with cluster-wide workloads. If your implementation requires network segregation, you can use a storage network to isolate Longhorn in-cluster data traffic.

important

Shut down all VMs before configuring this setting.

Specify an IP range in the IPv4 CIDR format. The number of IPs must be four times the number of your cluster nodes.

Default value: ""

Example:

{
  "vlan": 100,
  "clusterNetwork": "storage",
  "range": "192.168.0.0/24"
}

support-bundle-image

Definition: Support bundle image, with various versions available in rancher/support-bundle-kit.

Default value:

{
  "repository": "rancher/support-bundle-kit",
  "tag": "v0.0.25",
  "imagePullPolicy": "IfNotPresent"
}

support-bundle-namespaces

Definition: Additional namespaces that you can use when generating a support bundle.

By default, the support bundle only collects resources from the following predefined namespaces:

  • cattle-dashboards

  • cattle-fleet-local-system

  • cattle-fleet-system

  • cattle-fleet-clusters-system

  • cattle-monitoring-system

  • fleet-local

  • harvester-system

  • local

  • longhorn-system

  • cattle-logging-system

Namespaces that you select are appended to the predefined namespaces list.

Default value: None

support-bundle-timeout

Definition: Number of minutes SUSE® Virtualization allows for the completion of the support bundle generation process.

The process is considered to have failed when the data collection and file packing tasks are not completed within the configured number of minutes. SUSE® Virtualization does not continue or retry support bundle generation processes that have timed out. When the value is 0, the timeout feature is disabled.

Default value: 10

support-bundle-expiration

Versions: v1.3.0 and later

Definition: Number of minutes SUSE® Virtualization waits before deleting a support bundle that has been packaged but not downloaded (either deliberately or unsuccessfully) or retained.

The minimum value is 30.

Default value: 30

support-bundle-node-collection-timeout

Versions: v1.3.1 and later

Definition: Number of minutes SUSE® Virtualization allows for collection of logs and configurations on the nodes for the support bundle.

If the collection process is not completed within the allotted time, SUSE® Virtualization still allows you to download the support bundle (without the uncollected data). The minimum value is 30.

Default value: 30

upgrade-checker-enabled

Definition: Setting that automatically checks for available upgrades.

Default value: true

Example:

false

upgrade-checker-url

Definition: URL used to check for available upgrades.

This setting can only be used if the upgrade-checker-enabled setting is set to true.

Default value: https://harvester-upgrade-responder.rancher.io/v1/checkupgrade

Example:

https://your.upgrade.checker-url/v99/checkupgrade

vip-pools

Versions: Deprecated as of v1.2.0 (Use IP pools instead.)

Definition: Global or namespace-specific IP address pools of the VIP by CIDR or IP range.

Default value: {}

Example:

{
  "default": "172.16.0.0/24,172.16.1.0/24",
  "demo": "172.16.2.50-172.16.2.100,172.16.2.150-172.16.3.200"
}

vm-force-reset-policy

Definition: Setting that allows you to force rescheduling of a VM when the node that it is running on becomes unavailable.

When the state of the node changes to Not Ready, the VM is force deleted and rescheduled to an available node after the configured number of seconds.

When the node becomes unavailable or is powered off, the VM only restarts and does not migrate.

Default value: {"enable":true, "period":300}

Example:

{
  "enable": "true",
  "period": 300
}

volume-snapshot-class

Definition: VolumeSnapshotClassName for the VolumeSnapshot and VolumeSnapshotContent when restoring a VM to a namespace that does not contain the source VM.

Default value: longhorn

Example:

longhorn

UI Settings

branding

Definition: Setting allows you to globally rebrand the UI by customizing the product name, logos, and color scheme.

Default value: Harvester

Because this setting is part of the settings.management.cattle.io custom resource, you cannot configure any of the supported options (for example, Logo and Primary Color using a configuration file.
containerd-registry

Supported options and values:

  • Private Label: Product name or other text that replaces "Harvester" in most locations on the UI.

  • Logo: Logo image in the top-level navigation header. You must upload logos for both light and dark modes.

  • Favicon: Small image displayed next to the page title in the browser tab.

  • Primary Color: Main color used throughout the UI.

  • Link Color: Color used for link text throughout the UI.

ui-index

Definition: HTML index location for the UI.

Default value: https://releases.rancher.com/harvester-ui/dashboard/latest/index.html

Example:

https://your.static.dashboard-ui/index.html

ui-path

Definition: Path that describes the location of index.html, which is used to access the UI.

ui-path serves as the entry point to the UI and is active only in the following situations:

  • The value of ui-source is bundled.

  • The value of ui-source is auto, but ui-index is unable to retrieve the HTML file.

Default value: /usr/share/harvester/harvester

Examples:

index.html is stored in a container in /home/samplefolder. The value of ui-source is bundled.

Scenario 1: The value of ui-path is /home/samplefolder. Whenever you access the UI, the content of /home/samplefolder/index.html is displayed.

Scenario 2: The value of ui-index points to a page that is unavailable or non-existent (for example, notexist-example.com/index.html). When you access the UI for the first time, the content of /home/samplefolder/index.html is displayed. However, if you modify the ui-index setting to use the default value and access the UI again, the content of /home/samplefolder/index.html is still displayed (even if the new ui-index value points to an available page). For more information, see Issue #6066.

ui-plugin-index

Definition: JavaScript address for the plugin (when accessing SUSE® Virtualization from Rancher).

Default value: https://releases.rancher.com/harvester-ui/plugin/harvester-latest/harvester-latest.umd.min.js

Example:

https://your.static.dashboard-ui/*.umd.min.js

ui-source

Definition: Setting that allows you to configure how to load the UI source.

Default value: auto

Supported values:

  • auto: Automatically detects whether to use the bundled UI or not.

  • external: Uses the external UI source.

  • bundled: Uses the bundled UI source.

Example:

external