SPIRL Bridge

SPIRL Bridge is a sidecar service that provides SPIFFE SVIDs (X.509 certificates or JWT tokens) to applications running in Kubernetes or standalone environments. It watches for credential updates from the Defakto Agent and delivers them to applications as files.

Overview

SPIRL Bridge serves as a bridge between the Defakto Agent and your applications, providing:

• X.509 Certificate Management: Automatic retrieval and rotation of X.509-SVIDs
• JWT Token Management: Automatic retrieval and rotation of JWT-SVIDs with audience support
• Federation Support: Handling of federated trust domain certificates
• Content Control: Configurable credential delivery (identity only, bundles only, or full credentials)
• Flexible Output: Credentials delivered via files or environment variables
• Kubernetes Integration: Automatic sidecar injection via annotations

Prerequisites

1. Version v0.26.0-rc1 or greater of spirl-system must be installed.
2. Defakto Agent must be running on the node.
3. SPIRL Bridge must have write access to directories specified in command-line flags or Kubernetes pod annotations.

Standalone Configuration

Command-Line Flags

Run spirl-bridge as a standalone service using command-line flags or environment variables.

Basic Usage

spirl-bridge [flags]

info

1. At least one of the *-path flags must be set.
2. The --x509-cert-path and --x509-key-path flags must be set together.
3. When --jwt-token-path is set, --jwt-audience must also be set.

Socket Configuration

Flag	Environment Variable	Description	Default
--socket-path	SPIFFE_ENDPOINT_SOCKET	Path to the Defakto Agent socket	unix:///var/run/spirl/sockets/agent.sock
--include-federation	BRIDGE_INCLUDE_FEDERATION	Include federated trust domains in bundles	false

X.509 Certificate Configuration

Flag	Environment Variable	Description	Default
--x509-cert-path	BRIDGE_X509_CERT_PATH	Full path to write X.509 certificate (e.g., /run/spirl/certs/cert.pem)	Empty
--x509-key-path	BRIDGE_X509_KEY_PATH	Full path to write X.509 private key (e.g., /run/spirl/certs/key.pem)	Empty
--x509-bundle-path	BRIDGE_X509_BUNDLE_PATH	Full path to write X.509 Certificate Authority bundle (e.g., /run/spirl/certs/bundle.pem)	Empty

JWT Token Configuration

Flag	Environment Variable	Description	Default
--jwt-audience	BRIDGE_JWT_AUDIENCE	JWT audience claim(s). Multiple audiences can be specified as comma-separated values (e.g., "aud1,aud2")	Empty
--jwt-token-path	BRIDGE_JWT_TOKEN_PATH	Full path to write JWT-SVID token (e.g., /run/spirl/jwt/token.jwt)	Empty
--jwt-bundle-path	BRIDGE_JWT_BUNDLE_PATH	Full path to write JWT Bundle file (e.g., /run/spirl/jwt/bundle.jwt)	Empty

Example Configurations

X.509 Credentials Only

spirl-bridge \
  --x509-cert-path /var/run/creds/cert.pem \
  --x509-key-path /var/run/creds/key.pem \
  --x509-bundle-path /var/run/creds/bundle.pem

JWT Credentials with Bundle

spirl-bridge \
  --jwt-audience my-service \
  --jwt-token-path /var/run/creds/token.jwt \
  --jwt-bundle-path /var/run/creds/jwt-bundle.pem

Combined X.509 and JWT

spirl-bridge \
  --x509-cert-path /var/run/creds/cert.pem \
  --x509-key-path /var/run/creds/key.pem \
  --x509-bundle-path /var/run/creds/bundle.pem \
  --jwt-audience my-service \
  --jwt-token-path /var/run/creds/token.jwt \
  --jwt-bundle-path /var/run/creds/jwt-bundle.pem

JWT Bundle Only (for verification)

spirl-bridge \
  --jwt-bundle-path /var/run/creds/jwt-bundle.pem

Kubernetes Integration

SPIRL Bridge integrates with Kubernetes through automatic sidecar injection using pod annotations. The Defakto Controller watches for annotated pods and automatically injects the sidecar.

Pod Annotations

Core Annotations

Annotation	Values	Description
bridge.spirl.com/inject	*, container1,container2	Target containers for injection
bridge.spirl.com/include-federation	true, false	Include federated trust domain certificates

X.509 Configuration Annotations

Annotation	Description	Example
bridge.spirl.com/x509-cert-path	Full path for X.509 certificate	/run/spirl/certs/cert.pem
bridge.spirl.com/x509-key-path	Full path for X.509 private key	/run/spirl/certs/key.pem
bridge.spirl.com/x509-bundle-path	Full path for X.509 CA bundle	/run/spirl/certs/bundle.pem

JWT Configuration Annotations

Annotation	Description	Example
bridge.spirl.com/jwt-audience	JWT audience claim (required for JWT)	my-service
bridge.spirl.com/jwt-token-path	Full path for JWT token	/run/spirl/jwt/token.jwt
bridge.spirl.com/jwt-bundle-path	Full path for JWT CA bundle	/run/spirl/jwt/bundle.jwt

Example Pod Configurations

Basic X.509 Injection

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  annotations:
    bridge.spirl.com/inject: "*"
    bridge.spirl.com/x509-cert-path: "/run/spirl/certs/cert.pem"
    bridge.spirl.com/x509-key-path: "/run/spirl/certs/key.pem"
    bridge.spirl.com/x509-bundle-path: "/run/spirl/certs/bundle.pem"
spec:
  containers:
  - name: app
    image: my-app:latest
    volumeMounts:
    - name: spirl-cert-bundle-key
      mountPath: /run/spirl/certs
      readOnly: true

X.509 Injection With Federation

apiVersion: v1
kind: Pod
metadata:
  name: my-app-no-federation
  annotations:
    bridge.spirl.com/inject: "*"
    bridge.spirl.com/x509-cert-path: "/run/spirl/certs/cert.pem"
    bridge.spirl.com/x509-key-path: "/run/spirl/certs/key.pem"
    bridge.spirl.com/x509-bundle-path: "/run/spirl/certs/bundle.pem"
    bridge.spirl.com/include-federation: "true"
spec:
  containers:
  - name: app
    image: my-app:latest
    volumeMounts:
    - name: spirl-cert-bundle-key
      mountPath: /run/spirl/certs
      readOnly: true

JWT with Bundle Support

apiVersion: v1
kind: Pod
metadata:
  name: jwt-app
  annotations:
    bridge.spirl.com/inject: "*"
    bridge.spirl.com/jwt-audience: "my-service"
    bridge.spirl.com/jwt-token-path: "/run/spirl/jwt/token.jwt"
    bridge.spirl.com/jwt-bundle-path: "/run/spirl/jwt/bundle.jwt"
spec:
  containers:
  - name: app
    image: my-app:latest
    volumeMounts:
    - name: spirl-jwt-bundle-token
      mountPath: /run/spirl/jwt
      readOnly: true

Combined X.509 and JWT

apiVersion: v1
kind: Pod
metadata:
  name: combined-app
  annotations:
    bridge.spirl.com/inject: "*"
    # X.509 Configuration
    bridge.spirl.com/x509-cert-path: "/run/spirl/certs/cert.pem"
    bridge.spirl.com/x509-key-path: "/run/spirl/certs/key.pem"
    bridge.spirl.com/x509-bundle-path: "/run/spirl/certs/bundle.pem"
    # JWT Configuration
    bridge.spirl.com/jwt-audience: "my-service"
    bridge.spirl.com/jwt-token-path: "/run/spirl/jwt/token.jwt"
    bridge.spirl.com/jwt-bundle-path: "/run/spirl/jwt/bundle.jwt"
spec:
  containers:
  - name: app
    image: my-app:latest
    volumeMounts:
    - name: spirl-cert-bundle-key
      mountPath: /run/spirl/certs
      readOnly: true
    - name: spirl-jwt-bundle-token
      mountPath: /run/spirl/jwt
      readOnly: true

Configuration Reference

Output Mode

SPIRL Bridge writes credentials as files to mounted volumes. The specific file paths are configured using command-line flags or Kubernetes annotations.

File Structure Example:

/run/spirl/certs/
├── cert.pem      # X.509 certificate
├── key.pem       # X.509 private key
└── bundle.pem    # X.509 CA bundle (local + federated CAs if enabled)

/run/spirl/jwt/
├── token.jwt     # JWT token
└── bundle.jwt    # JWT CA bundle (SPIFFE Bundle File format)

Click here for bundle format details.

Federation Support

SPIRL Bridge can optionally include federated domains in the trust bundles:

• X.509 Bundles: When federation is enabled, contains certificates from all trusted domains concatenated in PEM format. When disabled, contains only the local trust domain's CA certificate.
• JWT Bundles: When federated is enabled, contains public keys from all trusted domains in JSON format, base64-encoded per trust domain.