Tag 5: Status und Conditions
Ziel: Der site-operator meldet über
status, Conditions und Events, wie es der Website geht – lesbar für Menschen (kubectl get), Skripte (kubectl wait) und Monitoring · Dauer: ca. 90 min · Voraussetzung: Tag 4
Briefing
specgehört dem Nutzer,statusdem Operator. Geschrieben wird der Status über die Subresource/status.- Conditions sind eine Liste
{type, status, reason, message, observedGeneration, lastTransitionTime};meta.SetStatusConditionpflegt sie und ändertlastTransitionTimenur bei echten Wechseln. observedGenerationsagt: „Diesen Stand der Spec habe ich gesehen.” Ohne sie istAvailable=Truewomöglich veraltet.- Status nur schreiben, wenn er sich ändert – sonst weckt jedes Update den eigenen Watch (Hotloop).
Reconcile -> reconcileResources() --(dep, err)--> updateStatus()
updateStatus: Degraded Fehler? ContentMissing / ReconcileError
Available readyReplicas >= spec.replicas
Progressing Rollout fertig?
Events nur bei Zustandswechsel
Drill 1: Condition-Typen als Konstanten
Neuer Tag, neue Kopie. Typen und Reasons gehören in das API-Paket – Tests, Tools und andere Operatoren importieren sie von dort.
source ~/op-lab/env.sh
cp -r ~/op-lab/tag04-site-operator ~/op-lab/tag05-site-operator
cd ~/op-lab/tag05-site-operator
cat > api/v1alpha1/conditions.go <<'EOF'
package v1alpha1
// Condition-Typen einer StaticSite (Kubernetes-API-Konventionen).
const (
ConditionAvailable = "Available" // genug Pods bereit
ConditionProgressing = "Progressing" // Rollout läuft
ConditionDegraded = "Degraded" // Operator kann nicht abgleichen
)
// Reasons sind CamelCase, maschinenlesbar und stabil – Alerts hängen daran.
const (
ReasonAllReplicasReady = "AllReplicasReady"
ReasonReplicasNotReady = "ReplicasNotReady"
ReasonRolloutInProgress = "RolloutInProgress"
ReasonRolloutComplete = "RolloutComplete"
ReasonContentMissing = "ContentMissing"
ReasonReconcileError = "ReconcileError"
ReasonAsExpected = "AsExpected"
)
EOFReasons sind ein Vertrag: Alerts, Runbooks und
kubectl wait-Skripte hängen daran. Umbenennen ist ein
Breaking Change.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Printer-Columns
Marker über dem StaticSite-Typ steuern, was
kubectl get zeigt. Du fügst sie per sed direkt
unter dem shortName-Marker aus Tag 3 ein:
mkdir -p lab
cat > lab/columns.txt <<'EOF'
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
// +kubebuilder:printcolumn:name="Available",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].status`
// +kubebuilder:printcolumn:name="URL",type=string,JSONPath=`.status.url`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
EOF
sed -i.bak '/shortName=site/r lab/columns.txt' api/v1alpha1/staticsite_types.go
rm api/v1alpha1/staticsite_types.go.bak
make manifests generate
grep -B1 'name: Available' config/crd/bases/web.lab.example_staticsites.yamlErwartet:
- jsonPath: .status.conditions[?(@.type=="Available")].status
name: Available
Der JSONPath-Filter [?(@.type=="Available")] pickt eine
Condition aus der Liste – dieselbe Syntax nutzt du gleich in
Skripten.
Achtung: Marker dürfen nicht umbrochen werden. Die
Available-Zeile ist deshalb länger als üblich – nicht von Hand aufteilen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Status berechnen
updateStatus bekommt das Deployment und den Fehler aus
dem Abgleich und leitet daraus alles ab. Der Vergleich mit
equality.Semantic.DeepEqual verhindert Schreibzugriffe ohne
Änderung.
cat > internal/controller/status.go <<'EOF'
package controller
import (
"context"
"errors"
"fmt"
appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
"k8s.io/apimachinery/pkg/api/equality"
"k8s.io/apimachinery/pkg/api/meta"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"sigs.k8s.io/controller-runtime/pkg/client"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
// updateStatus leitet den Status aus Deployment und Reconcile-Fehler ab und
// schreibt ihn nur, wenn sich etwas geändert hat (sonst: Hotloop-Gefahr).
func (r *StaticSiteReconciler) updateStatus(ctx context.Context,
site *webv1alpha1.StaticSite, dep *appsv1.Deployment, recErr error) error {
orig := site.DeepCopy()
st := &site.Status
st.ObservedGeneration = site.Generation
st.URL = fmt.Sprintf("http://%s.%s.svc", site.Name, site.Namespace)
set := func(typ string, s metav1.ConditionStatus, reason, msg string) {
meta.SetStatusCondition(&st.Conditions, metav1.Condition{
Type: typ, Status: s, Reason: reason, Message: msg,
ObservedGeneration: site.Generation,
})
}
switch {
case errors.Is(recErr, errContentMissing):
set(webv1alpha1.ConditionDegraded, metav1.ConditionTrue,
webv1alpha1.ReasonContentMissing, recErr.Error())
case recErr != nil:
set(webv1alpha1.ConditionDegraded, metav1.ConditionTrue,
webv1alpha1.ReasonReconcileError, recErr.Error())
default:
set(webv1alpha1.ConditionDegraded, metav1.ConditionFalse,
webv1alpha1.ReasonAsExpected, "alle Objekte abgeglichen")
}
if dep == nil { // Deployment existiert (noch) nicht
st.ReadyReplicas = 0
set(webv1alpha1.ConditionAvailable, metav1.ConditionFalse,
webv1alpha1.ReasonReplicasNotReady, "kein Deployment")
} else {
setReplicaConditions(site, dep, set)
}
if equality.Semantic.DeepEqual(orig.Status, site.Status) {
return nil
}
r.recordTransitions(orig, site)
// MergeFrom: nur der Status-Diff geht an den API-Server.
return r.Status().Patch(ctx, site, client.MergeFrom(orig))
}
func setReplicaConditions(site *webv1alpha1.StaticSite, dep *appsv1.Deployment,
set func(string, metav1.ConditionStatus, string, string)) {
want, ds := site.Spec.Replicas, dep.Status
site.Status.ReadyReplicas = ds.ReadyReplicas
msg := fmt.Sprintf("%d/%d Pods bereit", ds.ReadyReplicas, want)
if ds.ReadyReplicas >= want {
set(webv1alpha1.ConditionAvailable, metav1.ConditionTrue,
webv1alpha1.ReasonAllReplicasReady, msg)
} else {
set(webv1alpha1.ConditionAvailable, metav1.ConditionFalse,
webv1alpha1.ReasonReplicasNotReady, msg)
}
// Rollout fertig: Deployment-Controller hat die aktuelle Generation gesehen
// und alle Pods sind aktualisiert und bereit.
done := ds.ObservedGeneration >= dep.Generation &&
ds.UpdatedReplicas >= want && ds.ReadyReplicas >= want
if done {
set(webv1alpha1.ConditionProgressing, metav1.ConditionFalse,
webv1alpha1.ReasonRolloutComplete, msg)
} else {
set(webv1alpha1.ConditionProgressing, metav1.ConditionTrue,
webv1alpha1.ReasonRolloutInProgress, msg)
}
}
// recordTransitions erzeugt Events nur bei Zustandswechseln, nicht bei jedem Lauf.
func (r *StaticSiteReconciler) recordTransitions(orig, site *webv1alpha1.StaticSite) {
if r.Recorder == nil { // z. B. im Test ohne Recorder
return
}
for _, typ := range []string{
webv1alpha1.ConditionAvailable, webv1alpha1.ConditionDegraded,
} {
before := meta.FindStatusCondition(orig.Status.Conditions, typ)
now := meta.FindStatusCondition(site.Status.Conditions, typ)
if now == nil || (before != nil && before.Status == now.Status) {
continue
}
evType := corev1.EventTypeNormal
if typ == webv1alpha1.ConditionDegraded && now.Status == metav1.ConditionTrue {
evType = corev1.EventTypeWarning
}
r.Recorder.Eventf(site, nil, evType, now.Reason, "Reconcile",
"%s=%s: %s", typ, now.Status, now.Message)
}
}
EOFWarum Status().Patch mit MergeFrom? Der
Patch enthält nur den Status-Diff und keine resourceVersion
– kein Konflikt, wenn parallel jemand die Spec ändert. Optimistisches
Locking und Konflikte vertiefst du an Tag 13.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Reconcile umbauen
Der Abgleich aus Tag 4 wandert in reconcileResources;
Reconcile schreibt danach immer den Status
– auch im Fehlerfall. Der Kopf der Datei (bis vor
resolveContent) wird ersetzt, der Rest bleibt:
F=internal/controller/staticsite_controller.go
sed -n '/^\/\/ resolveContent liefert/,$p' $F > lab/rest.txt
cat > $F <<'EOF'
package controller
import (
"context"
"errors"
"fmt"
"time"
appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
apierrors "k8s.io/apimachinery/pkg/api/errors"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/client-go/tools/events"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
logf "sigs.k8s.io/controller-runtime/pkg/log"
webv1alpha1 "example.com/site-operator/api/v1alpha1"
)
// errContentMissing: die referenzierte ConfigMap fehlt (noch).
var errContentMissing = errors.New("content source not found")
// StaticSiteReconciler gleicht StaticSites mit ConfigMap, Deployment und Service ab.
type StaticSiteReconciler struct {
client.Client
Scheme *runtime.Scheme
Recorder events.EventRecorder
}
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites,verbs=get;list;watch
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites,verbs=update;patch
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites/status,verbs=get;patch
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites/status,verbs=update
// +kubebuilder:rbac:groups=web.lab.example,resources=staticsites/finalizers,verbs=update
// +kubebuilder:rbac:groups="",resources=configmaps;services,verbs=get;list;watch
// +kubebuilder:rbac:groups="",resources=configmaps;services,verbs=create;update;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=create;update;patch
// +kubebuilder:rbac:groups=events.k8s.io,resources=events,verbs=create;patch
func (r *StaticSiteReconciler) Reconcile(ctx context.Context,
req ctrl.Request) (ctrl.Result, error) {
var site webv1alpha1.StaticSite
if err := r.Get(ctx, req.NamespacedName, &site); err != nil {
return ctrl.Result{}, client.IgnoreNotFound(err) // gelöscht: nichts zu tun
}
dep, recErr := r.reconcileResources(ctx, &site)
// Status immer schreiben – gerade im Fehlerfall will der Nutzer wissen, warum.
if err := r.updateStatus(ctx, &site, dep, recErr); err != nil {
return ctrl.Result{}, errors.Join(recErr, err)
}
if errors.Is(recErr, errContentMissing) {
logf.FromContext(ctx).Info("Inhalt fehlt, neuer Versuch in 30s",
"error", recErr.Error())
return ctrl.Result{RequeueAfter: 30 * time.Second}, nil
}
return ctrl.Result{}, recErr // nil oder Backoff durch die Workqueue
}
// reconcileResources gleicht ConfigMap, Deployment und Service ab.
func (r *StaticSiteReconciler) reconcileResources(ctx context.Context,
site *webv1alpha1.StaticSite) (*appsv1.Deployment, error) {
content, err := r.resolveContent(ctx, site)
if err != nil {
return nil, err
}
hash, err := r.reconcileConfigMap(ctx, site, content)
if err != nil {
return nil, err
}
dep, err := r.reconcileDeployment(ctx, site, hash)
if err != nil {
return nil, err
}
return dep, r.reconcileService(ctx, site)
}
EOF
cat lab/rest.txt >> $F && rm lab/rest.txterrors.Join liefert nil, wenn beide Fehler
nil sind – und beide, wenn beide schiefgehen. Der Recorder
kommt aus dem Manager; in cmd/main.go verdrahtest du ihn
mit derselben sed-Technik:
printf '\t\tRecorder: mgr.GetEventRecorder("site-operator"),\n' > lab/recorder.txt
sed -i.bak '/Scheme: mgr.GetScheme(),/r lab/recorder.txt' cmd/main.go
rm cmd/main.go.bak
make manifests generate fmt vet
go build ./... && echo build-ok
grep -A2 'StaticSiteReconciler{' cmd/main.go
grep -A3 'events.k8s.io' config/rbac/role.yamlErwartet (gekürzt):
build-ok
if err := (&controller.StaticSiteReconciler{
Client: mgr.GetClient(),
Scheme: mgr.GetScheme(),
- events.k8s.io
resources:
- events
verbs:
GetEventRecorder nutzt die neue Events-API
(events.k8s.io/v1); das ältere
GetEventRecorderFor ist in controller-runtime v0.25
deprecated. Signatur:
Eventf(regarding, related, typ, reason, action, note, args...).
Fortschritt speichern? Kostenlos registrieren
Drill 5: Erster Lauf mit Status
Die CRD hat neue Printer-Columns, also startest du envtest in Terminal 2 neu (Ctrl+C, dann):
cd ~/op-lab/tag05-site-operator
envtest-up -crds config/crd/basesTerminal 3 startet den Operator:
cd ~/op-lab/tag05-site-operator
go run ./cmd/main.go -health-probe-bind-address=0 2>&1 | tee run.logIn Terminal 1:
kubectl apply -f lab/demo.yaml
sleep 2
kubectl get staticsite
kubectl get staticsite demo -o json | \
jq -c '.status.conditions[] | {type, status, reason}'
ev() { kubectl events --for "staticsite/$1" -o json | \
jq -r '.items[] | "\(.type) \(.reason): \(.message)"'; }
ev demoErwartet:
staticsite.web.lab.example/demo created
NAME READY AVAILABLE URL AGE
demo False http://demo.default.svc 2s
{"type":"Degraded","status":"False","reason":"AsExpected"}
{"type":"Available","status":"False","reason":"ReplicasNotReady"}
{"type":"Progressing","status":"True","reason":"RolloutInProgress"}
Normal ReplicasNotReady: Available=False: 0/1 Pods bereit
Normal AsExpected: Degraded=False: alle Objekte abgeglichen
READY ist leer, weil readyReplicas: 0 per
omitempty wegfällt. kubectl events ohne
-o json zeigt oft (x2 over 2s): Der zweite
Reconcile las die StaticSite noch ohne Status aus dem Cache – ein
harmloser Effekt der verzögerten Informer.
Fortschritt speichern? Kostenlos registrieren
Drill 6:
Bereitschaft simulieren und kubectl wait
In envtest gibt es keine Pods. Du spielst den Deployment-Controller und patchst den Deployment-Status über die Subresource:
fake_ready() { # $1 = Deployment, $2 = bereite Pods (Default 1)
local n=${2:-1} gen
gen=$(kubectl get deployment "$1" -o jsonpath='{.metadata.generation}')
kubectl patch deployment "$1" --subresource=status --type=merge -p "{\"status\":{
\"observedGeneration\":$gen, \"replicas\":$n, \"updatedReplicas\":$n,
\"readyReplicas\":$n, \"availableReplicas\":$n}}"
}
kubectl wait staticsite/demo --for=condition=Available --timeout=3s
fake_ready demo
kubectl wait staticsite/demo --for=condition=Available --timeout=10s
kubectl get staticsite
ev demo | tail -1Erwartet:
error: timed out waiting for the condition on staticsites/demo
deployment.apps/demo patched
staticsite.web.lab.example/demo condition met
NAME READY AVAILABLE URL AGE
demo 1 True http://demo.default.svc 11s
Normal AllReplicasReady: Available=True: 1/1 Pods bereit
Die Status-Änderung am Deployment weckt per Owns() die
StaticSite. kubectl wait --for=condition=… ist genau das,
worauf CI-Pipelines und Argo-CD-Health-Checks warten.
Fortschritt speichern? Kostenlos registrieren
Drill 7: observedGeneration
metadata.generation zählt Spec-Änderungen. Erst wenn
status.observedGeneration gleichzieht, beschreibt der
Status die aktuelle Spec.
kubectl patch staticsite demo --type=merge -p '{"spec":{"replicas":2}}'
kubectl wait staticsite/demo --for=jsonpath='{.status.observedGeneration}'=2 \
--timeout=10s
kubectl get staticsite demo -o json | jq -c '.metadata.generation,
(.status.conditions[] | [.type, .status, .reason, .observedGeneration])'
fake_ready demo 2
kubectl wait staticsite/demo --for=condition=Progressing=False --timeout=10s
kubectl get staticsite demoErwartet:
staticsite.web.lab.example/demo patched
staticsite.web.lab.example/demo condition met
2
["Degraded","False","AsExpected",2]
["Available","False","ReplicasNotReady",2]
["Progressing","True","RolloutInProgress",2]
deployment.apps/demo patched
staticsite.web.lab.example/demo condition met
NAME READY AVAILABLE URL AGE
demo 2 True http://demo.default.svc 16s
Ein Skript, das nur auf Available=True wartet, wäre
direkt nach dem Patch fälschlich zufrieden gewesen – der alte Status war
noch True. Deshalb erst auf observedGeneration
warten, dann auf die Condition.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Degraded im Zusammenspiel
Jetzt der Fehlerfall aus Tag 4 – diesmal sieht ihn auch, wer keine Operator-Logs lesen darf:
kubectl apply -f lab/extern.yaml
kubectl wait staticsite/extern --for=condition=Degraded --timeout=10s
kubectl get staticsite extern -o json | jq -c '.status.conditions[]
| select(.type=="Degraded") | {reason, message}'
ev extern | grep Warning
kubectl create configmap extern-html \
--from-literal=index.html='<h1>Aus der ConfigMap</h1>'
kubectl wait staticsite/extern --for=condition=Degraded=False --timeout=40s
kubectl get staticsiteErwartet (das zweite wait dauert bis zu 30 s):
staticsite.web.lab.example/extern created
staticsite.web.lab.example/extern condition met
{"reason":"ContentMissing","message":"configmap extern-html: content source not found"}
Warning ContentMissing: Degraded=True: configmap extern-html: content source not found
configmap/extern-html created
staticsite.web.lab.example/extern condition met
NAME READY AVAILABLE URL AGE
demo 2 True http://demo.default.svc 50s
extern False http://extern.default.svc 30s
extern ist nicht mehr degradiert, aber noch nicht
verfügbar – zwei unabhängige Aussagen. Genau deshalb gibt es mehrere
Condition-Typen statt eines einzelnen phase-Felds.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Operator läuft, demo und extern
existieren:
cat > lab/check.sh <<'EOF'
ok() { echo "✔ $1"; }
nok() { echo "✘ $1"; }
cond() { kubectl get staticsite "$1" \
-o jsonpath="{.status.conditions[?(@.type==\"$2\")].status}"; }
[ "$(kubectl get crd staticsites.web.lab.example \
-o jsonpath='{.spec.versions[0].additionalPrinterColumns[*].name}')" \
= "Ready Available URL Age" ] && ok "Printer-Columns" || nok "Printer-Columns"
[ "$(cond demo Available)" = True ] && ok "demo Available=True" || nok "demo"
[ "$(kubectl get staticsite demo -o jsonpath='{.status.observedGeneration}')" \
= "$(kubectl get staticsite demo -o jsonpath='{.metadata.generation}')" ] \
&& ok "observedGeneration aktuell" || nok "observedGeneration"
[ "$(cond extern Degraded)" = False ] && ok "extern erholt" || nok "extern"
kubectl events --for staticsite/extern --types=Warning | grep -q ContentMissing \
&& ok "Warning-Event ContentMissing" || nok "Event fehlt"
rv=$(kubectl get staticsite demo -o jsonpath='{.metadata.resourceVersion}')
sleep 5
[ "$rv" = "$(kubectl get staticsite demo -o jsonpath='{.metadata.resourceVersion}')" ] \
&& ok "kein Status-Hotloop" || nok "Status ändert sich ständig"
EOF
bash lab/check.shErwartet:
✔ Printer-Columns
✔ demo Available=True
✔ observedGeneration aktuell
✔ extern erholt
✔ Warning-Event ContentMissing
✔ kein Status-Hotloop
Challenge
Ergänze eine Spalte Reason (Reason der
Available-Condition), die nur bei
kubectl get staticsite -o wide erscheint.
Hinweis: Printer-Columns kennen das Attribut
priority; alles über 0 zeigt kubectl nur in der
Wide-Ansicht.
Lösung
cat > lab/reason.txt <<'EOF'
// +kubebuilder:printcolumn:name="Reason",type=string,priority=1,JSONPath=`.status.conditions[?(@.type=="Available")].reason`
EOF
sed -i.bak '/printcolumn:name="URL"/r lab/reason.txt' api/v1alpha1/staticsite_types.go
rm api/v1alpha1/staticsite_types.go.bak
make manifests && make install
kubectl get staticsite -o wideErwartet (gekürzt):
customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example configured
NAME READY AVAILABLE URL REASON AGE
demo 2 True http://demo.default.svc AllReplicasReady 2m53s
extern False http://extern.default.svc ReplicasNotReady 2m9s
make install aktualisiert die CRD im laufenden envtest –
der Operator muss dafür nicht neu starten, nur kubectl liest das neue
Schema. Der Code-Stand in code/tag05-site-operator enthält
die Challenge nicht.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Halte dich an die Kubernetes-API-Konventionen für Conditions
(
metav1.Condition, positive Polarität beiAvailable,Degradedals „abnormal-true”); Tools wie kstatus, Argo CD und Flux werten sie aus. - Reasons und Condition-Typen sind öffentliche API: in Alerts
(
kube_customresource_…via kube-state-metrics CustomResourceState) und Runbooks verwenden, nie still umbenennen. - Messages können Kundendaten enthalten (Pfade, Hostnamen, Fehlertexte von Drittsystemen) – keine Secrets und Tokens hineinschreiben, auch nicht in Events.
- Events sind kurzlebig (Default-TTL eine Stunde) und kein Audit-Log. Für Nachvollziehbarkeit: Logs und Metriken (Tag 11).
- Bei vielen Objekten Status-Updates bündeln und nur bei Änderungen schreiben – jede unnötige Statusänderung ist ein etcd-Write und ein Watch-Event für alle Clients.