Andrew Mercer
on this page

12.1 Installation methods

  1. ISO (virtual media via IPMI/iDRAC/iLO, or USB).
  2. USB (dd the ISO).
  3. PXE / iPXE with a Harvester configuration file — the way to do it at scale.
  4. Nested in a VM for labs (enable nested virtualization; slow but useful).

12.2 Interactive ISO flow

  1. Boot → choose Create a new Harvester cluster (first node), Join an existing Harvester cluster, or install as a witness.
  2. Choose installation disk and (optionally) a separate data disk.
  3. Hostname, management NIC(s), bond mode, VLAN (if the management network is tagged), IP (static or DHCP).
  4. DNS, NTP, proxy.
  5. VIP: the cluster virtual IP (served by kube-vip) — this is the address for the UI/API and for joining nodes.
  6. Cluster token: shared secret used by joining nodes.
  7. Password for the rancher OS user; optional SSH keys.
  8. Confirm — install, reboot. The console shows status until it reads Ready.

Browse to https://<VIP> and set the admin password.

12.3 Harvester configuration file (automated install)

The same choices can be expressed in YAML and passed via harvester.install.config_url= kernel parameter (PXE) or harvester.install.automatic=true:

# create-node1.yaml
scheme_version: 1
token: "a-long-random-cluster-token"
os:
  hostname: hv-node1
  password: "$6$...hashed..."          # or plain text for labs
  ssh_authorized_keys:
    - ssh-ed25519 AAAAC3... andrew@workstation
  ntp_servers:
    - 0.ca.pool.ntp.org
    - 1.ca.pool.ntp.org
  dns_nameservers:
    - 10.0.0.1
install:
  mode: create
  device: /dev/nvme0n1
  data_disk: /dev/nvme1n1
  iso_url: http://pxe.lab.example.net/harvester/harvester-v1.9.0-amd64.iso
  management_interface:
    interfaces:
      - name: eno1
      - name: eno2
    method: static
    ip: 10.0.10.11
    subnet_mask: 255.255.255.0
    gateway: 10.0.10.1
    default_route: true
    bond_options:
      mode: 802.3ad
      miimon: 100
    mtu: 1500
    # vlan_id: 10          # if mgmt network is tagged
  vip: 10.0.10.10
  vip_mode: static
  skipchecks: false
  automatic: true

# join-node2.yaml
scheme_version: 1
server_url: https://10.0.10.10:443
token: "a-long-random-cluster-token"
os:
  hostname: hv-node2
  ssh_authorized_keys:
    - ssh-ed25519 AAAAC3... andrew@workstation
install:
  mode: join
  device: /dev/nvme0n1
  data_disk: /dev/nvme1n1
  iso_url: http://pxe.lab.example.net/harvester/harvester-v1.9.0-amd64.iso
  management_interface:
    interfaces:
      - name: eno1
      - name: eno2
    method: static
    ip: 10.0.10.12
    subnet_mask: 255.255.255.0
    gateway: 10.0.10.1
    default_route: true
    bond_options:
      mode: 802.3ad
      miimon: 100
  automatic: true

Other notable config keys:

  • install.role: default, management, worker, witness.
  • install.with_net_images, install.persistent_partition_size (space for container images and logs).
  • os.write_files, os.after_install_chroot_commands — customize the host (sparingly; it's immutable for a reason).
  • os.modules, os.sysctls, os.environment (proxy).
  • os.labels — node labels applied at join (great for zone/rack topology).
  • system_settings — pre-seed Harvester Setting values (backup target, overcommit, etc.).

12.4 iPXE example

#!ipxe
set base http://pxe.lab.example.net/harvester/v1.9.0
kernel ${base}/harvester-v1.9.0-vmlinuz-amd64 initrd=harvester-v1.9.0-initrd-amd64 ip=dhcp net.ifnames=1 rd.cos.disable rd.noverifyssl root=live:${base}/harvester-v1.9.0-rootfs-amd64.squashfs console=tty1 harvester.install.automatic=true harvester.install.config_url=http://pxe.lab.example.net/harvester/configs/${mac:hexhyp}.yaml
initrd ${base}/harvester-v1.9.0-initrd-amd64
boot

Serving per-MAC config files gives you fully hands-off cluster builds. Pair with the harvester-seeder add-on (IPMI/Redfish out-of-band management) for power control.

12.5 Post-install checklist

  • [ ] Change/rotate the admin password; configure an auth provider (or rely on Rancher's after import).
  • [ ] Download the kubeconfig (Support page) and verify kubectl get nodes.
  • [ ] Set NTP and confirm clocks — etcd and Longhorn hate skew.
  • [ ] Configure SSL certificate for the UI (ssl-certificates setting) and additional-ca if you use an internal CA.
  • [ ] Add data disks (Hosts → Edit → Disks) or set auto-disk-provision-paths.
  • [ ] Configure cluster networks and VLAN networks for VMs.
  • [ ] Configure the storage network if you have a dedicated NIC/VLAN.
  • [ ] Set the backup target (S3 or NFS).
  • [ ] Upload base images (cloud images with cloud-init).
  • [ ] Enable add-ons you need (monitoring, logging, PCI devices, vm-import).
  • [ ] Review overcommit settings.
  • [ ] Import into Rancher if you have one.

← Harvester hardware planning · Index · Harvester networking in depth →