Kubernetes Installation in Harvester

Kubernetes Installation in Harvester cover image

This is the written companion to a homelab walkthrough I recorded while putting Kubernetes on top of Harvester and Rancher. The interesting part is the boundary between the physical server, the virtualization layer, and the Kubernetes cluster that eventually runs workloads. A managed cloud hides most of that boundary. Harvester makes you decide what it should look like.

The original walkthrough is from May 2025 and does not record the exact Harvester, Rancher, or RKE2 patch versions used. Treat the video as an installation tour, not as a version-neutral copy-and-paste runbook. The links in this article point to the Harvester v1.8 documentation, which is marked as the latest version at the time of this revision. Before touching a server, choose a supported combination in the SUSE Harvester support matrix. The v1.9 documentation is still marked as development documentation.

Choose the route before you start. Use Rancher's Harvester node driver when you want Rancher to create cloud-image VMs and manage an RKE2 guest cluster end to end; the expected result is a Rancher-managed guest cluster with Harvester cloud-provider and CSI integration. Use manual install and import when Kubernetes is already running in Harvester VMs or you need to own the guest bootstrap; the expected result is an imported guest cluster, with those integrations installed separately. Both routes require a healthy Harvester cluster, stable IPs and VIP, working DNS/NTP, a supported release pair, and an image-registry path. The rest of this page follows the node-driver route.

What is being installed?

There are three layers here, including two Kubernetes clusters. Keeping them separate makes the setup much easier to debug:

  1. Harvester. Harvester is installed on bare-metal servers. It provides the management cluster, virtual machines, networks, and storage used by the rest of the stack. Its built-inmgmt network is for cluster management; VM workloads can use it for testing or use a VLAN-backed VM network.
  2. Rancher. Rancher can import the Harvester cluster so that virtualization resources and Kubernetes clusters are managed from one control plane. Importing Harvester into Rancher is different from installing the guest Kubernetes cluster.
  3. The guest cluster. In the managed path described here, Rancher uses the Harvester node driver to create VMs and provisions an RKE2 cluster on those VMs. The Harvester cloud provider and CSI integration let that guest cluster request Harvester-backed load balancers and storage.

This distinction matters when running kubectl. A command against the Harvester management kubeconfig tells you about hosts, Harvester controllers, and VM infrastructure. The same command against the guest kubeconfig tells you about RKE2 nodes, application pods, and guest-cluster storage. Always check the context before deciding which layer is broken.

Prerequisites for a useful homelab cluster

Start with the Harvester v1.8 hardware and network requirements. The numbers below are a planning baseline from that document, not a promise that every workload will fit.

  • For development and testing, Harvester lists hardware-assisted virtualization, 8 CPU cores, 32 GiB of memory, at least 250 GiB of local storage, 5,000+ random IOPS per disk, and a 1 Gbps network connection. Its production guidance is 16 cores, 64 GiB of memory, at least 500 GiB of storage (1 TiB or more is recommended), 5,000+ random IOPS, and 10 Gbps networking.
  • Three nodes are needed to get the full multi-node Harvester feature set and form an HA management cluster. Some releases support a single-node installation, but it does not provide HA, multiple replicas, or live migration. A one-node lab and a resilient cluster are different projects.
  • Harvester v1.8 installation media requires UEFI; new installations should not be planned around legacy BIOS. Mixed-architecture clusters and nested virtualization are not supported.
  • Give every physical node a stable address. A DHCP reservation is fine, but the same node must receive the same address for its lifetime. Set aside a virtual IP (VIP) for the Harvester API and UI, and make sure the DHCP configuration supplies a default route.
  • Plan DNS and NTP before the install. Kubernetes and etcd are much harder to diagnose when names do not resolve or clocks drift between nodes. Use more than one NTP server when the environment allows it.
  • Configure the switch for the network design you intend to use. A VLAN-backed VM network needs trunking, and the Rancher Harvester node driver requires a VLAN network plus DHCP or Harvester Managed DHCP so it can discover the addresses of newly created VMs.
  • If Rancher will manage the cluster, every Harvester node needs to reach TCP 443 on the Rancher load balancer. The Harvester nodes and guest VMs also need a way to pull the images required by the registration agent and RKE2. In an air-gapped lab, plan the private registry or proxy path first.

For a guest cluster, prepare a cloud image rather than an installer ISO. The Harvester node driver supports cloud images. The image also needs a working qemu-guest-agent; current node-driver versions do not silently add it for you. Without it, Rancher may create a VM but be unable to discover the address needed to continue provisioning.

The installation sequence

1. Select the release pair before downloading anything

Pick Harvester first, then select the compatible Rancher and RKE2 versions from the support matrix. Do not use a floating “latest” image for a reproducible build. Record the Harvester release, Rancher release, RKE2 version, guest operating-system image, and the date you made the choice. Those five details turn a future failure from guesswork into a comparison against a known setup.

Download the ISO from the v1.8 ISO installation guide. Use the release checksum and your normal artifact-verification process before booting it on a server.

2. Install the first Harvester node

Boot the server from the ISO and choose Harvester Installer. For the first machine, select Create a new Harvester cluster. The installer walks through the password, installation and data disks, hostname, management interface, pod and service CIDRs, DNS servers, VIP, cluster token, NTP servers, and optional proxy or SSH key settings.

The two values that are easiest to treat as incidental are the node IP and the VIP. They are part of the cluster identity. If you use DHCP, reserve those addresses rather than hoping the next lease will match. The node IP cannot be changed safely after the node is installed, and the VIP is the address other Harvester nodes use when they join.

Keep the default pod and service ranges unless they overlap with your homelab. If you customize them, the ranges must not overlap each other or the networks already used by your physical and guest environments; the cluster DNS address must be inside the service range. When the installer finishes, open the HTTPS URL shown by the console, set the initial admin password, and wait for the management cluster to settle before adding Rancher.

3. Join the remaining Harvester nodes

On each additional server, boot the same release and chooseJoin an existing Harvester cluster. Supply the first cluster's VIP and cluster token, then choose the role for the node. With three nodes, Harvester promotes the first three appropriate nodes to management nodes. If the machine is only for compute, use the worker role deliberately rather than relying on a later scheduling decision.

Before continuing, check the Harvester UI and the management kubeconfig. The baseline check is intentionally boring:

kubectl config current-context
kubectl get nodes -o wide
kubectl get pods --all-namespaces
kubectl get storageclass

Every expected node should be Ready. A completed Job is not a problem, but unexplained Pending,CrashLoopBackOff, or storage errors are a reason to stop here. Adding Rancher will not repair an unhealthy Harvester base layer; it will only give the problem another UI.

Import Harvester into Rancher

The import step makes Harvester visible to Rancher. It does not create a guest Kubernetes cluster yet. In the Rancher UI, openVirtualization Management, chooseImport Existing, enter a name, and follow the registration guide on the target Harvester dashboard. The current virtualization-management guide explains both the UI and API paths.

Rancher creates a cattle-cluster-agent pod in the Harvester cluster. That image is selected from the Rancher server version and is pulled when the import runs; it is not necessarily bundled in the Harvester ISO. If the Harvester cluster cannot reach the registry, use the documented private-registry, proxy, or preloading approach rather than repeatedly restarting the agent.

For the v1.8 path in this page, follow the v1.8 support-matrix row: it currently pairs Harvester v1.8 with Rancher v2.14, and the extension table lists the Harvester UI Extension 1.8.x for Rancher 2.14. Use the exact patch versions shown in the matrix; do not generalize this to every Rancher 2.10+ release. A successful registration with a missing or mismatched extension can look like a broken Harvester UI even though the agent is connected.

If the import is stuck, inspect the agent on the Harvester context:

kubectl -n cattle-system get pods
agent_pod="$(kubectl -n cattle-system get pods -o name | awk '/cattle-cluster-agent-/ { print; exit }')"
if [ -n "$agent_pod" ]; then
  kubectl -n cattle-system describe "$agent_pod"
  kubectl -n cattle-system logs "$agent_pod"
else
  echo "No cattle-cluster-agent pod found" >&2
fi

ImagePullBackOff usually points to registry reachability, DNS, proxy configuration, or an image-policy problem. It is not evidence that RKE2 failed, because RKE2 has not been provisioned at this point.

Provision the guest RKE2 cluster

Once Harvester is imported, create a cloud credential in Rancher by choosing Cluster Management → Cloud Credentials → Create → Harvester. Select the imported Harvester cluster. Then create a cluster and choose the RKE2/K3s path with the Harvester node driver. The required fields in the current guide are the cluster name, namespace, cloud credential, cloud image, VM network, and SSH user.

Start with a small node pool so that the first failure is legible. Put control-plane/etcd and worker capacity in separate pools when the lab has enough hardware. If you use host labels or zones, add node affinity in the machine-pool advanced settings so a replacement VM is scheduled where you expect it. The Harvester RKE2 guide documents the exact fields and the supported affinity options.

The guest image must contain the qemu guest agent. If it does not, add it through cloud-init or use an image that already includes it:

#cloud-config
package_update: true
packages:
  - qemu-guest-agent
runcmd:
  - systemctl enable --now qemu-guest-agent

Calico and Canal also need iptables orxtables-nft in the guest image. Whether that package is called iptables or something distribution-specific depends on the image, so check the image documentation instead of pasting a package command blindly:

#cloud-config
packages:
  - iptables

Select the Harvester cloud provider in the cluster configuration. With the supported RKE2 node-driver path, Rancher and the Harvester integration deploy the cloud provider and CSI pieces for the guest cluster. They are what make a Kubernetes LoadBalancer Service and a persistent volume meaningful on this infrastructure. Check the cloud-provider guide and the CSI-driver guide if you need to use a custom cluster instead.

There is a second, valid workflow: install RKE2 yourself in an existing Harvester VM and import that guest cluster into Rancher. It is not the same as the node-driver workflow. In that case, follow the official import-existing-VM guide and install the cloud provider and CSI driver explicitly. Mixing steps from the two workflows is a reliable way to end up with a cluster that registers but has no working storage or load balancer integration.

Prove the guest cluster works

Switch to the guest kubeconfig before checking anything. Then verify nodes, system pods, and storage classes:

kubectl config current-context
kubectl get nodes -o wide
kubectl get pods --all-namespaces
kubectl get storageclass

A useful smoke test exercises scheduling, service discovery, and a real HTTP request without introducing ingress or external DNS. Save the following as smoke-test.yaml and apply it to the guest cluster:

apiVersion: v1
kind: Namespace
metadata:
  name: smoke-test
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
  namespace: smoke-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: nginx
          image: nginx:1.27.5
          ports:
            - name: http
              containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: hello
  namespace: smoke-test
spec:
  selector:
    app: hello
  ports:
    - name: http
      port: 80
      targetPort: http
kubectl apply -f smoke-test.yaml
kubectl rollout status deployment/hello -n smoke-test --timeout=120s
kubectl get pods,service,endpointslices -n smoke-test
kubectl port-forward service/hello 8080:80 -n smoke-test

With the port-forward running, use another terminal for the actual HTTP check:

curl --fail --show-error --include http://localhost:8080/

You should see HTTP/1.1 200 OK and the nginx welcome-page HTML, including Welcome to nginx!. This checks that the pod scheduled, the Service selected it, and traffic can reach it. The image tag is deliberately pinned; replace it with an image from your own registry when the guest cluster is isolated from Docker Hub.

If the cluster will hold state, test a small PVC separately. First look at the available StorageClasses. A claim that stays Pending usually means there is no default class, the requested access mode is not supported, or the Harvester/CSI integration is not healthy. Kubernetes explains the relationship between claims and StorageClasses in its persistent-volume documentation.

Troubleshoot from the layer that failed

The fastest way to lose an afternoon is to debug Rancher when the physical network is wrong, or debug Kubernetes when the VM never got an address. Use the symptom to choose the layer:

  • A Harvester node will not join. Recheck the VIP, cluster token, stable node address, default route, DNS, NTP, and firewall paths. If an HTTP proxy is configured, make sure the node CIDR is in noProxy when Harvester nodes communicate directly with one another. The Harvester troubleshooting guide has the version-specific proxy failure mode.
  • Rancher import is stuck. Inspectcattle-cluster-agent in cattle-system and read the pod event. An image pull error means registry, proxy, DNS, or trust configuration; first fix that path. Also verify that every Harvester node can reach Rancher on TCP 443.
  • Rancher creates a VM but provisioning stops. Check that the VM is using a cloud image, that the selected network is a VLAN network with DHCP or Managed DHCP, and that the qemu guest agent is installed and running. Without an address, Rancher cannot finish installing RKE2.
  • Guest nodes are present but the CNI is unhealthy. Check the guest image for iptables orxtables-nft, then inspect the RKE2 system pods and their events. A running VM is not the same thing as a working Kubernetes node.
  • Pods are Pending or a PVC never binds. Inspect capacity, taints, events, and StorageClasses in the guest cluster. Then check the Harvester host, disk, and CSI controller in the management layer. Avoid changing Longhorn settings directly while trying random fixes; Harvester documents those settings as managed infrastructure.
  • A LoadBalancer Service has no external address. A Kubernetes Service only describes the desired interface. The Harvester cloud provider must be installed and the VM network/IPAM configuration must have an address available. For ordinary HTTP debugging, use port-forward first and add a load balancer only after the guest cluster is healthy. Kubernetes describes the Service behavior in its Services documentation.

What “working” means here

The video shows the path from a bare server to a cluster visible in Rancher. That is useful, but it is not proof of production readiness. Before putting important state on the cluster, record the versions and network choices, confirm that the guest can provision and mount a test volume, test the ingress or load-balancer path you actually plan to use, and decide how backups and upgrades will be performed.

I would also remove the temporary installation shortcuts. The official Harvester post-installation guidance recommends disabling SSH password authentication after installation. Only after the base layer is repeatable would I add GitOps, ingress, observability, and application state. Separating those steps makes the next failure specific enough to fix.