The Quint admission webhook

What the quint-admission webhook refuses in a governed namespace, how to run it, and how it signs and delivers the record that makes a run contained.

Quint on Kubernetes is early access. The Quint container images, the Helm charts and the admission webhook are not available for download. Your Quint contact gives you each of them, with the image digests for your release, so talk to your Quint contact before you plan an install.

quint-admission is a validating admission webhook. It checks every pod in a namespace labelled quintai.dev/governed=true before Kubernetes creates or changes it, and refuses any pod that would let the agent get around Quint. Both the standard and the restricted setup need it. On a cluster you run yourself it also signs a record of each pod it admits, which is what lets Quint record a run as contained.

​

What the webhook refuses

In a governed namespace, the webhook refuses a pod when:

• Quint’s containers are missing, in the wrong order, or use images that are not pinned by digest or not on the webhook’s list.
• The agent, or any other container that is not Quint’s, runs as root or as a user other than agentUID, can gain privileges, or adds any capability.
• The pod shares the node’s process, network or IPC namespace, or shares one process namespace between its containers.
• The pod mounts the service account token, a hostPath volume or an inline csi volume, or the agent can read Quint’s own volumes, Secrets or ConfigMaps.
• The pod sets any fsGroup, or pod-level supplementalGroups in the standard setup.
• A Quint container has extra mounts, environment variables outside the webhook’s list, a Quint API or ingest address the webhook was not given, or CPU and memory requests below the webhook’s floors.
• The pod uses the older single-container Quint layout (qhelper.mode=inprocess).
• The pod has a field the webhook does not know.
• The pod’s name contains a dot and it sets no spec.hostname, or its hostname names the loopback, such as localhost.

On a running pod it refuses any change to a Quint container, a resize of a Quint container, kubectl exec and kubectl attach into a Quint container, and kubectl port-forward to the pod. An ephemeral container from kubectl debug is admitted only if the whole pod still passes. Your agent container may still be resized, and you can still kubectl exec into it.

Pod status updates are checked by the quint-status-annotations ValidatingAdmissionPolicy instead, which refuses a status update that adds, changes or removes a quintai.dev/* annotation or adds a container runtime annotation. Install it once per cluster; see Install the status policy.

​

Run the webhook

Get the quint-admission webhook from your Quint contact, and ask how to run it in your cluster. It is not available for download. The Quint images you name in --sidecar-image and --qhelper-image, and their digests, come from your Quint contact too.

serve refuses to start without digest-pinned Quint images. Run it in the quint-system namespace behind a Service named quint-admission, then register it with the API server:

quint-admission serve --tls-cert tls.crt --tls-key tls.key \
  --sidecar-image REG/quint-sidecar@sha256:<digest> --qhelper-image REG/quint-qhelper@sha256:<digest> \
  --signing-key /signing/ed25519.key --org-id <your organisation ID> \
  --client-ca /client-ca/ca.crt --client-identity kube-apiserver-admission-client
quint-admission webhook-config --service-namespace quint-system --ca-bundle ca.crt | kubectl apply -f -

Send the output of quint-admission key-entry --public-key pub.pem, run on the signing key’s public half, to your Quint contact so Quint can check your webhook’s records. Until Quint has registered that key, every run is recorded as unverified.

​

Signed records need the API server’s client certificate

The webhook signs a record only when the request reached it over the API server’s own client certificate. Give the API server that certificate with kube-apiserver --admission-control-config-file, and start the webhook with --client-ca set to a CA that signs that one certificate only. Never use the cluster CA as --client-ca. It signs every kubelet’s and user’s certificate, so any of them could get a record signed.

Amazon EKS and Google GKE managed clusters do not let you set --admission-control-config-file. There the webhook still checks every pod and refuses those that break the rules, but signs no record, so runs stay unverified. The webhook also signs no record for pods in the restricted setup.

A record says the pod met the rules when it was created. If someone later removes the namespace’s quintai.dev/governed label, the webhook stops checking that namespace. Treat the right to change namespace labels as cluster-admin.

​

Record delivery

Without delivery, every run is unverified. With it, the webhook keeps each record it signs and hands it to the pod it names, and the Quint sidecar presents it when the run registers. Start the webhook with:

quint-admission serve ... \
  --record-url https://quint-admission.quint-system.svc/v1/record \
  --record-addr <the Service's ClusterIP>:443 --record-ca-file serving-ca.crt

Then install the quint-sidecar chart, which comes from your Quint contact, with the same values: admissionRecord.enabled=true, admissionRecord.url, admissionRecord.addr, and admissionRecord.caBundle set to the CA that signed the webhook’s serving certificate (--set-file admissionRecord.caBundle=ca.crt). Only the Quint sidecar sees these; the agent never does. Delivery works in the standard setup only.

The webhook’s service account needs:

# ClusterRole, bound to the webhook's service account
- {apiGroups: [authentication.k8s.io], resources: [tokenreviews], verbs: [create]}
- {apiGroups: [""], resources: [pods], verbs: [get]}
# Role in the webhook's namespace
- {apiGroups: [""], resources: [secrets], verbs: [create, get, list, delete]}

Keep these in mind:

• The webhook serves a record only to a connection from the pod’s own address. On a network that rewrites pod source addresses to a Service backend, every fetch is refused and runs stay unverified.
• If you let Quint reach private ranges (--allowed-private-cidrs on the webhook, QUINT_ALLOW_PRIVATE_CIDRS on the sidecar), also set --record-refuse-cidrs to the ranges the webhook’s pods get their addresses from, and the same value as admissionRecord.refuseCIDRs.
• A record is kept for 15 minutes and served once. If storing it fails, the pod is still admitted and that run is unverified.

​

Rotate the record CA

--record-ca-file can be given more than once, and each pod’s CA must match one of them.

1. Issue the new CA and restart the webhook with --record-ca-file old.crt --record-ca-file new.crt. It keeps serving with its old certificate.
2. Switch the webhook’s serving certificate to one signed by the new CA.
3. Set the new admissionRecord.caBundle on your workloads and roll the pods. Do this promptly: until then, a new pod with the old CA fails its TLS check and registers unverified.
4. Once no pod carries the old CA, restart the webhook with --record-ca-file new.crt only.

​

Next

• Standard setup