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.Interfaceist 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
EOFErwartet (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
}
EOFEin 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/podsErwartet (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()
}
EOFfake.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/podsErwartet:
=== 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
}
EOFWarum? 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/podsErwartet:
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)
}
EOFcat > 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 -hErwartet:
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 beendetErwartet (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.
-contextimmer 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/podsErwartet (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,watchaufpods; im Cluster per ServiceAccount undrest.InClusterConfig()statt kubeconfig. - Große Cluster: Informer statt wiederholter Lists,
cfg.QPS/cfg.Burstbewusst setzen und mit Label-Selektoren filtern (WithTweakListOptions). - Die
seen-Map wächst unbegrenzt – einenDeleteFunc-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-runtimebzw. kubebuilder statt reiner Informer.