Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Kyverno-Grundlagen

Ziel: Kyverno per Helm installieren, seine Bausteine verstehen und eine erste ValidatingPolicy mit CEL von Audit auf Deny schalten. · Dauer: ca. 75 min · Voraussetzung: Tag 0

Briefing

  • Kyverno ist ein Admission-Webhook: Der API-Server fragt Kyverno, bevor er ein Objekt speichert. Kyverno antwortet mit erlauben, ablehnen oder ändern.
  • Vier Controller: Admission (Webhooks), Background (Generate, Mutate-Existing), Reports (PolicyReports aus Hintergrund-Scans) und Cleanup (Löschregeln, Tag 12).
  • Seit Kyverno 1.15 gibt es CEL-basierte Typen (ValidatingPolicy, MutatingPolicy, GeneratingPolicy, ImageValidatingPolicy). In 1.19 ist ClusterPolicy deprecated.
  • validationActions steuert die Wirkung: Audit (nur melden), Warn (Warnung an den Client), Deny (ablehnen).
kubectl apply ──> API-Server ──> Mutating-Webhooks ──> Validating-Webhooks ──> etcd
                                   │                     │
                                   └──── kyverno-svc:443 ┘   (Admission-Controller)
Background-Controller ── Generate/Mutate-Existing ──> neue Objekte
Reports-Controller ───── Hintergrund-Scan ──────────> PolicyReports pro Ressource

Drill 1: Cluster und Demo-App

Der Cluster kyverno-lab kommt aus Tag 0 (~/guard-lab/kind/kyverno-lab.yaml). Zum Üben reicht ein Node: Lösch bei wenig RAM die beiden worker-Zeilen.

mkdir -p ~/guard-lab/tag07 && cd ~/guard-lab/tag07
cp -R ~/books/kyverno-networkpolicy-training/code/kyverno ~/guard-lab/code/
kind create cluster --config ~/guard-lab/kind/kyverno-lab.yaml
kubectl apply -f ~/guard-lab/code/demo/ >/dev/null
kubectl wait --for=condition=Ready pod --all -A --timeout=300s >/dev/null
kubectl get pods -A -l 'app in (frontend,api,db,scraper,client)' --no-headers | wc -l

Erwartet:

7

Fortschritt speichern? Kostenlos registrieren

Drill 2: Kyverno per Helm installieren

Erst die Version prüfen, dann installieren. Die Lab-Werte setzen jeden Controller auf eine Replika und erlauben Registries ohne gültiges TLS (Lab-Komfort, Tag 10 zeigt die Grenzen).

helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update kyverno
helm search repo kyverno/kyverno --versions -o json \
  | jq -r '.[:2][] | "\(.name) \(.version) \(.app_version)"'
cat ~/guard-lab/code/kyverno/tag07/values-lab.yaml

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

kyverno/kyverno 3.9.1 v1.19.1
kyverno/kyverno 3.9.0 v1.19.0
# Lab-Werte (Tag 7): eine Replika je Controller, unsichere Registries erlaubt
admissionController:
  replicas: 1
...
features:
  registryClient:
    allowInsecure: true
helm install kyverno kyverno/kyverno -n kyverno --create-namespace \
  --version 3.9.1 -f ~/guard-lab/code/kyverno/tag07/values-lab.yaml \
  --wait --timeout 8m
kubectl -n kyverno get deploy

Erwartet (gekürzt):

STATUS: deployed
Chart version: 3.9.1
Kyverno version: v1.19.1
⚠️  WARNING: Setting the admission controller replica count below 2 means Kyverno
is not running in high availability mode.
⚠️  WARNING: The legacy kyverno.io policy types are deprecated and will be removed
in a future release. Migrate to their policies.kyverno.io replacements:
    - ClusterPolicy / Policy → ValidatingPolicy, MutatingPolicy, GeneratingPolicy,
      ImageValidatingPolicy (and their namespaced variants)
NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
kyverno-admission-controller    1/1     1            1           2m49s
kyverno-background-controller   1/1     1            1           2m49s
kyverno-cleanup-controller      1/1     1            1           2m49s
kyverno-reports-controller      1/1     1            1           2m49s

Achtung: Die Images ziehen beim ersten Mal rund 300 MB. Läuft die Installation in den Timeout, prüf mit kubectl -n kyverno get pods auf ImagePullBackOff oder no space left on device und gib Docker mehr Platz.

Der Helm-Hinweis zur Deprecation ist der Grund, warum dieses Buch die neuen Typen nutzt.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Architektur im Cluster ansehen

kubectl get crd -o name | grep policies.kyverno.io | sed 's/.*\///'
kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations \
  -o custom-columns=NAME:.metadata.name,HOOKS:.webhooks[*].name | grep resource

Erwartet (gekürzt):

deletingpolicies.policies.kyverno.io
generatingpolicies.policies.kyverno.io
imagevalidatingpolicies.policies.kyverno.io
mutatingpolicies.policies.kyverno.io
namespaceddeletingpolicies.policies.kyverno.io
...
policyexceptions.policies.kyverno.io
validatingpolicies.policies.kyverno.io
kyverno-resource-validating-webhook-cfg   <none>
kyverno-resource-mutating-webhook-cfg     <none>

Noch keine Policy, also noch keine Webhook-Regeln (<none>). Kyverno registriert Webhooks dynamisch: nur für die Ressourcen, die eine Policy wirklich braucht. Das hält den API-Server schnell.

Controller Aufgabe Ausfall bedeutet
admission Webhooks: validate, mutate, verify images je nach failurePolicy blockiert
background GeneratingPolicy, Mutate-Existing keine neuen generierten Objekte
reports Hintergrund-Scans, PolicyReports Reports veralten
cleanup DeletingPolicy, TTL-Label nichts wird aufgeräumt

Fortschritt speichern? Kostenlos registrieren

Drill 4: Erste ValidatingPolicy im Audit-Modus

cd ~/guard-lab/tag07
cp ~/guard-lab/code/kyverno/tag07/{require-app-label,pod-ohne-label}.yaml .
cat require-app-label.yaml

Erwartet:

# Tag 7: erste ValidatingPolicy - jeder Pod in Demo-Namespaces braucht das Label app
apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
  name: require-app-label
spec:
  validationActions: [Audit]
  matchConstraints:
    resourceRules:
      - apiGroups: [""]
        apiVersions: [v1]
        operations: [CREATE, UPDATE]
        resources: [pods]
    namespaceSelector:
      matchLabels:
        guard-lab: demo
  validations:
    - expression: "has(object.metadata.labels) && 'app' in object.metadata.labels"
      message: "Pod braucht das Label app (z. B. app=api)."

Der Aufbau ist bewusst der von Kubernetes’ eigener ValidatingAdmissionPolicy: matchConstraints wählt aus, validations prüft per CEL, object ist das Objekt.

kubectl apply -f require-app-label.yaml
kubectl get vpol
kubectl get validatingwebhookconfiguration kyverno-resource-validating-webhook-cfg \
  -o jsonpath='{.webhooks[0].failurePolicy} {.webhooks[0].rules[*].resources}{"\n"}'

Erwartet:

validatingpolicy.policies.kyverno.io/require-app-label created
NAME                AGE   READY
require-app-label   5s    true
Fail ["pods"] ["daemonsets","deployments","replicasets","statefulsets"] ["cronjobs"]
["jobs"]

Warum Deployments und CronJobs im Webhook? Autogen: Kyverno übersetzt Pod-Regeln automatisch auf Pod-Controller. Ein falsches Deployment scheitert so schon beim apply und nicht erst still beim ReplicaSet.

kubectl apply -f pod-ohne-label.yaml

Erwartet:

pod/nolabel created

Im Audit-Modus kommt alles durch. Der Verstoß landet im Report (Drill 5).

Fortschritt speichern? Kostenlos registrieren

Drill 5: PolicyReports lesen

Der Reports-Controller schreibt pro Ressource einen PolicyReport (Kurzname polr) in deren Namespace. Gib ihm 20 bis 40 Sekunden.

kubectl get polr -n shop

Erwartet (gekürzt):

NAME                                   KIND         NAME              PASS   FAIL ...
14795326-85c9-4ced-b6a5-73e578ad135f   Deployment   api               1      0
48b6a355-629b-4043-a60e-8508813c3092   Deployment   frontend          1      0
5b790e1c-3eb1-4e64-a372-ccf0409eedb2   ReplicaSet   db-5d6755ff6b     1      0
9cb9fd4b-c97c-4267-b14f-18355ae9e27b   Pod          nolabel           0      1
...

Die Demo-Workloads bestehen, nolabel fällt durch. Die Details:

R=$(kubectl -n shop get polr \
  -o jsonpath='{.items[?(@.scope.name=="nolabel")].metadata.name}')
kubectl -n shop get polr "$R" -o yaml | sed -n '/^results/,/source/p'
kubectl -n shop get events --field-selector involvedObject.name=nolabel \
  | grep PolicyViolation

Erwartet:

results:
- message: Pod braucht das Label app (z. B. app=api).
  policy: require-app-label
  properties:
    cel.validationIndex: "0"
    process: background scan
  result: fail
  scored: true
  source: KyvernoValidatingPolicy
17s   Warning   PolicyViolation   pod/nolabel   policy require-app-label/ fail: Pod
braucht das Label app (z. B. app=api).

cel.validationIndex sagt dir, welche der validations gegriffen hat. Bei Policies mit vielen Regeln ist das Gold wert.

Tipp: Für eine UI über alle Reports gibt es den Policy Reporter (Tag 12).

Fortschritt speichern? Kostenlos registrieren

Drill 6: Warn und Deny

Warn lässt durch, zeigt dem Client aber eine Warnung. Deny lehnt ab.

kubectl -n shop delete pod nolabel
kubectl patch vpol require-app-label --type merge \
  -p '{"spec":{"validationActions":["Warn"]}}'
kubectl run warnme -n shop --image=nginxinc/nginx-unprivileged:1.31-alpine \
  --dry-run=server -o name
kubectl patch vpol require-app-label --type merge \
  -p '{"spec":{"validationActions":["Deny"]}}'
kubectl apply -f pod-ohne-label.yaml
kubectl run ok -n shop -l app=ok --image=nginxinc/nginx-unprivileged:1.31-alpine \
  --dry-run=server -o name

Erwartet:

pod "nolabel" deleted from shop namespace
validatingpolicy.policies.kyverno.io/require-app-label patched
Warning: Policy require-app-label failed: Pod braucht das Label app (z. B. app=api).
pod/warnme
validatingpolicy.policies.kyverno.io/require-app-label patched
Error from server: error when creating "pod-ohne-label.yaml": admission webhook
"vpol.validate.kyverno.svc-fail" denied the request: Policy require-app-label failed:
Pod braucht das Label app (z. B. app=api).
pod/ok

kubectl run setzt nur run=warnme, also kein app. --dry-run=server schickt das Objekt durch alle Webhooks, speichert es aber nicht: ideal, um Policies gefahrlos zu testen. [Audit, Warn] geht auch: melden und warnen zugleich.

Achtung: Schalte nie direkt auf Deny. Erst Audit, Reports eine Weile beobachten, Ausnahmen klären, dann Deny. Sonst stoppst du Deployments anderer Teams.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Kyverno-CLI ohne Cluster

Die CLI wendet Policies lokal auf YAML an: für CI und für schnelle Versuche. Die Labels der Namespaces kennt sie nicht, also gibst du sie in einer Werte-Datei mit.

cp ~/guard-lab/code/kyverno/tag07/values.yaml .
cat values.yaml
kyverno apply require-app-label.yaml -f values.yaml -r pod-ohne-label.yaml \
  -r ~/guard-lab/code/demo/10-shop.yaml
echo "rc=$?"

Erwartet:

apiVersion: cli.kyverno.io/v1alpha1
kind: Value
metadata:
  name: values
namespaceSelector:
  - name: shop
    labels:
      guard-lab: demo
Applying 1 policy rule(s) to 10 resource(s)...
policy require-app-label -> resource shop/Pod/nolabel failed:
1 -  Pod braucht das Label app (z. B. app=api).

pass: 3, fail: 1, warn: 0, error: 0, skip: 0
rc=1

pass: 3 sind die drei Deployments aus 10-shop.yaml (Autogen auch in der CLI). Ohne -f values.yaml meldet die CLI pass: 0, fail: 0, weil der namespaceSelector nichts trifft. Diese Falle kostet in CI gern eine Stunde. Ein Exit-Code ungleich 0 lässt die Pipeline scheitern, egal ob die Policy auf Audit steht.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
kubectl -n kyverno get deploy --no-headers | awk '$2!="1/1"{e=1} END{exit e}' \
  && ok "4 Kyverno-Controller bereit" || nok "Controller nicht bereit"
kubectl get crd validatingpolicies.policies.kyverno.io >/dev/null 2>&1 \
  && ok "CRD ValidatingPolicy" || nok "CRD fehlt"
[ "$(kubectl get vpol require-app-label -o jsonpath='{.spec.validationActions[0]}')" \
  = Deny ] && ok "require-app-label auf Deny" || nok "require-app-label nicht Deny"
kubectl apply -f pod-ohne-label.yaml --dry-run=server >/dev/null 2>&1 \
  && nok "Pod ohne app kommt durch" || ok "Pod ohne app abgelehnt"
kubectl get polr -n shop --no-headers 2>/dev/null | grep -q . \
  && ok "PolicyReports in shop" || nok "keine PolicyReports"
kyverno apply require-app-label.yaml -f values.yaml -r pod-ohne-label.yaml \
  >/dev/null 2>&1 && nok "CLI meldet keinen Fehler" || ok "CLI meldet Verstoß"

Challenge

Verschärfe require-app-label: Das Label app darf nicht leer sein und höchstens 30 Zeichen haben. Die Meldung soll den Pod-Namen und die tatsächliche Länge nennen. Prüf mit der CLI gegen challenge-pods.yaml aus dem Code-Ordner.

Hinweis: Optional-Zugriff object.metadata.?labels[?'app'].orValue('') liefert nie einen Fehler, und messageExpression baut die Meldung per CEL.

Lösung

cp ~/guard-lab/code/kyverno/tag07/{require-app-label-v2,challenge-pods}.yaml .
sed -n '/variables:/,$p' require-app-label-v2.yaml
kyverno apply require-app-label-v2.yaml -f values.yaml -r challenge-pods.yaml \
  -r pod-ohne-label.yaml

Erwartet:

  variables:
    - name: app
      expression: "object.metadata.?labels[?'app'].orValue('')"
  validations:
    - expression: "variables.app != '' && size(variables.app) <= 30"
      messageExpression: >-
        'Pod ' + object.metadata.name + ': Label app fehlt, ist leer oder zu lang ('
        + string(size(variables.app)) + ' Zeichen, max. 30).'
Applying 1 policy rule(s) to 3 resource(s)...
policy require-app-label -> resource shop/Pod/leer failed:
1 -  Pod leer: Label app fehlt, ist leer oder zu lang (0 Zeichen, max. 30).
policy require-app-label -> resource shop/Pod/lang failed:
1 -  Pod lang: Label app fehlt, ist leer oder zu lang (34 Zeichen, max. 30).
policy require-app-label -> resource shop/Pod/nolabel failed:
1 -  Pod nolabel: Label app fehlt, ist leer oder zu lang (0 Zeichen, max. 30).

pass: 0, fail: 3, warn: 0, error: 0, skip: 0

Mit kubectl apply -f require-app-label-v2.yaml ersetzt du die Policy im Cluster, denn der Name ist gleich.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Admission-Controller mit mindestens 3 Replikas und PodDisruptionBudget betreiben. Mit failurePolicy: Fail blockiert ein toter Kyverno sonst alle Deployments (Tag 12).
  • Kyverno-Namespace, kube-system und Operator-Namespaces bewusst ausnehmen oder testen. Ein Webhook, der Kyverno selbst blockiert, ist ein klassisches Henne-Ei-Problem.
  • Neue Policies immer erst Audit, Reports auswerten, dann Deny. Rollout per GitOps, nicht per kubectl patch.
  • Chart-Version fest pinnen (--version) und Upgrades im Staging testen: CRDs und API-Versionen ändern sich zwischen Minor-Versionen.
  • OpenShift bringt eigene SCCs mit, RKE2 Pod Security Admission. Kyverno ergänzt diese, ersetzt sie aber nicht automatisch (Tag 13).