Inhoud van de handleiding

☸️ Agent in Kubernetes

In 30 seconden

Voor wie al een Kubernetes-cluster in de werkplaats heeft (k3s, MicroK8s of een ander).
Je maakt hem aan in BolloPrint (Nieuwe agent → Kubernetes) en kopieert zijn manifest: een Secret met de sleutels en een Deployment met één replica. De sleutels worden maar één keer getoond.
Je past het ongewijzigd toe met kubectl apply -f en binnen een minuut staat er Online.
Hij werkt zichzelf bij. Vragen we je ooit om het met de hand te doen, dan pas je de versie van de image aan en pas je het opnieuw toe.

Deze pagina is voor wie Kubernetes al gebruikt. Is dat bij jou niet zo, zet het dan niet alleen voor de agent op: met Docker, of met het pakket voor je computer (in De lokale agent), heb je hetzelfde met minder onderdelen.

Wat je nodig hebt

Een Kubernetes-cluster en kubectl met toegang ertoe.
Dat de node waarop de agent draait in hetzelfde netwerk als de printers zit. De agent gebruikt het netwerk van de node (hostNetwork) om ze te vinden, net als network_mode: host bij Docker.
Wil je het persistent volume (verderop), dan een standaard-StorageClass in het cluster.

Hij is licht: het manifest reserveert 256 MB geheugen voor hem en laat hem niet boven 512 MB gaan.

💡 Met meerdere nodes: zet hem vast op een node in het netwerk van de printers

Heeft je cluster nodes in verschillende netwerken, dan kan de pod op een node terechtkomen die de printers niet ziet. Hij werkt gewoon door, maar hij vindt ze niet vanzelf en je moet ze via IP toevoegen. Om dat te voorkomen, voeg je aan de Deployment een nodeSelector toe met een node uit dat netwerk.

Hem aanmaken in BolloPrint

Ga naar Instellingen → Printers en open het tabblad Lokale agent.
Klik op Nieuwe agent. Kies bij Waar ga je hem installeren? voor Kubernetes, onder Met een container.
Geef hem een naam die je herkent. Liever waar hij staat dan wat hij is: “Rack in de hal”, “Cluster kantoor”.
Klik op Agent aanmaken.
Het manifest verschijnt, op het tabblad Kubernetes, met de sleutels van de agent er al in geschreven. Wil je dat, vink dan Met persistent volume aan (zie hieronder). Klik op Kopiëren.
Klik, als het manifest veilig bewaard is, op Opslaan om het venster te sluiten.

🔐 De sleutels worden maar één keer getoond

Kopieer het manifest op dat moment. De sleutels verlopen niet, maar we bewaren ze niet, dus we kunnen ze je niet nog een keer laten zien. Ben je het kwijt, open de agent dan met Bewerken en gebruik onder Installatie de knop Sleutels opnieuw genereren.

Wat er in het manifest staat

Een Secret met de naam bolloprint-agent met de twee sleutels van de agent: BP_AGENT_CODE (in welke werkplaats hij werkt) en BP_AGENT_INSTANCE_ID (wie hij is). Behandel ze als een wachtwoord.
Een Deployment met de naam bolloprint-agent, met één replica, die de pod in één keer vervangt (Recreate), zodat er nooit twee tegelijk zijn. Hij draait zonder privileges, met het netwerk van de node en met een geheugenlimiet van 512 MB.
Met Met persistent volume aangevinkt bovendien een PersistentVolumeClaim van 256 MB.

Er staat geen namespace in: hij wordt aangemaakt in de namespace die je actief hebt. Wil je hem apart, maak die dan aan en pas het toe met -n.

Met of zonder persistent volume?

Zonder volume werkt de agent net zo goed. Het verschil zit in de updates: de agent werkt zichzelf bij door de nieuwe versie te downloaden, en zonder volume gaat die download verloren telkens als de pod herstart. Dan start hij met de versie van de image en duurt het even voordat hij weer bij is (een paar minuten, of tot de lopende print klaar is).

Vink het aan als je cluster een standaard-StorageClass heeft. Dat is aan te raden.
Laat het uit als dat niet zo is: een volume dat niet kan worden aangemaakt laat de pod eeuwig wachten, en de agent start nooit op.

Weet je niet of je er een hebt? kubectl get storageclass markeert hem met (default).

Hem toepassen

Sla het manifest op in een bestand, bijvoorbeeld bolloprint-agent.yaml.
Pas het toe:

kubectl apply -f bolloprint-agent.yaml

Wil je liever een eigen namespace:

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

(Zet je hem in een namespace, voeg dan dezelfde -n bolloprint toe aan alle commando's op deze pagina.)

Controleren of het werkt

Binnen een minuut gaat de agent op het tabblad Lokale agent van Niet geïnstalleerd naar Online. Hij vraagt je niet om toestemming: deze installatie is al goedgekeurd.

Verschijnt hij niet, kijk dan eerst of de pod draait en daarna naar zijn log:

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

Wat er gebeurt	Waar je naar kijkt
De pod blijft op Pending staan	Bijna altijd is het het persistent volume zonder standaard-StorageClass. Vink het vakje uit, kopieer het manifest opnieuw en pas het nog eens toe, of maak de StorageClass aan.
De pod draait, maar de agent verschijnt niet	Is het hele manifest toegepast, zonder wijzigingen? Kan de node het internet bereiken? Is er een netwerkbeleid dat het uitgaande verkeer blokkeert?
Hij verschijnt, maar vraagt om toestemming	In het Secret staat geen `BP_AGENT_INSTANCE_ID` (het is met de hand bewerkt of het is een oud manifest). Genereer de sleutels opnieuw en pas het nieuwe manifest toe zoals het is.
Hij is online maar vindt geen printers	De node zit in een ander netwerk dan de printers. Voeg ze toe met Toevoegen via IP, of zet de pod vast op een node in hun netwerk.

Staat de agent online, dan is de volgende stap je printers koppelen: dat lees je in Printers via het lokale netwerk.

Hem bijwerken

Vanaf versie 2026.1.1 werkt de agent zichzelf bij: komt er een nieuwe versie uit, dan downloadt hij die, controleert hij dat die van ons is en herstart hij ermee. Dat doet hij nooit terwijl een van zijn printers aan het printen is.

Met de hand hoeft het alleen als BolloPrint je erom vraagt: een melding boven de tabbladen van Instellingen → Printers met de knop Hoe bijwerken, en de versie van de agent in het oranje (of in het rood, als die niet meer wordt ondersteund).

Alleen de versie in de regel image: verandert. Al het andere blijft hetzelfde, en het Secret met de sleutels raak je niet aan. De juiste versie vind je op het tabblad Installatie van je agent (menu ⋮ → Bewerken).

Pas de versie in je bestand aan en pas het opnieuw toe:

kubectl apply -f bolloprint-agent.yaml

Of verander, zonder het bestand aan te raken, direct de image van de deployment:

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

Doe je het zo, pas dan ook het bestand aan, anders ga je de volgende keer dat je het toepast terug naar de oude versie.

⚠️ Pas het manifest van het tabblad Installatie niet toe over het jouwe heen

Bij een agent die al bestaat, toont BolloPrint CHANGE_ME in plaats van de sleutels, omdat het ze niet bewaart. Pas je dat manifest toe, dan blijft er CHANGE_ME in het Secret staan en maakt de agent geen verbinding meer. Pas alleen de versie van de image in je bestand aan.

Binnen een minuut staat de agent weer op Online, met de nieuwe versie en zonder waarschuwingskleur. Terwijl de pod wordt vervangen, kunnen de printers een paar seconden op Niet verbonden staan: ze komen vanzelf terug.

En als de nieuwe versie problemen geeft? Zet de vorige versie terug en pas het op dezelfde manier toe (of kubectl rollout undo deployment/bolloprint-agent). Open daarna een aanvraag bij support.

Hem naar een ander cluster of een andere node verhuizen

Binnen hetzelfde cluster hoef je niets te doen: verhuist de pod naar een andere node, dan blijft het dezelfde agent, omdat zijn identiteit in het Secret staat.

Om hem naar een ander cluster te brengen, verwijder je de deployment in het oude en pas je hetzelfde bestand toe in het nieuwe:

kubectl delete deployment bolloprint-agent

Verwijder hem voordat je hem in het nieuwe toepast: twee agents met dezelfde sleutels tegelijk zitten elkaars verbinding in de weg.

De sleutels opnieuw genereren

In het venster van de agent (menu ⋮ → Bewerken), tabblad Installatie, maakt Sleutels opnieuw genereren een nieuwe code en identiteit aan en toont je het manifest daarmee. Gebruik het als je het manifest kwijt bent of denkt dat iemand je sleutels heeft.

Het verbreekt de agent meteen, tot je het nieuwe manifest toepast. Bij het toepassen verandert het Secret, maar de pod die al draait leest het niet vanzelf opnieuw in: herstart hem.

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

Heeft de agent nooit verbinding gemaakt (hij staat op Niet geïnstalleerd), dan verbreekt opnieuw genereren niets.

Om bij te werken hoef je niet opnieuw te genereren. Het is genoeg om de versie van de image te veranderen.

Verschijnt er bij Status een installatie die op autorisatie wacht die je niet herkent, autoriseer hem dan niet: iemand anders heeft je code. Genereer de sleutels opnieuw.

Hem weghalen

Kies in BolloPrint, in de regel van de agent, menu ⋮ → Verwijderen. Zijn printers verdwijnen met hem uit de lijst (hun geschiedenis gaat niet verloren).
Verwijder in het cluster wat het manifest heeft aangemaakt:

kubectl delete -f bolloprint-agent.yaml

Heb je hem met persistent volume geïnstalleerd, dan verwijdert dit ook het volume.

Wat je NIET moet doen

Verhoog het aantal replica's niet. Een agent is één pod; twee replica's zijn twee agents met dezelfde sleutels die om de verbinding vechten. Wil je de vloot verdelen, maak dan in BolloPrint nog een agent aan.
Genereer de sleutels niet opnieuw om bij te werken.
Pas het manifest van het tabblad Installatie niet toe bij een agent die al bestaat: daar staat CHANGE_ME in plaats van de sleutels.

Veelgestelde vragen

Moet ik poorten openzetten of een Service aanmaken? Nee. De agent belt BolloPrint, niet andersom, en luistert op geen enkele poort.

Werkt hij op ARM-nodes, zoals een Raspberry Pi met k3s? Ja. De image werkt op Intel/AMD en ARM.

Kan ik Helm of Argo CD gebruiken? Ja, zolang wat er in het cluster aankomt hetzelfde manifest is: een Secret met de twee sleutels en een Deployment met één replica. Bewaar de sleutels zoals je je andere secrets bewaart, nooit in een openbare repository.