# docker-secret-operator/dso architecture

> Architecture diagram of the GitHub repository docker-secret-operator/dso, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker-secret-operator/dso
- Repository: https://github.com/docker-secret-operator/dso

## Overview

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: [`internal/setup/engine.go`](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/engine.go) (Setup Engine), [`internal/cli/root.go`](https://github.com/docker-secret-operator/dso/blob/main/internal/cli/root.go) (CLI Commands), [`internal/watcher/controller.go`](https://github.com/docker-secret-operator/dso/blob/main/internal/watcher/controller.go) (Docker Reloader), [`internal/agent/agent.go`](https://github.com/docker-secret-operator/dso/blob/main/internal/agent/agent.go) (Agent Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_setup["CLI and Setup"]
  node_dso_cli["DSO CLI<br/>executable"]
  node_cli_surface["CLI Commands<br/>command surface"]
  node_setup_engine["Setup Engine<br/>orchestrator"]
  node_environment_discovery["Environment Discovery<br/>detector"]
  node_setup_validation["Setup Validation<br/>validator"]
  node_install_planner["Install Planner<br/>[planner.go]"]
  node_transactional_installer["Transactional Installer<br/>[apply.go]"]
  node_setup_rollback["Setup Rollback<br/>rollback executor"]
  node_setup_events["Setup Events<br/>event stream"]
end

subgraph group_agent_rotation["Agent and Rotation"]
  node_agent_runtime["Agent Runtime<br/>daemon"]
  node_rotation_trigger["Rotation Trigger<br/>trigger engine"]
  node_docker_reloader["Docker Reloader<br/>controller"]
  node_container_event_queue["Container Event Queue<br/>bounded queue"]
  node_container_analyzer["Container Analyzer<br/>configuration analyzer"]
  node_rotation_decision["Rotation Decision<br/>strategy engine"]
  node_rolling_rotation["Rolling Rotation<br/>rotation executor"]
  node_rotation_locks["Rotation Locks<br/>lock manager"]
  node_agent_state["Agent State Tracker<br/>recovery tracker"]
  node_timeout_isolation["Secret Timeout Isolation<br/>timeout controller"]
end

subgraph group_secrets["Secrets and Injection"]
  node_config_model["Configuration Model<br/>[config.go]"]
  node_provider_loader["Provider Loader<br/>plugin loader"]
  node_provider_plugins["Cloud Provider Plugins<br/>plugin processes"]
  node_local_vault[("Encrypted Local Vault<br/>secret store")]
  node_secret_injector["Secret Injector<br/>container injector"]
end

subgraph group_runtime["Runtime Interfaces"]
  node_agent_ipc["Agent IPC Server<br/>Unix socket server"]
  node_rest_api["REST and Health API<br/>HTTP API"]
  node_tcp_proxy["TCP Proxy Manager<br/>traffic switcher"]
  node_metrics["Observability Metrics<br/>Prometheus telemetry"]
end

subgraph group_external["External Systems"]
  node_docker_cli_user(("Docker CLI User<br/>external actor"))
  node_secret_backends[("External Secret Backends")]
  node_docker_engine["Docker Engine and Compose<br/>container platform"]
end

node_docker_cli_user -->|"invokes docker dso"| node_dso_cli
node_dso_cli -->|"dispatches commands"| node_cli_surface
node_cli_surface -->|"starts setup"| node_setup_engine
node_setup_engine -->|"detects environment"| node_environment_discovery
node_setup_engine -->|"validates conditions"| node_setup_validation
node_setup_engine -->|"plans and previews"| node_install_planner
node_setup_engine -->|"applies plan"| node_transactional_installer
node_setup_engine -->|"rolls back failure"| node_setup_rollback
node_setup_engine -->|"emits events"| node_setup_events
node_setup_engine -->|"returns setup result"| node_cli_surface
node_cli_surface -->|"uses Unix socket"| node_agent_ipc
node_agent_runtime -->|"fetches secrets"| node_secret_backends
node_provider_plugins -->|"retrieves secrets"| node_secret_backends
node_rotation_trigger -->|"locks rotation"| node_rotation_locks
node_docker_reloader -->|"watches containers"| node_docker_engine
node_docker_reloader -->|"starts event queue"| node_container_event_queue
node_docker_reloader -->|"registers backends"| node_tcp_proxy
node_container_analyzer -->|"supplies analysis"| node_rotation_decision
node_agent_runtime -->|"records rotation state"| node_agent_state
node_secret_injector -->|"injects secrets"| node_docker_engine
node_tcp_proxy -->|"routes traffic"| node_docker_engine

click node_dso_cli "https://github.com/docker-secret-operator/dso/blob/main/cmd/dso/main.go"
click node_cli_surface "https://github.com/docker-secret-operator/dso/blob/main/internal/cli/root.go"
click node_setup_engine "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/engine.go"
click node_environment_discovery "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/detector.go"
click node_setup_validation "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/validator.go"
click node_install_planner "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/planner.go"
click node_transactional_installer "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/apply.go"
click node_setup_rollback "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/rollback.go"
click node_setup_events "https://github.com/docker-secret-operator/dso/blob/main/internal/setup/events.go"
click node_agent_runtime "https://github.com/docker-secret-operator/dso/blob/main/internal/agent/agent.go"
click node_rotation_trigger "https://github.com/docker-secret-operator/dso/blob/main/internal/agent/trigger.go"
click node_docker_reloader "https://github.com/docker-secret-operator/dso/blob/main/internal/watcher/controller.go"
click node_container_event_queue "https://github.com/docker-secret-operator/dso/blob/main/internal/events/backpressure.go"
click node_container_analyzer "https://github.com/docker-secret-operator/dso/blob/main/internal/analyzer/container_analyzer.go"
click node_rotation_decision "https://github.com/docker-secret-operator/dso/blob/main/internal/strategy/decision_engine.go"
click node_rolling_rotation "https://github.com/docker-secret-operator/dso/blob/main/internal/rotation/rolling_strategy.go"
click node_rotation_locks "https://github.com/docker-secret-operator/dso/blob/main/internal/rotation/lock_manager.go"
click node_agent_state "https://github.com/docker-secret-operator/dso/blob/main/internal/agent/state_tracker.go"
click node_timeout_isolation "https://github.com/docker-secret-operator/dso/blob/main/internal/agent/timeout_controller.go"
click node_config_model "https://github.com/docker-secret-operator/dso/blob/main/pkg/config/config.go"
click node_provider_loader "https://github.com/docker-secret-operator/dso/blob/main/pkg/provider/load.go"
click node_provider_plugins "https://github.com/docker-secret-operator/dso/tree/main/cmd/plugins"
click node_local_vault "https://github.com/docker-secret-operator/dso/blob/main/pkg/vault/vault.go"
click node_secret_injector "https://github.com/docker-secret-operator/dso/blob/main/internal/injector/inject.go"
click node_agent_ipc "https://github.com/docker-secret-operator/dso/blob/main/internal/agent/server.go"
click node_rest_api "https://github.com/docker-secret-operator/dso/blob/main/internal/server/rest.go"
click node_tcp_proxy "https://github.com/docker-secret-operator/dso/blob/main/internal/proxy/manager.go"
click node_metrics "https://github.com/docker-secret-operator/dso/blob/main/pkg/observability/metrics.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dso_cli,node_cli_surface,node_setup_engine,node_environment_discovery,node_setup_validation,node_install_planner,node_transactional_installer,node_setup_rollback,node_setup_events toneBlue
class node_agent_runtime,node_rotation_trigger,node_docker_reloader,node_container_event_queue,node_container_analyzer,node_rotation_decision,node_rolling_rotation,node_rotation_locks,node_agent_state,node_timeout_isolation toneAmber
class node_config_model,node_provider_loader,node_provider_plugins,node_local_vault,node_secret_injector toneMint
class node_agent_ipc,node_rest_api,node_tcp_proxy,node_metrics toneRose
class node_docker_cli_user,node_secret_backends,node_docker_engine toneIndigo
```

## Components

### CLI and Setup

Docker plugin entry point and transactional setup workflow.

- [DSO CLI](https://github.com/docker-secret-operator/dso/blob/main/cmd/dso/main.go): executable · `cmd/dso/main.go`
- [CLI Commands](https://github.com/docker-secret-operator/dso/blob/main/internal/cli/root.go): command surface · `internal/cli/root.go`
- [Setup Engine](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/engine.go): orchestrator · `internal/setup/engine.go`
- [Environment Discovery](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/detector.go): detector · `internal/setup/detector.go`
- [Setup Validation](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/validator.go): validator · `internal/setup/validator.go`
- [Install Planner](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/planner.go): planner · `internal/setup/planner.go`
- [Transactional Installer](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/apply.go): installer · `internal/setup/apply.go`
- [Setup Rollback](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/rollback.go): rollback executor · `internal/setup/rollback.go`
- [Setup Events](https://github.com/docker-secret-operator/dso/blob/main/internal/setup/events.go): event stream · `internal/setup/events.go`

### Agent and Rotation

Daemon runtime, watching, recovery, and container rotation.

- [Agent Runtime](https://github.com/docker-secret-operator/dso/blob/main/internal/agent/agent.go): daemon · `internal/agent/agent.go`
- [Rotation Trigger](https://github.com/docker-secret-operator/dso/blob/main/internal/agent/trigger.go): trigger engine · `internal/agent/trigger.go`
- [Docker Reloader](https://github.com/docker-secret-operator/dso/blob/main/internal/watcher/controller.go): controller · `internal/watcher/controller.go`
- [Container Event Queue](https://github.com/docker-secret-operator/dso/blob/main/internal/events/backpressure.go): bounded queue · `internal/events/backpressure.go`
- [Container Analyzer](https://github.com/docker-secret-operator/dso/blob/main/internal/analyzer/container_analyzer.go): configuration analyzer · `internal/analyzer/container_analyzer.go`
- [Rotation Decision](https://github.com/docker-secret-operator/dso/blob/main/internal/strategy/decision_engine.go): strategy engine · `internal/strategy/decision_engine.go`
- [Rolling Rotation](https://github.com/docker-secret-operator/dso/blob/main/internal/rotation/rolling_strategy.go): rotation executor · `internal/rotation/rolling_strategy.go`
- [Rotation Locks](https://github.com/docker-secret-operator/dso/blob/main/internal/rotation/lock_manager.go): lock manager · `internal/rotation/lock_manager.go`
- [Agent State Tracker](https://github.com/docker-secret-operator/dso/blob/main/internal/agent/state_tracker.go): recovery tracker · `internal/agent/state_tracker.go`
- [Secret Timeout Isolation](https://github.com/docker-secret-operator/dso/blob/main/internal/agent/timeout_controller.go): timeout controller · `internal/agent/timeout_controller.go`

### Secrets and Injection

Provider access, local vault, and container secret delivery.

- [Configuration Model](https://github.com/docker-secret-operator/dso/blob/main/pkg/config/config.go): configuration model · `pkg/config/config.go`
- [Provider Loader](https://github.com/docker-secret-operator/dso/blob/main/pkg/provider/load.go): plugin loader · `pkg/provider/load.go`
- [Cloud Provider Plugins](https://github.com/docker-secret-operator/dso/tree/main/cmd/plugins): plugin processes · `cmd/plugins`
- [Encrypted Local Vault](https://github.com/docker-secret-operator/dso/blob/main/pkg/vault/vault.go): secret store · `pkg/vault/vault.go`
- [Secret Injector](https://github.com/docker-secret-operator/dso/blob/main/internal/injector/inject.go): container injector · `internal/injector/inject.go`

### Runtime Interfaces

IPC, HTTP control, proxying, and observability.

- [Agent IPC Server](https://github.com/docker-secret-operator/dso/blob/main/internal/agent/server.go): Unix socket server · `internal/agent/server.go`
- [REST and Health API](https://github.com/docker-secret-operator/dso/blob/main/internal/server/rest.go): HTTP API · `internal/server/rest.go`
- [TCP Proxy Manager](https://github.com/docker-secret-operator/dso/blob/main/internal/proxy/manager.go): traffic switcher · `internal/proxy/manager.go`
- [Observability Metrics](https://github.com/docker-secret-operator/dso/blob/main/pkg/observability/metrics.go): Prometheus telemetry · `pkg/observability/metrics.go`

### External Systems

Users, Docker, and secret backends.

- **Docker CLI User**: external actor
- **External Secret Backends**: secret backends · AWS Secrets Manager, Azure Key Vault, Huawei Cloud CSMS, HashiCorp Vault, and local mode source.
- **Docker Engine and Compose**: container platform

## Connections

- 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.
