☸️ Agent v Kubernetes

Tato stránka je pro ty, kdo už Kubernetes používají. Pokud to není váš případ, nestavějte ho jen kvůli agentovi: s Dockerem nebo s balíčkem pro vaše zařízení (na stránce Místní agent) máte totéž s menším počtem dílků.

---

Co potřebujete

• Cluster Kubernetes a kubectl s přístupem k němu.
• Aby byl uzel, na kterém agent poběží, ve stejné síti jako tiskárny. Agent používá síť uzlu (hostNetwork), aby je našel, stejně jako network_mode: host v Dockeru.
• Pokud chcete trvalý svazek (viz níže), výchozí StorageClass v clusteru.

Je nenáročný: manifest mu vyhrazuje 256 MB paměti a nedovolí mu překročit 512 MB.

---

Vytvoření v BolloPrint

1. Přejděte do Nastavení → Tiskárny a otevřete záložku Místní agent.
2. Klikněte na Nový agent. U otázky Kam ho nainstalujete? zvolte v části V kontejneru možnost Kubernetes.
3. Dejte mu název, který poznáte. Lepší je kde je než co je: „Rack v hale“, „Cluster v kanceláři“.
4. Klikněte na Vytvořit agenta.
5. Zobrazí se manifest na záložce Kubernetes, s klíči agenta už vepsanými. Pokud chcete, zaškrtněte S trvalým svazkem (viz níže). Klikněte na Kopírovat.
6. Až budete mít manifest uložený na bezpečném místě, klikněte na Uložit a okno se zavře.

Co manifest obsahuje

• Secret s názvem bolloprint-agent se dvěma klíči agenta: BP_AGENT_CODE (ve které dílně pracuje) a BP_AGENT_INSTANCE_ID (kdo je). Zacházejte s nimi jako s heslem.
• Deployment s názvem bolloprint-agent, s jedinou replikou, který mění pod najednou (Recreate), aby nikdy neběžely dva současně. Běží bez oprávnění, se sítí uzlu a s limitem paměti 512 MB.
• Pokud je zaškrtnuto S trvalým svazkem, navíc PersistentVolumeClaim o velikosti 256 MB.

Neobsahuje namespace: vytvoří se v tom, který máte aktivní. Pokud ho chcete mít zvlášť, vytvořte ho a aplikujte s -n.

S trvalým svazkem, nebo bez něj?

Bez svazku agent funguje stejně. Rozdíl je v aktualizacích: agent se aktualizuje sám tak, že stáhne novou verzi, a bez svazku se toto stažení při každém restartu podu ztratí. Pak se spustí s verzí z image a chvíli trvá, než se znovu aktualizuje (několik minut, nebo dokud neskončí probíhající tisk).

• Zaškrtněte ho, pokud má váš cluster výchozí StorageClass. To je doporučená volba.
• Nechte ho nezaškrtnutý, pokud ji nemá: svazek, který nelze vytvořit, nechá pod čekat donekonečna a agent se vůbec nespustí.

Nevíte, jestli ji máte? kubectl get storageclass ji označí jako (default).

---

Aplikace

1. Uložte manifest do souboru, například bolloprint-agent.yaml.
2. Aplikujte ho:

kubectl apply -f bolloprint-agent.yaml

Pokud dáváte přednost vlastnímu namespace:

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

(Pokud ho umístíte do namespace, přidejte stejné -n bolloprint ke všem příkazům na této stránce.)

---

Kontrola, že funguje

Za méně než minutu se agent na záložce Místní agent změní z Nenainstalováno na Online. O autorizaci vás žádat nebude: tato instalace je už autorizovaná.

Pokud se nezobrazí, zkontrolujte nejdřív, že pod běží, a potom jeho log:

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

Co se děje	Co zkontrolovat
Pod zůstává ve stavu Pending	Téměř vždy jde o trvalý svazek bez výchozí StorageClass. Zrušte zaškrtnutí, zkopírujte manifest znovu a znovu ho aplikujte, nebo StorageClass vytvořte.
Pod běží, ale agent se nezobrazí	Byl aplikován celý manifest, beze změn? Má uzel přístup k internetu? Neblokuje odchozí provoz síťová politika?
Zobrazí se, ale žádá o autorizaci	Secret neobsahuje BP_AGENT_INSTANCE_ID (byl ručně upraven nebo je starší). Přegenerujte klíče a aplikujte nový manifest beze změn.
Je online, ale nenachází tiskárny	Uzel je v jiné síti než tiskárny. Přidejte je přes Přidat podle IP, nebo připněte pod k uzlu v jejich síti.

Jakmile je agent online, dalším krokem je připojit tiskárny: najdete to na stránce Tiskárny v místní síti.

---

Aktualizace

Od verze 2026.1.1 se agent aktualizuje sám: když vyjde nová verze, stáhne ji, ověří, že pochází od nás, a restartuje se s ní. Nikdy to neudělá, dokud některá z jeho tiskáren tiskne.

Ručně je to potřeba udělat, jen pokud vás o to BolloPrint požádá: upozorněním nad záložkami v Nastavení → Tiskárny s tlačítkem Jak aktualizovat a verzí agenta zobrazenou oranžově (nebo červeně, pokud už není podporovaná).

Mění se jen verze na řádku image:. Všechno ostatní zůstává stejné a Secret s klíči se nemění. Verzi, která má běžet, najdete na záložce Nasazení svého agenta (nabídka ⋮ → Upravit).

Změňte verzi ve svém souboru a znovu ho aplikujte:

kubectl apply -f bolloprint-agent.yaml

Nebo, bez úpravy souboru, změňte přímo image nasazení:

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

Pokud to uděláte takto, změňte i soubor, jinak se při jeho příštím použití vrátíte ke staré verzi.

Za méně než minutu se agent znovu zobrazí jako Online, s novou verzí a bez varovné barvy. Během výměny podu se tiskárny mohou na pár sekund zobrazit jako Odpojená: samy se vrátí.

A když vám nová verze dělá problémy? Vraťte předchozí verzi a aplikujte stejným způsobem (nebo kubectl rollout undo deployment/bolloprint-agent). Potom založte požadavek na podporu.

---

Přesun do jiného clusteru nebo na jiný uzel

V rámci stejného clusteru nemusíte nic dělat: pokud se pod přesune na jiný uzel, zůstává stále tentýž agent, protože jeho identita je v Secretu.

Chcete-li ho přenést do jiného clusteru, smažte nasazení ve starém a aplikujte stejný soubor v novém:

kubectl delete deployment bolloprint-agent

Smažte ho dřív, než ho aplikujete v novém: dva agenti se stejnými klíči najednou si navzájem přebírají spojení.

---

Přegenerování klíčů

V okně agenta (nabídka ⋮ → Upravit), na záložce Nasazení, vytvoří Přegenerovat klíče nový kód a novou identitu a ukáže vám s nimi manifest. Použijte to, pokud jste manifest ztratili nebo máte podezření, že vaše klíče má někdo jiný.

Agenta to okamžitě odpojí, dokud neaplikujete nový manifest. Jeho aplikací se změní Secret, ale pod, který už běží, si ho sám znovu nenačte: restartujte ho.

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

Pokud se agent nikdy nepřipojil (zobrazuje se jako Nenainstalováno), přegenerování nic nepřeruší.

K aktualizaci není přegenerování potřeba. Stačí změnit verzi image.

Pokud se ve Stavu objeví instalace čekající na autorizaci, kterou nepoznáváte, neautorizujte ji: váš kód má ještě někdo jiný. Přegenerujte klíče.

---

Odebrání

1. V BolloPrint, na řádku agenta, zvolte nabídku ⋮ → Smazat. Jeho tiskárny zmizí ze seznamu spolu s ním (jejich historie se neztratí).
2. V clusteru smažte, co manifest vytvořil:

kubectl delete -f bolloprint-agent.yaml

Pokud jste ho nasadili s trvalým svazkem, smaže se tím i svazek.

---

Co NEDĚLAT

• Nezvyšujte počet replik. Jeden agent je jeden pod; dvě repliky jsou dva agenti se stejnými klíči, kteří se přetahují o spojení. Chcete-li flotilu rozdělit, vytvořte v BolloPrint dalšího agenta.
• Nepřegenerovávejte klíče kvůli aktualizaci.
• Neaplikujte manifest ze záložky Nasazení u agenta, který už existuje: místo klíčů obsahuje CHANGE_ME.

---

Časté dotazy

Musím otevírat porty nebo vytvářet Service? Ne. Agent se připojuje k BolloPrint, ne naopak, a na žádném portu nenaslouchá.

Funguje na uzlech ARM, třeba na Raspberry Pi s k3s? Ano. Image funguje pro Intel/AMD i ARM.

Mohu použít Helm nebo Argo CD? Ano, pokud do clusteru dorazí stejný manifest: Secret se dvěma klíči a Deployment s jednou replikou. Klíče uchovávejte tak, jak uchováváte ostatní tajné údaje, nikdy ve veřejném repozitáři.