Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: notes auf Kubernetes

Ziel: Mit dem Kubernetes-Provider notes auf k3s bringen – Namespace, Secret, Deployment, Service und Ingress –, Drift im Cluster erkennen und bewusst ignorieren, was ein anderer verwaltet. · Dauer: ca. 90 min · Voraussetzung: Tag 5

Briefing

  • Der Kubernetes-Provider spricht mit der API des Clusters. Jede Kubernetes-Art hat eine eigene Ressource: kubernetes_namespace_v1, kubernetes_deployment_v1 … Die Felder heißen wie im YAML, nur in snake_case und als Blöcke.
  • Anders als kubectl apply merkt sich OpenTofu, was es angelegt hat: Löscht du eine Ressource aus dem Code, löscht apply sie im Cluster.
  • kubernetes_deployment_v1 wartet, bis der Rollout fertig ist – ein apply endet erst, wenn die Pods laufen.
  • lifecycle { ignore_changes = [ … ] } lässt Felder in Ruhe, die jemand anderes verwaltet, etwa die Zahl der Replikas bei einem Autoscaler.
 tag06/*.tf ─► Provider kubernetes ─► k3s API
   Namespace notes ─► Secret notes-api ─► Deployment notes-api ─► Service ─► Ingress
                                         http://notes.<VM_IP>.sslip.io (Traefik)

Drill 1: Provider und Namespace

k3s nutzt eine eigene Container-Laufzeit, nicht Docker. Das lokal gebaute Image muss einmal hinüber:

docker save notes-api:0.4.0 | sudo k3s ctr images import - 2>&1 | tail -1 | cut -c1-40
sudo k3s ctr images ls -q | grep notes-api
mkdir -p ~/tf-lab/tag06 && cd ~/tf-lab/tag06
cat > versions.tf <<'EOF'
terraform {
  required_version = ">= 1.13.0"
  required_providers {
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 3.4"
    }
  }
}

provider "kubernetes" {
  config_path = "/etc/rancher/k3s/k3s.yaml"
}
EOF
cat > namespace.tf <<'EOF'
resource "kubernetes_namespace_v1" "notes" {
  metadata {
    name = "notes"
    labels = {
      "app.kubernetes.io/managed-by" = "opentofu"
    }
  }
}
EOF
tofu init -no-color | grep -E 'Installed|initialized'
tofu apply -auto-approve -no-color | grep 'Apply complete'
kubectl get namespace notes --show-labels

Erwartet (Alter weicht ab):

unpacking docker.io/library/notes-api:0.4.0
docker.io/library/notes-api:0.4.0
- Installed hashicorp/kubernetes v3.4.0 (signed, key ID 0C0AF313E5FD9F80)
OpenTofu has been successfully initialized!
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
NAME    STATUS   AGE   LABELS
notes   Active   5s    app.kubernetes.io/managed-by=opentofu,kubernetes.io/metadata.na…

config_path zeigt auf die kubeconfig von k3s. Bei einem Cluster in der Cloud stünden dort Adresse, Zertifikat und Token – oder ein Befehl, der sie holt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Secret und Deployment

cat > variables.tf <<'EOF'
variable "api_key" {
  type      = string
  sensitive = true
  default   = "lab-api-key-123"
}

variable "vm_ip" {
  description = "IP der VM für den Hostnamen <name>.<IP>.sslip.io"
  type        = string
}
EOF
cat > notes.tf <<'EOF'
resource "kubernetes_secret_v1" "api" {
  metadata {
    name      = "notes-api"
    namespace = kubernetes_namespace_v1.notes.metadata[0].name
  }
  data = {
    NOTES_API_KEY = var.api_key
  }
}

resource "kubernetes_deployment_v1" "api" {
  metadata {
    name      = "notes-api"
    namespace = kubernetes_namespace_v1.notes.metadata[0].name
    labels    = { app = "notes-api" }
  }
  spec {
    replicas = 1
    selector {
      match_labels = { app = "notes-api" }
    }
    template {
      metadata {
        labels = { app = "notes-api" }
      }
      spec {
        container {
          name              = "notes-api"
          image             = "notes-api:0.4.0"
          image_pull_policy = "Never"
          port {
            container_port = 8080
          }
          env_from {
            secret_ref {
              name = kubernetes_secret_v1.api.metadata[0].name
            }
          }
          readiness_probe {
            http_get {
              path = "/healthz"
              port = 8080
            }
            period_seconds = 2
          }
          resources {
            requests = { cpu = "50m", memory = "32Mi" }
            limits   = { memory = "64Mi" }
          }
        }
      }
    }
  }
}
EOF
export TF_VAR_vm_ip=$VM_IP
tofu apply -auto-approve -no-color | grep -E 'Creation complete|Apply complete'
kubectl -n notes get pods -l app=notes-api

Erwartet (IDs, Pod-Name und Alter weichen ab):

kubernetes_secret_v1.api: Creation complete after 0s [id=notes/notes-api]
kubernetes_deployment_v1.api: Creation complete after 4s [id=notes/notes-api]
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
NAME                         READY   STATUS    RESTARTS   AGE
notes-api-576b8c9b56-7bq4x   1/1     Running   0          5s
  • image_pull_policy = "Never": Das Image liegt nur lokal in k3s, eine Registry gibt es nicht.
  • Ohne NOTES_DB_URL speichert notes-api im Speicher – für den Anfang genug. Tag 7 bringt Postgres.
  • Der Name der Namespace-Referenz kubernetes_namespace_v1.notes.metadata[0].name sorgt für die richtige Reihenfolge: erst der Namespace, dann alles darin.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Service und Ingress

cat > netz.tf <<'EOF'
resource "kubernetes_service_v1" "api" {
  metadata {
    name      = "notes-api"
    namespace = kubernetes_namespace_v1.notes.metadata[0].name
  }
  spec {
    selector = kubernetes_deployment_v1.api.spec[0].template[0].metadata[0].labels
    port {
      port        = 80
      target_port = 8080
    }
  }
}

resource "kubernetes_ingress_v1" "api" {
  metadata {
    name      = "notes-api"
    namespace = kubernetes_namespace_v1.notes.metadata[0].name
  }
  spec {
    ingress_class_name = "traefik"
    rule {
      host = "notes.${var.vm_ip}.sslip.io"
      http {
        path {
          path      = "/"
          path_type = "Prefix"
          backend {
            service {
              name = kubernetes_service_v1.api.metadata[0].name
              port {
                number = 80
              }
            }
          }
        }
      }
    }
  }
}

output "url" {
  value = "http://notes.${var.vm_ip}.sslip.io"
}
EOF
tofu apply -auto-approve -no-color | grep 'Apply complete'
U=$(tofu output -raw url)
until curl -sf -o /dev/null "$U/healthz"; do sleep 2; done
curl -s -X POST -H "X-API-Key: $NOTES_API_KEY" -H 'Content-Type: application/json' \
  -d '{"text":"aus Kubernetes"}' "$U/notes" | jq -r .text
curl -s "$U/notes" | jq -r '.[].text'

Erwartet:

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
aus Kubernetes
aus Kubernetes

Der Service wählt die Pods über dieselben Labels wie das Deployment – hier direkt aus dessen Spezifikation gelesen, damit beide nie auseinanderlaufen.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Drift und ignore_changes

kubectl -n notes scale deployment notes-api --replicas=3 >/dev/null
tofu plan -no-color | grep -E 'replicas|Plan:'
tofu apply -auto-approve -no-color | grep 'Apply complete'
kubectl -n notes get deployment notes-api -o jsonpath='{.spec.replicas}'; echo

Erwartet:

          ~ replicas                  = "3" -> "1"
Plan: 0 to add, 1 to change, 0 to destroy.
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
1

OpenTofu setzt den Cluster auf den Code zurück. Soll aber ein Autoscaler die Replikas steuern, kämpfen beide gegeneinander. Dann gehört das Feld dem anderen:

printf '  lifecycle {\n    ignore_changes = [spec[0].replicas]\n  }\n' > ignore.txt
sed -i '/^resource "kubernetes_deployment_v1" "api" {$/r ignore.txt' notes.tf
kubectl -n notes scale deployment notes-api --replicas=2 >/dev/null
tofu plan -no-color | grep -E 'Plan:|No changes'

Erwartet:

No changes. Your infrastructure matches the configuration.

ignore_changes gilt nur für Änderungen von außen. Der Startwert aus dem Code wird beim ersten Anlegen trotzdem gesetzt.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Was OpenTofu nicht kennt

kubectl -n notes create configmap von-hand --from-literal=x=1 >/dev/null
tofu plan -no-color | grep -E 'Plan:|No changes'
kubectl -n notes get configmap

Erwartet (Alter weicht ab):

No changes. Your infrastructure matches the configuration.
NAME               DATA   AGE
kube-root-ca.crt   1      10m
von-hand           1      1s

OpenTofu sieht nur, was in seinem State steht. Eine von Hand angelegte ConfigMap im selben Namespace bemerkt es nicht – erst beim Löschen des Namespace verschwindet sie mit. Wer einen Namespace mit OpenTofu verwaltet, sollte darin nichts von Hand anlegen.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

curl -s -o /dev/null -w '%{http_code}\n' "$(tofu output -raw url)/healthz"

Erwartet:

200
tofu state list

Erwartet:

kubernetes_deployment_v1.api
kubernetes_ingress_v1.api
kubernetes_namespace_v1.notes
kubernetes_secret_v1.api
kubernetes_service_v1.api
kubectl -n notes get secret notes-api -o jsonpath='{.data.NOTES_API_KEY}' \
  | base64 -d; echo

Erwartet:

lab-api-key-123

Challenge

Ändere den API-Key auf lab-api-key-456. Das Deployment soll danach neue Pods starten, damit sie den neuen Key lesen – ohne dass du von Hand etwas neu startest.

Hinweis: Pods lesen ein Secret nur beim Start. Eine Annotation am Pod-Template mit einem Hash des Secret-Inhalts (sha256(...)) erzwingt einen Rollout, sobald sich der Inhalt ändert.

Lösung

zeile='        annotations = { "notes/secret-hash" = sha256(var.api_key) }'
echo "$zeile" > hash.txt
sed -i '/^    template {$/{n;r hash.txt
}' notes.tf
tofu fmt >/dev/null
tofu apply -auto-approve -no-color -var api_key=lab-api-key-456 | grep 'Apply complete'
U=$(tofu output -raw url)
until curl -sf -o /dev/null "$U/healthz"; do sleep 2; done
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H "X-API-Key: lab-api-key-456" \
  -H 'Content-Type: application/json' -d '{"text":"neuer Key"}' "$U/notes"
tofu apply -auto-approve -no-color | grep 'Apply complete'

Erwartet:

Apply complete! Resources: 0 added, 2 changed, 0 destroyed.
201
Apply complete! Resources: 0 added, 2 changed, 0 destroyed.

Der zweite Lauf ohne -var setzt den Standard-Key wieder ein – und rollt erneut aus. Ändert sich das Secret, ändert sich der Hash, und Kubernetes startet die Pods neu.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Rohe Ressourcen oder Helm? Der Kubernetes-Provider passt gut für Namespaces, Rechte und Grundausstattung. Anwendungen kommen meist als Helm-Chart (Tag 7) oder per GitOps (Argo CD, Flux).
  • Cluster und Inhalt trennen: Wer den Cluster selbst mit OpenTofu baut, verwaltet dessen Inhalt in einer eigenen Konfiguration. Ein Provider, dessen Zugangsdaten erst im selben Lauf entstehen, führt zu schwer lösbaren Abhängigkeiten.
  • Secrets im State: Der Wert von kubernetes_secret_v1 steht im State im Klartext – ein weiterer Grund für einen verschlüsselten Remote-State (Tag 9).