Workload Identity

A workload identity is the core primitive in Riptides. It binds a cryptographic identity — a SPIFFE ID backed by an X.509 certificate or JWT token — to a specific workload running on a node. The kernel module uses this binding to authenticate workloads on every connection, transparently and without application changes.

SPIFFE IDs

Every workload identity maps to a SPIFFE ID, a URI-formatted identifier within a trust domain:

spiffe://example.com/frontend
spiffe://example.com/payment-service

SPIFFE IDs are not tied to network addresses or hostnames. They represent the workload itself, regardless of where it runs. This makes them stable across deployments, scaling events, and infrastructure changes.

SVIDs

Workloads prove their identity using SVIDs (SPIFFE Verifiable Identity Documents). Riptides supports two SVID types:

• X.509 SVIDs — Certificates used for mutual TLS. The SPIFFE ID is encoded in the certificate’s Subject Alternative Name (SAN) URI field. These are the primary identity credential for service-to-service communication.
• JWT SVIDs — Signed tokens used for federation with external systems. The SPIFFE ID appears in the sub claim. These are typically used when exchanging workload identity for cloud provider credentials via OIDC.

Both types are issued automatically by the platform and rotated before expiration without workload restarts.

How Workloads Are Identified

Workload identification is performed by the daemon. When a process opens a new network connection, the daemon evaluates the connecting process against selectors defined in the WorkloadIdentity resource, using metadata collected from the environment (Kubernetes pod labels, process names, namespaces, etc.).

Selectors describe workload attributes:

• Process selectors — Match by process name or command line (for example, process:name or process:cmdline).
• Kubernetes selectors — Match by pod label, namespace, or container name (for example, k8s:label:app, k8s:pod:namespace, k8s:container:name).
• OS selectors — Match by operating system (for example, linuxos:name).

A workload must satisfy all selectors in a WorkloadIdentity to receive that identity. This ensures that only the intended process, running in the correct context, can assume a given SPIFFE ID.

Example

A Next.js frontend running in Kubernetes might be identified by combining two selectors:

apiVersion: core.riptides.io/v1alpha1
kind: WorkloadIdentity
metadata:
  name: frontend
  namespace: riptides-system
spec:
  workloadID: frontend
  selectors:
    - k8s:label:app: frontend
      process:cmdline: node server.js

Only a process whose command line matches node server.js, running inside a pod with the label app=frontend, will receive the spiffe://example.com/frontend identity.

Identity Lifecycle

Issuance

When a new connection triggers evaluation and the daemon matches the connecting process to a WorkloadIdentity, the kernel module generates a private key in kernel memory and sends a certificate signing request (CSR) to the daemon. The daemon forwards it to the control plane. The resulting X.509 SVID is loaded back into the kernel module.

Rotation

Certificates are short-lived and automatically rotated before they expire. The daemon monitors certificate lifetimes and triggers renewal. The new certificate is loaded into the kernel module, and active connections are unaffected. No workload restart is required.

Revocation

When a WorkloadIdentity resource is deleted or a workload no longer matches its selectors, the corresponding identity is removed from the kernel module. Subsequent connections from that workload will no longer present the revoked identity.

Scope

WorkloadIdentity resources can be scoped to different levels:

• Daemon scope — The identity applies to workloads on a single node. This is the default when an daemon operates independently.
• DaemonGroup scope — The identity applies across a fleet of nodes managed by the same control plane. All daemons in the group receive the same identity policies, allowing the same workload identity to be used by instances of a service running on multiple nodes.

The control plane distributes identity policies to the appropriate daemons based on scope, ensuring consistent identity assignment across the infrastructure.