ISO Installation

Harvester ships as a bootable appliance image, you can install it directly on a bare metal server with the ISO image. To get the ISO image, download 💿 harvester-v1.x.x-amd64.iso from the Harvester releases page.

During the installation, you can either choose to create a new Harvester cluster or join the node to an existing Harvester cluster.

The following video shows a quick overview of an ISO installation.

Installation Steps

  1. Mount the Harvester ISO file and boot the server by selecting the Harvester Installer option.

    iso-install.png

  2. Use the arrow keys to choose an installation mode. By default, the first node will be the management node of the cluster.

    choose-installation-mode.png

    • Create a new Harvester cluster: creates an entirely new Harvester cluster.

    • Join an existing Harvester cluster: joins an existing Harvester cluster. You need the VIP and cluster token of the cluster you want to join.

    • Install Harvester binaries only: If you choose this option, additional setup is required after the first bootup.

    ISO Installation - 图3info

    When there are 3 nodes, the other 2 nodes added first are automatically promoted to management nodes to form an HA cluster. If you want to promote management nodes from different zones, you can add the node label topology.kubernetes.io/zone in the os.labels config by providing a URL of Harvester configuration on the customize the host step. In this case, at least three different zones are required.

  3. Choose the installation disk you want to install the Harvester cluster on and the data disk you want to store VM data on. By default, Harvester uses GUID Partition Table (GPT) partitioning schema for both UEFI and BIOS. If you use the BIOS boot, then you will have the option to select Master boot record (MBR).

    choose-installation-target-data-disk.png

    • Installation disk: The disk to install the Harvester cluster on.
    • Data disk: The disk to store VM data on. Choosing a separate disk to store VM data is recommended.
    • Persistent size: If you only have one disk or use the same disk for both OS and VM data, you need to configure persistent partition size to store system packages and container images. The default and minimum persistent partition size is 150 GiB. You can specify a size like 200Gi or 153600Mi.

  4. Configure the HostName of the node.

    config-hostname.png

  5. Configure network interface(s) for the management network. By default, Harvester creates a bonded NIC named mgmt-bo, and the IP address can be configured via DHCP or statically assigned.

    ISO Installation - 图6note

    It is not possible to change the node IP throughout the lifecycle of a Harvester cluster. If using DHCP, you must ensure the DHCP server always offers the same IP for the same node. If the node IP is changed, the related node cannot join the cluster and might even break the cluster.

    config-network.png

  6. (Optional) Configure the DNS Servers. Use commas as a delimiter to add more DNS servers. Leave it blank to use the default DNS server.

    config-dns-server.png

  7. Configure the virtual IP (VIP) by selecting a VIP Mode. This VIP is used to access the cluster or for other nodes to join the cluster.

    ISO Installation - 图9note

    If using DHCP to configure the IP address, you need to configure a static MAC-to-IP address mapping on your DHCP server to have a persistent virtual IP (VIP), and the VIP must be unique.

    config-virtual-ip.png

  8. Configure the Cluster token. This token is used for adding other nodes to the cluster.

    config-cluster-token.png

  9. Configure and confirm a Password to access the node. The default SSH user is rancher.

    config-password.png

  10. Configure NTP servers to make sure all nodes’ times are synchronized. This defaults to 0.suse.pool.ntp.org. Use commas as a delimiter to add more NTP servers.

    config-ntp-server.png

  11. (Optional) If you need to use an HTTP proxy to access the outside world, enter the Proxy address. Otherwise, leave this blank.

    config-proxy.png

  12. (Optional) You can choose to import SSH keys by providing HTTP URL. For example, your GitHub public keys https://github.com/<username>.keys can be used.

    import-ssh-keys.png

  13. (Optional) If you need to customize the host with a Harvester configuration file, enter the HTTP URL here.

    remote-config.png

  14. Review and confirm your installation options. After confirming the installation options, Harvester will be installed to your host. The installation may take a few minutes to be complete.

    confirm-install.png

  15. Once the installation is complete, your node restarts. After the restart, the Harvester console displays the management URL and status. The default URL of the web interface is https://your-virtual-ip. You can use F12 to switch from the Harvester console to the Shell and type exit to go back to the Harvester console.

    ISO Installation - 图18note

    Choosing Install Harvester binaries only on the first page requires additional setup after the first bootup.

    iso-installed.png

  16. You will be prompted to set the password for the default admin user when logging in for the first time.

    first-login.png

Known Issue

Installer may crash when using an older graphics card/monitor

In some cases, if you are using an older graphics card/monitor, you may encounter a panic: invalid dimensions error during ISO installation.

invalid-dimensions.png

We are working on this known issue and planning a fix for a future release. You can try to use another GRUB entry to force it to use the resolution of 1024x768 when booting up.

force-resolution.png

If you are using a version earlier than v1.1.1, please try the following workaround:

  1. Boot up with the ISO, and press E to edit the first menu entry:

    grub-menu.png

  2. Append vga=792 to the line started with $linux:

    edit-menu-entry.png

  3. Press Ctrl+X or F10 to boot up.