API machinery
Admission Control
1.What is admission control ?
The API server's last gate before etcd. Admission plugins can change a write, then reject it.
- Runs in kube-apiserver after authn and authz. Writes only : create, update, delete, connect.
- Mutating plugins may change the object. Validating plugins only say yes or no.
- One rejection, in either phase, fails the request.
- Only new writes are checked. Existing objects are left alone.
Any reject in either phase ends the request with an error.
2.Inside admission, in order (v1.37)
- Built-in mutators first : ServiceAccount, DefaultStorageClass, LimitRanger ...
- Then each bound MutatingAdmissionPolicy (CEL).
- Then mutating webhooks, serial, any order.
- Object changed ? Built-ins run again, and
reinvocationPolicy: IfNeededhooks may too. - Schema check, built-in validators (PodSecurity ...), ValidatingAdmissionPolicies, validating webhooks (parallel), ResourceQuota last. One deny is enough.
3.Built-in plugins
Compiled into kube-apiserver, 25 on by default in v1.37. Change the set with --enable-admission-plugins / --disable-admission-plugins (order does not matter).
| Plugin | Type | What it does |
|---|---|---|
| NamespaceLifecycle | M | Rejects objects in missing or terminating namespaces. default, kube-system, kube-public cannot be deleted |
| LimitRanger | M + V | Applies LimitRange defaults, enforces the namespace min / max |
| ResourceQuota | V | Rejects a write that would push the namespace past its quota |
| ServiceAccount | M + V | Defaults the SA to default, rejects a missing SA, adds the API token volume |
| PodSecurity | V | Pod Security Standards from namespace labels (stable v1.25), see Pod Security |
| DefaultStorageClass | M | New PVC with no class gets the default one. Create only, newest default wins |
M = mutating, V = validating.
4.Picking a mechanism
| Mechanism | Runs in, logic in | Good for |
|---|---|---|
| ValidatingAdmissionPolicy | kube-apiserver, CEL (GA v1.30) | Deny / warn / audit rules, no server to run |
| MutatingAdmissionPolicy | kube-apiserver, CEL (GA v1.36) | Simple defaults : labels, sidecars, PSA labels |
| Validating webhook | your HTTPS server, any language | Complex rules, external data. Called in parallel |
| Mutating webhook | your HTTPS server, any language | Complex mutation, external APIs. Called serially |
| Kyverno (v1.19) | webhooks, YAML + CEL | Policy library, generate / cleanup, image checks |
| OPA Gatekeeper | webhooks, Rego | ConstraintTemplate + Constraint, audits old objects |
1.Webhooks : how a call works
- Register in a Mutating or ValidatingWebhookConfiguration (v1).
- The API server POSTs an AdmissionReview. The reply echoes
request.uidand setsallowed. - Changes return as a base64 JSONPatch.
warnings[]reach the client as Warning headers (code 299).
- clientConfig : a Service (port 443, path / by default) or an https URL.
- caBundle : CA for the serving cert, valid for
<svc>.<ns>.. Filled by cert-manager's cainjector, see cert-manager.svc
2.Webhook settings
| Field | Values | Default | Notes |
|---|---|---|---|
| failurePolicy | Fail, Ignore | Fail | Errors and timeouts only. allowed: false always denies |
| timeoutSeconds | 1 to 30 | 10 | On timeout, failurePolicy decides |
| sideEffects | None, NoneOnDryRun | required | Legacy v1beta1 Some / Unknown fail dry-run |
| matchPolicy | Exact, Equivalent | Equivalent | Also catches other group / versions of the resource |
| namespaceSelector | label selector | all | Leave out kube-system and the webhook's own namespace |
| objectSelector | label selector | all | Opt-in hooks only : whoever writes the labels can skip it |
| matchConditions | up to 64 CEL | none | Called only if all are true (GA v1.30) |
| reinvocationPolicy | Never, IfNeeded | Never | Mutating only. IfNeeded needs an idempotent hook |
Matching : rules (operations, apiGroups, apiVersions, resources, scope), then the two selectors and matchConditions. Since v1.37 (beta, on by default), TokenReview, SubjectAccessReview and other virtual auth resources skip webhooks.
3.ValidatingAdmissionPolicy : CEL, no server
# demo : at most 5 replicas per Deployment apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingAdmissionPolicy metadata: name: max-replicas.example.com spec: matchConstraints: resourceRules: - apiGroups: ["apps"] apiVersions: ["v1"] operations: ["CREATE", "UPDATE"] resources: ["deployments"] validations: - expression: "object.spec.replicas <= 5" --- apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingAdmissionPolicyBinding metadata: name: max-replicas-demo.example.com spec: policyName: max-replicas.example.com validationActions: [Deny] # [Warn, Audit] to trial matchResources: namespaceSelector: matchLabels: kubernetes.io/metadata.name: demo
- GA since v1.30. Does nothing until a binding names it in
policyName. failurePolicy defaults to Fail. validationActions: Deny, Warn, Audit. Never Deny and Warn together.paramKind+paramRefpass a ConfigMap or any CR to CEL asparams.parameterNotFoundAction(Allow / Deny) is required.- CEL sees
object,oldObject(null on CREATE),request,namespaceObject,variables,authorizer. Type errors :status..typeChecking
reinvocationPolicy is required. Binds the same way.Manifest-based admission (beta v1.37) : staticManifestsDir loads webhooks and policies from disk, enforced from API server start, even with etcd down. Names end in .static.k8s.io.
4.When a webhook goes down
- namespaceSelector : skip kube-system, own ns.
- 2+ replicas behind the Service.
- Mutating hooks fail open, a validator checks.
- Small timeoutSeconds : mutating hooks are serial.
- Break glass :
kubectl deletethe Validating / MutatingWebhookConfiguration