✦ For everyone, free.

Practical knowledge for real and everyday life

Home

9.2.4.4 Immutable Config Intent

A focused guide to Immutable Config Intent, connecting core concepts with practical Docker and container operations.

Immutable config intent reflects the underlying design philosophy behind Compose's configs mechanism: configuration content is meant to be treated as a fixed, versioned artifact injected at container start, rather than something a running container is expected to modify or that changes dynamically without an explicit, deliberate update step.

How This Intent Shapes Expected Usage

A config's content, once injected into a running container, is not expected to be altered by the application itself — any actual change to the configuration should happen by updating the source and explicitly recreating the affected service.

configs:
  app-config:
    file: ./app-config.yaml

services:
  api:
    configs:
      - source: app-config
        target: /app/config.yaml

docker compose up -d --force-recreate api

Updating ./app-config.yaml and recreating the service is the intended, deliberate way to apply a configuration change, rather than expecting the running container to somehow detect and adapt to an in-place file modification.

Why This Immutability Supports Predictable, Reproducible Deployments

Treating configuration as an immutable, versioned artifact tied to a specific deployment makes that deployment's exact configuration state fully reproducible and auditable — re-deploying the same config source reliably reproduces the same configuration, without depending on any runtime mutation having occurred along the way.

git log -- app-config.yaml

This history accurately reflects every actual configuration change, since changes only ever happen through this deliberate, versioned update process rather than untracked runtime modification.

Contrasting With Mechanisms That Don't Carry This Same Intent

A general-purpose, writable bind mount carries no such expectation of immutability — an application could, in principle, write to it, which is exactly the kind of dynamic behavior the configs mechanism is specifically not designed around.

volumes:
  - ./mutable-state:/app/state
Why Understanding Immutable Config Intent Matters

Recognizing that Compose's configs mechanism is built around an expectation of immutability, rather than dynamic runtime modification, clarifies the correct way to apply configuration changes and reinforces why this approach supports more predictable, reproducible deployments than ad hoc runtime configuration mutation would.

Related content