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

01 What this topic covers

ABOUT THIS TOPIC Juju machines the pkgproxy charm runs the snap on a machine 1 The snap, pinned to the charm 2 Options through snap set 3 Storage, ports and status 4 The same actions as on Kubernetes
The topic title, Juju machines, and its 4 scenes in order: The snap, pinned to the charm; Options through snap set; Storage, ports and status; The same actions as on Kubernetes

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 SNAP IT INSTALLS a charm revision x86_64 = revision N the snap it pins a machine snap install pkgproxy --revision=N snap refresh --hold pkgproxy $ juju refresh pkgproxy the snap moves to the new charm's pin published by CI the snap of the same commit $ juju attach-resource pkgproxy pkgproxy-snap=./pkgproxy.snap a snap of your own, installed with --dangerous in place of the pin
A charm revision carries a pinned snap revision per architecture; on the machine the charm installs that revision and holds it; juju refresh moves it to the next charm's pin; CI pins the snap of the same commit; an attached pkgproxy-snap resource is installed instead

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

OPTIONS $ juju config pkgproxy revalidate-ttl=10m no service-type here snap set pkgproxy revalidate-ttl=10m snap set pkgproxy files-max-size! a default: unset the snap's configure hook checks refused: unit blocked the hook's last line; last good kept the model's proxy settings juju-http-proxy, juju-https-proxy, juju-no-proxy → http-proxy, https-proxy, no-proxy
juju config becomes snap set on the machine, or an unset for a default; the snap's configure hook checks the values; a refused change keeps the last good options and blocks the unit with the hook's last line; the model's proxy settings become the snap's proxy options

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

STORAGE, PORTS AND STATUS $ juju deploy pkgproxy --storage cache=100G a machine the pkgproxy snap cache /var/snap/pkgproxy/common/cache no storage: the root disk no extended attributes: blocked 3142 · 3143 $ juju expose pkgproxy Ubuntu 24.04 and 26.04, amd64 active: offline: serving the cache only
A machine running the snap: optional cache storage at /var/snap/pkgproxy/common/cache, or the root disk without it; storage without extended attributes blocks the unit; ports 3142 and 3143 opened for juju expose; Ubuntu 24.04 and 26.04 on amd64; offline shows as an active status with a message

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

ACTIONS the same three actions as the Kubernetes charm $ juju run pkgproxy/0 stats $ juju run pkgproxy/0 invalidate url=http://.../dists/resolute/InRelease $ juju run pkgproxy/0 setup-script client=apt a script to run on the client machine each runs the snap's pkgproxyctl on the machine the address in the script, the first that is set public-url the unit's address, port 3142
Three juju run commands on the machine charm: stats, invalidate with a URL, and setup-script with a client; each runs the snap's pkgproxyctl on the machine; the setup script names public-url, else the unit's address on port 3142

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

WHERE NEXT the snap, kept at its charm's revision you are here Juju machines On Kubernetes the same options and actions Settings what each option sets in the daemon The setup page pointing client machines at it
Where next from Juju machines: On Kubernetes, the same options and actions; Settings, what each option sets; The setup page, pointing client machines at it

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

CommandWhat it does
juju deploy pkgproxythe charm from Charmhub, which installs the snap revision it pins
juju deploy pkgproxy --storage cache=100Gthe same, with the cache on Juju storage
juju expose pkgproxymakes ports 3142 and 3143 reachable
juju refresh pkgproxya new charm revision, and the snap revision it pins
juju attach-resource pkgproxy pkgproxy-snap=./pkgproxy.snapinstalls 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/edge follows the main branch, latest/stable the releases.

The snap it installs

  • The charm installs pkgproxy from the store at the revision it pins for the machine's architecture, then holds it with snap 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-snap resource. 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.

OptionDefaultSnap option
public-urlemptypublic-url
setup-pagetruesetup-page
trusted-networksemptytrusted-networks
offline-modestore-overloadedoffline-mode
revalidate-ttl5m0srevalidate-ttl
upstream-idle-timeout1m0supstream-idle-timeout
upstream-retry-for2m0supstream-retry-for
docker-upstreamhttps://registry-1.docker.iodocker-upstream
files-allow-hostemptyfiles-allow-host
files-allow-networkemptyfiles-allow-network
files-max-size8Gfiles-max-size
lxd-tlstruefalse 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-proxy and juju-no-proxy set the snap's http-proxy, https-proxy and no-proxy. Without them those are unset, and the snap takes the proxies of /etc/environment.

Storage and ports

Storage cacheoptional, at most one, at least 16G, mounted at /var/snap/pkgproxy/common/cache
Without itthe cache is on the machine's root disk
Extended attributesrequired; storage without them blocks the unit
Ports3142, and 3143 unless lxd-tls is false, opened for juju expose

Status

StatusMessage
blockedthe cache storage does not keep extended attributes: use another storage pool
blockedthe configure hook's last line, for a refused option
waitingwaiting for pkgproxy to answer
activeempty; 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:

ActionParametersResult
statsnoneoutput: the report of pkgproxyctl stats
invalidateurl (required): the http:// address of an apt file under dists/ or pool/output: what pkgproxyctl cache invalidate printed
setup-scriptclient (required): apt, snap, go, docker, lxd, lxd-remote, snapcraft, rockcraft or charmcraft; undo (default false)script: the script to run on the client
  • setup-script uses the host and port of public-url when it is set (port 80 when it names none), else the unit's address on port 3142. For lxd-remote it adds port 3143 on the same host.
  • It refuses docker when docker-upstream is off, and lxd-remote when lxd-tls is false.
  • Run the scripts for apt, snap and docker as root, and for go, lxd, lxd-remote and the craft tools as yourself, the user who runs lxc. Each craft tool takes its base images through lxd-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 charmKubernetes charm
Runsthe snap, at a pinned revisionthe rock, by digest
Options reach pkgproxy assnap optionsPKGPROXY_* variables
Cache storageoptionalrequired
service-typenone: juju exposecluster or loadbalancer
Address setup-script gives without public-urlthe unit's juju-info address, port 3142the LoadBalancer's, else APP.MODEL.svc:3142

In the documentation

Roads from here

CORE · the path every side shares

SETUP AND THE COMMAND LINE

RUNNING PKGPROXY

OPERATIONS

  • Settings — what each option sets in the daemon