Guardrails / docker

Dockerfiles declare a health check

docker/healthcheck@v1

Every Dockerfile declares a HEALTHCHECK, so the orchestrator can tell a container that is running from one that is actually working.

Id	docker/healthcheck
Version	v1
Category	docker
Default severity	warning
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	docker

Collectors

This guardrail doesn't gather anything itself. It relies on the collectors below, which the CLI runs once per build before any check, and reads what they found from GUARDRAIL_FACTS. If a collector collects nothing, this guardrail is skipped, not failed.

Collector	Gathers	Inputs it is given
docker	Every Dockerfile in the tree, parsed without a tool: the stages it builds, the image each one starts from and how that image is pinned, the user the image ends as, the ports it exposes, the paths it copies in and the names of the build arguments and environment variables it declares, plus the findings of a hadolint report when the build already left one behind.	none

The inputs above are this guardrail's own inputs, passed straight through to the collector. Setting one in buildnote.json changes what is collected, and two guardrails configured the same way share a single collection.

Configuration

{
  "guardrails": {
      "failOn": "error",
      "checks": [
          {
              "use": "docker/healthcheck@v1",
              "severity": "warning",
              "with": {
                  "finalStageOnly": "true",
                  "ignore": ""
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
finalStageOnly	Whether only the last stage in the file is checked. A build stage is thrown away and never runs, so it has nothing to health check.	true	GUARDRAIL_INPUT_FINALSTAGEONLY
ignore	Comma separated globs naming Dockerfiles to skip, such as one that only ever builds a job image.	``	GUARDRAIL_INPUT_IGNORE

How to fix

Add a HEALTHCHECK to the Dockerfile that probes what the container exists to do, not just whether the process is alive:

HEALTHCHECK --interval=30s --timeout=3s --start-period=20s \
  CMD curl -fsS http://localhost:8080/health || exit 1

Without one, the runtime only knows that PID 1 hasn't exited. A process that is deadlocked, out of connections or serving 500s stays in the load balancer's rotation until somebody notices.

If you deploy to Kubernetes, a readinessProbe in the manifest does the same job and is a complete answer on its own, because the probe lives in the manifest instead of the image. List those Dockerfiles in ignore, which is matched as a glob against the path:

{ "use": "docker/healthcheck@v1", "with": { "ignore": "deploy/k8s/*/Dockerfile" } }

Also list images that run a job and exit there, since they are meant to stop and have nothing to keep reporting on.

More in docker

• docker/base-pinned. Every image a Dockerfile builds from is pinned to a digest, so rebuilding the same commit starts from the same bytes.
• docker/lint-clean. Every finding the Dockerfile linter reported is below the severity your team gates on.
• docker/no-build-secrets. No ARG or ENV declared in a Dockerfile has a name that looks like a credential.
• docker/nonroot-user. Every Dockerfile ends with a USER that is not root, so the container runs its process without privileges.

All 5 docker guardrails