pkgproxy design: the rock
The OCI image of pkgproxy, built with rockcraft. Part of the pkgproxy design, whose index says which file holds each § number.
29. The rock: an OCI image built with rockcraft
rockcraft.yaml at the repository root builds pkgproxy as a rock: an OCI
image for docker, podman and Kubernetes, and the workload image of the
Kubernetes charm (gitlab.com/zygoon/pkgproxy#101). Rockcraft puts Pebble
in every rock as its entrypoint, and pkgproxy runs as a Pebble service.
29.1 Image layout
base: bare,build-base: ubuntu@26.04, the release of the snap’s core26, for amd64 and arm64. The image holds the static (CGO_ENABLED=0) binary, the CA certificates (theca-certificates_datachisel slice) for the upstreams reached over HTTPS, and Pebble. It has no shell./usr/bin/pkgproxy, and/usr/bin/pkgproxyctlas a symlink to it: the binary is multi-call, as in the snap.run-user: _daemon_, rockcraft’s shared non-root user (UID and GID 584792). Pebble and pkgproxy run as that user./var/cache/pkgproxyand/run/pkgproxy, owned by 584792: the daemon’s own default cache and run directories (cmd/pkgproxy/statssocket.go). With the defaults, the image sets noPKGPROXY_*variable, anddocker exec CONTAINER pkgproxyctl statsfinds the stats socket without flags.pkgproxyctldoes not readPKGPROXY_*, so other paths would need its-socket-pathon every call.- pkgproxy needs no
/tmp: the Go side writes its temporary files under the cache (gitlab.com/zygoon/pkgproxy#152).
29.2 Storage
A rock does not declare volumes or ports: rockcraft.yaml has no keys for
them, and the image has no OCI Volumes or ExposedPorts. Which storage
is mounted, and which ports are published, is the runtime’s choice. The
image only prepares /var/cache/pkgproxy for a volume:
- A new named docker or podman volume mounted there is seeded from the image, ownership included, so it is writable by 584792 with no further step.
- A bind mount is not seeded: the host directory has to be owned by
584792 (
chown 584792:584792), or mounted with podman’s:U. - On Kubernetes the charm declares the storage and mounts it at
/var/cache/pkgproxy. Making it writable by 584792 is the charm’s task.
Without a volume the cache lives in the container’s writable layer and is
lost with the container. /run/pkgproxy holds only the sockets, which
pkgproxy makes again at every start, and needs no volume.
29.3 Configuration
pkgproxy reads every option from its flag or from PKGPROXY_<NAME>
(§18), so the
rock needs no configuration file. In a rock, an option can come from
five places. The strongest first:
- A flag.
docker run IMAGE --args pkgproxy -addr=:8080replaces the empty[ ]default arguments of the service’s command, and a flag beats a variable. - The Pebble service’s own
environment. Pebble starts a service with its own environment and adds the service’senvironmentafter it, so the service’s values win over the container’s. - The container’s environment:
docker run -e, a pod’senv. - The rock’s top-level
environment, which becomes the image’s OCIEnv, under the container’s environment. - The daemon’s default.
So a default meant to be changed with -e belongs in the top-level
environment, never in the service’s. The rock sets no PKGPROXY_*
variable in either: the daemon’s defaults suit a container, auto-offline
and the offline mode included. Its top-level environment has only
PEBBLE_VERBOSE=1. Without it, Pebble’s entrypoint (pebble enter)
keeps what its services print to itself, and docker logs or kubectl logs would show none of pkgproxy’s log, its message about an invalid
option included. The default
-auto-offline network follows the container’s own network namespace,
as the snap follows the machine’s. A charm configures pkgproxy through
the service’s environment, in a Pebble layer of its own over the
rock’s, and pkgproxy -check-config validates the result.
29.4 Service, health and stopping
The pkgproxy service starts with the container. When pkgproxy exits,
for whatever reason, Pebble shuts down (on-success and on-failure: shutdown). The container then ends, and its runtime decides what comes
next: a restart policy, or a pod’s restart. An invalid option shows as a
container that exits with pkgproxy’s message, not as a restart loop
inside it.
The health check (level: ready) asks GET /pkgproxy/v1/health on
localhost:3142
(§12). It fails when
-addr names another port, which a charm that changes the port replaces
with its own check.
kill-delay is 15s, above pkgproxy’s -shutdown-grace (10s), so that
requests in progress finish before Pebble sends SIGKILL. Rockcraft
cannot set the OCI stop timeout, and docker stop waits 10s by default,
so docker users pass docker stop -t 20. Kubernetes gives a pod 30s.
29.5 Version
The rock’s version comes from git describe, as the snap’s does, with
- in place of +, which an OCI tag cannot hold: v0.12.1 on a tag,
v0.12.1-git5.abc1234 after it. The binary’s own version comes from Go’s
VCS stamping (cmd/pkgproxy/version.go), so the build needs .git and
a clean tree, and a worktree’s .git file does not reach the build
instance. Pack from a clone.