Ouroboros - Fleet Secrets Rotation Sidecar

Ouroboros is a sidecar. It does not replace your app. You run it beside the app, hand it a config file, and it rotates the secrets in that file.

Image 709825985650.dkr.ecr.us-east-1.amazonaws.com/jan-pro/ouro:1.0.0

Quick check (optional) docker run --rm --entrypoint /ouro
709825985650.dkr.ecr.us-east-1.amazonaws.com/jan-pro/ouro:1.0.0 version

docker run --rm --entrypoint /ouro
709825985650.dkr.ecr.us-east-1.amazonaws.com/jan-pro/ouro:1.0.0 rotate --demo

The demo walks the full rotation against an in-memory backend. No Vault or database needed.

1. Write a config Save something like this as config.json:

{ "state_dir": "/var/lib/ouro", "metrics_addr": ":9102", "backends": { "vault": { "addr": "https://vault.example.com ", "token": "YOUR_TOKEN", "kv_mount": "secret" }, "asm": { "region": "us-east-1" } }, "secrets": [ { "ref": { "backend": "vault", "path": "app/db", "type": "dbcred" }, "target": { "kind": "postgres", "params": { "admin_dsn": "postgres://admin:PASSWORD@db.example.com :5432/app?sslmode=require" } }, "interval": "24h", "dual_write_window": "30s", "drain_poll": "5s", "drain_timeout": "10m" } ] }

Notes:

• Use backend "vault" or "asm" per secret.
• For AWS Secrets Manager, omit "endpoint" in real AWS. The task role needs secretsmanager permissions.
• state_dir must be writable. Mount a volume at /var/lib/ouro. The image runs as non-root and will fail if that path is read-only.
• Keep admin credentials out of the image. Use secrets/env injection from ECS or Kubernetes.

2. Commands buyers actually use version /ouro version

one-shot rotation (good for first bring-up) /ouro rotate --config /etc/ouro/config.json

long-running sidecar (normal production mode) /ouro agent --config /etc/ouro/config.json

see rotation state /ouro status --config /etc/ouro/config.json

Default container command is already: agent --config /etc/ouro/config.json

3. Run on ECS

• Add an ouro container to your task definition next to the app.
• Image: 709825985650.dkr.ecr.us-east-1.amazonaws.com/jan-pro/ouro:1.0.0
• Mount config at /etc/ouro/config.json
• Mount a writable volume at /var/lib/ouro
• Publish container port 9102 if you scrape metrics
• Task role needs access to Vault and/or Secrets Manager, plus network reachability to Postgres
• Optional health check: CMD /ouro status --config /etc/ouro/config.json
• App container can dependOn ouro with condition HEALTHY if you want the sidecar up first

4. Run on Kubernetes

• Deploy as a sidecar in the same pod as the app, or use the included Helm chart and set the image to the URI above.
• Mount config as a ConfigMap/Secret at /etc/ouro/config.json
• Mount an emptyDir or PVC at /var/lib/ouro
• Scrape :9102 for Prometheus

5. After it is running

• GET http://<task-or-pod>:9102/healthz should return ok
• GET http://<task-or-pod>:9102/metrics for rotation counters and timings
• /ouro status --config /etc/ouro/config.json shows SECRET, STATE, UPDATED, LAST ERROR
• Healthy end state for a secret is IDLE
• If a rotation fails the health check, Ouroboros rolls back and leaves the old credential in place

6. What this version supports

• PostgreSQL dbcred rotation
• Vault KV v2 and AWS Secrets Manager
• Scheduled rotation via agent interval
• Dual-write, health check, drain, revoke, rollback

If status shows a stuck state or LAST ERROR is set, check agent logs, Vault/ASM permissions, and that Postgres accepts the admin_dsn.