On Kubernetes
running pkgproxy for administrators for CI operators
The pkgproxy-k8s charm runs the pkgproxy rock on Kubernetes with Juju, one unit with its cache on Juju storage, options that are the daemon's settings checked before they apply, a ClusterIP or LoadBalancer Service, and actions for stats, invalidating a file and setup scripts.
On the map: running pkgproxy
▶ Watch this deck — 7 scenes, ~4 min
Part of journeys
- Operating pkgproxy for CI, step 6 of 12 · previous: In a container · next: Juju machines
01 What this topic covers
The pkgproxy-k8s charm: the rock as its workload, the cache
on Juju storage, options, Services and actions.
The Kubernetes charm runs pkgproxy on Kubernetes, with Juju, as the shared cache of the machines around a model. You will see the rock it deploys and how a release pairs the two. Then come the cache on Juju storage, options that are the daemon's settings, and the Service clients reach it on. Last come the actions that stand in for a shell.
02 The rock, deployed by Juju
juju deploy pkgproxy-k8s: Charmhub releases the charm with the
pkgproxy-image resource of its commit, by digest. A local
charm needs --resource pkgproxy-image=IMAGE. One unit only.
The Kubernetes charm runs pkgproxy in a pod, with Juju. Its workload is the rock, the same image you can run with docker, given to the charm as a resource. Each release on Charmhub pairs a charm revision with the rock built from the same commit, named by its digest, so a channel always runs the rock it was tested with. A charm you pack yourself has no rock of its own: name one when you deploy it. The charm runs one unit, and a second one leaves it blocked.
03 The cache on Juju storage
Storage cache: a filesystem of at least 16G at
/var/cache/pkgproxy, owned by 584792, the rock's user. Size it
with --storage cache=SIZE. Without extended attributes the
unit is blocked.
The cache is Juju storage named cache, a file system of at least sixteen gigabytes, mounted where the rock keeps its cache. On Kubernetes it is a persistent volume claim, so it outlives the pod. After a restart or a juju refresh, the cache, the statistics and the LXD certificate are still there. pkgproxy runs as the rock's own user, and the charm gives that user the volume before pkgproxy starts. A volume that cannot keep extended attributes leaves the unit blocked, with a message that says why.
04 Options are the daemon's settings
juju config pkgproxy-k8s NAME=VALUE becomes
PKGPROXY_NAME when it is not the default.
pkgproxy -check-config runs first; a refusal blocks the unit.
The model's juju-http-proxy and the others become
HTTP_PROXY, HTTPS_PROXY and NO_PROXY.
Each charm option is the daemon setting of the same name. The charm passes it as its environment variable only when it differs from the default, so an option set back to its default leaves the environment. Before it applies anything, the charm runs pkgproxy with the check config flag inside the workload. A refused value blocks the unit with the daemon's own message, and pkgproxy keeps running with the last good settings. The model's proxy settings reach the daemon as its proxy variables.
05 A Service for the clients
service-type=cluster (default):
pkgproxy-k8s.MODEL.svc:3142.
service-type=loadbalancer adds APP-lb with
externalTrafficPolicy: Local. Refused:
juju trust APP --scope=cluster.
Clients in the cluster reach pkgproxy on the application's Service, by its name in the model, on port 3142, and 3143 for LXD. Machines outside the cluster need an address of their own. Setting the service-type option to loadbalancer adds a second Service, of type LoadBalancer, that keeps each client's own address, for the access log and the trusted-networks option. Juju 3.6 lets the charm make that Service. Where the cluster refuses, the unit is blocked, and its status names the juju trust command to run.
06 Actions instead of a shell
juju run pkgproxy-k8s/0 stats, invalidate url=URL
and setup-script client=CLIENT [undo=true], for apt, snap,
go, docker, lxd, lxd-remote, snapcraft, rockcraft and charmcraft. Offline
mode is the offline-mode option.
The rock has no shell, so the commands of pkgproxyctl are actions instead, run with juju run. Stats prints the report. Invalidate throws away the cached copy of one apt file, given by its URL. The setup-script action prints the script that points one tool on a client machine at this pkgproxy. It names the public-url option when it is set, else the load balancer's address, else the Service in the cluster. There is no action for offline mode: it is an option, so juju config always says what pkgproxy does.
07 Where to go next
Next: In a container, for the rock; Juju machines, for the machine charm; The setup page, for pointing clients at it.
pkgproxy now runs on Kubernetes as one unit, with its cache on a claim that outlives its pods, and clients inside and outside the cluster can reach it. To see the image the charm runs, watch In a container. To run the snap on a machine with Juju instead, watch Juju machines. To point client machines at it, watch The setup page.
Read more
Deploying
| Command | What it does |
|---|---|
juju deploy pkgproxy-k8s | the charm from Charmhub, with the rock released with it |
juju deploy pkgproxy-k8s --storage cache=100G | the same, with a cache larger than the 16G minimum |
juju deploy ./CHARM --resource pkgproxy-image=IMAGE | a charm you packed, with the rock you name |
- Charm
pkgproxy-k8s, base Ubuntu 26.04, amd64. It needs Juju 3.6 or later. - Channels on Charmhub:
latest/edgefollows the main branch,latest/stablethe releases. Each charm revision is released with the rock of the same commit, by digest. - One unit. A second one leaves the application blocked.
Options
Each option is the daemon setting of the same name, passed as its PKGPROXY_* variable only when it differs from the default. Settings has what each one does.
| Option | Default | Sets |
|---|---|---|
public-url | empty | the address the setup page tells visitors to use |
setup-page | true | the setup page at / and its scripts under /setup/ |
trusted-networks | empty | networks whose visitors may see the cache page |
offline-mode | store-overloaded | store-overloaded, never or offline |
revalidate-ttl | 5m0s | how long lists are served before they are checked |
upstream-idle-timeout | 1m0s | how long an upstream may send nothing |
upstream-retry-for | 2m0s | how long a broken-off download is asked for again |
docker-upstream | https://registry-1.docker.io | the Docker Hub registry, or off |
files-allow-host | empty | hosts files by checksum may come from |
files-allow-network | empty | private networks files may come from |
files-max-size | 8G | the largest file by checksum |
service-type | cluster | cluster, or loadbalancer for a Service with an outside address (the charm's own) |
lxd-tls | true | false turns port 3143 off (lxd-tls-addr=off) |
- Before applying a change, the charm runs
pkgproxy -check-configin the workload with the new environment. A refused value blocks the unit with the daemon's message, and pkgproxy keeps the last good settings. - The model's
juju-http-proxy,juju-https-proxyandjuju-no-proxyreach pkgproxy asHTTP_PROXY,HTTPS_PROXYandNO_PROXY, in both spellings. - A change that is accepted restarts pkgproxy, in seconds.
Storage and ports
Storage cache | a filesystem of at least 16G, mounted at /var/cache/pkgproxy; a persistent volume claim that outlives the pod |
| Owner | UID and GID 584792, the rock's user; the charm hands the volume to it before pkgproxy starts |
| Extended attributes | required; a volume without them blocks the unit |
| Ports | 3142, and 3143 unless lxd-tls is false |
| In the cluster | http://pkgproxy-k8s.MODEL.svc:3142 |
service-type=loadbalancer | a Service APP-lb of type LoadBalancer, with externalTrafficPolicy: Local, so pkgproxy sees each client's own address |
Where the cluster refuses to let the charm manage APP-lb, the unit is blocked with service-type=loadbalancer needs trust: juju trust APP --scope=cluster, and pkgproxy keeps serving the clients in the cluster. Back on cluster, and when the application is removed, APP-lb is deleted.
Actions
| Action | Parameters | Result |
|---|---|---|
stats | none | output: the report of pkgproxyctl stats |
invalidate | url (required): the http:// address of an apt file under dists/ or pool/ | output: what pkgproxyctl cache invalidate printed |
setup-script | client (required): apt, snap, go, docker, lxd, lxd-remote, snapcraft, rockcraft or charmcraft; undo (default false) | script: the script to run on the client |
- Run them with
juju run pkgproxy-k8s/0 ACTION [PARAM=VALUE ...]. A failure gives whatpkgproxyctlprinted. setup-scriptuses the host and port ofpublic-urlwhen it is set (port 80 when it names none), else the LoadBalancer Service's address, elseAPP.MODEL.svc:3142. Forlxd-remoteit adds port 3143 on the same host.setup-scriptrefusesdockerwhendocker-upstreamisoff, andlxd-remotewhenlxd-tlsisfalse.- Run the scripts for
apt,snapanddockeras root, forgoas yourself, and forlxd,lxd-remoteand the craft tools as the user who runslxc. Each craft tool takes its base images throughlxd-remote, so set that up too. - There is no action for offline mode: set the
offline-modeoption.
Status
The first that applies:
| Status | Message |
|---|---|
| blocked | scale to one unit: more are not supported yet (pkgproxy#111) |
| blocked | an unknown service-type, or the juju trust message above |
| blocked | the cache storage does not keep extended attributes: use another storage pool |
| blocked | the daemon's message about a refused option |
| waiting | waiting for the cache storage, waiting for Pebble, waiting for pkgproxy to answer |
| active | empty; offline: serving the cache only; or offline by itself: REASON |
Offline is active, not blocked: what the cache holds is still served.
In the documentation
- Running pkgproxy in a container: the rock this charm runs
- Settings: every setting with its default
- Where the cache lives: extended attributes
Roads from here
CORE · the path every side shares
- Offline mode — the offline-mode option
SETUP AND THE COMMAND LINE
- The setup page — the scripts client machines fetch
RUNNING PKGPROXY
- In a container — the image the charm runs
- Juju machines — the charm that runs the snap on a machine
OPERATIONS
- Settings — what each option sets in the daemon
- The access log — the client addresses a load balancer keeps