Add a Containers page, grouped by project and led by what is exposed
Every container on this machine is created by rootless podman-compose and
labelled with the project it belongs to, so the grouping is read from the
labels rather than invented. State then decides prominence within that
grouping -- running containers get rows, stopped ones collapse to a line --
which is why neither axis had to be chosen over the other.
Acting on a stack uses plain podman over the labelled set, never
`podman-compose down`, which would remove containers this shell did not
create. The compose file is the source of truth for what exists and belongs
to the repository. Nothing here needs privilege.
The findings on top are the crossing the Firewall page reports, seen from the
side that can close it: the firewall knows only that something is listening,
while this page knows which container, which compose file, and which token is
missing from it. So `bind-local` prepends a loopback address and leaves the
line byte-for-byte -- variables, quoting and style intact -- then re-parses and
rolls back unless exactly those ports moved. It refuses anything ambiguous
rather than guessing. Rewriting the mapping to the port podman reports today
would have deleted the ${POSTGRES_PORT} indirection that makes it
configurable at all.
Unused volumes are read from podman's own dangling filter. The first version
used MountCount, which is a runtime lock counter and not a usage signal: it
reads zero for a volume a running container has mounted this second, so
"remove unused volumes" offered to delete the live Command Center database.
The cross-check against `podman system df` is what exposed it. The contract
reintroduces that bug deliberately and fails if the guard does not catch it,
because a guard nobody has seen fail proves nothing.
Every mutation in the contract runs against a stubbed podman. Nothing in the
suite starts, stops or removes a real container, image or volume.
Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L
This commit is contained in:
Gabriel Brown
Executable
+275
@@ -0,0 +1,275 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# The containers page shows rootless podman-compose stacks: what they are, what
|
||||
# they expose, and what they cost.
|
||||
#
|
||||
# The rules:
|
||||
#
|
||||
# 1. A volume in use is never offered for deletion. MountCount is a runtime
|
||||
# lock counter, not a usage signal -- it reads zero for a volume a running
|
||||
# container has mounted this second. Trusting it offered to delete the live
|
||||
# Command Center database. This is the rule the whole file exists for.
|
||||
# 2. Grouping is read from the compose labels, never invented. Where the
|
||||
# project name says nothing ("docker" is a directory), the repository does.
|
||||
# 3. Acting on a stack uses plain `podman`, never `podman-compose down`, which
|
||||
# would REMOVE containers this tool did not create.
|
||||
# 4. Exposure means published on every interface. A stopped container exposes
|
||||
# nothing yet, and is reported as such rather than as a live finding.
|
||||
# 5. Pruning names what it removes, by id, from the state that was shown.
|
||||
# 6. The compose edit adds an address and changes nothing else -- variables,
|
||||
# quoting, comments and layout all survive -- and is undone if the file
|
||||
# does not read back exactly as intended.
|
||||
# 7. A refusal states its reason. "Something failed" has let a mutation
|
||||
# through three times on this project.
|
||||
#
|
||||
# Every mutation runs against a stubbed podman. Nothing here starts, stops or
|
||||
# removes a real container, image or volume: the containers on this machine are
|
||||
# a working development database.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
|
||||
helper="$repo_dir/config/dot/quickshell/scripts/panama-containers"
|
||||
|
||||
fail() {
|
||||
printf 'containers contract: %s\n' "$1" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
[[ -r "$helper" ]] || fail "missing $helper"
|
||||
[[ -x "$helper" ]] || fail 'panama-containers is not executable'
|
||||
|
||||
work="$(mktemp -d)"
|
||||
trap 'rm -rf "$work"' EXIT
|
||||
|
||||
calls="$work/calls.log"
|
||||
: >"$calls"
|
||||
|
||||
# A repository laid out like the real one: the compose file sits well below the
|
||||
# root, in a directory called "docker", which is exactly how podman-compose ends
|
||||
# up naming the project after a directory that means nothing.
|
||||
repo="$work/command-center"
|
||||
compose_dir="$repo/packages/db/docker"
|
||||
mkdir -p "$compose_dir"
|
||||
git -C "$repo" init --quiet 2>/dev/null || fail 'could not create the fixture repository'
|
||||
compose="$compose_dir/compose.yml"
|
||||
|
||||
# ── a podman that answers, and records what it was asked to do ───────────────
|
||||
#
|
||||
# State lives in files so a test can change it between calls. Mutating verbs are
|
||||
# recorded and otherwise do nothing, which is the entire point.
|
||||
|
||||
cat >"$work/ps.json" <<PSJSON
|
||||
[
|
||||
{"Id":"aaaaaaaaaaaa1","Names":["kcc-postgres"],"Image":"pgvector:pg17",
|
||||
"State":"running","Status":"Up 32 hours (healthy)","ExitCode":0,"StartedAt":1,"Restarts":0,
|
||||
"Ports":[{"host_ip":"","host_port":5432,"container_port":5432,"protocol":"tcp","range":1}],
|
||||
"Labels":{"com.docker.compose.project":"docker","com.docker.compose.service":"kcc-postgres",
|
||||
"com.docker.compose.project.config_files":"$compose",
|
||||
"com.docker.compose.project.working_dir":"$compose_dir"}},
|
||||
{"Id":"aaaaaaaaaaaa2","Names":["kcc-redis"],"Image":"redis:7-alpine",
|
||||
"State":"running","Status":"Up 32 hours (healthy)","ExitCode":0,"StartedAt":1,"Restarts":0,
|
||||
"Ports":[{"host_ip":"127.0.0.1","host_port":6379,"container_port":6379,"protocol":"tcp","range":1}],
|
||||
"Labels":{"com.docker.compose.project":"docker","com.docker.compose.service":"kcc-redis",
|
||||
"com.docker.compose.project.config_files":"$compose",
|
||||
"com.docker.compose.project.working_dir":"$compose_dir"}},
|
||||
{"Id":"bbbbbbbbbbbb1","Names":["planner_db"],"Image":"postgres:17",
|
||||
"State":"exited","Status":"Exited (137) 3 weeks ago","ExitCode":137,"StartedAt":1,"Restarts":0,
|
||||
"Ports":[{"host_ip":"","host_port":54322,"container_port":5432,"protocol":"tcp","range":1}],
|
||||
"Labels":{"com.docker.compose.project":"planner","com.docker.compose.service":"db"}}
|
||||
]
|
||||
PSJSON
|
||||
|
||||
cat >"$work/images.json" <<'IMGJSON'
|
||||
[
|
||||
{"Id":"1111111111112222","Names":["docker.io/library/postgres:16"],"Size":458000000,"Containers":0},
|
||||
{"Id":"3333333333334444","Names":["pgvector:pg17"],"Size":450000000,"Containers":1}
|
||||
]
|
||||
IMGJSON
|
||||
|
||||
# Two volumes exist. docker_kcc-pg-data is mounted by the RUNNING postgres, so
|
||||
# podman does not consider it dangling; the anonymous one it does.
|
||||
cat >"$work/volumes-dangling.json" <<'VOLJSON'
|
||||
[{"Name":"7a830b1a58f2anonymous"}]
|
||||
VOLJSON
|
||||
|
||||
cat >"$work/df.json" <<'DFJSON'
|
||||
[
|
||||
{"Type":"Images","Total":2,"Active":1,"RawSize":908000000,"RawReclaimable":458000000},
|
||||
{"Type":"Containers","Total":3,"Active":2,"RawSize":11886090,"RawReclaimable":10795752},
|
||||
{"Type":"Local Volumes","Total":2,"Active":1,"RawSize":274720148,"RawReclaimable":84280000}
|
||||
]
|
||||
DFJSON
|
||||
|
||||
cat >"$work/podman" <<STUB
|
||||
#!/usr/bin/env bash
|
||||
printf '%s\n' "\$*" >>"$calls"
|
||||
case "\$1 \$2" in
|
||||
"ps -a") cat "$work/ps.json" ;;
|
||||
"images --format") cat "$work/images.json" ;;
|
||||
"system df") cat "$work/df.json" ;;
|
||||
"volume ls") cat "$work/volumes-dangling.json" ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
STUB
|
||||
chmod +x "$work/podman"
|
||||
export PANAMA_CONTAINERS_PODMAN="$work/podman"
|
||||
|
||||
# His actual compose style: flow sequence, an interpolation containing a colon,
|
||||
# and comments that must survive.
|
||||
cat >"$compose" <<'COMPOSE'
|
||||
services:
|
||||
kcc-postgres:
|
||||
# pgvector is the official Postgres image with the extension preinstalled.
|
||||
image: docker.io/pgvector/pgvector:pg17
|
||||
ports: ["${POSTGRES_PORT:-5432}:5432"]
|
||||
restart: unless-stopped
|
||||
kcc-redis:
|
||||
image: redis:7-alpine
|
||||
ports: ["127.0.0.1:${REDIS_PORT:-6379}:6379"]
|
||||
COMPOSE
|
||||
cp "$compose" "$work/compose.original"
|
||||
|
||||
snap() { "$helper" snapshot; }
|
||||
field() { python3 -c "import json,sys; print(json.load(sys.stdin)$1)"; }
|
||||
|
||||
state="$(snap)" || fail 'snapshot failed'
|
||||
|
||||
# ── 1. A volume in use is never offered for deletion ─────────────────────────
|
||||
|
||||
unused_volumes="$(printf '%s' "$state" | field "['disk']['unusedVolumes']")"
|
||||
case "$unused_volumes" in
|
||||
*pg-data*) fail 'a volume mounted by a running container was offered for deletion' ;;
|
||||
esac
|
||||
[[ "$unused_volumes" == *anonymous* ]] || fail 'the genuinely unused volume was not found'
|
||||
|
||||
grep -q 'dangling=true' "$helper" \
|
||||
|| fail 'unused volumes are not read from podman own dangling filter'
|
||||
# Matched as code, not as prose: the comment explaining why MountCount is the
|
||||
# wrong signal is the reason this rule is here, and must not trip it.
|
||||
grep -q 'get("MountCount")' "$helper" \
|
||||
&& fail 'MountCount is being used to decide whether a volume is in use'
|
||||
|
||||
# ── 2. Grouping comes from the labels, and says something ────────────────────
|
||||
|
||||
titles="$(printf '%s' "$state" | field "['projects']")"
|
||||
[[ "$titles" == *"'name': 'docker'"* ]] || fail 'the compose project label was not read'
|
||||
case "$titles" in
|
||||
*"'title': 'docker'"*) fail 'a project named after a directory was shown as "docker"' ;;
|
||||
esac
|
||||
|
||||
running_first="$(printf '%s' "$state" | field "['projects'][0]['running']")"
|
||||
[[ "$running_first" == "2" ]] || fail "the running project is not first (got $running_first)"
|
||||
|
||||
# ── 3. Stacks are acted on with podman, never compose down ───────────────────
|
||||
|
||||
: >"$calls"
|
||||
"$helper" project-stop docker >/dev/null || fail 'project-stop failed'
|
||||
grep -q '^stop kcc-postgres$' "$calls" || fail 'project-stop did not stop the containers'
|
||||
grep -qi 'compose' "$calls" && fail 'project-stop invoked podman-compose'
|
||||
grep -qE '^(rm|rmi) ' "$calls" && fail 'project-stop removed something'
|
||||
|
||||
# A verb with nothing to do refuses, and says why.
|
||||
: >"$calls"
|
||||
reason="$(printf '%s' "$("$helper" start kcc-postgres)" | field "['error']")"
|
||||
[[ "$reason" == *"already running"* ]] \
|
||||
|| fail "starting a running container did not say why it refused (got: $reason)"
|
||||
[[ -s "$calls" ]] && grep -qE '^start ' "$calls" && fail 'it started an already-running container'
|
||||
|
||||
# ── 4. Exposure is published-on-every-interface, and honest about state ──────
|
||||
|
||||
exposed="$(printf '%s' "$state" | field "['exposed']")"
|
||||
[[ "$exposed" == *kcc-postgres* ]] || fail 'a container published on every interface was not reported'
|
||||
case "$exposed" in
|
||||
*kcc-redis*) fail 'a container bound to loopback was reported as exposed' ;;
|
||||
esac
|
||||
[[ "$exposed" == *"'container': 'planner_db'"* ]] || fail 'a stopped publisher was dropped entirely'
|
||||
printf '%s' "$state" | python3 -c "
|
||||
import json,sys
|
||||
for e in json.load(sys.stdin)['exposed']:
|
||||
if e['container'] == 'planner_db' and e['running']:
|
||||
raise SystemExit('a stopped container was reported as currently reachable')
|
||||
" || fail 'a stopped container was reported as currently reachable'
|
||||
|
||||
# ── 5. Pruning names what it removes ─────────────────────────────────────────
|
||||
|
||||
: >"$calls"
|
||||
"$helper" prune-images >/dev/null || fail 'prune-images failed'
|
||||
grep -q '^rmi 111111111111$' "$calls" || fail 'prune-images did not remove the unused image by id'
|
||||
grep -q '^rmi 333333333333$' "$calls" && fail 'prune-images removed an image still in use'
|
||||
grep -q 'image prune' "$calls" && fail 'prune-images used a blanket prune instead of named ids'
|
||||
|
||||
# Nothing to do refuses with a reason.
|
||||
cat >"$work/images.json" <<'ALLUSED'
|
||||
[{"Id":"3333333333334444","Names":["pgvector:pg17"],"Size":450000000,"Containers":1}]
|
||||
ALLUSED
|
||||
: >"$calls"
|
||||
reason="$(printf '%s' "$("$helper" prune-images)" | field "['error']")"
|
||||
[[ "$reason" == *"in use"* ]] || fail "prune-images did not say why it refused (got: $reason)"
|
||||
grep -qE '^rmi ' "$calls" && fail 'prune-images removed something while refusing'
|
||||
|
||||
# ── 6. The compose edit adds an address and nothing else ─────────────────────
|
||||
|
||||
result="$("$helper" bind-local docker kcc-postgres)" || fail 'bind-local failed'
|
||||
reason="$(printf '%s' "$result" | field "['error']")"
|
||||
[[ -z "$reason" ]] || fail "bind-local refused a valid edit: $reason"
|
||||
|
||||
grep -q 'ports: \["127.0.0.1:\${POSTGRES_PORT:-5432}:5432"\]' "$compose" \
|
||||
|| fail 'the edit did not preserve the interpolation, the quoting, or the flow style'
|
||||
grep -q '# pgvector is the official Postgres image' "$compose" \
|
||||
|| fail 'the edit destroyed a comment'
|
||||
grep -q 'restart: unless-stopped' "$compose" \
|
||||
|| fail 'the edit disturbed the rest of the service'
|
||||
[[ "$(grep -c '' "$compose")" == "$(grep -c '' "$work/compose.original")" ]] \
|
||||
|| fail 'the edit changed the shape of the file'
|
||||
|
||||
# Twice is a refusal, not a second address.
|
||||
reason="$(printf '%s' "$("$helper" bind-local docker kcc-postgres)" | field "['error']")"
|
||||
[[ -n "$reason" ]] || fail 'binding an already-bound service was allowed'
|
||||
grep -q '127.0.0.1:127.0.0.1' "$compose" && fail 'the address was prepended twice'
|
||||
|
||||
# A service whose ports it cannot read is refused, not guessed at.
|
||||
cat >"$compose" <<'RANGE'
|
||||
services:
|
||||
kcc-postgres:
|
||||
ports:
|
||||
- "5432:5432"
|
||||
- "5432:5432"
|
||||
RANGE
|
||||
reason="$(printf '%s' "$("$helper" bind-local docker kcc-postgres)" | field "['error']")"
|
||||
[[ "$reason" == *"times"* || "$reason" == *"not clear"* ]] \
|
||||
|| fail "an ambiguous mapping was not refused with a reason (got: $reason)"
|
||||
grep -q '127.0.0.1' "$compose" && fail 'an ambiguous compose file was edited anyway'
|
||||
|
||||
# ── 7. The tests above must be capable of failing ────────────────────────────
|
||||
#
|
||||
# Rule 1 is the one that matters, so it is proven to fail: told to use
|
||||
# MountCount, the helper must offer the live database for deletion and be
|
||||
# caught. A guard nobody has seen fail is not a guard.
|
||||
|
||||
probe="$work/probe-helper"
|
||||
sed 's/"volume", "ls", "--filter", "dangling=true", "--format", "json"/"volume", "ls", "--format", "json"/' \
|
||||
"$helper" >"$probe"
|
||||
chmod +x "$probe"
|
||||
cat >"$work/volumes-all.json" <<'ALLVOL'
|
||||
[{"Name":"docker_kcc-pg-data","MountCount":0},{"Name":"7a830b1a58f2anonymous","MountCount":0}]
|
||||
ALLVOL
|
||||
sed -i "s|\"volume ls\") cat \"$work/volumes-dangling.json\"|\"volume ls\") cat \"$work/volumes-all.json\"|" "$work/podman"
|
||||
cat >"$work/podman" <<STUB2
|
||||
#!/usr/bin/env bash
|
||||
printf '%s\n' "\$*" >>"$calls"
|
||||
case "\$1 \$2" in
|
||||
"ps -a") cat "$work/ps.json" ;;
|
||||
"images --format") cat "$work/images.json" ;;
|
||||
"system df") cat "$work/df.json" ;;
|
||||
"volume ls") cat "$work/volumes-all.json" ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
STUB2
|
||||
chmod +x "$work/podman"
|
||||
|
||||
leaked="$("$probe" snapshot | field "['disk']['unusedVolumes']")"
|
||||
[[ "$leaked" == *pg-data* ]] \
|
||||
|| fail 'the volume guard cannot be made to fail, so it proves nothing'
|
||||
|
||||
printf 'containers contract: ok\n'
|
||||
Reference in New Issue
Block a user