fix(docker): give the distroless slim stage the RUNTIME_HOME state volume

The runtime-slim and runtime-code-slim bake targets build the distroless
runtime-slim stage, which declared no ARG RUNTIME_HOME and no VOLUME, so
the RUNTIME_HOME=/root passed by the root slim targets did nothing and
~/.headroom stayed in the container layer.

Declare RUNTIME_HOME in that stage, create ~/.headroom owned by the
runtime user (distroless has no shell, so build it in a helper stage and
COPY it in) and declare it as a VOLUME, matching the python-slim stage.

Replace the HCL-text-only test with one that resolves each bake target to
its Dockerfile stage (following FROM <stage> inheritance) and checks the
stage declares every RUNTIME_* arg the target passes and puts its VOLUME
under RUNTIME_HOME.

Refs #4443
This commit is contained in:
drakeo338
2026-10-29 17:54:07 +00:00
parent ad55b5d0e0
commit 59bd12d814
2 changed files with 69 additions and 18 deletions
+13
View File
@@ -214,14 +214,23 @@ ENTRYPOINT ["headroom", "proxy"]
# Keep host and port defaults in the CLI so HEADROOM_HOST and HEADROOM_PORT
# remain authoritative for the published image.
# Distroless has no shell, so the ~/.headroom state directory cannot be made
# with RUN there. Build it here and COPY it in with the right owner (#4443).
FROM python:${PYTHON_VERSION}-slim AS runtime-slim-state
RUN mkdir -p /state/.headroom
FROM ${DISTROLESS_IMAGE} AS runtime-slim
ARG RUNTIME_USER=nonroot
ARG RUNTIME_HOME=/home/nonroot
ARG PYTHON_SITE_PACKAGES
COPY --from=builder ${PYTHON_SITE_PACKAGES} ${PYTHON_SITE_PACKAGES}
# Native Rust reverse proxy binary (issue #976).
COPY --from=builder /usr/local/bin/headroom-proxy /usr/local/bin/headroom-proxy
# Owned by the runtime user so the volume below is writable (user and group
# are both named after RUNTIME_USER in the distroless image).
COPY --from=runtime-slim-state --chown=${RUNTIME_USER}:${RUNTIME_USER} /state/ ${RUNTIME_HOME}/
USER ${RUNTIME_USER}
WORKDIR /app
@@ -231,6 +240,10 @@ ENV HEADROOM_HOST=127.0.0.1 \
PYTHONDONTWRITEBYTECODE=1 \
PYTHONPATH=${PYTHON_SITE_PACKAGES}
# Same persistent-state volume as the python-slim stage; pass
# --build-arg RUNTIME_HOME=/root when building with RUNTIME_USER=root.
VOLUME ${RUNTIME_HOME}/.headroom
EXPOSE 8787
# This stage is distroless, so there is no shell to expand ${HEADROOM_PORT}.
+56 -18
View File
@@ -156,29 +156,67 @@ def test_every_published_docker_variant_includes_bedrock_auth_dependencies() ->
assert {"boto3", "botocore"} <= bedrock_names
def test_root_docker_bake_targets_pass_runtime_home_root() -> None:
"""Root image variants must declare the volume/workdir under ``/root`` (#4443).
def _dockerfile_stages() -> dict[str, list[str]]:
"""Map each Dockerfile stage to its instruction lines, parent stages first.
``RUNTIME_HOME`` defaults to ``/home/nonroot`` in the Dockerfile, so a bake
target with ``RUNTIME_USER = "root"`` that omits it ships an image whose
VOLUME and WORKDIR are ``/home/nonroot`` while the process runs with
``HOME=/root``; ``~/.headroom`` then lands in the container layer.
A stage that is ``FROM <earlier stage>`` inherits that stage's filesystem
and metadata (VOLUME, WORKDIR, ARG-derived values), so the parent's lines
are part of what the child ships.
"""
own: dict[str, list[str]] = {}
parent: dict[str, str] = {}
current: list[str] | None = None
for raw in (ROOT / "Dockerfile").read_text(encoding="utf-8").splitlines():
line = raw.strip()
from_match = re.match(r"FROM\s+(\S+)\s+AS\s+(\S+)$", line, re.IGNORECASE)
if from_match:
base, name = from_match.groups()
current = own.setdefault(name, [])
if base in own:
parent[name] = base
elif current is not None and line and not line.startswith("#"):
current.append(line)
stages: dict[str, list[str]] = {}
for name in own:
chain, node = [], name
while node:
chain.insert(0, node)
node = parent.get(node, "")
stages[name] = [line for stage in chain for line in own[stage]]
return stages
def test_docker_bake_runtime_args_are_declared_by_the_selected_stage() -> None:
"""Each bake target's runtime args must reach the stage it builds (#4443).
Build args are scoped to one Dockerfile stage, so passing ``RUNTIME_HOME``
to a target whose ``target =`` stage has no ``ARG RUNTIME_HOME`` is a
silent no-op. The distroless ``runtime-slim`` stage once ignored it, so the
slim root variants shipped without the state volume.
"""
stages = _dockerfile_stages()
bake = (ROOT / "docker-bake.hcl").read_text(encoding="utf-8")
blocks = re.findall(r'^target "([^"]+)" \{\n(.*?)^\}', bake, flags=re.S | re.M)
root_targets = {
name: body for name, body in blocks if re.search(r'RUNTIME_USER\s*=\s*"root"', body)
}
assert set(root_targets) == {"runtime", "runtime-code", "runtime-slim", "runtime-code-slim"}
missing = [
name
for name, body in root_targets.items()
if not re.search(r'RUNTIME_HOME\s*=\s*"/root"', body)
]
assert not missing, f"root bake targets without RUNTIME_HOME=/root: {missing}"
checked = {}
for name, body in blocks:
if re.search(r'RUNTIME_USER\s*=\s*"nonroot"', body):
assert "RUNTIME_HOME" not in body or "/home/nonroot" in body, name
stage_match = re.search(r'^\s*target\s*=\s*"([^"]+)"', body, re.M)
if not stage_match:
continue
stage = stage_match.group(1)
assert stage in stages, f"{name} selects unknown Dockerfile stage {stage}"
declared = {m.group(1) for line in stages[stage] if (m := re.match(r"ARG\s+(\w+)", line))}
passed = set(re.findall(r"^\s*(RUNTIME_\w+)\s*=", body, re.M))
assert passed <= declared, f"{name}: stage {stage} does not declare {passed - declared}"
home = re.search(r'RUNTIME_HOME\s*=\s*"([^"]+)"', body)
user = re.search(r'RUNTIME_USER\s*=\s*"([^"]+)"', body)
if user and user.group(1) == "root":
assert home and home.group(1) == "/root", f"{name}: root target needs /root"
if home:
# The stage must put its state volume under the home it was given.
assert "VOLUME ${RUNTIME_HOME}/.headroom" in stages[stage], f"{name}: {stage}"
checked[name] = stage
assert {"runtime", "runtime-code", "runtime-slim", "runtime-code-slim"} <= set(checked)
assert {checked[n] for n in ("runtime-slim", "runtime-code-slim")} == {"runtime-slim"}
def test_every_docker_variant_includes_the_redis_extra() -> None: