Juju machines
running pkgproxy for administrators for CI operators
The pkgproxy machine charm installs the pkgproxy snap at a revision pinned to the charm, sets the same options as the Kubernetes charm with snap set, keeps the cache on optional Juju storage, opens the ports for juju expose, and has the Kubernetes charm's actions for stats, invalidating a file and setup scripts.
On the map: running pkgproxy
▶ Watch this deck — 6 scenes, ~4 min
Part of journeys
- Operating pkgproxy for CI, step 7 of 12 · previous: On Kubernetes · next: One listener
01 What this topic covers
The pkgproxy charm: the snap at a pinned revision, options
through snap set, optional storage and open ports, and the Kubernetes charm's actions.
The machine charm runs the pkgproxy snap on a machine that Juju manages, as the shared cache of the machines around it. You will see how it installs the snap, pinned to the charm, and how its options reach the snap through snap set. Then come the optional cache storage, the ports it opens and the status it shows. Last come its actions, the same as on Kubernetes.
02 The snap, pinned to the charm
The charm runs snap install pkgproxy --revision=N and
snap refresh --hold pkgproxy; juju refresh
moves it to the next pin. A non-empty pkgproxy-snap resource
is installed with --dangerous instead.
The machine charm installs the pkgproxy snap from the store, at the revision the charm pins for the machine's architecture, and holds it there. So the snap changes only when you refresh the charm, which moves it to the new charm's pin. When CI publishes a charm, it pins the snap built from the same commit, matched by its version. To try a snap of your own, attach it as the pkgproxy-snap resource, and the charm installs that instead of the one from the store.
03 Options through snap set
juju config pkgproxy NAME=VALUE runs
snap set pkgproxy NAME=VALUE, or NAME! for the
default. The model's proxies set http-proxy,
https-proxy and no-proxy.
The machine charm has the options of the Kubernetes charm, without the service-type. Each one is the snap option of the same name: the charm sets it with snap set when it differs from its default, and unsets it otherwise. The snap's configure hook checks every value, so a refused change leaves snapd with the last good options, and the unit is blocked with the hook's last line, the daemon's own message. The model's proxy settings become the snap's proxy options.
04 Storage, ports and status
juju deploy pkgproxy --storage cache=100G mounts it at
/var/snap/pkgproxy/common/cache. juju expose
pkgproxy opens 3142 and 3143. Offline shows as an active status
with a message.
Cache storage is optional here. Deploy with it, and the volume is mounted on the snap's cache directory; without it, the cache is on the machine's root disk. Storage that cannot keep extended attributes blocks the unit. The charm opens 3142, and 3143 unless the lxd-tls option is false, so juju expose makes them reachable. It runs on Ubuntu 24.04 and 26.04, on amd64. When pkgproxy is offline, the unit stays active and says so.
05 The same actions as on Kubernetes
juju run pkgproxy/0 stats, invalidate url=URL
and setup-script client=CLIENT [undo=true]. The address is
public-url's, else the unit's juju-info address.
The machine charm has the Kubernetes charm's three actions, so you run both charms the same way. Each runs pkgproxyctl from the snap on the machine. Stats prints the report, and invalidate throws away the cached copy of one apt file. 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 unit's own address, on port 3142. You run that script on the client.
06 Where to go next
Next: On Kubernetes, for the same options and actions; Settings, for what each option sets; The setup page, for pointing clients at it.
Juju now installs the pkgproxy snap on a machine, keeps it at the revision of its charm and sets its options for you. To run the same options and actions on Kubernetes, watch On Kubernetes. For what each option changes in the daemon, watch Settings. To point client machines at it, watch The setup page.
Read more
Deploying
| Command | What it does |
|---|---|
juju deploy pkgproxy | the charm from Charmhub, which installs the snap revision it pins |
juju deploy pkgproxy --storage cache=100G | the same, with the cache on Juju storage |
juju expose pkgproxy | makes ports 3142 and 3143 reachable |
juju refresh pkgproxy | a new charm revision, and the snap revision it pins |
juju attach-resource pkgproxy pkgproxy-snap=./pkgproxy.snap | installs that snap with --dangerous instead of the pinned one |
- Charm
pkgproxy, for Ubuntu 24.04 and 26.04, amd64 only for now. - Channels on Charmhub:
latest/edgefollows the main branch,latest/stablethe releases.
The snap it installs
- The charm installs
pkgproxyfrom the store at the revision it pins for the machine's architecture, then holds it withsnap refresh --hold pkgproxy. The snap does not refresh by itself. - A charm published by CI pins the snap revisions built from the same commit. The charm's version, such as
v0.12.1-6-g169a226, is matched to the snap's,v0.12.1+git6.169a226; the commit hashes need only agree in their common prefix. - A charm packed by hand pins a released snap.
- The published charm comes with an empty
pkgproxy-snapresource. A non-empty one replaces the pinned snap, at install and whenever a new one is attached.
Options
The options of On Kubernetes, without service-type. Each is the snap option of the same name: the charm runs snap set pkgproxy NAME=VALUE when it differs from its default, and snap set pkgproxy NAME! otherwise.
| Option | Default | Snap option |
|---|---|---|
public-url | empty | public-url |
setup-page | true | setup-page |
trusted-networks | empty | trusted-networks |
offline-mode | store-overloaded | offline-mode |
revalidate-ttl | 5m0s | revalidate-ttl |
upstream-idle-timeout | 1m0s | upstream-idle-timeout |
upstream-retry-for | 2m0s | upstream-retry-for |
docker-upstream | https://registry-1.docker.io | docker-upstream |
files-allow-host | empty | files-allow-host |
files-allow-network | empty | files-allow-network |
files-max-size | 8G | files-max-size |
lxd-tls | true | false sets lxd-tls-addr=off |
- The snap's configure hook runs
pkgproxy -check-config. When it refuses a value, snapd keeps the last good options and the unit is blocked with the hook's last line. - The model's
juju-http-proxy,juju-https-proxyandjuju-no-proxyset the snap'shttp-proxy,https-proxyandno-proxy. Without them those are unset, and the snap takes the proxies of/etc/environment.
Storage and ports
Storage cache | optional, at most one, at least 16G, mounted at /var/snap/pkgproxy/common/cache |
| Without it | the cache is on the machine's root disk |
| Extended attributes | required; storage without them blocks the unit |
| Ports | 3142, and 3143 unless lxd-tls is false, opened for juju expose |
Status
| Status | Message |
|---|---|
| blocked | the cache storage does not keep extended attributes: use another storage pool |
| blocked | the configure hook's last line, for a refused option |
| waiting | waiting for pkgproxy to answer |
| active | empty; offline: serving the cache only; or offline by itself: REASON |
Actions
The same actions as the Kubernetes charm, each running the snap's pkgproxyctl on the machine:
| 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 |
setup-scriptuses the host and port ofpublic-urlwhen it is set (port 80 when it names none), else the unit's address on port 3142. Forlxd-remoteit adds port 3143 on the same host.- It refuses
dockerwhendocker-upstreamisoff, andlxd-remotewhenlxd-tlsisfalse. - Run the scripts for
apt,snapanddockeras root, and forgo,lxd,lxd-remoteand the craft tools as yourself, the user who runslxc. Each craft tool takes its base images throughlxd-remote, so set that up too.
juju run pkgproxy/0 setup-script client=apt --format=json | jq -r '.[].results.script' | sudo sh
Differences from the Kubernetes charm
| Machine charm | Kubernetes charm | |
|---|---|---|
| Runs | the snap, at a pinned revision | the rock, by digest |
| Options reach pkgproxy as | snap options | PKGPROXY_* variables |
| Cache storage | optional | required |
service-type | none: juju expose | cluster or loadbalancer |
Address setup-script gives without public-url | the unit's juju-info address, port 3142 | the LoadBalancer's, else APP.MODEL.svc:3142 |
In the documentation
- Changing settings: snap options
- Settings: every setting with its default
- Where the cache lives: extended attributes
Roads from here
CORE · the path every side shares
- The store — where the cache lives on disk
- Offline mode — the offline-mode option
- One listener — the ports juju expose opens and the health route
SETUP AND THE COMMAND LINE
- The setup page — the scripts client machines fetch
RUNNING PKGPROXY
- On Kubernetes — the same options and actions on Kubernetes
OPERATIONS
- Settings — what each option sets in the daemon