Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Finalizer und externe Ressourcen

Ziel: Der site-operator trägt jede StaticSite bei einem externen DNS-Registrar ein und räumt den Eintrag per Finalizer zuverlässig wieder ab – auch wenn der Dienst zwischendurch ausfällt · Dauer: ca. 120 min · Voraussetzung: Tag 6

Briefing

  • Owner References räumen nur Kubernetes-Objekte ab. Alles außerhalb des Clusters (DNS, Cloud-Load-Balancer, Vault-Policies) braucht einen Finalizer.
  • Ein Finalizer ist nur ein String in metadata.finalizers. Solange er dort steht, setzt der API-Server beim Löschen nur deletionTimestamp – das Objekt bleibt.
  • Der Controller sieht deletionTimestamp, räumt extern auf und entfernt seinen Finalizer. Erst dann verschwindet das Objekt.
  • Fällt der externe Dienst aus, bleibt der Finalizer stehen: Retry mit Backoff statt Datenleiche.
kubectl delete  ->  deletionTimestamp gesetzt, finalizers: [web.lab.example/finalizer]
                        |
        Reconcile: DELETE /records/<name>.<ns>  --(503)-->  Fehler, Backoff, nochmal
                        | 204/404
              RemoveFinalizer + Update  ->  API-Server löscht das Objekt endgültig

Drill 1: Der externe Dienst – ein Lab-Registrar

Neuer Tag, neues Verzeichnis: Du arbeitest auf einer Kopie von Tag 6 weiter.

source ~/op-lab/env.sh
cp -r ~/op-lab/tag06-site-operator ~/op-lab/tag07-site-operator
mkdir -p ~/op-lab/registrar && cd ~/op-lab/registrar
cat > go.mod <<'EOF'
module example.com/registrar

go 1.26
EOF

Der Registrar ist ein kleiner HTTP-Dienst mit einer Map als Speicher. Er spielt den DNS-Anbieter, den du beim Kunden per API pflegen würdest – inklusive Wartungsfenster per /admin/outage.

cat > main.go <<'EOF'
// registrar ist ein Lab-"DNS-Registrar": ein externer Dienst, den der
// site-operator (Tag 7) per HTTP pflegt. Daten liegen nur im Speicher.
//
//  PUT    /records/<name>  {"target":"..."}  -> 201 neu, 200 geändert
//  GET    /records                           -> 200 alle Einträge
//  DELETE /records/<name>                    -> 204 oder 404
//  PUT    /admin/outage   / DELETE /admin/outage -> Ausfall an/aus (503)
package main

import (
    "encoding/json"
    "flag"
    "log/slog"
    "net/http"
    "os"
    "regexp"
    "sort"
    "sync"
)

// Record ist ein DNS-Eintrag: Name -> Ziel (z. B. Service-URL).
type Record struct {
    Name   string `json:"name"`
    Target string `json:"target"`
}

type registrar struct {
    mu      sync.Mutex
    records map[string]Record
    outage  bool
}

var validName = regexp.MustCompile(`^[a-z0-9]([-a-z0-9.]{0,251}[a-z0-9])?$`)

func main() {
    addr := flag.String("addr", "127.0.0.1:18090", "Listen-Adresse")
    flag.Parse()
    log := slog.New(slog.NewTextHandler(os.Stderr, nil))
    r := &registrar{records: map[string]Record{}}

    mux := http.NewServeMux()
    mux.HandleFunc("GET /records", r.list)
    mux.HandleFunc("PUT /records/{name}", r.put)
    mux.HandleFunc("DELETE /records/{name}", r.del)
    mux.HandleFunc("PUT /admin/outage", r.setOutage(true))
    mux.HandleFunc("DELETE /admin/outage", r.setOutage(false))

    log.Info("registrar startet", "addr", *addr)
    h := logging(log, r.guard(mux))
    if err := http.ListenAndServe(*addr, h); err != nil {
        log.Error("beendet", "err", err)
        os.Exit(1)
    }
}

// guard simuliert einen Ausfall: Alles außer /admin/ liefert dann 503.
func (r *registrar) guard(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        r.mu.Lock()
        down := r.outage
        r.mu.Unlock()
        if down && req.URL.Path != "/admin/outage" {
            http.Error(w, "registrar: Wartung", http.StatusServiceUnavailable)
            return
        }
        next.ServeHTTP(w, req)
    })
}

func (r *registrar) list(w http.ResponseWriter, _ *http.Request) {
    r.mu.Lock()
    out := make([]Record, 0, len(r.records))
    for _, rec := range r.records {
        out = append(out, rec)
    }
    r.mu.Unlock()
    sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
    writeJSON(w, http.StatusOK, out)
}

func (r *registrar) put(w http.ResponseWriter, req *http.Request) {
    name := req.PathValue("name")
    var body struct {
        Target string `json:"target"`
    }
    err := json.NewDecoder(http.MaxBytesReader(w, req.Body, 4096)).Decode(&body)
    if err != nil || body.Target == "" || !validName.MatchString(name) {
        http.Error(w, "ungültiger Name oder target fehlt", http.StatusBadRequest)
        return
    }
    r.mu.Lock()
    _, existed := r.records[name]
    rec := Record{Name: name, Target: body.Target}
    r.records[name] = rec
    r.mu.Unlock()
    status := http.StatusCreated
    if existed {
        status = http.StatusOK // PUT ist idempotent
    }
    writeJSON(w, status, rec)
}

func (r *registrar) del(w http.ResponseWriter, req *http.Request) {
    name := req.PathValue("name")
    r.mu.Lock()
    _, ok := r.records[name]
    delete(r.records, name)
    r.mu.Unlock()
    if !ok {
        http.Error(w, "nicht gefunden", http.StatusNotFound)
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

func (r *registrar) setOutage(on bool) http.HandlerFunc {
    return func(w http.ResponseWriter, _ *http.Request) {
        r.mu.Lock()
        r.outage = on
        r.mu.Unlock()
        w.WriteHeader(http.StatusNoContent)
    }
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func logging(log *slog.Logger, next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        log.Info("request", "method", req.Method, "path", req.URL.Path)
        next.ServeHTTP(w, req)
    })
}
EOF

Bauen und im Hintergrund starten – er läuft den ganzen Tag mit:

go vet ./... && go build -o ~/op-lab/bin/registrar .
registrar > ~/op-lab/registrar/registrar.log 2>&1 & REG_PID=$!
curl -s -X PUT localhost:18090/records/demo.default \
  -d '{"target":"http://demo.default.svc"}' -w ' %{http_code}\n'
curl -s localhost:18090/records
curl -s -X DELETE localhost:18090/records/demo.default -w '%{http_code}\n'
curl -s -X DELETE localhost:18090/records/demo.default -w ' %{http_code}\n'

Erwartet:

{"name":"demo.default","target":"http://demo.default.svc"}
 201
[{"name":"demo.default","target":"http://demo.default.svc"}]
204
nicht gefunden
 404

Warum? Der zweite DELETE liefert 404 – für deinen Operator heißt das „schon weg” und damit Erfolg. Aufräumen muss idempotent sein, weil Reconcile jederzeit wiederholt werden kann.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Ein Client mit Timeout

Der Operator spricht nicht direkt net/http im Reconcile, sondern über ein kleines Paket. Das hält den Controller lesbar und den Dienst austauschbar.

cd ~/op-lab/tag07-site-operator
mkdir -p internal/registrar
cat > internal/registrar/client.go <<'EOF'
// Package registrar spricht mit dem Lab-DNS-Registrar (code/registrar).
package registrar

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

// Client pflegt DNS-Einträge per HTTP. Ein leerer BaseURL schaltet ihn ab.
type Client struct {
    BaseURL string
    HTTP    *http.Client
}

// New liefert einen Client mit Timeout – ein hängender Dienst darf den
// Reconcile-Worker nicht blockieren.
func New(baseURL string) *Client {
    return &Client{BaseURL: baseURL, HTTP: &http.Client{Timeout: 5 * time.Second}}
}

// Upsert legt den Eintrag an oder aktualisiert ihn (PUT ist idempotent).
func (c *Client) Upsert(ctx context.Context, name, target string) error {
    body, err := json.Marshal(map[string]string{"target": target})
    if err != nil {
        return err
    }
    return c.do(ctx, http.MethodPut, name, body, http.StatusOK, http.StatusCreated)
}

// Delete entfernt den Eintrag. 404 zählt als Erfolg: Das Ziel ist erreicht.
func (c *Client) Delete(ctx context.Context, name string) error {
    return c.do(ctx, http.MethodDelete, name, nil,
        http.StatusNoContent, http.StatusNotFound)
}

func (c *Client) do(ctx context.Context, method, name string, body []byte,
    ok ...int) error {
    url := fmt.Sprintf("%s/records/%s", c.BaseURL, name)
    req, err := http.NewRequestWithContext(ctx, method, url, bytes.NewReader(body))
    if err != nil {
        return err
    }
    resp, err := c.HTTP.Do(req)
    if err != nil {
        return fmt.Errorf("registrar %s %s: %w", method, name, err)
    }
    defer resp.Body.Close()
    for _, code := range ok {
        if resp.StatusCode == code {
            return nil
        }
    }
    return fmt.Errorf("registrar %s %s: HTTP %d", method, name, resp.StatusCode)
}
EOF

Warum? Ohne Timeout kann ein hängender Dienst einen Reconcile-Worker für immer blockieren – und mit MaxConcurrentReconciles=1 (Standard) steht dann der ganze Controller.

Getestet wird der Client gleich mit – über den Finalizer-Test in envtest (Drill 4).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Finalizer setzen und abarbeiten

Die ganze Finalizer-Logik kommt in eine eigene Datei. Ist kein Registrar konfiguriert, setzt der Operator auch keinen Finalizer – so laufen Tests und Cluster ohne Registrar weiter wie bisher.

cd ~/op-lab/tag07-site-operator
cat > internal/controller/finalizer.go <<'EOF'
package controller

import (
    "context"
    "fmt"

    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
    logf "sigs.k8s.io/controller-runtime/pkg/log"

    webv1alpha1 "example.com/site-operator/api/v1alpha1"
)

// siteFinalizer hält die StaticSite fest, bis der DNS-Eintrag weg ist.
const siteFinalizer = "web.lab.example/finalizer"

// recordName ist der Schlüssel im Registrar: <name>.<namespace>.
func recordName(site *webv1alpha1.StaticSite) string {
    return site.Name + "." + site.Namespace
}

// registerDNS trägt die Site beim Registrar ein (PUT ist idempotent).
func (r *StaticSiteReconciler) registerDNS(ctx context.Context,
    site *webv1alpha1.StaticSite) error {
    if r.Registrar == nil {
        return nil // --registrar-url leer: DNS-Pflege aus
    }
    url := fmt.Sprintf("http://%s.%s.svc", site.Name, site.Namespace)
    return r.Registrar.Upsert(ctx, recordName(site), url)
}

// reconcileDelete räumt extern auf und gibt danach das Objekt frei.
func (r *StaticSiteReconciler) reconcileDelete(ctx context.Context,
    site *webv1alpha1.StaticSite) (ctrl.Result, error) {
    if !controllerutil.ContainsFinalizer(site, siteFinalizer) {
        return ctrl.Result{}, nil // nicht (mehr) unsere Aufgabe
    }
    if r.Registrar != nil {
        if err := r.Registrar.Delete(ctx, recordName(site)); err != nil {
            return ctrl.Result{}, err // Finalizer bleibt, Retry mit Backoff
        }
        logf.FromContext(ctx).Info("DNS-Eintrag entfernt", "record", recordName(site))
    }
    controllerutil.RemoveFinalizer(site, siteFinalizer)
    return ctrl.Result{}, r.Update(ctx, site)
}
EOF

Der Reconciler bekommt ein Feld für den Client (internal/controller/staticsite_controller.go, Import "example.com/site-operator/internal/registrar" ergänzen):

type StaticSiteReconciler struct {
    client.Client
    Scheme    *runtime.Scheme
    Recorder  events.EventRecorder
    Registrar *registrar.Client // nil: keine DNS-Pflege
}

In Reconcile direkt nach dem Get zwei Weichen, und nach den Kubernetes-Objekten der DNS-Eintrag:

    if !site.DeletionTimestamp.IsZero() { // kubectl delete: aufräumen
        return r.reconcileDelete(ctx, &site)
    }
    if r.Registrar != nil && controllerutil.AddFinalizer(&site, siteFinalizer) {
        if err := r.Update(ctx, &site); err != nil {
            return ctrl.Result{}, err
        }
    }

    dep, recErr := r.reconcileResources(ctx, &site)
    if recErr == nil {
        recErr = r.registerDNS(ctx, &site)
    }
    // Status immer schreiben – ... (wie an Tag 5)

Warum zuerst der Finalizer, dann die externe Ressource? Andersherum könnte der Operator abstürzen, nachdem der DNS-Eintrag existiert, aber bevor der Finalizer steht – ein späteres Löschen hinterließe eine Leiche. AddFinalizer liefert true nur, wenn es wirklich etwas geändert hat; das Update läuft also einmal pro Objekt.

Fehler aus registerDNS landen in recErr – updateStatus aus Tag 5 setzt daraus Degraded=True mit Reason ReconcileError, die Workqueue wiederholt mit Backoff. Die RBAC-Regel staticsites/finalizers: update hat Kubebuilder schon an Tag 3 erzeugt; sie ist ab heute nötig.

Fehlt noch das Flag in cmd/main.go. Import "example.com/site-operator/internal/registrar" ergänzen, dann bei den anderen Flags:

    var registrarURL string
    flag.StringVar(&registrarURL, "registrar-url", "",
        "Basis-URL des DNS-Registrars, z. B. http://127.0.0.1:18090 (leer: aus)")

und beim Anlegen des Reconcilers:

    var reg *registrar.Client
    if registrarURL != "" {
        reg = registrar.New(registrarURL)
    }
    if err := (&controller.StaticSiteReconciler{
        Client:    mgr.GetClient(),
        Scheme:    mgr.GetScheme(),
        Recorder:  mgr.GetEventRecorder("site-operator"),
        Registrar: reg,
    }).SetupWithManager(mgr); err != nil {
go build ./... && go vet ./... && echo ok

Erwartet:

ok

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ein Registrar im Test

envtest kennt keinen Registrar. Die Suite startet deshalb einen httptest-Server, der sich wie der echte verhält – und auf Knopfdruck ausfällt.

cat > internal/controller/fakeregistrar_test.go <<'EOF'
package controller

import (
    "net/http"
    "net/http/httptest"
    "sync"
    "sync/atomic"
)

// fakeRegistrar spielt den Registrar im Testprozess: Map statt DNS.
type fakeRegistrar struct {
    *httptest.Server
    mu      sync.Mutex
    records map[string]bool
    down    atomic.Bool // true: jede Anfrage bekommt 503
}

func newFakeRegistrar() *fakeRegistrar {
    f := &fakeRegistrar{records: map[string]bool{}}
    f.Server = httptest.NewServer(http.HandlerFunc(
        func(w http.ResponseWriter, r *http.Request) {
            if f.down.Load() {
                http.Error(w, "Wartung", http.StatusServiceUnavailable)
                return
            }
            name := r.URL.Path[len("/records/"):]
            f.mu.Lock()
            defer f.mu.Unlock()
            switch r.Method {
            case http.MethodPut:
                f.records[name] = true
                w.WriteHeader(http.StatusOK)
            case http.MethodDelete:
                delete(f.records, name)
                w.WriteHeader(http.StatusNoContent)
            }
        }))
    return f
}

// has meldet, ob der Eintrag existiert.
func (f *fakeRegistrar) has(name string) bool {
    f.mu.Lock()
    defer f.mu.Unlock()
    return f.records[name]
}
EOF

In internal/controller/suite_test.go eine Variable fakeReg *fakeRegistrar in den var-Block, Import "example.com/site-operator/internal/registrar", dann den Reconciler mit Registrar starten und in AfterSuite den Server schließen:

    fakeReg = newFakeRegistrar()
    Expect((&StaticSiteReconciler{
        Client:    mgr.GetClient(),
        Scheme:    mgr.GetScheme(),
        Recorder:  mgr.GetEventRecorder("site-operator"),
        Registrar: registrar.New(fakeReg.URL),
    }).SetupWithManager(mgr)).To(Succeed())
    // ...
var _ = AfterSuite(func() {
    By("Manager und envtest stoppen")
    cancel()
    fakeReg.Close()
    Expect(testEnv.Stop()).To(Succeed())
})

Drei Specs: Glücksfall, Ausfall beim Löschen, Ausfall beim Eintragen. Die Helfer newNamespace und newStaticSite kennst du aus Tag 6.

cat > internal/controller/finalizer_test.go <<'EOF'
package controller

import (
    "time"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    apierrors "k8s.io/apimachinery/pkg/api/errors"
    "k8s.io/apimachinery/pkg/api/meta"
    "sigs.k8s.io/controller-runtime/pkg/client"

    webv1alpha1 "example.com/site-operator/api/v1alpha1"
)

var _ = Describe("Finalizer und Registrar", func() {
    var (
        site   *webv1alpha1.StaticSite
        record string
    )

    BeforeEach(func(ctx SpecContext) {
        site = newStaticSite(newNamespace(ctx), "dns")
        record = "dns." + site.Namespace
        Expect(k8sClient.Create(ctx, site)).To(Succeed())
        Eventually(func() bool { return fakeReg.has(record) }).Should(BeTrue())
    })

    // gone ist erfüllt, wenn die StaticSite endgültig weg ist.
    gone := func(ctx SpecContext) func() bool {
        return func() bool {
            err := k8sClient.Get(ctx, client.ObjectKeyFromObject(site), site)
            return apierrors.IsNotFound(err)
        }
    }

    It("setzt den Finalizer und räumt beim Löschen ab", func(ctx SpecContext) {
        Expect(k8sClient.Get(ctx, client.ObjectKeyFromObject(site), site)).
            To(Succeed())
        Expect(site.Finalizers).To(ContainElement("web.lab.example/finalizer"))

        Expect(k8sClient.Delete(ctx, site)).To(Succeed())
        Eventually(gone(ctx)).Should(BeTrue())
        Expect(fakeReg.has(record)).To(BeFalse())
    })

    It("hält die Site fest, solange der Registrar ausfällt", func(ctx SpecContext) {
        fakeReg.down.Store(true)
        DeferCleanup(func() { fakeReg.down.Store(false) })

        Expect(k8sClient.Delete(ctx, site)).To(Succeed())
        Consistently(gone(ctx), 2*time.Second).Should(BeFalse())
        Expect(site.DeletionTimestamp).NotTo(BeNil()) // Terminating

        fakeReg.down.Store(false)
        Eventually(gone(ctx), 30*time.Second).Should(BeTrue())
        Expect(fakeReg.has(record)).To(BeFalse())
    })

    It("meldet Degraded, wenn der Eintrag nicht klappt", func(ctx SpecContext) {
        fakeReg.down.Store(true)
        DeferCleanup(func() { fakeReg.down.Store(false) })

        patch := client.MergeFrom(site.DeepCopy()) // Patch: kein Konflikt
        site.Spec.Replicas = 2                     // neue Generation -> Reconcile
        Expect(k8sClient.Patch(ctx, site, patch)).To(Succeed())
        Eventually(func() string {
            _ = k8sClient.Get(ctx, client.ObjectKeyFromObject(site), site)
            c := meta.FindStatusCondition(site.Status.Conditions,
                webv1alpha1.ConditionDegraded)
            if c == nil || c.Status != "True" {
                return ""
            }
            return c.Message
        }).Should(ContainSubstring("HTTP 503"))
    })
})
EOF
go test ./internal/controller/ -count=1 -v -ginkgo.no-color -ginkgo.focus=Finalizer \
  2>&1 | grep -E '^(Ran|SUCCESS|FAIL|ok)'

Erwartet:

Ran 3 of 17 Specs in 8.822 seconds
SUCCESS! -- 3 Passed | 0 Failed | 0 Pending | 14 Skipped
ok      example.com/site-operator/internal/controller   9.237s

Warum hält der zweite Test durch? Envtest hat keinen Garbage Collector, aber Finalizer wertet der API-Server selbst aus: Solange die Liste nicht leer ist, bleibt das Objekt mit deletionTimestamp stehen. Das testest du hier echt, nicht simuliert.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Live – Operator, Registrar, API-Server

Terminal 1: envtest-up --crds config/crd/bases (aus ~/op-lab/tag07-site-operator). Terminal 3: der Operator, diesmal mit Registrar:

source ~/op-lab/env.sh && cd ~/op-lab/tag07-site-operator
go run ./cmd/main.go -health-probe-bind-address=0 \
  --registrar-url=http://127.0.0.1:18090 2>&1 | tee run.log

Terminal 2:

kubectl apply -f lab/demo.yaml
kubectl get staticsite demo -o jsonpath='{.metadata.finalizers}{"\n"}'
curl -s localhost:18090/records; echo
kubectl delete staticsite demo
curl -s localhost:18090/records; echo
grep -E 'PUT|DELETE' ~/op-lab/registrar/registrar.log | tail -2

Erwartet (gekürzt):

staticsite.web.lab.example/demo created
["web.lab.example/finalizer"]
[{"name":"demo.default","target":"http://demo.default.svc"}]
staticsite.web.lab.example "demo" deleted from default namespace
[]
... msg=request method=PUT path=/records/demo.default
... msg=request method=DELETE path=/records/demo.default

kubectl delete wartet, bis das Objekt wirklich weg ist – also bis dein Operator den Finalizer entfernt hat. In run.log steht dazu DNS-Eintrag entfernt ... "record": "demo.default".

Fortschritt speichern? Kostenlos registrieren

Drill 6: Ausfall und hängender Finalizer

Erst der Ausfall: Registrar in Wartung, dann löschen.

kubectl apply -f lab/demo.yaml && sleep 2
curl -s -X PUT localhost:18090/admin/outage
kubectl delete staticsite demo --wait=false
sleep 4
kubectl get staticsite demo \
  -o jsonpath='{.metadata.deletionTimestamp} {.metadata.finalizers}{"\n"}'
grep 'Reconciler error' run.log | tail -1 | grep -o '"error": "[^"]*"'

Erwartet:

staticsite.web.lab.example/demo created
staticsite.web.lab.example "demo" deleted from default namespace
2026-10-10T08:48:44Z ["web.lab.example/finalizer"]
"error": "registrar DELETE demo.default: HTTP 503"

Die Site ist „Terminating”, der Eintrag bleibt bestehen, der Operator versucht es mit wachsendem Abstand weiter. Wartung beenden – Sekunden später ist sie weg:

curl -s -X DELETE localhost:18090/admin/outage
sleep 3; kubectl get staticsite demo

Erwartet:

Error from server (NotFound): staticsites.web.lab.example "demo" not found

Jetzt der Klassiker aus dem Betrieb: Der Operator ist weg (deinstalliert, CrashLoop, RBAC kaputt), der Finalizer bleibt. Site anlegen, dann in Terminal 3 den Operator mit Ctrl+C beenden:

kubectl apply -f lab/demo.yaml && sleep 2
# Terminal 3: Ctrl+C
kubectl delete staticsite demo --timeout=5s
kubectl get site

Erwartet:

staticsite.web.lab.example "demo" deleted from default namespace
error: timed out waiting for the condition on staticsites/demo
NAME   READY   AVAILABLE   URL                       AGE
demo           False       http://demo.default.svc   9s

Richtige Lösung: Operator wieder starten – er räumt ab. Notlösung, wenn er nie wiederkommt: Finalizer von Hand entfernen. Dann musst du die externe Ressource abräumen:

kubectl patch staticsite demo --type=json \
  -p '[{"op":"remove","path":"/metadata/finalizers"}]'
kubectl get site
curl -s localhost:18090/records; echo
curl -s -X DELETE localhost:18090/records/demo.default -w '%{http_code}\n'

Erwartet:

staticsite.web.lab.example/demo patched
No resources found in default namespace.
[{"name":"demo.default","target":"http://demo.default.svc"}]
204

Achtung: Finalizer von Hand zu entfernen ist ein Eingriff mit Folgen: Die externe Ressource verwaist. Beim Kunden gehört das ins Runbook – mit dem Schritt „extern prüfen und aufräumen”.

Starte den Operator in Terminal 3 wieder (gleicher Befehl wie in Drill 5) für den Kontrollpunkt.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/op-lab/tag07-site-operator
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
go test ./internal/... -count=1 >/dev/null 2>&1 && ok "Tests grün" || nok "Tests"
curl -sf localhost:18090/records >/dev/null && ok "Registrar läuft" || nok "Registrar"
kubectl apply -f lab/demo.yaml >/dev/null; sleep 2
kubectl get site demo -o jsonpath='{.metadata.finalizers}' | grep -q finalizer \
  && ok "Finalizer gesetzt" || nok "Finalizer fehlt (läuft der Operator?)"
curl -s localhost:18090/records | grep -q '"demo.default"' \
  && ok "DNS-Eintrag angelegt" || nok "DNS-Eintrag fehlt"
kubectl delete site demo --timeout=10s >/dev/null && ok "Site gelöscht" || nok "hängt"
curl -s localhost:18090/records | grep -q '"demo.default"' \
  && nok "DNS-Eintrag noch da" || ok "DNS-Eintrag entfernt"

Erwartet:

✔ Tests grün
✔ Registrar läuft
✔ Finalizer gesetzt
✔ DNS-Eintrag angelegt
✔ Site gelöscht
✔ DNS-Eintrag entfernt

Aufräumen: Operator (Terminal 3) und envtest-up (Terminal 1) mit Ctrl+C beenden. Den Registrar brauchst du an Tag 8 nicht: kill $REG_PID.

Challenge

Baue einen dokumentierten Notausgang: Trägt eine StaticSite die Annotation web.lab.example/skip-cleanup: "true", entfernt der Operator beim Löschen seinen Finalizer, ohne den Registrar zu fragen – und loggt das. Teste es mit ausgefallenem Registrar.

Hinweis: Die Weiche gehört in reconcileDelete vor den Delete-Aufruf; eine Annotation lässt sich auch an einem Objekt mit deletionTimestamp noch setzen.

Lösung

In finalizer.go eine Konstante und die Weiche:

// skipCleanupAnnotation: Notausgang, wenn der Registrar dauerhaft weg ist.
const skipCleanupAnnotation = "web.lab.example/skip-cleanup"

    if site.Annotations[skipCleanupAnnotation] == "true" {
        logf.FromContext(ctx).Info("Aufräumen übersprungen", "record", recordName(site))
    } else if r.Registrar != nil {
        if err := r.Registrar.Delete(ctx, recordName(site)); err != nil {

Operator in Terminal 3 neu starten (Drill 5), dann mit ausgefallenem Registrar:

kubectl apply -f lab/demo.yaml && sleep 2
curl -s -X PUT localhost:18090/admin/outage
kubectl annotate staticsite demo web.lab.example/skip-cleanup=true
kubectl delete staticsite demo --timeout=10s
grep -o 'Aufräumen übersprungen' run.log
curl -s -X DELETE localhost:18090/admin/outage
curl -s localhost:18090/records; echo

Erwartet:

staticsite.web.lab.example/demo created
staticsite.web.lab.example/demo annotated
staticsite.web.lab.example "demo" deleted from default namespace
Aufräumen übersprungen
[{"name":"demo.default","target":"http://demo.default.svc"}]

Der Eintrag bleibt absichtlich stehen – genau das sagt die Annotation. Wer sie setzt, räumt extern selbst auf.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Finalizer-Namen sind API: Einmal ausgerollt, musst du sie in jeder späteren Version weiter abarbeiten, sonst hängen Altobjekte.
  • Externe Aufrufe brauchen Timeout, Idempotenz (PUT/404 = ok) und eine eindeutige Zuordnung (z. B. Tag mit UID der StaticSite) – sonst löscht ein neuer Operator fremde Einträge.
  • Exponentieller Backoff wird bei langen Ausfällen bis zu ~16 min groß; für bekannte Wartungsfenster lieber RequeueAfter mit festem Intervall und eine Metrik „Löschungen hängend”.
  • Namespace-Löschung blockiert, solange ein Objekt darin einen Finalizer hat – Operator nie vor seinen CRs deinstallieren (Helm-Hooks, Reihenfolge in GitOps).
  • Zugangsdaten zum echten DNS-/Cloud-API gehören in ein Secret (oder Workload Identity), nie in Flags oder ConfigMaps.