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

Pod spec podCertificate source kubelet key in memory, empty stub kube-apiserver NodeRestriction, stub check PCR req-xxxxx in the Pod's namespace signer Issued + chain kubelet writes the PEM file app reads, must reload ClusterTrustBundle ca.pem, same volume
  • No approval step. The signer sets one of Issued, Denied, Failed via /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 signerName plus labelSelector: {} (Private PKI).

3.The volume

FieldNotes
signerNameRequired. <domain>/<path> : exactly one /, a domain of at least two labels
keyTypeRequired. RSA3072, RSA4096, ECDSAP256, ECDSAP384, ECDSAP521, ED25519
maxExpiration­SecondsDefault 86400, min 3600, max 7862400. At most 86400 for kubernetes.io/ signers
credentialBundle­PathRecommended. One PEM : PRIVATE KEY first, then the chain, leaf first
keyPath, certificate­ChainPathSeparate files. Can be read mid-rotation and not match
userAnnotationsCopied into the PCR as unverifiedUserAnnotations. Untrusted input
userAlpha, gate AtomicWriteVolume­UserFields. 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 no fsGroup, any UID in the container can read the key. With fsGroup or user, the mode is forced to 0600.
  • 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 podCertificate source naming that signer, or the node passes an extra authorization check.
  • So a signer can trust podName, serviceAccountName, nodeName and their UIDs. Never unverifiedUserAnnotations : 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 reasonsUnsupportedKeyType, InvalidUnverifiedUserAnnotations. No short name : kubectl get pcr fails.

2.States

PCR created one answer, once, then immutable Issued Denied Failed kubelet, per projection (metric states) not_yet_issued fresh refresh : new key, new PCR, at beginRefreshAt retried denied, failed first issue or refresh permanent expired still served overdue_for_refresh 10 min late
  • Metric : kubelet_podcertificate_states {signer_name, state}, six states.
  • Refresh starts at beginRefreshAt plus 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

WhatValue
Default lifetime24 h
Minimum1 h
Maximum91 days
kubernetes.io/ signersat most 24 h
Refresh jitter0 to 5 min after beginRefreshAt
Refresh passevery 1 to 2 min
Overdue event10 min past the jittered time
PCR deleted15 min after creation, any state
Cleaner runsevery 5 min
Signer notBeforewithin 5 min of the API server clock
beginRefreshAt10 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 CertificateExpired event, the expired state.
  • 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

CommandShows
kubectl get podcertificaterequests -ARecent PCRs. Only the last 15 to 20 minutes survive
kubectl get podcertificaterequests -n <ns> <name> -o yamlCondition, timestamps and chain
kubectl explain pod.spec.volumes.projected.sources.podCertificateField docs from the live server
kubectl api-resources --api-group=certificates.k8s.ioIs the API served ?
kubectl get events --field-selector involvedObject.name=<pod>Denied, Failed, Certificate­OverdueForRefresh, CertificateExpired
kubelet_podcertificate_states{state=~"expired|overdue_for_refresh|denied|failed"}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) :

RightNotes
sign on signersName <domain>/<path> or <domain>/*. Checked when a status update changes the status
update on statusOn podcertificate­requests/status : write the answer
attest on signersPublish its ClusterTrustBundle

2.Writing a signer

  1. Own a name : example.com/<path>, never kubernetes.io/.
  2. Watch PCRs, filter on spec.signerName.
  3. Trust only API-checked fields. Deny with InvalidUnverifiedUserAnnotations or UnsupportedKeyType.
  4. Sign the stub's key. SANs by policy : spiffe://<td>/ns/<ns>/sa/<sa> or <svc>.<ns>.svc.
  5. Lifetime and beginRefreshAt inside the rules, clock within 5 minutes.
  6. Answer well inside 15 minutes.
  7. Publish the CA in a signer-linked ClusterTrustBundle, rotate with overlap (Private PKI).
PCR signerName, Pod, SA, node signer controller policy identity to SANs, lifetime /status Issued + chain CA key signs signer-linked ClusterTrustBundle clusterTrustBundle source Pods verify peers

Skew : a v1-only signer cannot serve kubelets older than 1.36. v1 dropped pkixPublicKey, proofOfPossession.

3.Compared

PCRCSR
Scopenamespacedcluster-scoped
Askerthe kubelet, for a Pod on its nodeany user with create
Approvenonean Approved condition
Contentempty stub, key onlythe full CSR
Lives15 min after creation1 h approved or denied, 24 h pending
Useworkload identitykubelet and user certs
Pod CertificatesSPIRE
Deliveryprojected volume, kubelet writesWorkload API socket via csi.spiffe.io
ProofAPI server NodeRestrictionnode and workload attestation
FormatsX.509 onlyX.509 and JWT SVIDs
Rotationkubelet swaps files, app reloadspushed over the Workload API
Installa signerserver, 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/v1 PodCertificateRequests 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.