How docker-secret-operator/dso works
1. Purpose and principal workflow
Docker Secret Operator (DSO) is a Docker CLI plugin and host-local daemon that retrieves secrets from cloud or local vaults, injects them into Docker Compose workloads, and can rotate managed containers with rollback and TCP-proxy-assisted cutover. The concretely mapped principal workflow is initiated by a Docker CLI user (external; repository path: null) running docker dso setup: DSO detects the host, validates prerequisites, plans and previews changes, applies them transactionally, and rolls back failed application.
2. Components
CLI and provisioning
• DSO CLI executable — cmd/dso/main.go: assigns build metadata and invokes the CLI package’s Execute entry point.
• CLI command surface — internal/cli/root.go: provides the Docker-plugin commands, including setup, compose, secret, status, watch, validation, and system-management commands.
• Setup Engine — internal/setup/engine.go: owns the fixed Detect → Validate → Plan → Preview → Apply orchestration, dry-run gate, lifecycle events, and failure rollback initiation.
• Environment discovery — internal/setup/detector.go: detects host, Docker, OS, user, provider, and service conditions for setup.
• Setup validation — internal/setup/validator.go: validates the detected environment and requested setup options before planning.
• Installation planner and preview — internal/setup/planner.go: produces an install plan subsequently rendered for terminal or structured preview.
• Transactional installer — internal/setup/apply.go: applies planned filesystem, permissions, service, and configuration operations as a transaction.
• Setup rollback executor — internal/setup/rollback.go: reverses recorded setup operations when application fails.
• Setup event stream — internal/setup/events.go: lets the engine emit progress events while keeping orchestration independent of terminal rendering.
Agent, watching, and rotation
• Agent runtime — internal/agent/agent.go: documented long-running daemon that coordinates configured providers, managed containers, recovery, and runtime control.
• Rotation trigger engine — internal/agent/trigger.go: the documented agent layer that polls providers and initiates secret-change handling.
• Docker reloader controller — internal/watcher/controller.go: creates a Docker client, reconciles containers labelled dso.reloader=true, consumes container lifecycle events, and registers eligible targets with the proxy.
• Bounded container-event queue — internal/events/backpressure.go: buffers and dispatches Docker events with bounded capacity and workers for rotation-heavy workloads.
• Container configuration analyzer — internal/analyzer/container_analyzer.go: derives properties such as fixed ports, explicit names, health checks, restart policy, and statefulness.
• Rotation strategy decision engine — internal/strategy/decision_engine.go: scores analyzer results to recommend rolling rotation at score ≥70 or restart below that threshold.
• Rolling rotation executor — internal/rotation/rolling_strategy.go: implements the replacement path that starts and verifies a new container before retiring the old one.
• Rotation lock manager — internal/rotation/lock_manager.go: serializes per-container or per-secret rotations using in-process mutexes and optional kernel-released flock locks.
• Agent state and recovery tracker — internal/agent/state_tracker.go: maintains runtime rotation state used for reconciliation and documented crash recovery.
• Per-secret timeout isolation — internal/agent/timeout_controller.go: gives individual secret operations distinct timeout contexts so a slow provider does not block other rotations.
Secrets and injection
• Configuration model and validation — pkg/config/config.go: represents DSO YAML configuration, including provider, agent, secret mapping, injection, and rotation settings.
• Provider plugin loader — pkg/provider/load.go: loads provider implementations through the repository’s provider abstraction.
• Cloud provider plugin binaries — cmd/plugins: separate HashiCorp go-plugin processes implement AWS Secrets Manager, Azure Key Vault, Huawei CSMS, and HashiCorp Vault access; sampled implementations initialize provider SDK clients and expose context-aware secret reads.
• External secret backends — repository path: null: AWS Secrets Manager, Azure Key Vault, Huawei Cloud CSMS, HashiCorp Vault, and the documented local mode source supply secret values.
• Encrypted local vault — pkg/vault/vault.go: supports the local-mode secret store and cryptographic handling.
• Secret injector — internal/injector/inject.go: implements runtime delivery into containers, including documented environment (dso://) and stdin/tmpfs file (dsofile://) injection modes.
Runtime interfaces, state exposure, and traffic switching
• Agent IPC server — internal/agent/server.go: implements the Unix-socket control interface used by CLI-to-agent operations.
• REST, health, and event API — internal/server/rest.go: exposes the documented localhost HTTP control, health, metrics, event, and webhook surface.
• TCP proxy manager — internal/proxy/manager.go: owns allowed host-port listeners and atomically shifts new connections between registered container backends during a healthy replacement.
• Docker Engine and Compose host — repository path: null: supplies container lifecycle events, container metadata, networking, execution, and lifecycle operations.
• Metrics and observability — pkg/observability/metrics.go: provides the Prometheus-oriented telemetry described for agent monitoring.
3. Relationships
• Docker CLI user -> DSO CLI executable: invokes docker dso; documented CLI-plugin entry point.
• DSO CLI executable -> CLI command surface: dispatches commands through cli.Execute; direct call in main.
• CLI command surface -> Setup Engine: starts the docker dso setup workflow; documented setup command behavior.
• Setup Engine -> Environment discovery: detects the environment; direct Detect call.
• Setup Engine -> Setup validation: validates detected conditions; direct Validate call.
• Setup Engine -> Installation planner and preview: creates and renders the installation plan; direct Plan and preview calls.
• Setup Engine -> Transactional installer: applies a non-dry-run plan; direct Apply call.
• Setup Engine -> Setup rollback executor: executes reverse rollback after apply failure; direct rollback construction and call.
• Setup Engine -> Setup event stream: emits setup lifecycle events; direct Events.emit calls.
• Setup Engine -> CLI command surface: returns a setup result with success, pending, or failed status.
• CLI command surface -> Agent IPC server: uses the documented Unix socket for runtime CLI-to-agent communication; exact command-handler wiring was not sampled.
• Agent runtime -> External secret backends: polls or otherwise fetches configured secret values; documented runtime behavior.
• Cloud provider plugin binaries -> External secret backends: retrieve secrets through their respective provider SDK/API clients; directly shown for AWS, Azure, Huawei, and Vault plugins.
• Rotation trigger engine -> Rotation lock manager: prevents concurrent rotation for a secret/container; documented rotation sequence, with call site not sampled.
• Docker reloader controller -> Docker Engine and Compose host: lists labelled containers and subscribes to start, stop, and die events; direct Docker-client use.
• Docker reloader controller -> Bounded container-event queue: constructs and starts the queue before event processing; direct calls.
• Docker reloader controller -> TCP proxy manager: registers reconciled or started containers as proxy backends; direct calls.
• Container configuration analyzer -> Rotation strategy decision engine: supplies analysis results used for rolling-versus-restart scoring; decision-engine contract.
• Agent runtime -> Agent state and recovery tracker: records rotation state for documented restart recovery; assembly call site not sampled.
• Secret injector -> Docker Engine and Compose host: delivers resolved values into managed containers; documented injection design.
• TCP proxy manager -> Docker Engine and Compose host: routes host-port traffic to registered container IP/port backends.
4. Coverage limits
The sampled source proves the setup orchestration, provider SDK access, watcher/proxy interactions, locking, and timeout behavior. Agent startup assembly, exact trigger-to-injector-to-rotation call chains, persistence implementation, REST handlers, provider-loader wiring, and Docker secret-driver wiring were not sampled; those runtime relationships are identified as documented where applicable rather than asserted as directly observed calls.
Main entry points: engine.go Setup Engine · root.go CLI Commands · controller.go Docker Reloader · agent.go Agent Runtime
Components 31
CLI and Setup
Docker plugin entry point and transactional setup workflow.
- DSO CLI
cmd/dso/main.go - CLI Commands
internal/cli/root.go - Setup Engine
internal/setup/engine.go - Environment Discovery
internal/setup/detector.go - Setup Validation
internal/setup/validator.go - Install Planner
internal/setup/planner.go - Transactional Installer
internal/setup/apply.go - Setup Rollback
internal/setup/rollback.go - Setup Events
internal/setup/events.go
Agent and Rotation
Daemon runtime, watching, recovery, and container rotation.
- Agent Runtime
internal/agent/agent.go - Rotation Trigger
internal/agent/trigger.go - Docker Reloader
internal/watcher/controller.go - Container Event Queue
internal/events/backpressure.go - Container Analyzer
internal/analyzer/container_analyzer.go - Rotation Decision
internal/strategy/decision_engine.go - Rolling Rotation
internal/rotation/rolling_strategy.go - Rotation Locks
internal/rotation/lock_manager.go - Agent State Tracker
internal/agent/state_tracker.go - Secret Timeout Isolation
internal/agent/timeout_controller.go
Secrets and Injection
Provider access, local vault, and container secret delivery.
- Configuration Model
pkg/config/config.go - Provider Loader
pkg/provider/load.go - Cloud Provider Plugins
cmd/plugins - Encrypted Local Vault
pkg/vault/vault.go - Secret Injector
internal/injector/inject.go
Runtime Interfaces
IPC, HTTP control, proxying, and observability.
- Agent IPC Server
internal/agent/server.go - REST and Health API
internal/server/rest.go - TCP Proxy Manager
internal/proxy/manager.go - Observability Metrics
pkg/observability/metrics.go
External Systems
Users, Docker, and secret backends.
- Docker CLI User
- External Secret Backends · AWS Secrets Manager, Azure Key Vault, Huawei Cloud CSMS, HashiCorp Vault, and local mode source.
- Docker Engine and Compose
Connections 21
- Docker CLI User → DSO CLI: invokes docker dso · Docker CLI plugin entry point.
- DSO CLI → CLI Commands: dispatches commands · Calls cli.Execute.
- CLI Commands → Setup Engine: starts setup · Runs the docker dso setup workflow.
- Setup Engine → Environment Discovery: detects environment · Direct Detect call.
- Setup Engine → Setup Validation: validates conditions · Direct Validate call.
- Setup Engine → Install Planner: plans and previews · Direct Plan and preview calls.
- Setup Engine → Transactional Installer: applies plan · Applies non-dry-run plans.
- Setup Engine → Setup Rollback: rolls back failure · Reverses recorded operations after apply failure.
- Setup Engine → Setup Events: emits events · Emits setup lifecycle events.
- Setup Engine → CLI Commands: returns setup result · Returns success, pending, or failed status.
- CLI Commands → Agent IPC Server: uses Unix socket · Runtime CLI-to-agent communication; exact handler wiring was not sampled.
- Agent Runtime → External Secret Backends: fetches secrets · Polls or otherwise fetches configured secret values.
- Cloud Provider Plugins → External Secret Backends: retrieves secrets · Uses provider SDK/API clients.
- Rotation Trigger → Rotation Locks: locks rotation · Prevents concurrent secret or container rotation.
- Docker Reloader → Docker Engine and Compose: watches containers · Lists labelled containers and subscribes to lifecycle events.
- Docker Reloader → Container Event Queue: starts event queue · Constructs and starts bounded event processing.
- Docker Reloader → TCP Proxy Manager: registers backends · Registers reconciled or started containers.
- Container Analyzer → Rotation Decision: supplies analysis · Provides results for rolling-versus-restart scoring.
- Agent Runtime → Agent State Tracker: records rotation state · Supports documented restart recovery.
- Secret Injector → Docker Engine and Compose: injects secrets · Delivers resolved values into managed containers.
- TCP Proxy Manager → Docker Engine and Compose: routes traffic · Routes host-port traffic to registered container backends.