SPIFFE & SPIRE Cheatsheet

Canonical SPIFFE ID format. Trust domain is your organisation; path identifies the workload.

Production note: Use a hierarchical path that mirrors deployment scope: /ns/<namespace>/sa/<service-account> on Kubernetes.

Production-style SPIFFE ID. Encodes cluster, namespace, and service account in the path so authz can prefix-match.

Production note: Pick the trust domain once; changing it later requires re-issuing every SVID across the fleet.

X.509 certificate whose URI SAN is the SPIFFE ID. Used for mTLS handshakes.

Production note: Default TTL in SPIRE is 1 hour with rotation at half-life. Tune via -ttl on the registration entry.

Signed JWT with the SPIFFE ID in the `sub` claim. For HTTP/gRPC services that cannot terminate TLS themselves.

Warning: JWT SVIDs are bearer tokens — anyone who steals them can impersonate the workload until they expire. Prefer X.509 mTLS where possible.

Start the SPIRE Server with the given config file. Server holds the trust domain CA and issues SVIDs.

Production note: Run as a StatefulSet on Kubernetes with persistent storage for the datastore. HA needs an external SQL backend.

Generate a one-time join token to bootstrap a SPIRE Agent. Use only when no native attestation method is available.

Warning: Join tokens are bearer secrets. Prefer node-level attestation (k8s_psat, aws_iid, gcp_iit, k8s_sat) in production.

Print the trust bundle (CA chain) for this trust domain. Federate it to peer trust domains.

Production note: Combine with the Bundle Endpoint protocol (`-format pem` for static seeding).

Liveness probe. Exits 0 when the server is ready to serve.

Production note: Wire into Kubernetes liveness/readiness probes. Combine with prometheus_metrics for SLOs.

Start the SPIRE Agent on a node. Attests workloads via local OS or Kubernetes signals and proxies the Workload API.

Production note: Deploy as a DaemonSet; mount /run/spire/agent.sock as the Workload API endpoint for pods.

Fetch the current X.509 SVID for the workload calling the Workload API. Used for diagnostics.

Production note: In code, use the go-spiffe SDK (workloadapi.NewX509Source) so rotation is automatic.

Mint a JWT SVID with the given audience. Audience is the receiving service URL.

Warning: Always validate `aud` on the receiving end — a JWT minted for service A must not be accepted by service B.

Verify the agent has registered with the server and is serving the Workload API.

Production note: If agent healthcheck passes but workloads cannot fetch SVIDs, the registration entries are missing or the selectors do not match.

Create a registration entry. The agent issues the SVID to any workload that matches all selectors AND descends from the parent.

Production note: Combine multiple selectors (k8s:ns + k8s:sa + k8s:image-id) so identity binds to the specific deployment, not just the namespace.

Show all registration entries on this server. Pipe through grep to find the entry for a specific SPIFFE ID.

Production note: In production, manage entries declaratively with the SPIRE Controller Manager (CRDs ClusterSPIFFEID + ClusterFederatedTrustDomain) instead of imperative CLI.

Update an existing entry. -ttl sets SVID validity in seconds (default 3600).

Production note: Shorter TTLs reduce blast radius of leaked SVIDs but increase load on SPIRE Server. 600–3600s is typical for production.

Delete a registration entry. Workload loses identity at next refresh.

Warning: Plan deletes carefully — services using the SVID will fail TLS handshakes within minutes.

Match pods in a specific Kubernetes namespace.

Warning: Single-selector entries on namespace alone match every pod in the namespace — a misplaced pod gets the SVID.

Match pods running under a specific ServiceAccount.

Production note: Combine with k8s:ns: for tenant + role scoping.

Match pods with a specific label.

Production note: Use for "app=payments-api" style identity binding when ServiceAccounts are shared.

Match pods running a specific container image (by digest).

Production note: Strongest selector — binds identity to the exact image hash. Combine with k8s:ns: and k8s:sa: for defence in depth.

Unix Workload Attestor selectors. Match the calling process by UID, path, or SHA256.

Production note: Use for VM / non-Kubernetes workloads. unix:sha256:<digest> binds identity to the specific binary.

Federate with another trust domain. SPIRE will fetch the peer's trust bundle dynamically over the bundle endpoint.

Production note: https_web uses public CA validation for the bundle endpoint (simplest). https_spiffe uses a SPIFFE ID for endpoint authentication (most secure).

Show configured federation relationships.

Production note: Workloads can authenticate peers in any federated trust domain — combine with authz policy that allowlists the peer SPIFFE IDs you trust.

Static seed of a peer trust bundle. One-time bootstrap before bundle endpoint takes over.

Warning: Static bundles go stale. Always pair with bundle endpoint for ongoing rotation.

Confirm the registration entry exists with the expected selectors.

Production note: If empty: the entry was never created (most common cause).

Tail the SPIRE Agent on the node where the workload is running. Look for "Workload not registered" or selector-mismatch messages.

Production note: Run on the right node — DaemonSet means there is one agent per node.

From inside the workload pod (or via kubectl exec), call the Workload API directly to see what (if anything) the agent issues.

Production note: If empty here but entry exists: selectors do not match. Compare actual pod labels/SA to what the entry expects.

List all entries scoped to a namespace. Useful when entries were created with overly broad selectors.

Warning: If an entry matches more workloads than intended, every match gets the same SVID — review selectors carefully.