repository·main·Indexed 22 days ago
https://github.com/syself/cluster-api-provider-hetznerA Cluster API provider for the declarative management of self-managed Kubernetes clusters on Hetzner Cloud and Hetzner Bare Metal infrastructure. It enables automated deployment and lifecycle management, supporting both cloud and bare-metal instances. The documentation covers management cluster setup using clusterctl, workload cluster generation, HCloud secret configuration, and the installation of Cilium CNI and Cloud Controller Managers (CCM).
To ensure secure operation, Kubernetes requires signing kubelet serving certificates. When the kubelet flag rotate-server-certificates: "true" is set (configured via initConfiguration/joinConfiguration.nodeRegistration.kubeletExtraArgs), the kubelet automatically submits a Certificate Signing Request (CSR) to the Kubernetes certificates API.
CAPH includes a built-in CSR controller that automatically approves these requests. The controller validates the request by checking the DNS name and the IP address to ensure only the intended nodes receive signed certificates.
Important Configuration Note: To avoid errors with the default controller, do not manually set the following kubelet flags:
tls-cert-file: "/var/lib/kubelet/pki/kubelet-client-current.pem"tls-private-key-file: "/var/lib/kubelet/pki/kubelet-client-current.pem"# Do NOT set these flags if you want to use the default CSR controller
tls-cert-file: "/var/lib/kubelet/pki/kubelet-client-current.pem"
tls-private-key-file: "/var/lib/kubelet/pki/kubelet-client-current.pem"The lifecycle of a host follows these stages:
HetznerBareMetalMachine selects the host, updating the host's status and triggering provisioning.HetznerBareMetalMachine is deleted, the host deprovisions and returns to a neutral state.maintenanceMode to ensure no machines consume it.The HetznerCluster object supports two primary deployment modes:
kubeadm and supports private networks.Important constraints for Bare Metal clusters:
cloud-init for provisioning.ProviderID format matches the requirements for your chosen CCM.The HetznerBareMetalMachine lifecycle is managed by the HetznerBareMetalMachineController. Crucially, the controller does not create or delete physical Hetzner dedicated machines directly. Instead, it operates on an inventory of existing HetznerBareMetalHosts (which represent already existing bare metal servers).
Provisioning Flow:
HetznerBareMetalMachine is created with specs defined in a HetznerBareMetalMachineTemplate.HetznerBareMetalHost.ready.Deprovisioning Flow:
HetznerBareMetalMachine is deleted, it removes provisioning information from the associated host.The cluster-api-provider-hetzner supports multi-tenancy, allowing you to run multiple Kubernetes clusters within the same Hetzner cloud project simultaneously.
To ensure isolation and prevent resource conflicts, the controller uses labels on all provisioned Hetzner resources that correspond to the specific cluster name. This labeling mechanism allows the controller to manage and distinguish resources belonging to different clusters even when they reside in the same project.
When working with the Cluster API Provider Hetzner (CAPH), it is important to distinguish between standard Cluster API (CAPI) objects and the provider-specific objects that implement them.
HetznerCluster is the provider-specific counterpart to the CAPI Cluster object.Machine object is implemented by either an HCloudMachine or a HetznerBareMetalMachine, depending on the infrastructure type.The HetznerBareMetalRemediationTemplate allows you to define custom methods for how Machine Health Checks treat unhealthy HetznerBareMetalMachine objects. These templates are reconciled by the HetznerBareMetalRemediationController, which triggers the specified remediation on the relevant machine.
To use this, you must define a strategy within the spec. Currently, only the Reboot strategy type is supported.
When deploying clusters using bare metal servers with CAPH, you can select from different pre-defined templates known as 'flavors'. These flavors determine whether control plane nodes run on bare metal or HCloud (virtualized) and how the cluster handles machine remediation (recovery from failure).
Note: These flavors are intended for demonstration purposes and are not recommended for production environments.
# Flavors are consumed using the clusterctl tool
# Example usage pattern (conceptual):
clusterctl generate cluster --flavor <flavor-name> ...A standard CAPH installation managed via clusterctl involves four primary components. While the default installation is not highly available, these components can be scaled to improve reliability:
The HetznerBareMetalHost object represents a one-to-one relationship with a Hetzner dedicated server. It is used to make bare metal servers available to clusters.
Key characteristics:
HetznerCluster and can be used by multiple clusters. This allows you to track server availability independently.HetznerBareMetalMachine selects the host and updates its status.Bare metal servers in Hetzner Robot require two SSH keys: one for the rescue system and one for the actual system. These keys are managed via Kubernetes Secrets containing both the public and private key data.
Configuration Locations:
HetznerCluster specification.HetznerBareMetalMachineTemplate. There is no cluster-wide alternative for the actual system key.Important Lifecycle Notes: