Terraform Hetzner Cloud K8s

Hetzner Infrastructure Architecture

flowchart TD
    subgraph External ["External Access & Clients"]
        User["<i class='fas fa-user'></i> Developers / kubectl / Clients"]
        GitLabCI["<i class='fab fa-gitlab'></i> GitLab CI/CD Pipeline"]
    end

    subgraph HcloudInfra ["Hetzner Cloud Infrastructure (hcloud)"]
        direction TB

        subgraph EdgeSecurity ["Edge Security & Load Balancing Layer"]
            Firewall["<i class='fas fa-shield-alt'></i> Hetzner Cloud Firewall<br/><small>hcloud_firewall (Only 6443/80/443 Allowed)</small>"]:::accent
            HLB["<i class='fas fa-network-wired'></i> Hetzner Cloud Load Balancer<br/><small>hcloud_load_balancer (Static Public IP)</small>"]:::accent
        end

        subgraph PrivateNet ["Isolated Private Subnet (hcloud_network: 10.0.0.0/16)"]
            direction TB
            
            subgraph ControlPlane ["Control Plane HA (Spread Placement Group: hcloud_placement_group)"]
                direction LR
                CP1["<b>Control Plane 1 (nbg1)</b><br/><small>cpx31 (10.0.1.11)</small>"]:::boxNode
                CP2["<b>Control Plane 2 (fsn1)</b><br/><small>cpx31 (10.0.1.12)</small>"]:::boxNode
                CP3["<b>Control Plane 3 (hel1)</b><br/><small>cpx31 (10.0.1.13)</small>"]:::boxNode
            end

            subgraph StorageLayer ["State Persistence & Storage Layer"]
                direction LR
                Vol1["<b>hcloud_volume 1</b><br/><small>etcd Datastore</small>"]
                Vol2["<b>hcloud_volume 2</b><br/><small>etcd Datastore</small>"]
                Vol3["<b>hcloud_volume 3</b><br/><small>etcd Datastore</small>"]
                ExtDB["<b>External DB</b><br/><small>PostgreSQL Node</small>"]
            end

            subgraph Workers ["Worker Node Pools (hcloud_server_network)"]
                direction LR
                Worker1["<b>Worker Node 1</b><br/><small>cx22 / cpx31 (10.0.1.21)</small>"]:::boxNode
                Worker2["<b>Worker Node 2</b><br/><small>cx22 / cpx31 (10.0.1.22)</small>"]:::boxNode
            end

            subgraph CloudDrivers ["Hetzner Native Cloud Drivers"]
                direction LR
                HCCM["<b>Hetzner CCM Driver</b><br/><small>Private IP Auto-Discovery</small>"]:::accent
                HCSI["<b>Hetzner CSI Driver</b><br/><small>Dynamic PVC Provisioning</small>"]:::accent
            end
        end
    end

    User --> Firewall
    GitLabCI --> Firewall
    Firewall --> HLB
    HLB -->|"Private LB Health Checks (10.0.1.X)"| CP1

    CP1 --- Vol1
    CP2 --- Vol2
    CP3 --- Vol3
    CP1 --> ExtDB

    CP1 --- Worker1
    CP2 --- Worker2
    HCCM --> CP1
    HCSI --> CP1

    classDef accent fill:#1f2630,stroke:#f97316,stroke-width:2px,color:#f97316;
    classDef boxNode fill:#232a33,stroke:#313a44,stroke-width:1.5px,color:#f5f7fa;

Infrastructure Architectural Design Pillars

1. Hardware Fault Tolerance with Spread Placement Groups (hcloud_placement_group):

   • Control plane nodes use type = "spread" placement groups. Hetzner Cloud guarantees control plane instances are hosted on physically separate hypervisor hardware frames, preventing single-point hardware failures.

2. Isolated Private Network Topology (hcloud_network & hcloud_subnetwork):

   • All cluster nodes communicate strictly over an encrypted, high-speed Hetzner Private Subnet (10.0.0.0/16).
   • Cluster internal traffic (CNI overlay, etcd quorum ports 2379-2380, Kubelet 10250) is kept off public interfaces and isolated within 10.0.1.X.

3. Edge Security & Strict Firewall Rules (hcloud_firewall):

   • Public node interfaces are locked down using Hetzner Cloud Firewalls.
   • Public ingress is restricted strictly to necessary API ports (6443) on the Load Balancer and standard HTTP/HTTPS (80/443) ingress controllers.

4. Dedicated Load Balancer Target Pools (hcloud_load_balancer_target):

   • Hetzner Load Balancer proxies incoming Kubernetes API and workload traffic directly to node private IPs (10.0.1.X), automatically setting tls-san and node-ip for secure external kubectl access.

5. Hetzner Native Cloud Controller (CCM) & Storage (CSI) Integration:

   • Hetzner CCM (hcloud-cloud-controller-manager): Auto-discovers server private IPs, routes, and external load balancers natively within Kubernetes.
   • Hetzner CSI (hcloud-csi-driver): Enables Kubernetes Persistent Volume Claims (PVCs) to dynamically provision and attach high-performance Hetzner Block Storage volumes.

6. Multi-Datacenter Geo-Redundancy:

   • Supports distributing control plane nodes and worker pools across Hetzner Cloud datacenters in Nuremberg (nbg1), Falkenstein (fsn1), Helsinki (hel1), and Ashburn (ash).