Identity and trust
Pod Certificates
1.What are Pod Certificates ?
A Pod asks for an X.509 certificate by adding a podCertificate source to a projected volume. The kubelet makes the key, sends a PodCertificateRequest (PCR), waits for a signer, then writes key plus chain into the Pod's tmpfs volume and keeps it fresh. No Secret.
- Alpha 1.34, beta 1.35 and 1.36 (off by default). GA in v1.37 :
certificates.k8s.io/v1, gate on, not locked in 1.37.
No signer in coreKubernetes ships the API, the kubelet and the admission plumbing only. Install a signer, or Pods wait forever. The one well-known name,
kubernetes.io/kube-apiserver-client-pod , is documented as unimplemented.2.The flow
- No approval step. The signer sets one of
Issued,Denied,Failedvia/status, then it is immutable. - The stub is an empty PKCS#10 request : its signature proves the kubelet holds the key.
- The API server checks the answer : requested key, lifetimes, clock skew.
- Trust side : mount the signer-linked bundle with
signerNamepluslabelSelector: {}(Private PKI).
3.The volume
| Field | Notes |
|---|---|
signerName | Required. <domain>/<path> : exactly one /, a domain of at least two labels |
keyType | Required. RSA3072, RSA4096, ECDSAP256, ECDSAP384, ECDSAP521, ED25519 |
maxExpirationSeconds | Default 86400, min 3600, max 7862400. At most 86400 for kubernetes.io/ signers |
credentialBundlePath | Recommended. One PEM : PRIVATE KEY first, then the chain, leaf first |
keyPath, certificateChainPath | Separate files. Can be read mid-rotation and not match |
userAnnotations | Copied into the PCR as unverified. Untrusted input |
user | Alpha, gate AtomicWriteVolumeUserFields. Owner UID of the files |
securityContext: {fsGroup: 2000}
volumes:
- name: creds
projected:
sources:
- podCertificate: {keyType: ED25519,
signerName: coolcert.example.com/foo,
credentialBundlePath: credentialbundle.pem}
- clusterTrustBundle: {labelSelector: {},
signerName: coolcert.example.com/foo,
path: ca.pem, optional: true}
- There is no field to ask for DNS or IP SANs. The signer picks them.
- The docs example sets
defaultMode: 0644: with no file owner and nofsGroup, any UID in the container can read the key. WithfsGrouporuser, the mode is forced to0600. - Never mount with
subPath: the file never updates.
4.Who vouches
- NodeRestriction : a node asks only for a Pod bound to it, with matching Pod, ServiceAccount and node UIDs. Never for a mirror (static) Pod. No Pod phase check.
- Since 1.37 the Pod must mount a
podCertificatesource naming that signer, or the node passes an extra authorization check. - So a signer can trust
podName,serviceAccountName,nodeNameand their UIDs. NeverunverifiedUserAnnotations: any Pod author writes those.
In short : A Pod names a signer and a key type. The kubelet makes the key and asks, the API server vouches for the Pod and its ServiceAccount, a signer signs, and the app reads one file.
1.The PodCertificateRequest
- ObjectNamespaced. The kubelet creates it with
generateName: req-and an ownerReference to the Pod (Garbage Collection). - SpecImmutable :
signerName,podName/podUID,serviceAccountName/serviceAccountUID,nodeName/nodeUID,maxExpirationSeconds,stubPKCS10Request,unverifiedUserAnnotations. - StatusOne update, then immutable : one condition,
certificateChain(leaf first),notBefore,notAfter,beginRefreshAt. - Deny reasons
UnsupportedKeyType,InvalidUnverifiedUserAnnotations. No short name :kubectl get pcrfails.
2.States
- Metric :
kubelet_podcertificate_states{signer_name, state}, six states. - Refresh starts at
beginRefreshAtplus 0 to 5 minutes of jitter, with a new key. - Files are swapped atomically. The app must notice (inotify or polling).
- KEP suggestion : 24 h certs refreshed at 12 h ride out a 12 h control plane outage.
3.The numbers
| What | Value |
|---|---|
| Default lifetime | 24 h |
| Minimum | 1 h |
| Maximum | 91 days |
kubernetes.io/ signers | at most 24 h |
| Refresh jitter | 0 to 5 min after beginRefreshAt |
| Refresh pass | every 1 to 2 min |
| Overdue event | 10 min past the jittered time |
| PCR deleted | 15 min after creation, any state |
| Cleaner runs | every 5 min |
Signer notBefore | within 5 min of the API server clock |
beginRefreshAt | 10 min inside notBefore and notAfter |
4.What goes wrong
- No signer answers : the Pod sits in
ContainerCreating, with a fresh key and PCR every 15 to 20 minutes. - Denied or Failed is permanent, on first issue and on refresh. Only a new Pod helps.
- Expired is quiet : the kubelet keeps serving the old files. One
CertificateExpiredevent, theexpiredstate. - One failing source blocks the whole projected volume write.
- A kubelet restart re-keys and re-requests everything.
- The app must reload the file. Kubernetes sends no signal.
5.Commands
| Command | Shows |
|---|---|
kubectl get podcertificaterequests -A | Recent PCRs. Only the last 15 to 20 minutes survive |
kubectl get podcertificaterequests -n <ns> <name> -o yaml | Condition, timestamps and chain |
kubectl explain pod.spec.volumes. | Field docs from the live server |
kubectl api-resources --api-group= | Is the API served ? |
kubectl get events --field-selector involvedObject.name=<pod> | Denied, Failed, CertificateOverdueForRefresh, CertificateExpired |
kubelet_podcertificate_states | Kubelet /metrics. Alert on it (Prometheus) |
In short : The kubelet re-keys and re-requests at
beginRefreshAt, and a PCR lives only 15 minutes. Denied is permanent and expired is quiet, so alert on the kubelet metric and make the app reload.1.Who ships a signer (2026-10-08)
- Nobody in core. Upstream expects in-tree signers for Service DNS and SPIFFE client certs, no version given.
- cert-manager v1.21.2 : no PCR support. Its CSR signers serve CertificateSigningRequests.
- SPIRE v1.15.3 : no PCR signer.
- A toy reference signer (by the KEP author) and a community signer exist : third-party, unvetted.
A signer is a controller. What it needs (RBAC) :
| Right | Notes |
|---|---|
sign on signers | Name <domain>/<path> or <domain>/*. Checked when a status update changes the status |
update on status | On podcertificaterequests/status : write the answer |
attest on signers | Publish its ClusterTrustBundle |
2.Writing a signer
- Own a name :
example.com/<path>, neverkubernetes.io/. - Watch PCRs, filter on
spec.signerName. - Trust only API-checked fields. Deny with
InvalidUnverifiedorUserAnnotations UnsupportedKeyType. - Sign the stub's key. SANs by policy :
spiffe://<td>/ns/<ns>/sa/<sa>or<svc>.<ns>.svc. - Lifetime and
beginRefreshAtinside the rules, clock within 5 minutes. - Answer well inside 15 minutes.
- Publish the CA in a signer-linked ClusterTrustBundle, rotate with overlap (Private PKI).
Skew : a v1-only signer cannot serve kubelets older than 1.36. v1 dropped pkixPublicKey, proofOfPossession.
3.Compared
| PCR | CSR | |
|---|---|---|
| Scope | namespaced | cluster-scoped |
| Asker | the kubelet, for a Pod on its node | any user with create |
| Approve | none | an Approved condition |
| Content | empty stub, key only | the full CSR |
| Lives | 15 min after creation | 1 h approved or denied, 24 h pending |
| Use | workload identity | kubelet and user certs |
| Pod Certificates | SPIRE | |
|---|---|---|
| Delivery | projected volume, kubelet writes | Workload API socket via csi.spiffe.io |
| Proof | API server NodeRestriction | node and workload attestation |
| Formats | X.509 only | X.509 and JWT SVIDs |
| Rotation | kubelet swaps files, app reloads | pushed over the Workload API |
| Install | a signer | server, agents, CSI driver |
IDs and SVIDs : SPIFFE, SPIRE. cert-manager's csi-driver and csi-driver-spiffe also put certs in Pods. Replacing a mesh is a KEP non-goal.
4.Seen in practice
- A v1.37 cluster serves
certificates.k8s.io/v1PodCertificateRequests and ClusterTrustBundles with no flags, but nothing uses them until you deploy a signer. - Often the only ClusterTrustBundle is the one kube-controller-manager publishes for
kubernetes.io/.kube-apiserver-serving - Clusters on SPIRE lean on JWT-SVIDs (OpenBao logins, object storage STS; see OIDC). X.509-only Pod Certificates do not replace them.
- Where it fits : operators that take projected volumes but no CSI, like CloudNativePG's
projectedVolumeTemplate. A signer backed by your private CA avoids a SPIRE-to-Secret bridge.
In short : No signer ships in core, so install or write one (
sign, status update, attest). Pick Pod Certificates for kubelet-made X.509 without a CSI driver, SPIRE for JWTs and attestation.