Deploy and manage Kubernetes clusters on Hetzner Cloud using Talos Linux, powered by Golang Pulumi. This project provides reusable infrastructure code to provision, configure, and manage experimental-grade Kubernetes clusters on Hetzner.
- Automated Cluster Provisioning: Use Pulumi (in Go) to declaratively manage Hetzner resources and Talos-based Kubernetes clusters.
- Customizable Node Pools: Define control plane and worker node pools with flexible sizing and configuration.
- Infrastructure as Code: All cluster resources, networking, and firewall rules are managed in code.
- Go Package Distribution: This project is distributed as a Go library that can be updated via
go modcommands, with automated dependency management through tools like Dependabot or Renovate Bot. - Makefile Automation: Common tasks (build, lint, test, deploy) are automated via
make. - Talos Image Creation: Uses hcloud-upload-image to create and upload Talos images to Hetzner Cloud.
This experimental project comes with pre-configured Kubernetes components that integrate with Hetzner Cloud. While functional, these components are designed for testing and development environments:
- 🚀 Cluster Autoscaler: Automatically scales worker nodes based on pod resource demands, with configurable min/max limits and utilization thresholds
- 📊 Kubernetes Metrics Server: Provides container resource metrics for Horizontal Pod Autoscaling (HPA) and other autoscaling pipelines
- 🔐 Kubelet Serving Certificate Approver: Automatically approves kubelet serving certificates for secure metrics collection
- ☁️ Hetzner Cloud Controller Manager (CCM): Native integration for Hetzner load balancers, volumes, and networking
- 💾 Hetzner CSI Driver: Persistent volume support with encryption, configurable storage classes, and automatic volume provisioning
- 🔥 Firewall Management: Automated firewall rules for cluster communication and optional public API access
- 📦 Longhorn Distributed Storage (Optional): Cloud-native distributed block storage with replication, snapshots, and backup capabilities when enabled in configuration
- 🔒 etcd Encryption at Rest: Optional Kubernetes secrets encryption using secretbox encryption
- 🌐 Private Networking: VPC with custom subnets, private IPs, and secure inter-node communication
- 🔧 Custom Registry Support: Configure private container registries with authentication and TLS
- ⚖️ Multi-Region Control Plane: Deploy control plane nodes across multiple Hetzner regions for maximum availability
- 🔄 Control Plane Placement Groups: Anti-affinity rules ensure control plane nodes are distributed across different physical hosts (worker nodes do not use placement groups)
- 🎯 Control Plane Load Balancer: Highly available Kubernetes API server with automatic failover
- 📋 Node Taints & Labels: Flexible workload scheduling with custom node labeling and tainting
- 🏗️ ARM64 & AMD64: Full support for both x86_64 and ARM64 architectures with automatic image selection
- 🖼️ Talos Image Factory: Automatic building and uploading of architecture-specific Talos images
All Helm chart components are configured with sensible defaults but remain fully customizable through Helm values and configuration overrides.
This guide helps you get started with a new Hetzner Talos Kubernetes cluster using the Cookiecutter template.
Optional:
- k9s (Kubernetes CLI UI)
# Install all required tools
brew install cookiecutter
brew install go
brew install pulumi/tap/pulumi
brew install siderolabs/tap/talosctl
# Verify installations
go version
pulumi version
talosctl version --clientFor Linux users, please refer to the official installation guides:
💡 Recommendation: Use a dedicated Hetzner Cloud project for each cluster deployment to ensure proper resource isolation.
# Navigate to your desired parent directory (e.g., ~/projects or ~/dev)
cd ~/projects
# Generate the new project using cookiecutter
# This will execute a configuration wizard where you can customize your cluster setup
cookiecutter https://github.com/exivity/pulumi-hcloud-k8sThe cookiecutter command will launch an interactive wizard that guides you through configuring your cluster. You'll be prompted to set options like project name, Kubernetes version, node pool configuration, and enabled components. For a complete list of all available options and their descriptions, see the Cookiecutter Template Options documentation.
Navigate into the newly created project directory:
cd <your-project-slug>Execute the initial deployment to create the Kubernetes cluster and node pools:
pulumi up --yesNote: The deployment consists of two phases:
- Infrastructure Phase: Creates Hetzner Cloud resources, Talos cluster, and node pools
- Kubernetes Phase: Installs applications and Helm charts on the cluster
The first deployment will fail during the Kubernetes phase because the cluster needs time to fully boot and become ready. This is expected behavior since there's no built-in check to wait for cluster readiness.
After the first deployment completes (with failures), wait a few minutes for the cluster to fully initialize, then run the deployment again to install the Kubernetes applications:
pulumi up --yesExport kubeconfig and talosconfig:
make kubeconfig
make talosconfigAccess the cluster using k9s:
make k9sSee Configuration for all available configuration options and Architecture for system design details.
main.go— Pulumi entrypoint (cluster definition)pkg/— Go packages for Hetzner, Talos, and Kubernetes resource abstractionsMakefile— Automation for build, test, lint, and deploymentdocs/— Documentation and diagrams
Note: This project is under active development. Pulumi stack configuration files are included for development purposes and may be removed in future releases. Contributions and feedback are welcome!