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

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

Collectors

This guardrail gathers nothing itself. It depends on the collectors below, which the CLI runs once per build before any check, and reads what they found out of GUARDRAIL_FACTS. A collector that collects nothing skips this guardrail rather than failing it.

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, enriched with the findings of a hadolint report when the build already left one behind.	none

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

Configuration

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

Inputs

Input	Description	Default	Environment variable
finalStageOnly	Whether only the file's last stage is judged. 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 that are not judged, such as one that only ever builds a job image.	``	GUARDRAIL_INPUT_IGNORE

How to fix

Add a HEALTHCHECK to the Dockerfile, probing the thing the container exists to do rather than the process being alive:

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

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

A Kubernetes deployment declares this as a readinessProbe instead, and that is a complete answer: the probe lives in the manifest rather than in the image. Name those Dockerfiles in ignore, which is matched as a glob against the path:

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

An image that runs a job and exits is the other one worth naming there, because it is meant to stop and has nothing to keep reporting on.

More in docker

• docker/base-pinned. Every image a Dockerfile builds from is pinned to a digest, so a rebuild of the same commit starts from the same bytes.
• docker/lint-clean. Every finding the Dockerfile linter reported sits below the severity the team gates on.
• docker/no-build-secrets. No ARG or ENV a Dockerfile declares is named like a credential.
• docker/nonroot-user. Every Dockerfile ends on a USER that is not root, so the container runs its process unprivileged.

All 5 docker guardrails