Skip to content

HOWTO: Bootstrap an RKE2 Cluster via HyOps

Purpose: Deploy a production-ready RKE2 cluster on Proxmox VMs using the HybridOps module, with full preflight coverage and a validated run record.

Difficulty: Advanced

Track: Platform Services

Overview

RKE2 cluster provisioning in HybridOps is a module-managed operation: VMs are pre-provisioned with static IPs from NetBox IPAM, the onprem/rke2@v1 module handles the full bootstrap sequence, and the run record documents every step from kubeconfig generation to node registration. This HOWTO covers the deployment path; workload onboarding is covered by the onprem/rke2-workloads@v1 module.

1. Module Overview

  • Module ID: onprem/rke2@v1.
  • Architecture: multi-node control plane + workers.
  • CNI options and default storage class.

2. Prerequisites

  • Control plane and worker VMs provisioned with IPAM-allocated static IPs.
  • VM template with cloud-init support (from core/onprem/template-image).
  • Proxmox network configuration with target VLAN bridged.

3. Module Inputs

  • Control plane node IPs (minimum 3 for HA).
  • Worker node IPs.
  • CNI selection and CNI-specific options.
  • Storage class backend.
  • TLS SANs for the API server.
  • GitOps agent type and initial repository reference.

4. Running the Bootstrap

  • Preflight check: VM reachability, SSH access, CNI prerequisite check.
  • Bootstrap sequence: first control plane → additional control planes → workers.
  • kubeconfig generation and storage.

5. Validation

  • Node registration: kubectl get nodes.
  • Control plane HA: verify all control planes in etcd member list.
  • Default storage class functional.
  • GitOps agent health check.
  • Run record: all steps ok, kubeconfig records present.

6. Handoff to Workloads

  • Locating the kubeconfig in the run record.
  • Running onprem/rke2-workloads@v1 for initial platform workloads.
  • GitOps onboarding HOWTO reference.

References

License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.