Contents · The rock

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 (the ca-certificates_data chisel slice) for the upstreams reached over HTTPS, and Pebble. It has no shell.
  • /usr/bin/pkgproxy, and /usr/bin/pkgproxyctl as 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/pkgproxy and /run/pkgproxy, owned by 584792: the daemon’s own default cache and run directories (cmd/pkgproxy/statssocket.go). With the defaults, the image sets no PKGPROXY_* variable, and docker exec CONTAINER pkgproxyctl stats finds the stats socket without flags. pkgproxyctl does not read PKGPROXY_*, so other paths would need its -socket-path on 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:

  1. A flag. docker run IMAGE --args pkgproxy -addr=:8080 replaces the empty [ ] default arguments of the service’s command, and a flag beats a variable.
  2. The Pebble service’s own environment. Pebble starts a service with its own environment and adds the service’s environment after it, so the service’s values win over the container’s.
  3. The container’s environment: docker run -e, a pod’s env.
  4. The rock’s top-level environment, which becomes the image’s OCI Env, under the container’s environment.
  5. 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.