Zero to Kubernetes Part 1: Infrastructure with Terraform ...

Series: Zero to Kubernetes — Part 1 · Part 2 · Part 3 · Part 4 · Part 5

This is the first part of a 5-part guide where we'll build, from absolute scratch, a full Kubernetes cluster with Terraform, deploy a backend with a database, two independent frontends, and manage everything with GitOps using ArgoCD.

This isn't a "click here and hope" tutorial. We're going to understand every piece. By the end of the series, you'll have a real cluster running in the cloud, with automatic TLS, reproducible deployments, and all the code versioned in GitHub.

What we'll build in Part 1:

3 VMs (1 control-plane + 2 workers) on Hetzner Cloud with Terraform
Private network between VMs, firewalls with Kubernetes ports, SSH keys
containerd as the container runtime on each node
kubeadm init on the control-plane, kubeadm join on the workers
Calico as the CNI (Container Network Interface)
Everything automated via cloud-init — you'll have a cluster in 5 minutes

Why kubeadm and not a managed service?

EKS, GKE, and AKS are excellent. But when you use a managed service, you don't touch the control-plane, you don't see etcd, you don't configure the CNI, you don't understand what happens when a node fails to join the cluster.

kubeadm is Kubernetes' official tool for bootstrapping clusters. It's what platform engineers use. By the end of this series, you'll know exactly what each component does and you'll be able to reproduce this cluster on any provider: Hetzner, AWS EC2, GCP Compute Engine, or your own bare metal.

Infrastructure Architecture

┌──────────────────────────────────────────────────────┐
│                  Hetzner Cloud                        │
│                                                      │
│  ┌─────────────────────┐  ┌──────────┐  ┌──────────┐ │
│  │   control-plane     │  │ worker-0 │  │ worker-1 │ │
│  │   (CX21, 2vCPU/4GB) │  │(CX21)    │  │(CX21)    │ │
│  │                     │  │          │  │          │ │
│  │ api-server          │  │ kubelet  │  │ kubelet  │ │
│  │ etcd                │  │ containerd│ │ containerd│ │
│  │ controller-manager  │  │ Calico   │  │ Calico   │ │
│  │ scheduler           │  │          │  │          │ │
│  │ kubelet             │  │          │  │          │ │
│  │ containerd          │  │          │  │          │ │
│  │ Calico              │  │          │  │          │ │
│  └────────┬────────────┘  └────┬─────┘  └────┬─────┘ │
│           │                    │             │       │
│           └────────────────────┼─────────────┘       │
│                                │                     │
│                    ┌───────────▼───────────┐         │
│                    │   Private Network     │         │
│                    │   (10.0.0.0/16)      │         │
│                    └───────────────────────┘         │
│                                                      │
│   Firewall: SSH(22) + k8s API(6443) + NodePorts      │
│   + Calico networking (179/tcp, 4789/udp)            │
└──────────────────────────────────────────────────────┘

Terraform Project Structure

Create an infra/ directory in your monorepo:

infra/
├── main.tf              # Providers, main resources
├── variables.tf         # Input variables
├── outputs.tf           # Outputs: IPs, kubeconfig
├── terraform.tfvars     # Values (don't commit secrets)
├── versions.tf          # Provider versions
├── cloud-init/
│   ├── control-plane.yaml
│   └── worker.yaml
└── .gitignore

Step 1: Configure Providers and Variables

versions.tf — Lock versions for reproducibility:

terraform {
  required_version = ">= 1.9.0"

  required_providers {
    hcloud = {
      source  = "hetznercloud/hcloud"
      version = "~> 1.47"
    }
    tls = {
      source  = "hashicorp/tls"
      version = "~> 4.0"
    }
  }
}

main.tf — The skeleton:

provider "hcloud" {
  token = var.hcloud_token
}

# Private network
resource "hcloud_network" "k8s" {
  name     = "k8s-network"
  ip_range = "10.0.0.0/16"
}

resource "hcloud_network_subnet" "k8s" {
  network_id   = hcloud_network.k8s.id
  type         = "cloud"
  network_zone = "eu-central"
  ip_range     = "10.0.1.0/24"
}

Step 2: SSH Keys

resource "tls_private_key" "k8s" {
  algorithm = "ED25519"
}

resource "hcloud_ssh_key" "k8s" {
  name       = "k8s-cluster-key"
  public_key = tls_private_key.k8s.public_key_openssh
}

Terraform stores the private key in state. Extract it with terraform output -raw ssh_private_key.

Step 3: Firewall with Exact Kubernetes Ports

Don't open everything. Kubernetes needs specific ports:

resource "hcloud_firewall" "k8s" {
  name = "k8s-firewall"

  # SSH from any IP (use your fixed IP for production)
  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "22"
    source_ips = ["0.0.0.0/0"]
  }

  # Kubernetes API (control-plane)
  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "6443"
    source_ips = ["0.0.0.0/0"]
  }

  # NodePort range (30000-32767 for ingress and services)
  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "30000-32767"
    source_ips = ["0.0.0.0/0"]
  }

  # Calico BGP (179/tcp) and VXLAN (4789/udp)
  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "179"
    source_ips = ["10.0.0.0/16"]
  }
  rule {
    direction  = "in"
    protocol   = "udp"
    port       = "4789"
    source_ips = ["10.0.0.0/16"]
  }

  # Full internal communication between cluster nodes
  rule {
    direction  = "in"
    protocol   = "tcp"
    port       = "10250-10256"
    source_ips = ["10.0.0.0/16"]
  }
}

What each port is for:

6443 → API server. kubectl and kubeadm talk to this endpoint
30000-32767 → NodePort range. The nginx ingress exposes itself here until we have a LoadBalancer
179/tcp → Calico BGP to share routes between nodes
4789/udp → Calico VXLAN to encapsulate pod traffic between nodes
10250 → Kubelet API (logs, exec, metrics)
10256 → kube-proxy health check
10257-10259 → Controller manager and scheduler (control-plane only)

Step 4: The VMs — the Heart of the Cluster

# Control-plane
resource "hcloud_server" "control_plane" {
  name        = "k8s-control-plane"
  server_type = "cx21"
  image       = "ubuntu-24.04"
  location    = "nbg1"
  ssh_keys    = [hcloud_ssh_key.k8s.id]
  firewall_ids = [hcloud_firewall.k8s.id]

  network {
    network_id = hcloud_network.k8s.id
    ip         = "10.0.1.10"
  }

  user_data = templatefile("${path.module}/cloud-init/control-plane.yaml", {
    pod_network_cidr = "192.168.0.0/16"
  })

  depends_on = [hcloud_network_subnet.k8s]
}

# Workers
resource "hcloud_server" "worker" {
  count = 2

  name         = "k8s-worker-${count.index}"
  server_type  = "cx21"
  image        = "ubuntu-24.04"
  location     = "nbg1"
  ssh_keys     = [hcloud_ssh_key.k8s.id]
  firewall_ids = [hcloud_firewall.k8s.id]

  network {
    network_id = hcloud_network.k8s.id
    ip         = "10.0.1.${20 + count.index}"
  }

  user_data = templatefile("${path.module}/cloud-init/worker.yaml", {
    control_plane_ip = "10.0.1.10"
  })

  depends_on = [hcloud_server.control_plane]
}

Step 5: cloud-init — The Magic That Automates Everything

This is where the actual Kubernetes installation happens. cloud-init runs these scripts on the first boot of each VM.

cloud-init/control-plane.yaml:

#cloud-config
hostname: control-plane
package_update: true
package_upgrade: true

packages:
  - containerd
  - apt-transport-https
  - ca-certificates
  - curl
  - gnupg

write_files:
  - path: /etc/containerd/config.toml
    permissions: '0644'
    content: |
      version = 2
      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
        runtime_type = "io.containerd.runc.v2"
        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
          SystemdCgroup = true

  - path: /etc/modules-load.d/k8s.conf
    content: |
      overlay
      br_netfilter

  - path: /etc/sysctl.d/k8s.conf
    content: |
      net.bridge.bridge-nf-call-iptables  = 1
      net.bridge.bridge-nf-call-ip6tables = 1
      net.ipv4.ip_forward                 = 1

runcmd:
  - modprobe overlay
  - modprobe br_netfilter
  - sysctl --system
  - swapoff -a
  - sed -i '/swap/d' /etc/fstab
  - systemctl restart containerd
  - systemctl enable containerd

  # Install kubeadm, kubelet, kubectl
  - |
    curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /" > /etc/apt/sources.list.d/kubernetes.list
    apt-get update
    apt-get install -y kubelet kubeadm kubectl
    apt-mark hold kubelet kubeadm kubectl

  # Initialize the cluster
  - |
    kubeadm init \
      --pod-network-cidr=${pod_network_cidr} \
      --apiserver-advertise-address=10.0.1.10 \
      --upload-certs \
      | tee /root/kubeadm-init.log

  # Configure kubeconfig for root
  - mkdir -p /root/.kube
  - cp /etc/kubernetes/admin.conf /root/.kube/config

  # Install Calico
  - |
    kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.1/manifests/tigera-operator.yaml --kubeconfig=/etc/kubernetes/admin.conf
    kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.1/manifests/custom-resources.yaml --kubeconfig=/etc/kubernetes/admin.conf

  # Generate join token for workers
  - kubeadm token create --print-join-command > /root/join-command.sh
  - chmod 644 /root/join-command.sh

final_message: "Control-plane bootstrap completed in $UPTIME seconds"

cloud-init/worker.yaml:

#cloud-config
hostname: worker
package_update: true
package_upgrade: true

packages:
  - containerd
  - apt-transport-https
  - ca-certificates
  - curl
  - gnupg

write_files:
  - path: /etc/containerd/config.toml
    permissions: '0644'
    content: |
      version = 2
      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
        runtime_type = "io.containerd.runc.v2"
        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
          SystemdCgroup = true

  - path: /etc/modules-load.d/k8s.conf
    content: |
      overlay
      br_netfilter

  - path: /etc/sysctl.d/k8s.conf
    content: |
      net.bridge.bridge-nf-call-iptables  = 1
      net.bridge.bridge-nf-call-ip6tables = 1
      net.ipv4.ip_forward                 = 1

runcmd:
  - modprobe overlay
  - modprobe br_netfilter
  - sysctl --system
  - swapoff -a
  - sed -i '/swap/d' /etc/fstab
  - systemctl restart containerd
  - systemctl enable containerd

  # Install kubeadm, kubelet, kubectl
  - |
    curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /" > /etc/apt/sources.list.d/kubernetes.list
    apt-get update
    apt-get install -y kubelet kubeadm kubectl
    apt-mark hold kubelet kubeadm kubectl

final_message: "Worker bootstrap completed in $UPTIME seconds. Run join command after control-plane init."

Step 6: Joining Workers to the Cluster

Since the join command is generated on the control-plane during bootstrap, workers need to retrieve it after. Use a null_resource in Terraform or do it manually the first time:

# From your local machine, after terraform apply:
scp root@<control-plane-ip>:/root/join-command.sh .
scp join-command.sh root@<worker-0-ip>:/root/
ssh root@<worker-0-ip> "bash /root/join-command.sh"
# Repeat for worker-1

In production, this is automated with Vault or a shared S3 bucket. For the tutorial, this 2-minute manual step is enough and lets you see exactly what happens.

Step 7: Verification

$ terraform apply
# ... (2-3 minutes to create VMs + cloud-init)

$ ssh root@<control-plane-ip>

root@control-plane:~# kubectl get nodes
NAME               STATUS   ROLES           AGE   VERSION
k8s-control-plane  Ready    control-plane   5m    v1.31.0
k8s-worker-0       Ready    <none>          2m    v1.31.0
k8s-worker-1       Ready    <none>          2m    v1.31.0

root@control-plane:~# kubectl get pods -A
NAMESPACE          NAME                                      READY   STATUS    RESTARTS   AGE
calico-system      calico-kube-controllers-xxxxx             1/1     Running   0          4m
calico-system      calico-node-xxxxx                         1/1     Running   0          4m
calico-system      calico-node-xxxxx                         1/1     Running   0          2m
calico-system      calico-node-xxxxx                         1/1     Running   0          2m
kube-system        coredns-xxxxx                             1/1     Running   0          5m
kube-system        coredns-xxxxx                             1/1     Running   0          5m
kube-system        etcd-control-plane                        1/1     Running   0          5m
kube-system        kube-apiserver-control-plane              1/1     Running   0          5m
kube-system        kube-controller-manager-control-plane     1/1     Running   0          5m
kube-system        kube-proxy-xxxxx                          1/1     Running   0          5m
kube-system        kube-scheduler-control-plane              1/1     Running   0          5m

Three nodes Ready, all system pods running. Cluster is live.

Terraform Outputs

output "control_plane_ip" {
  value = hcloud_server.control_plane.ipv4_address
}

output "worker_ips" {
  value = [for w in hcloud_server.worker : w.ipv4_address]
}

output "ssh_private_key" {
  value     = tls_private_key.k8s.private_key_pem
  sensitive = true
}

Real Costs

Resource	Monthly Price
3× CX21 (2vCPU, 4GB RAM, 40GB SSD)	€11.97
Private network	€0.00
Firewall	€0.00
Traffic (20TB included)	€0.00
Total	≈ €12/month

Under $13 USD per month for a real Kubernetes cluster with a dedicated control-plane. Compare with EKS charging $0.10/hour just for the control-plane ($72/month) plus the VMs separately.

What You Learned in This Part

Professional Terraform project structure for Kubernetes
Exact ports Kubernetes needs (and why each one)
cloud-init as a bootstrap automation tool
containerd as the container runtime (not Docker — Kubernetes deprecated Docker in v1.24)
kubeadm init and critical flags (pod-network-cidr, advertise-address)
Calico as the CNI for pod networking between nodes
The control-plane + workers concept and what runs on each

In Part 2, we'll take this empty cluster and turn it into a production-ready platform: namespaces, ingress controller with automatic TLS, persistent storage, and RBAC. All with Terraform, zero manual kubectl apply.

At Guayoyo Tech, we design and deploy Kubernetes architectures like this for real companies. Terraform, kubeadm, GitOps, CI/CD — we build it with you, no hype, no vendor lock-in. Want your infrastructure to look like what you just read? Talk to us free for 15 minutes. Your cluster, your cloud, your rules — we bring the engineering.

推荐订阅源

DEV Community