Harvester Configuration

Configuration Example

Harvester configuration file can be provided during manual or automatic installation to configure various settings. The following is a configuration example:

  1. server_url: https://someserver:8443
  2. token: TOKEN_VALUE
  3. os:
  4. ssh_authorized_keys:
  5. - ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB...
  6. - github:username
  7. write_files:
  8. - encoding: ""
  9. content: test content
  10. owner: root
  11. path: /etc/test.txt
  12. permissions: '0755'
  13. hostname: myhost
  14. modules:
  15. - kvm
  16. - nvme
  17. sysctl:
  18. kernel.printk: "4 4 1 7"
  19. kernel.kptr_restrict: "1"
  20. dns_nameservers:
  21. - 8.8.8.8
  22. - 1.1.1.1
  23. ntp_servers:
  24. - 0.us.pool.ntp.org
  25. - 1.us.pool.ntp.org
  26. password: rancher
  27. environment:
  28. http_proxy: http://myserver
  29. https_proxy: http://myserver
  30. install:
  31. mode: create
  32. networks:
  33. harvester-mgmt:
  34. interfaces:
  35. - name: ens5
  36. default_route: true
  37. method: dhcp
  38. force_efi: true
  39. device: /dev/vda
  40. silent: true
  41. iso_url: http://myserver/test.iso
  42. poweroff: true
  43. no_format: true
  44. debug: true
  45. tty: ttyS0
  46. vip: 10.10.0.19
  47. vip_hw_addr: 52:54:00:ec:0e:0b
  48. vip_mode: dhcp

Configuration Reference

Below is a reference of all configuration keys.

Warning

Security Risks: The configuration file contains credentials which should be kept secretly. Please do not make the configuration file publicly accessible at the moment.

server_url

Definition

The URL of the Harvester server to join as an agent.

This configuration is mandatory when the installation is in JOIN mode. It tells the Harvester installer where the main server is.

Example

  1. server_url: https://someserver:8443
  2. install:
  3. mode: join

token

Definition

The cluster secret or node token. If the value matches the format of a node token it will automatically be assumed to be a node token. Otherwise it is treated as a cluster secret.

In order for a new node to join the Harvester cluster, the token should match from what server has.

Example

  1. token: myclustersecret

Or a node token

  1. token: "K1074ec55daebdf54ef48294b0ddf0ce1c3cb64ee7e3d0b9ec79fbc7baf1f7ddac6::node:77689533d0140c7019416603a05275d4"

os.ssh_authorized_keys

Definition

A list of SSH authorized keys that should be added to the default user rancher. SSH keys can be obtained from GitHub user accounts by using the format github:${USERNAME}. This is done by downloading the keys from https://github.com/${USERNAME}.keys.

Example

  1. os:
  2. ssh_authorized_keys:
  3. - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC2TBZGjE+J8ag11dzkFT58J3XPONrDVmalCNrKxsfADfyy0eqdZrG8hcAxAR/5zuj90Gin2uBR4Sw6Cn4VHsPZcFpXyQCjK1QDADj+WcuhpXOIOY3AB0LZBly9NI0ll+8lo3QtEaoyRLtrMBhQ6Mooy2M3MTG4JNwU9o3yInuqZWf9PvtW6KxMl+ygg1xZkljhemGZ9k0wSrjqif+8usNbzVlCOVQmZwZA+BZxbdcLNwkg7zWJSXzDIXyqM6iWPGXQDEbWLq3+HR1qKucTCSxjbqoe0FD5xcW7NHIME5XKX84yH92n6yn+rxSsyUfhJWYqJd+i0fKf5UbN6qLrtd/D"
  4. - "github:ibuildthecloud"

os.write_files

A list of files to write to disk on boot. The encoding field specifies the content’s encoding. Valid encoding values are:

  • "": content data are written in plain text. In this case, the encoding field can be also omitted.
  • b64, base64: content data are base64-encoded.
  • gz, gzip: content data are gzip-compressed.
  • gz+base64, gzip+base64, gz+b64, gzip+b64: content data are gzip-compressed first and then base64-encoded.

Example

  1. os:
  2. write_files:
  3. - encoding: b64
  4. content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4...
  5. owner: root:root
  6. path: /etc/connman/main.conf
  7. permissions: '0644'
  8. - content: |
  9. # My new /etc/sysconfig/samba file
  10. SMDBOPTIONS="-D"
  11. path: /etc/sysconfig/samba
  12. - content: !!binary |
  13. f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAwARAAAAAAABAAAAAAAAAAJAVAAAAAA
  14. AEAAHgAdAAYAAAAFAAAAQAAAAAAAAABAAEAAAAAAAEAAQAAAAAAAwAEAAAAAAA
  15. AAAAAAAAAwAAAAQAAAAAAgAAAAAAAAACQAAAAAAAAAJAAAAAAAAcAAAAAAAAAB
  16. ...
  17. path: /bin/arch
  18. permissions: '0555'
  19. - content: |
  20. 15 * * * * root ship_logs
  21. path: /etc/crontab

os.hostname

Definition

Set the system hostname. This value will be overwritten by DHCP if DHCP supplies a hostname for the system. If DHCP doesn’t offer a hostname and this value is empty, a random hostname will be generated.

Example

  1. os:
  2. hostname: myhostname

os.modules

Definition

A list of kernel modules to be loaded on start.

Example

  1. os:
  2. modules:
  3. - kvm
  4. - nvme

os.sysctls

Definition

Kernel sysctl to setup on start. These are the same configuration you’d typically find in /etc/sysctl.conf. Must be specified as string values.

Example

  1. os:
  2. sysctl:
  3. kernel.printk: 4 4 1 7 # the YAML parser will read as a string
  4. kernel.kptr_restrict: "1" # force the YAML parser to read as a string

os.dns_nameservers

Definition

Fallback DNS name servers to use if DNS is not configured by DHCP or in the OS.

Example

  1. os:
  2. dns_nameservers:
  3. - 8.8.8.8
  4. - 1.1.1.1

os.ntp_servers

Definition

Fallback ntp servers to use if NTP is not configured elsewhere in the OS.

Example

  1. os:
  2. ntp_servers:
  3. - 0.us.pool.ntp.org
  4. - 1.us.pool.ntp.org

os.password

Definition

The password for the default user rancher. By default there is no password for the rancher user. If you set a password at runtime it will be reset on next boot. The value of the password can be clear text or an encrypted form. The easiest way to get this encrypted form is to just change your password on a Linux system and copy the value of the second field from /etc/shadow. You can also encrypt a password using openssl passwd -1.

Example

  1. os:
  2. password: "$1$tYtghCfK$QHa51MS6MVAcfUKuOzNKt0"

Or clear text

  1. os:
  2. password: supersecure

os.environment

Definition

Environment variables to be set on k3s and other processes like the boot process. Primary use of this field is to set the http proxy.

Example

  1. os:
  2. environment:
  3. http_proxy: http://myserver
  4. https_proxy: http://myserver

install.mode

Definition

Harvester installer mode:

  • create: Creating a new Harvester installer
  • join: Join an existing Harvester installer. Need to specify server_url.

Example

  1. install:
  2. mode: create

install.networks

Definition

Configure network interfaces for the host machine. Each key-value pair represents as a network interface. The key name becomes the network name, and the values are configurations for each network. Valid configuration fields are:

  • method: Method to assign IP for this network. Support static and dhcp.
  • ip: Static IP for this network. Required if static method is chosen.
  • subnet_mask: Subnet mask for this network. Required if static method is chosen.
  • gateway: Gateway for this network. Required if static method is chosen.
  • interfaces: An array of interface names. If provided, the installer then combines these NICs into a single logical bonded interface.
    • interfaces.name: The name of slave interface for the bonded network.
  • default_route: Set the network as the default route or not.
  • bond_options: Options for bonded interfaces. Refer to here for more info. If not provided, the following options would be used:
    • mode: balance-tlb
    • miimon: 100

Note

A network harvester-mgmt is mandatory to establish a valid management network.

Note

Harvester uses systemd net naming scheme. Please make sure the interface name presents on target machine before installation.

Example

  1. install:
  2. mode: create
  3. networks:
  4. harvester-mgmt: # The management bond name. This is mandatory.
  5. interfaces:
  6. - name: ens5
  7. default_route: true
  8. method: dhcp
  9. bond_options:
  10. mode: balance-tlb
  11. miimon: 100
  12. bond0:
  13. interfaces:
  14. - name: ens8
  15. method: static
  16. ip: 10.10.18.2
  17. subnet_mask: 255.255.255.0
  18. gateway: 192.168.11.1

install.force_efi

Force EFI installation even when EFI is not detected. Default: false.

install.device

The device to install the OS.

install.silent

Reserved.

install.iso_url

ISO to download and install from if booting from kernel/vmlinuz and not ISO.

install.poweroff

Shutdown the machine after install instead of rebooting

install.no_format

Do not partition and format, assume layout exists already.

install.debug

Run installation with more logging and configure debug for installed system.

install.tty

Definition

The tty device used for console.

Example

  1. install:
  2. tty: ttyS0,115200n8

install.vip

install.vip_mode

install.vip_hw_addr

Definition

  • install.vip: The VIP of Harvester management endpoint. After installation, users can access Harvester GUI at URL https://<VIP>.
  • install.vip_mode
    • dhcp: Harvester will send DHCP requests to get VIP. install.vip_hw_addr field needs to be provided.
    • static: Harvester uses a static VIP.
  • install.vip_hw_addr: The hardware address corresponding to the VIP. Users have to configure their on-premise DHCP server to offer the configured VIP. The field is mandatory when install.vip_mode is dhcp.

Example

Configure a static VIP.

  1. install:
  2. vip: 192.168.0.100
  3. vip_mode: static

Configure a DHCP VIP.

  1. install:
  2. vip: 10.10.0.19
  3. vip_mode: dhcp
  4. vip_hw_addr: 52:54:00:ec:0e:0b