Sidecar Pattern

Arcan can inject secrets into Kubernetes Pods via shared volumes using init containers or sidecar containers. The arcan generate sidecar command generates the Pod spec for you.

When to Use

Use the sidecar pattern when:

• Legacy apps read secrets from files (e.g., /etc/secrets/db-password)
• Database proxies (PgBouncer, ProxySQL) re-read auth files on rotation
• Air-gapped workloads where the app container has no network access to Arcan
• Multi-container Pods share secrets via a common volume
• Compliance requirements mandate secrets as files with 0400 permissions instead of environment variables
• Sidecar-based rotation is needed to refresh secrets on a schedule without restarting the app

Modes

Mode	Behavior
init	One-shot: secrets fetched once before app starts (init container)
sidecar	Continuous: secrets refreshed on a schedule (sidecar container)

Init Container Mode

The init container fetches secrets from Arcan and writes them to a shared volume. The app container reads them on startup. Secrets are not refreshed after the initial fetch.

arcan generate sidecar --realm=prod --env=prod --mode=init

Sidecar Continuous Mode

The sidecar container runs alongside the app, periodically fetching secrets and updating the shared volume. The app can detect file changes and reload.

arcan generate sidecar --realm=prod --env=prod --mode=sidecar --interval=300

Command Reference

arcan generate sidecar [flags]

Flags

Flag	Default	Description
--realm, -r	(required)	Realm slug
--env, -e	prod	Environment
--namespace, -n	default	Kubernetes namespace
--mode	init	Injection mode: init or sidecar
--image	your-app:latest	Application container image
--interval	60	Refresh interval in seconds (sidecar mode)
--server-url	(auto-detected)	Arcan server URL
--token-secret	arcan-credentials	K8s Secret holding the API token

Examples

# Init container (one-shot)
arcan generate sidecar --realm=prod --env=prod --mode=init

# Sidecar (continuous refresh every 5 minutes)
arcan generate sidecar --realm=prod --env=prod --mode=sidecar --interval=300

# Custom app image
arcan generate sidecar --realm=prod --mode=sidecar --image=myapp:latest

How It Works

1. A Kubernetes Secret (arcan-credentials) holds the Arcan API token
2. The init/sidecar container uses the Arcan CLI to fetch secrets
3. Secrets are written as files to an emptyDir volume (/arcan/secrets/)
4. The app container mounts the same volume and reads the files
5. In sidecar mode, the container loops on the configured interval, updating files in place

Security Considerations

• Secret files are written with 0400 permissions (read-only by owner)
• The shared volume is an emptyDir backed by memory (never written to disk on the node)
• The Arcan API token should have read-only scopes
• Use network policies to restrict which Pods can reach the Arcan server