☸️ Agent on Kubernetes

This page is for people who already use Kubernetes. If that's not you, don't set it up just for the agent: with Docker, or with your computer's package (in The local agent), you get the same with fewer moving parts.

---

What you need

• A Kubernetes cluster and kubectl with access to it.
• For the node the agent runs on to be on the same network as the printers. The agent uses the node's network (hostNetwork) to find them, just like Docker's network_mode: host.
• If you want the persistent volume (further down), a default StorageClass in the cluster.

It's lightweight: the manifest reserves 256 MB of memory for it and doesn't let it go over 512 MB.

---

Creating it in BolloPrint

1. Go to Settings → Printers and open the Local agent tab.
2. Click New agent. Under Where will you install it?, choose Kubernetes, in With a container.
3. Give it a name you'll recognise. Better where it is than what it is: "Unit rack", "Office cluster".
4. Click Create agent.
5. The manifest appears, in the Kubernetes tab, with the agent's keys already written in. If you want it, tick With a persistent volume (see below). Click Copy.
6. With the manifest saved somewhere safe, click Save to close the window.

What's in the manifest

• A Secret called bolloprint-agent with the agent's two keys: BP_AGENT_CODE (which workshop it works for) and BP_AGENT_INSTANCE_ID (who it is). Treat them like a password.
• A Deployment called bolloprint-agent, with a single replica, that swaps the pod all at once (Recreate) so there are never two at the same time. It runs without privileges, on the node's network and with a 512 MB memory limit.
• With With a persistent volume ticked, a 256 MB PersistentVolumeClaim as well.

It has no namespace: it's created in whichever one you have active. If you want it separate, create one and apply it with -n.

With a persistent volume or without?

Without a volume, the agent works just the same. The difference is in updates: the agent updates itself by downloading the new version, and without a volume that download is lost every time the pod restarts. It then starts on the image's version and takes a while to catch up again (a few minutes, or until the print in progress finishes).

• Tick it if your cluster has a default StorageClass. That's the recommended option.
• Leave it unticked if it doesn't: a volume that can't be created leaves the pod waiting forever, and the agent never starts.

Not sure whether you have one? kubectl get storageclass marks it with (default).

---

Applying it

1. Save the manifest to a file, for example bolloprint-agent.yaml.
2. Apply it:

kubectl apply -f bolloprint-agent.yaml

If you'd rather give it its own namespace:

kubectl create namespace bolloprint
kubectl apply -n bolloprint -f bolloprint-agent.yaml

(If you put it in a namespace, add the same -n bolloprint to every command on this page.)

---

Checking it works

In under a minute, the agent goes from Not installed to Online in the Local agent tab. It won't ask you for authorisation: that installation comes already authorised.

If it doesn't show up, first check that the pod is running and then look at its log:

kubectl get pods -l app=bolloprint-agent
kubectl logs deployment/bolloprint-agent --tail 50

What's happening	What to check
The pod stays in Pending	It's almost always the persistent volume without a default StorageClass. Untick the box, copy the manifest again and re-apply it, or create the StorageClass.
The pod is running but the agent doesn't show up	Was the whole manifest applied, unchanged? Can the node reach the internet? Is there a network policy blocking outbound traffic?
It shows up, but asks for authorisation	The Secret doesn't include BP_AGENT_INSTANCE_ID (it was edited by hand or is an older one). Regenerate the keys and apply the new manifest as is.
It's online but doesn't find any printers	The node is on a different network from the printers. Add them with Add by IP, or pin the pod to a node on their network.

With the agent online, the next step is connecting your printers: you'll find it in Local network printers.

---

Updating it

From version 2026.1.1 on, the agent updates by itself: when a new version comes out, it downloads it, checks that it's ours and restarts with it. It never does so while any of its printers is printing.

You only need to do it by hand if BolloPrint asks you to: a notice above the tabs in Settings → Printers with the How to update button, and the agent's version in orange (or in red, if it's no longer supported).

Only the version in the image: line changes. Everything else stays the same, and the Secret with the keys isn't touched. You'll find the version to use in your agent's Deployment tab (⋮ → Edit menu).

Change the version in your file and apply it again:

kubectl apply -f bolloprint-agent.yaml

Or, without touching the file, change the deployment's image directly:

kubectl set image deployment/bolloprint-agent agent=ghcr.io/bolloprint/bolloprint-agent:YYYY

If you do it that way, change the file too, or the next time you apply it you'll go back to the old version.

Within a minute the agent shows up again as Online, with the new version and no warning colour. While the pod is being swapped, the printers may show up as Disconnected for a few seconds: they come back on their own.

What if the new version gives you trouble? Put the previous version back and apply the same way (or kubectl rollout undo deployment/bolloprint-agent). Then open a case in support.

---

Moving it to another cluster or another node

Within the same cluster there's nothing to do: if the pod moves to another node, it's still the same agent, because its identity is in the Secret.

To take it to another cluster, delete the deployment on the old one and apply the same file on the new one:

kubectl delete deployment bolloprint-agent

Delete it before applying it on the new one: two agents with the same keys at the same time trip over each other's connection.

---

Regenerating the keys

In the agent's window (⋮ → Edit menu), Deployment tab, Regenerate keys creates a new code and identity and shows you the manifest with them. Use it if you've lost the manifest or you think someone has your keys.

It cuts the agent off immediately, until you apply the new manifest. Applying it changes the Secret, but the pod that's already running doesn't read it again on its own: restart it.

kubectl apply -f bolloprint-agent.yaml
kubectl rollout restart deployment/bolloprint-agent

If the agent never got to connect (it shows Not installed), regenerating doesn't cut anything off.

You don't need to regenerate to update. Changing the image version is enough.

If an installation awaiting authorisation that you don't recognise shows up under Status, don't authorise it: somebody else has your code. Regenerate the keys.

---

Removing it

1. In BolloPrint, on the agent's row, ⋮ → Delete menu. Its printers leave the list with it (their history isn't lost).
2. In the cluster, delete what the manifest created:

kubectl delete -f bolloprint-agent.yaml

If you deployed it with a persistent volume, that deletes the volume too.

---

What NOT to do

• Don't scale up the replicas. An agent is a single pod; two replicas are two agents with the same keys fighting over the connection. To split the fleet, create another agent in BolloPrint.
• Don't regenerate the keys to update.
• Don't apply the manifest from the Deployment tab of an agent that already exists: it has CHANGE_ME instead of the keys.

---

Frequently asked questions

Do I have to open ports or create a Service? No. The agent calls BolloPrint, not the other way round, and it doesn't listen on any port.

Does it work on ARM nodes, like a Raspberry Pi with k3s? Yes. The image works on Intel/AMD and ARM.

Can I use Helm or Argo CD? Yes, as long as what reaches the cluster is the same manifest: a Secret with the two keys and a single-replica Deployment. Store the keys the way you store your other secrets, never in a public repository.