Explanation

Why Kube-Hetzner?

Type: Explanation (Understanding-oriented)

Related Concepts: Infrastructure as Code | Tutorial: First Deployment

This document explains the architectural decisions behind using the kube-hetzner community project for our Kubernetes infrastructure.

The Migration Story

From Docker Swarm to Kubernetes

Our previous infrastructure ran on a single server with Docker Swarm orchestrating all services. While this worked initially, it had significant limitations:

  • Single Point of Failure: One server failure meant complete downtime

  • No Redundancy: No backup nodes if the primary failed

  • Limited Scalability: Vertical scaling only (bigger server, not more servers)

  • Reduced Isolation: All services sharing the same host resources

After gaining practical experience with Kubernetes in various projects, we recognized it as the solution to these problems. Kubernetes provides:

  • High Availability: Multiple nodes ensure service continuity

  • Horizontal Scaling: Add more nodes as demand grows

  • Better Isolation: Namespaces and resource quotas per application

  • Declarative Infrastructure: GitOps-style configuration management

Why Hetzner Cloud?

We’ve been satisfied Hetzner customers since the early days of the company. Hetzner provides:

  • Excellent Price-to-Performance Ratio: Competitive pricing for compute resources

  • European Data Centers: All infrastructure in EU (compliance-friendly)

  • Transparent Pricing: No hidden costs, clear billing

  • Reliable Infrastructure: Proven track record of uptime

  • ARM64 Support: CAX instances provide cost-effective ARM nodes

Why Not Managed Kubernetes?

Hetzner doesn’t offer an official managed Kubernetes service. The alternatives were:

  1. Other Cloud Providers (GKE, EKS, AKS)

    • Higher costs for equivalent resources

    • Vendor lock-in concerns

    • Learning curve for provider-specific APIs

  2. Self-Managed Kubernetes (kubeadm, Rancher, etc.)

    • Complex setup and maintenance

    • Manual upgrade procedures

    • More operational overhead

  3. Community Project: Kube-Hetzner ✅

    • Automated cluster provisioning via OpenTofu

    • Active community and regular updates

    • Best of both worlds: automation + flexibility

What is Kube-Hetzner?

Kube-Hetzner is a community-maintained OpenTofu/Terraform module that automates Kubernetes cluster deployment on Hetzner Cloud.

What It Provides

The kube-hetzner module handles:

  1. Machine Provisioning

    • Automated server creation on Hetzner Cloud

    • Placement groups for high availability

    • Network and firewall configuration

  2. OS and Kubernetes Installation

    • openSUSE MicroOS as the base OS (minimal, immutable, auto-updating)

    • K3S as the Kubernetes distribution (lightweight, production-ready)

    • Automatic node configuration and cluster bootstrapping

  3. Infrastructure Components

    • Networking: Cilium CNI with WireGuard encryption

    • Storage: Longhorn for persistent volumes, Hetzner CSI for block storage

    • Ingress: Traefik with automatic Let’s Encrypt certificates

    • Load Balancer: Hetzner Cloud Load Balancer integration

  4. Extensibility

    • Kustomize support for additional manifests

    • Helm chart deployment via HelmChart CRDs

    • Custom configuration via OpenTofu variables

Why K3S?

K3S is a certified Kubernetes distribution designed for production workloads with:

  • Lightweight: Single binary, minimal dependencies

  • Production-Ready: CNCF certified, API-compatible with upstream Kubernetes

  • Built-in Components: Traefik ingress, local-path provisioner, CoreDNS

  • Edge-Friendly: Efficient resource usage, perfect for ARM nodes

Why openSUSE MicroOS?

MicroOS is designed for containerized workloads:

  • Immutable: Root filesystem is read-only (increased security)

  • Transactional Updates: System updates are atomic and can be rolled back

  • Minimal Attack Surface: Only essential packages installed

  • Auto-Updates: Automatic security patching with kured (reboots during maintenance windows)

Our Infrastructure Design

Multi-Architecture Strategy

We run a mixed ARM64/AMD64 cluster:

Control Plane Nodes (ARM64):

  • 3x CAX21 (4 vCPU, 8GB RAM, 80GB disk)

  • Locations: Falkenstein (fsn1), Nuremberg (nbg1), Helsinki (hel1)

  • High availability across data centers

Agent Nodes (Mixed):

  • ARM64 Primary: 1x CAX31 + 3x CAX21 (cost-effective for web workloads)

  • AMD64 Legacy: 1x CPX31 + 1x CPX21 (for x86-only applications during migration)

Rationale:

  • ARM nodes provide 20-30% better price-to-performance for CPU-bound workloads

  • Most container images support multi-arch (automatic platform detection)

  • AMD64 nodes available for legacy applications during transition

Additional Infrastructure Components

Beyond what kube-hetzner provides, we’ve added:

  • Crossplane: Manages S3 buckets as Kubernetes resources

  • CloudNativePG (CNPG): PostgreSQL database operator

  • ArgoCD: GitOps continuous deployment

  • External Secrets Operator (ESO): Centralized secret management

  • kube-prometheus-stack: Prometheus, Grafana, Alertmanager

  • Loki: Log aggregation with S3 storage

  • SMB CSI Driver: Integration with Hetzner Storage Boxes

These components are deployed via kube-hetzner’s extra-manifests feature, treating them as infrastructure-tier components.

Benefits Realized

After migrating to kube-hetzner, we’ve achieved:

✅ High Availability: Control plane spread across 3 data centers ✅ Scalability: Horizontal scaling by adding agent nodes ✅ Cost Efficiency: ARM nodes reduce compute costs by ~25% ✅ Declarative Infrastructure: All configuration in Git, applied via OpenTofu ✅ Automated Updates: OS and Kubernetes updates handled automatically ✅ GitOps Workflows: Application deployments via ArgoCD ✅ Better Isolation: Namespaces and resource quotas per application ✅ Simplified Operations: Less manual intervention required

Trade-offs and Considerations

Advantages vs Managed Kubernetes

Advantages:

  • Lower costs (no management fees)

  • Full control over cluster configuration

  • No vendor lock-in to proprietary APIs

  • Learning opportunity for Kubernetes operations

Considerations:

  • We’re responsible for cluster upgrades

  • Need to monitor community project for updates

  • Limited support (community forums vs paid support)

When Kube-Hetzner Makes Sense

Kube-Hetzner is ideal when you:

  • Want Kubernetes on Hetzner Cloud

  • Have basic Kubernetes operational knowledge

  • Value cost optimization over managed convenience

  • Need infrastructure-as-code workflows

  • Want multi-data-center high availability

When to Consider Alternatives

Consider managed Kubernetes if you:

  • Lack Kubernetes expertise in-house

  • Need enterprise SLA guarantees

  • Require 24/7 vendor support

  • Want zero operational overhead

  • Have compliance requirements for managed services

Community and Ecosystem

The kube-hetzner project benefits from:

  • Active Development: Regular updates for new K3S and Hetzner features

  • Community Support: GitHub discussions, issue tracking

  • Documentation: Comprehensive README and examples

  • Production Usage: Many companies running production workloads

  • Transparency: Open source, auditable code

Conclusion

Kube-Hetzner provides a practical middle ground between fully managed Kubernetes and DIY cluster management. For teams with Kubernetes knowledge who value cost efficiency and infrastructure control, it’s an excellent choice.

The combination of:

  • Hetzner Cloud’s competitive pricing

  • openSUSE MicroOS’s security and stability

  • K3S’s production-readiness

  • kube-hetzner’s automation

…creates a robust, cost-effective Kubernetes platform that scales with our needs while remaining manageable with a small operations team.

Further Reading