17.2.2.3 Runtime Parameter Practice

Runtime parameter practice concerns the container runtime flags themselves, resource limits, restart policy, security options, ulimits, distinct from application-level configuration, and the core discipline is codifying these parameters into version-controlled deployment definitions rather than typing them manually as ad hoc flags on an interactive command line each time a container is started.

Why ad hoc flags are a recurring source of drift

A container started with a manually typed docker run command, including whatever resource limits and security options the operator happened to remember or consider necessary at that moment, has no durable record of those choices beyond the operator's own memory or shell history, which means the next person, or the same person weeks later, may start an equivalent container with subtly different, undocumented parameters:

docker run -d --memory=512m --cpus=1 --restart=unless-stopped my-api

docker run -d --memory=256m my-api

These two invocations, run at different times by different people, produce containers with meaningfully different resource limits and restart behavior, with nothing recording why, or even that, this difference exists, beyond whatever happens to still be in someone's shell history.

Codifying runtime parameters in version-controlled configuration

Capturing these parameters in a Compose file, or an equivalent declarative deployment definition, makes them an explicit, reviewable, version-controlled part of the project rather than an ephemeral detail of how a command happened to be typed on a given occasion:

services:
  api:
    image: my-api:1.4.2
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1"
      restart_policy:
        condition: on-failure

Any change to these parameters then goes through the same review and version control process as any other code change, which surfaces and documents the reasoning behind a resource limit adjustment the same way it would for any other meaningful project change.

Security-related runtime parameters deserving explicit attention

Security options, capability drops, read-only filesystem settings, seccomp profiles, are runtime parameters just as much as resource limits, and deserve the same deliberate, codified treatment rather than being left to whatever an operator happens to apply manually and inconsistently:

services:
  api:
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    read_only: true
    tmpfs:
      - /tmp

Codifying these specifically ensures every deployment of this service consistently applies the same security posture, rather than depending on whoever happens to be running the container remembering to apply the same flags manually each time.

Ulimits and other less commonly considered parameters

Beyond the more commonly discussed memory and CPU limits, parameters like file descriptor limits, process limits, and other ulimit settings are equally part of a container's runtime configuration and equally deserve explicit, deliberate, codified values rather than being left at whatever default the runtime happens to apply:

services:
  api:
    ulimits:
      nofile:
        soft: 4096
        hard: 8192
      nproc: 200

A service that legitimately needs a higher file descriptor limit than the default provides, for handling many simultaneous connections, for instance, should have that need documented and codified directly in its deployment configuration, rather than relying on a manually applied flag that might be forgotten the next time the service is deployed elsewhere.

Reviewing runtime parameters the same way as application code

Treating a pull request that changes a resource limit, restart policy, or security setting with the same review rigor as one changing application logic ensures these decisions receive the same scrutiny and documented reasoning, rather than being adjusted casually or reactively during an incident without a corresponding, lasting record of why the change was made:

git log -p -- docker-compose.production.yml

A reviewable history of exactly how and why a service's runtime parameters have changed over time is valuable both for understanding the current configuration's reasoning and for investigating whether a specific past change might be related to a current issue.

Avoiding parameter drift between environments

Runtime parameters appropriate for one environment, generous resource limits and relaxed restart behavior in development, for instance, are often deliberately different from production's stricter, more conservative settings; using the same layered override pattern applied to application configuration generally, a base definition with environment-specific overrides, keeps this difference explicit and intentional rather than an undocumented, easily-forgotten manual adjustment made separately for each environment:

services:
  api:
    deploy:
      resources:
        limits:
          memory: 256M

services:
  api:
    deploy:
      resources:
        limits:
          memory: 1024M

Verifying actually deployed parameters match the codified intent

Periodically confirming that a running container's actual, effective runtime parameters match what the version-controlled deployment definition specifies catches drift introduced by a manual, undocumented adjustment made directly against a running container outside of the normal deployment process:

docker inspect my-api --format '{{.HostConfig.Memory}} {{.HostConfig.RestartPolicy}}'

A mismatch here between what is actually running and what the deployment configuration specifies is a direct signal that someone modified the running container manually, outside of the codified, reviewable deployment process, which is exactly the kind of undocumented drift this entire practice is meant to prevent.

Common mistakes

• Starting containers with manually typed, ad hoc runtime flags rather than codifying them in a version-controlled deployment definition.
• Treating security-related runtime parameters as less important to codify than resource limits, leaving them inconsistently applied across deployments.
• Adjusting a runtime parameter directly against a running container during an incident without also updating the corresponding codified configuration afterward.
• Not reviewing changes to runtime parameters with the same rigor applied to application code changes, missing documented reasoning for why a specific limit or policy was set.
• Never verifying that a running container's actual, effective parameters match the version-controlled configuration's stated intent, allowing undocumented drift to accumulate unnoticed.

Runtime parameter practice treats resource limits, restart policy, security options, and ulimits as first-class, version-controlled configuration deserving the same review and documentation rigor as application code, rather than as ephemeral details of how a command happened to be typed on a particular occasion, which is what keeps deployments consistent and their reasoning traceable over time.