Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 11: Kubernetes mit client-go – podwatch

Ziel: Mit client-go Pods auflisten und per Informer beobachten, CrashLoops und Neustarts als Tabelle melden – komplett ohne Cluster getestet · Dauer: ca. 120 min · Voraussetzung: Tag 9

Briefing

  • kubernetes.Interface ist der typisierte Client – echt (NewForConfig) oder Fake (fake.NewClientset).
  • List holt einmal alle Pods; ein Informer macht List + Watch und hält einen lokalen Cache.
  • Die Prüflogik ist eine reine Funktion auf *corev1.Pod – testbar ohne API-Server.
  • kubeconfig wird wie bei kubectl gelesen: Flag, $KUBECONFIG, ~/.kube/config.
  • Exit-Code 1 bei Funden, 2 bei Fehlern – gut für Skripte und CI.
kubeconfig --> clientcmd --> kubernetes.Interface <-- fake.NewClientset (Tests)
                                  |
                 List (Scan) -----+----- Informer (Watch)
                                  v
                    Inspect(*Pod) -> []Finding -> Tabelle / Zeile

Drill 1: Modul anlegen

mkdir -p ~/go-lab/tag11-podwatch/{cmd/podwatch,internal/pods}
cd ~/go-lab/tag11-podwatch
go mod init example.com/podwatch
go get k8s.io/[email protected] k8s.io/[email protected] k8s.io/[email protected]
cat > .golangci.yml <<'EOF'
version: "2"
linters:
  exclusions:
    presets: [std-error-handling] # fmt.Fprint*, Close & Co. nicht anmahnen
EOF

Erwartet (gekürzt):

go: creating new go.mod: module example.com/podwatch
go: added k8s.io/api v0.37.1
go: added k8s.io/apimachinery v0.37.1
go: added k8s.io/client-go v0.37.1

Warum? client-go, api und apimachinery immer mit derselben Minor-Version pinnen; v0.37 passt zu Kubernetes 1.37. Gegen etwas ältere Cluster funktioniert der Client in der Regel trotzdem. Die .golangci.yml kennst du aus Tag 5.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Pod-Status prüfen

Die Kernlogik kennt keinen Client – nur den Pod-Typ aus k8s.io/api/core/v1.

cat > internal/pods/inspect.go <<'EOF'
// Package pods findet Pods mit CrashLoops, OOMKills und vielen Neustarts.
package pods

import (
    corev1 "k8s.io/api/core/v1"
)

// Finding ist ein auffälliger Container.
type Finding struct {
    Namespace string
    Pod       string
    Container string
    Reason    string
    Restarts  int32
}

// Inspect prüft alle Container eines Pods.
func Inspect(p *corev1.Pod, minRestarts int32) []Finding {
    var out []Finding
    for _, cs := range p.Status.ContainerStatuses {
        reason := ""
        switch {
        case cs.State.Waiting != nil &&
            cs.State.Waiting.Reason == "CrashLoopBackOff":
            reason = "CrashLoopBackOff"
        case cs.LastTerminationState.Terminated != nil &&
            cs.LastTerminationState.Terminated.Reason == "OOMKilled":
            reason = "OOMKilled"
        case cs.RestartCount >= minRestarts:
            reason = "Restarts"
        }
        if reason != "" {
            out = append(out, Finding{p.Namespace, p.Name, cs.Name,
                reason, cs.RestartCount})
        }
    }
    return out
}
EOF

Ein Helfer baut Test-Pods; die Tabelle deckt jeden Zweig im switch ab.

cat > internal/pods/inspect_test.go <<'EOF'
package pods

import (
    "testing"

    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// pod baut einen Test-Pod mit einem Container "app".
func pod(name string, restarts int32, waiting, lastTerm string) *corev1.Pod {
    cs := corev1.ContainerStatus{Name: "app", RestartCount: restarts}
    if waiting != "" {
        cs.State.Waiting = &corev1.ContainerStateWaiting{Reason: waiting}
    }
    if lastTerm != "" {
        cs.LastTerminationState.Terminated =
            &corev1.ContainerStateTerminated{Reason: lastTerm}
    }
    return &corev1.Pod{
        ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: "shop"},
        Status: corev1.PodStatus{
            ContainerStatuses: []corev1.ContainerStatus{cs}},
    }
}

func TestInspect(t *testing.T) {
    tests := []struct {
        name string
        pod  *corev1.Pod
        want string // "" = kein Finding
    }{
        {"gesund", pod("web", 0, "", ""), ""},
        {"crashloop", pod("api", 7, "CrashLoopBackOff", "Error"),
            "CrashLoopBackOff"},
        {"oom", pod("db", 1, "", "OOMKilled"), "OOMKilled"},
        {"viele restarts", pod("job", 5, "", "Completed"), "Restarts"},
        {"knapp darunter", pod("job", 2, "", "Completed"), ""},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := Inspect(tt.pod, 3)
            if tt.want == "" {
                if len(got) != 0 {
                    t.Fatalf("unerwartet: %+v", got)
                }
                return
            }
            if len(got) != 1 || got[0].Reason != tt.want {
                t.Fatalf("got %+v, want Reason %q", got, tt.want)
            }
        })
    }
}
EOF
go mod tidy
go test -v ./internal/pods

Erwartet (gekürzt):

--- PASS: TestInspect (0.00s)
    --- PASS: TestInspect/gesund (0.00s)
    --- PASS: TestInspect/crashloop (0.00s)
    --- PASS: TestInspect/oom (0.00s)
    --- PASS: TestInspect/viele_restarts (0.00s)
    --- PASS: TestInspect/knapp_darunter (0.00s)
ok      example.com/podwatch/internal/pods  0.169s

Warum? Die Reihenfolge im switch ist Absicht: Ein CrashLoop ist wichtiger als die reine Zahl der Neustarts. go mod tidy ist nach neuen Imports Pflicht – sonst fehlen transitive Einträge in go.sum.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Pods auflisten mit dem Fake-Clientset

Scan nimmt das Interface, nicht den konkreten Typ – deshalb passt der Fake.

cat > internal/pods/scan.go <<'EOF'
package pods

import (
    "context"
    "fmt"
    "io"
    "sort"
    "text/tabwriter"

    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes"
)

// Scan listet Pods einmalig ("" = alle Namespaces) und prüft sie.
func Scan(ctx context.Context, cs kubernetes.Interface, ns string,
    minRestarts int32) ([]Finding, error) {
    list, err := cs.CoreV1().Pods(ns).List(ctx, metav1.ListOptions{})
    if err != nil {
        return nil, fmt.Errorf("pods auflisten: %w", err)
    }
    var out []Finding
    for i := range list.Items {
        out = append(out, Inspect(&list.Items[i], minRestarts)...)
    }
    sort.Slice(out, func(i, j int) bool { return out[i].Restarts > out[j].Restarts })
    return out, nil
}

// Print schreibt die Findings als ausgerichtete Tabelle.
func Print(w io.Writer, fs []Finding) error {
    tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
    fmt.Fprintln(tw, "NAMESPACE\tPOD\tCONTAINER\tGRUND\tRESTARTS")
    for _, f := range fs {
        fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%d\n",
            f.Namespace, f.Pod, f.Container, f.Reason, f.Restarts)
    }
    return tw.Flush()
}
EOF

fake.NewClientset nimmt beliebige Objekte als Startzustand des In-Memory-API-Servers.

cat > internal/pods/scan_test.go <<'EOF'
package pods

import (
    "bytes"
    "context"
    "strings"
    "testing"

    "k8s.io/client-go/kubernetes/fake"
)

func TestScanAndPrint(t *testing.T) {
    cs := fake.NewClientset(
        pod("web", 0, "", ""),
        pod("api", 7, "CrashLoopBackOff", "Error"),
        pod("db", 1, "", "OOMKilled"),
    )
    fs, err := Scan(context.Background(), cs, "", 3)
    if err != nil {
        t.Fatal(err)
    }
    if len(fs) != 2 || fs[0].Pod != "api" {
        t.Fatalf("got %+v", fs)
    }
    var buf bytes.Buffer
    if err := Print(&buf, fs); err != nil {
        t.Fatal(err)
    }
    t.Log("\n" + buf.String())
    if !strings.Contains(buf.String(), "shop       api  app        CrashLoopBackOff") {
        t.Errorf("Tabelle passt nicht:\n%s", buf.String())
    }
}
EOF
go mod tidy
go test -v -run TestScan ./internal/pods

Erwartet:

=== RUN   TestScanAndPrint
    scan_test.go:29:
        NAMESPACE  POD  CONTAINER  GRUND             RESTARTS
        shop       api  app        CrashLoopBackOff  7
        shop       db   app        OOMKilled         1

--- PASS: TestScanAndPrint (0.03s)
ok      example.com/podwatch/internal/pods  0.306s

Warum? NewClientset ist der neuere Konstruktor und kann zusätzlich Server-Side Apply; NewSimpleClientset siehst du in älteren Beispielen. text/tabwriter richtet Spalten aus wie kubectl get.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Beobachten mit einem Informer

Ein Informer listet einmal und hält danach eine Watch-Verbindung offen. Du hängst nur Handler an.

cat > internal/pods/watch.go <<'EOF'
package pods

import (
    "context"
    "errors"

    corev1 "k8s.io/api/core/v1"
    "k8s.io/client-go/informers"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/cache"
)

// Watch meldet jedes neue Finding über report, bis ctx endet.
func Watch(ctx context.Context, cs kubernetes.Interface, ns string,
    minRestarts int32, report func(Finding)) error {
    factory := informers.NewSharedInformerFactoryWithOptions(cs, 0,
        informers.WithNamespace(ns))
    inf := factory.Core().V1().Pods().Informer()
    seen := map[Finding]bool{} // Handler laufen seriell: kein Mutex nötig
    check := func(obj any) {
        p, ok := obj.(*corev1.Pod)
        if !ok {
            return
        }
        for _, f := range Inspect(p, minRestarts) {
            if !seen[f] {
                seen[f] = true
                report(f)
            }
        }
    }
    _, err := inf.AddEventHandler(cache.ResourceEventHandlerFuncs{
        AddFunc:    check,
        UpdateFunc: func(_, obj any) { check(obj) },
    })
    if err != nil {
        return err
    }
    factory.Start(ctx.Done())
    if !cache.WaitForCacheSync(ctx.Done(), inf.HasSynced) {
        return errors.New("informer-cache nicht synchron")
    }
    <-ctx.Done()
    factory.Shutdown()
    return nil
}
EOF

Warum? Finding enthält nur vergleichbare Felder und taugt deshalb direkt als Map-Key. Steigt Restarts, entsteht ein neuer Key – der Pod wird erneut gemeldet.

Der Fake-Clientset hat keine resourceVersion: Änderungen zwischen List und Watch gehen verloren. Der Test wartet deshalb per Reactor, bis die Watch läuft.

cat > internal/pods/watch_test.go <<'EOF'
package pods

import (
    "context"
    "testing"
    "time"

    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/watch"
    "k8s.io/client-go/kubernetes/fake"
    k8stesting "k8s.io/client-go/testing"
)

func TestWatch(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    cs := fake.NewClientset(pod("api", 7, "CrashLoopBackOff", "Error"))
    // Der Fake kennt keine resourceVersion: erst ändern, wenn Watch läuft.
    started := make(chan struct{})
    cs.PrependWatchReactor("pods", func(a k8stesting.Action) (
        bool, watch.Interface, error) {
        w, err := cs.Tracker().Watch(a.GetResource(), a.GetNamespace())
        close(started)
        return true, w, err
    })
    got := make(chan Finding, 10)
    go func() { _ = Watch(ctx, cs, "shop", 3, func(f Finding) { got <- f }) }()

    expect := func(reason string) {
        t.Helper()
        select {
        case f := <-got:
            if f.Reason != reason {
                t.Fatalf("got %+v, want %s", f, reason)
            }
        case <-time.After(5 * time.Second):
            t.Fatalf("kein Finding %s", reason)
        }
    }
    expect("CrashLoopBackOff") // aus der initialen Liste
    <-started
    _, err := cs.CoreV1().Pods("shop").Update(ctx,
        pod("api", 8, "", "OOMKilled"), metav1.UpdateOptions{})
    if err != nil {
        t.Fatal(err)
    }
    expect("OOMKilled") // aus dem Watch-Event
}
EOF
go mod tidy
go test -race -count=10 -run TestWatch ./internal/pods

Erwartet:

ok      example.com/podwatch/internal/pods  1.796s

Warum -count=10? Tests mit Goroutines und Timing flackern gern. Zehn grüne Läufe mit Race-Detector (Tag 8) geben dir Vertrauen, dass der Reactor-Trick wirkt.

Tipp: Der Fake ist für Unit-Tests gedacht. Komplexes Controller-Verhalten testest du mit envtest (echter API-Server ohne Nodes) oder in einem kind-Cluster.

Fortschritt speichern? Kostenlos registrieren

Drill 5: kubeconfig laden wie kubectl

main macht nur Flags, Client und Exit-Codes; run ist mit dem Fake testbar.

cat > cmd/podwatch/main.go <<'EOF'
// podwatch meldet CrashLoops, OOMKills und häufige Neustarts von Pods.
package main

import (
    "context"
    "flag"
    "fmt"
    "io"
    "os"
    "os/signal"
    "syscall"
    "time"

    "example.com/podwatch/internal/pods"
    "k8s.io/client-go/kubernetes"
    "k8s.io/client-go/tools/clientcmd"
)

type options struct {
    ns       string
    restarts int
    watch    bool
}

func main() {
    kubeconfig := flag.String("kubeconfig", "", "Pfad zur kubeconfig")
    kctx := flag.String("context", "", "kubeconfig-Kontext (Default: aktueller)")
    var o options
    flag.StringVar(&o.ns, "n", "", "Namespace (leer = alle)")
    flag.IntVar(&o.restarts, "restarts", 3, "ab so vielen Neustarts melden")
    flag.BoolVar(&o.watch, "watch", false, "dauerhaft beobachten (Informer)")
    flag.Parse()

    cs, err := client(*kubeconfig, *kctx)
    if err != nil {
        fmt.Fprintln(os.Stderr, "podwatch:", err)
        os.Exit(2)
    }
    ctx, stop := signal.NotifyContext(context.Background(),
        os.Interrupt, syscall.SIGTERM)
    defer stop()
    n, err := run(ctx, cs, o, os.Stdout)
    if err != nil {
        fmt.Fprintln(os.Stderr, "podwatch:", err)
        os.Exit(2)
    }
    if n > 0 {
        os.Exit(1) // Findings: CI und Skripte sollen das merken
    }
}

// client baut den Clientset wie kubectl: Flag, $KUBECONFIG, ~/.kube/config.
func client(path, kctx string) (kubernetes.Interface, error) {
    rules := clientcmd.NewDefaultClientConfigLoadingRules()
    rules.ExplicitPath = path
    cfg, err := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(rules,
        &clientcmd.ConfigOverrides{CurrentContext: kctx}).ClientConfig()
    if err != nil {
        return nil, fmt.Errorf("kubeconfig: %w", err)
    }
    cfg.Timeout = 15 * time.Second
    return kubernetes.NewForConfig(cfg)
}

// run prüft einmalig (Tabelle) oder beobachtet dauerhaft (eine Zeile je Fund).
func run(ctx context.Context, cs kubernetes.Interface, o options,
    w io.Writer) (int, error) {
    if o.watch {
        n := 0
        err := pods.Watch(ctx, cs, o.ns, int32(o.restarts), func(f pods.Finding) {
            n++
            fmt.Fprintf(w, "%s %s/%s %s %s restarts=%d\n",
                time.Now().Format(time.TimeOnly), f.Namespace, f.Pod,
                f.Container, f.Reason, f.Restarts)
        })
        return n, err
    }
    fs, err := pods.Scan(ctx, cs, o.ns, int32(o.restarts))
    if err != nil {
        return 0, err
    }
    if len(fs) == 0 {
        fmt.Fprintln(w, "keine auffälligen Pods")
        return 0, nil
    }
    return len(fs), pods.Print(w, fs)
}
EOF
cat > cmd/podwatch/main_test.go <<'EOF'
package main

import (
    "bytes"
    "context"
    "strings"
    "testing"

    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/kubernetes/fake"
)

func TestRunScan(t *testing.T) {
    p := &corev1.Pod{
        ObjectMeta: metav1.ObjectMeta{Name: "api", Namespace: "shop"},
        Status: corev1.PodStatus{ContainerStatuses: []corev1.ContainerStatus{
            {Name: "app", RestartCount: 4}}},
    }
    tests := []struct {
        name  string
        ns    string
        wantN int
        want  string
    }{
        {"treffer", "shop", 1, "Restarts"},
        {"anderer namespace", "kube-system", 0, "keine auffälligen Pods"},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            var buf bytes.Buffer
            n, err := run(context.Background(), fake.NewClientset(p),
                options{ns: tt.ns, restarts: 3}, &buf)
            if err != nil || n != tt.wantN || !strings.Contains(buf.String(), tt.want) {
                t.Fatalf("n=%d err=%v out=%q", n, err, buf.String())
            }
        })
    }
}
EOF
go mod tidy
go vet ./... && go test -race -count=1 ./...

Erwartet:

ok      example.com/podwatch/cmd/podwatch   2.724s
ok      example.com/podwatch/internal/pods  2.394s

Warum? NewDefaultClientConfigLoadingRules folgt denselben Regeln wie kubectl, inklusive mehrerer Dateien in $KUBECONFIG. cfg.Timeout verhindert, dass ein toter API-Server dein Skript ewig blockiert.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Das Tool ist fertig

go build -o podwatch ./cmd/podwatch
ls -lh podwatch | awk '{print $5}'
./podwatch -h

Erwartet:

39M
Usage of ./podwatch:
  -context string
        kubeconfig-Kontext (Default: aktueller)
  -kubeconfig string
        Pfad zur kubeconfig
  -n string
        Namespace (leer = alle)
  -restarts int
        ab so vielen Neustarts melden (default 3)
  -watch
        dauerhaft beobachten (Informer)

Warum 39 MB? client-go zieht alle API-Typen mit. -ldflags="-s -w" spart etwas (Tag 14).

Fehlerpfade prüfst du gefahrlos mit einer Lab-kubeconfig, deren Server nicht existiert (Token ist ein Lab-Wert):

cat > lab-kubeconfig.yaml <<'EOF'
apiVersion: v1
kind: Config
clusters:
- name: lab
  cluster:
    server: https://127.0.0.1:1
contexts:
- name: lab
  context:
    cluster: lab
    user: lab
current-context: lab
users:
- name: lab
  user:
    token: lab-token-1234
EOF
./podwatch -kubeconfig /nicht/da; echo "exit=$?"
./podwatch -kubeconfig lab-kubeconfig.yaml -context prod; echo "exit=$?"
./podwatch -kubeconfig lab-kubeconfig.yaml -n shop; echo "exit=$?"

Erwartet (lange Zeile umbrochen):

podwatch: kubeconfig: stat /nicht/da: no such file or directory
exit=2
podwatch: kubeconfig: context "prod" does not exist
exit=2
podwatch: pods auflisten: Get "https://127.0.0.1:1/api/v1/namespaces/shop/pods":
  dial tcp 127.0.0.1:1: connect: connection refused
exit=2

Hast du einen eigenen Lab-Cluster (kind, minikube, Docker Desktop), probiere es dort – mit einem kaputten Deployment siehst du echte Funde:

kubectl --context kind-lab create deployment crash --image=busybox \
  -- sh -c 'exit 1'
./podwatch -context kind-lab -n default -restarts 1; echo "exit=$?"
./podwatch -context kind-lab -watch   # Strg+C beendet

Erwartet (gekürzt, kann je nach Version abweichen):

NAMESPACE  POD                     CONTAINER  GRUND             RESTARTS
default    crash-6c9f8b7d5-x2k4q   busybox    CrashLoopBackOff  3
exit=1
14:02:11 default/crash-6c9f8b7d5-x2k4q busybox CrashLoopBackOff restarts=3

Achtung: Nur gegen einen eigenen Lab-Kontext testen. -context immer explizit setzen – der aktuelle Kontext ist oft der falsche (Tag 5).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/go-lab/tag11-podwatch
check "gofmt sauber" "test -z \"\$(gofmt -l .)\""
check "go vet" "go vet ./..."
check "golangci-lint" "~/go-lab/bin/lint run ./..."
check "Tests mit -race" "go test -race -count=1 ./..."
check "Binary gebaut" "test -x podwatch"
check "Fehler -> exit 2" \
  "./podwatch -kubeconfig lab-kubeconfig.yaml; test \$? -eq 2"
check "kein echter Cluster im Test" "! grep -rq 'NewForConfig' internal/"

Erwartet:

✔ gofmt sauber
✔ go vet
✔ golangci-lint
✔ Tests mit -race
✔ Binary gebaut
✔ Fehler -> exit 2
✔ kein echter Cluster im Test

Challenge

Pods, deren Image nicht geladen werden kann, hängen ohne Neustart fest und fallen podwatch bisher nicht auf. Melde ImagePullBackOff und ErrImagePull als Grund ImagePull und ergänze den Table-Test.

Hinweis: Beide Gründe stehen wie der CrashLoop in State.Waiting.Reason – ein zusätzlicher case direkt nach dem CrashLoop genügt.

Lösung

In internal/pods/inspect.go nach dem CrashLoop-case einfügen:

        case cs.State.Waiting != nil &&
            (cs.State.Waiting.Reason == "ImagePullBackOff" ||
                cs.State.Waiting.Reason == "ErrImagePull"):
            reason = "ImagePull"

In internal/pods/inspect_test.go vor "knapp darunter" eine Zeile ergänzen:

        {"image fehlt", pod("new", 0, "ImagePullBackOff", ""), "ImagePull"},
go test -count=1 -v -run 'TestInspect/image' ./internal/pods

Erwartet (gekürzt):

--- PASS: TestInspect (0.00s)
    --- PASS: TestInspect/image_fehlt (0.00s)
ok      example.com/podwatch/internal/pods  0.277s

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • RBAC minimal halten: eine ClusterRole mit nur get, list, watch auf pods; im Cluster per ServiceAccount und rest.InClusterConfig() statt kubeconfig.
  • Große Cluster: Informer statt wiederholter Lists, cfg.QPS/cfg.Burst bewusst setzen und mit Label-Selektoren filtern (WithTweakListOptions).
  • Die seen-Map wächst unbegrenzt – einen DeleteFunc-Handler ergänzen, der Einträge gelöschter Pods entfernt.
  • Statt stdout: Prometheus-Metriken (Tag 9) oder Kubernetes-Events; mehrere Replikas brauchen Leader Election (k8s.io/client-go/tools/leaderelection).
  • Für echte Controller mit CRDs und Reconcile-Loop lohnt sich controller-runtime bzw. kubebuilder statt reiner Informer.