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

This Kubernetes reference implementation applies the HybridOps operating contract through onprem/rke2@v1. The exercised path consumes authoritative addressing, prepares the control plane and workers, verifies cluster readiness, and records the handoff from kubeconfig generation through node registration. Workload onboarding continues through onprem/rke2-workloads@v1 under the same contract.

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.