Inhalt des Handbuchs

☸️ Agent in Kubernetes

In 30 Sekunden

Für alle, die in der Werkstatt schon einen Kubernetes-Cluster haben (k3s, MicroK8s oder einen anderen).
Du legst ihn in BolloPrint an (Neuer Agent → Kubernetes) und kopierst sein Manifest: ein Secret mit den Schlüsseln und ein Deployment mit einer einzigen Replika. Die Schlüssel werden nur einmal angezeigt.
Du wendest es unverändert mit kubectl apply -f an, und in weniger als einer Minute erscheint er als Online.
Er aktualisiert sich von allein. Bitten wir dich doch einmal, es von Hand zu tun, änderst du die Version des Images und wendest es erneut an.

Diese Seite ist für alle, die Kubernetes schon nutzen. Wenn das bei dir nicht so ist, richte es nicht nur für den Agenten ein: mit Docker oder mit dem Paket für deinen Rechner (unter Der lokale Agent) hast du dasselbe mit weniger Teilen.

Was du brauchst

Einen Kubernetes-Cluster und kubectl mit Zugriff darauf.
Dass der Node, auf dem der Agent läuft, im selben Netzwerk wie die Drucker steht. Der Agent nutzt das Netzwerk des Nodes (hostNetwork), um sie zu finden, genau wie network_mode: host bei Docker.
Wenn du das persistente Volume willst (weiter unten), eine Standard-StorageClass im Cluster.

Er ist genügsam: Das Manifest reserviert ihm 256 MB Arbeitsspeicher und lässt ihn nicht über 512 MB gehen.

💡 Bei mehreren Nodes: leg ihn auf einen im Netzwerk der Drucker fest

Hat dein Cluster Nodes in verschiedenen Netzwerken, kann der Pod auf einem landen, der die Drucker nicht sieht. Er hört nicht auf zu funktionieren, findet sie aber nicht von allein, und du musst sie per IP hinzufügen. Um das zu vermeiden, ergänz im Deployment einen nodeSelector mit einem Node aus diesem Netzwerk.

In BolloPrint anlegen

Geh zu Einstellungen → Drucker und öffne den Tab Lokaler Agent.
Drück auf Neuer Agent. Wähl unter Wo installierst du ihn? bei Mit einem Container die Option Kubernetes.
Gib ihm einen Namen, den du wiedererkennst. Besser wo er steht als was er ist: „Rack in der Halle“, „Cluster Büro“.
Drück auf Agent anlegen.
Es erscheint das Manifest im Tab Kubernetes, in dem die Schlüssel des Agenten schon eingetragen sind. Wenn du willst, aktivier Mit persistentem Volume (siehe unten). Drück auf Kopieren.
Wenn das Manifest an einem sicheren Ort gespeichert ist, drück auf Speichern, um das Fenster zu schließen.

🔐 Die Schlüssel werden nur ein einziges Mal angezeigt

Kopier das Manifest in diesem Moment. Die Schlüssel laufen nicht ab, aber wir speichern sie nicht, deshalb können wir sie dir nicht noch einmal zeigen. Verlierst du es, öffne den Agenten mit Bearbeiten und nutze unter Bereitstellung Schlüssel neu erzeugen.

Was im Manifest steht

Ein Secret namens bolloprint-agent mit den beiden Schlüsseln des Agenten: BP_AGENT_CODE (für welche Werkstatt er arbeitet) und BP_AGENT_INSTANCE_ID (wer er ist). Behandle sie wie ein Passwort.
Ein Deployment namens bolloprint-agent mit einer einzigen Replika, das den Pod auf einmal austauscht (Recreate), damit nie zwei gleichzeitig laufen. Es läuft ohne Privilegien, mit dem Netzwerk des Nodes und mit einer Speichergrenze von 512 MB.
Ist Mit persistentem Volume aktiviert, zusätzlich ein PersistentVolumeClaim mit 256 MB.

Es enthält keinen namespace: Es landet in dem, der gerade aktiv ist. Willst du ihn getrennt haben, leg einen an und wende es mit -n an.

Mit persistentem Volume oder ohne?

Ohne Volume funktioniert der Agent genauso. Der Unterschied liegt bei den Aktualisierungen: Der Agent aktualisiert sich von allein, indem er die neue Version herunterlädt, und ohne Volume geht dieser Download bei jedem Neustart des Pods verloren. Dann startet er mit der Version des Images und braucht eine Weile, bis er wieder aktuell ist (ein paar Minuten, oder bis der laufende Druck fertig ist).

Aktivier es, wenn dein Cluster eine Standard-StorageClass hat. Das ist die Empfehlung.
Lass es aus, wenn er keine hat: Ein Volume, das sich nicht anlegen lässt, lässt den Pod für immer warten, und der Agent startet nie.

Du weißt nicht, ob du eine hast? kubectl get storageclass markiert sie mit (default).

Anwenden

Speicher das Manifest in einer Datei, zum Beispiel bolloprint-agent.yaml.
Wende es an:

kubectl apply -f bolloprint-agent.yaml

Wenn du lieber einen eigenen Namespace willst:

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

(Legst du ihn in einen Namespace, häng dasselbe -n bolloprint an alle Befehle auf dieser Seite an.)

Prüfen, ob es funktioniert

In weniger als einer Minute wechselt der Agent im Tab Lokaler Agent von Nicht installiert auf Online. Er fragt nicht nach einer Freigabe: diese Installation ist bereits freigegeben.

Erscheint er nicht, prüf zuerst, ob der Pod läuft, und dann sein Protokoll:

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

Was passiert	Was zu prüfen ist
Der Pod bleibt auf Pending	Fast immer ist es das persistente Volume ohne Standard-StorageClass. Nimm den Haken weg, kopier das Manifest erneut und wende es noch einmal an, oder leg die StorageClass an.
Der Pod läuft, aber der Agent erscheint nicht	Wurde das ganze Manifest ohne Änderungen angewendet? Kommt der Node ins Internet? Blockiert eine Network Policy den ausgehenden Verkehr?
Er erscheint, verlangt aber eine Freigabe	Das Secret enthält kein `BP_AGENT_INSTANCE_ID` (es wurde von Hand bearbeitet oder ist älter). Erzeuge die Schlüssel neu und wende das neue Manifest unverändert an.
Er ist online, findet aber keine Drucker	Der Node steht in einem anderen Netzwerk als die Drucker. Füg sie mit Per IP hinzufügen hinzu, oder leg den Pod auf einen Node in ihrem Netzwerk fest.

Ist der Agent online, ist der nächste Schritt, deine Drucker zu verbinden: das findest du unter Drucker im lokalen Netzwerk.

Aktualisieren

Seit Version 2026.1.1 aktualisiert sich der Agent von allein: Erscheint eine neue Version, lädt er sie herunter, prüft, dass sie von uns stammt, und startet mit ihr neu. Das tut er nie, während einer seiner Drucker druckt.

Von Hand ist es nur nötig, wenn BolloPrint dich darum bittet: ein Hinweis über den Tabs von Einstellungen → Drucker mit dem Button So aktualisierst du, und die Version des Agenten in Orange (oder in Rot, wenn sie nicht mehr unterstützt wird).

Es ändert sich nur die Version in der Zeile image:. Alles andere bleibt gleich, und das Secret mit den Schlüsseln wird nicht angefasst. Die passende Version findest du im Tab Bereitstellung deines Agenten (Menü ⋮ → Bearbeiten).

Ändere die Version in deiner Datei und wende sie erneut an:

kubectl apply -f bolloprint-agent.yaml

Oder ändere, ohne die Datei anzufassen, direkt das Image des Deployments:

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

Machst du es so, ändere auch die Datei, sonst landest du beim nächsten Anwenden wieder bei der alten Version.

⚠️ Wende das Manifest aus dem Tab „Bereitstellung“ nicht über deins an

Bei einem schon bestehenden Agenten zeigt BolloPrint CHANGE_ME statt der Schlüssel an, weil sie nicht gespeichert werden. Wendest du dieses Manifest an, steht im Secret CHANGE_ME, und der Agent verbindet sich nicht mehr. Ändere nur die Version des Images in deiner Datei.

In weniger als einer Minute erscheint der Agent wieder als Online, mit der neuen Version und ohne Warnfarbe. Während der Pod ausgetauscht wird, können die Drucker ein paar Sekunden als Getrennt erscheinen: sie kommen von allein zurück.

Und wenn die neue Version Probleme macht? Setz die vorherige Version wieder ein und wende genauso an (oder kubectl rollout undo deployment/bolloprint-agent). Stell danach eine Anfrage beim Support.

Auf einen anderen Cluster oder Node umziehen

Innerhalb desselben Clusters musst du nichts tun: Wechselt der Pod den Node, bleibt er derselbe Agent, weil seine Identität im Secret steht.

Um ihn auf einen anderen Cluster zu bringen, lösch das Deployment im alten und wende dieselbe Datei im neuen an:

kubectl delete deployment bolloprint-agent

Lösch es, bevor du es im neuen anwendest: zwei Agenten mit denselben Schlüsseln gleichzeitig kommen sich bei der Verbindung in die Quere.

Die Schlüssel neu erzeugen

Im Fenster des Agenten (Menü ⋮ → Bearbeiten), Tab Bereitstellung, erzeugt Schlüssel neu erzeugen einen neuen Code und eine neue Identität und zeigt dir das Manifest damit. Nutze es, wenn du das Manifest verloren hast oder glaubst, dass jemand deine Schlüssel hat.

Es trennt den Agenten sofort, bis du das neue Manifest anwendest. Beim Anwenden ändert sich das Secret, aber der laufende Pod liest es nicht von allein neu ein: starte ihn neu.

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

Hat sich der Agent nie verbunden (er steht auf Nicht installiert), trennt das Neu-Erzeugen nichts.

Zum Aktualisieren musst du nichts neu erzeugen. Es reicht, die Version des Images zu ändern.

Erscheint unter Status eine Installation, die auf Freigabe wartet, die du nicht wiedererkennst, gib sie nicht frei: dann hat jemand anderes deinen Code. Erzeuge die Schlüssel neu.

Entfernen

In BolloPrint, in der Zeile des Agenten, Menü ⋮ → Löschen. Seine Drucker verschwinden mit ihm aus der Liste (ihr Verlauf geht nicht verloren).
Lösch im Cluster, was das Manifest angelegt hat:

kubectl delete -f bolloprint-agent.yaml

Hast du ihn mit persistentem Volume ausgerollt, wird damit auch das Volume gelöscht.

Was du NICHT tun solltest

Erhöh nicht die Zahl der Repliken. Ein Agent ist ein einziger Pod; zwei Repliken sind zwei Agenten mit denselben Schlüsseln, die sich um die Verbindung streiten. Um die Flotte aufzuteilen, leg in BolloPrint einen weiteren Agenten an.
Erzeuge die Schlüssel nicht neu, um zu aktualisieren.
Wende das Manifest aus dem Tab „Bereitstellung“ nicht an, wenn der Agent schon besteht: dort steht CHANGE_ME statt der Schlüssel.

Häufige Fragen

Muss ich Ports öffnen oder einen Service anlegen? Nein. Der Agent ruft BolloPrint an, nicht umgekehrt, und lauscht auf keinem Port.

Läuft er auf ARM-Nodes, etwa einem Raspberry Pi mit k3s? Ja. Das Image gibt es für Intel/AMD und ARM.

Kann ich Helm oder Argo CD verwenden? Ja, solange im Cluster dasselbe Manifest ankommt: ein Secret mit den beiden Schlüsseln und ein Deployment mit einer Replika. Bewahre die Schlüssel so auf wie deine anderen Secrets, niemals in einem öffentlichen Repository.