☸️ Agent w Kubernetes

Ta strona jest dla tych, którzy już korzystają z Kubernetesa. Jeśli to nie twój przypadek, nie stawiaj go tylko dla agenta: z Dockerem albo z pakietem dla twojego komputera (w Agent lokalny) masz to samo przy mniejszej liczbie elementów.

---

Czego potrzebujesz

• Klastra Kubernetes i kubectl z dostępem do niego.
• Żeby węzeł, na którym działa agent, był w tej samej sieci co drukarki. Agent używa sieci węzła (hostNetwork), żeby je znaleźć, tak samo jak network_mode: host w Dockerze.
• Jeśli chcesz używać trwałego wolumenu (niżej), domyślnej StorageClass w klastrze.

Jest lekki: manifest rezerwuje mu 256 MB pamięci i nie pozwala przekroczyć 512 MB.

---

Tworzenie go w BolloPrint

1. Przejdź do Ustawienia → Drukarki i otwórz kartę Agent lokalny.
2. Kliknij Nowy agent. W Gdzie go zainstalujesz? wybierz Kubernetes, w sekcji W kontenerze.
3. Nadaj mu nazwę, którą rozpoznasz. Lepiej nazwać go od tego, gdzie stoi, niż od tego, czym jest: „Szafa w hali”, „Klaster w biurze”.
4. Kliknij Utwórz agenta.
5. Pojawia się manifest, na karcie Kubernetes, z kluczami agenta już wpisanymi w środku. Jeśli chcesz, zaznacz Z trwałym wolumenem (patrz niżej). Kliknij Kopiuj.
6. Gdy manifest jest zapisany w bezpiecznym miejscu, kliknij Zapisz, żeby zamknąć okno.

Co zawiera manifest

• Secret o nazwie bolloprint-agent z dwoma kluczami agenta: BP_AGENT_CODE (w którym warsztacie pracuje) i BP_AGENT_INSTANCE_ID (kim jest). Traktuj je jak hasło.
• Deployment o nazwie bolloprint-agent, z jedną repliką, który wymienia poda za jednym razem (Recreate), żeby nigdy nie działały dwa naraz. Działa bez uprawnień uprzywilejowanych, z siecią węzła i z limitem pamięci 512 MB.
• Gdy zaznaczysz Z trwałym wolumenem, dodatkowo PersistentVolumeClaim o rozmiarze 256 MB.

Nie ma w nim namespace: tworzy się w tej przestrzeni nazw, która jest u ciebie aktywna. Jeśli chcesz go mieć osobno, utwórz ją i zastosuj manifest z -n.

Z trwałym wolumenem czy bez?

Bez wolumenu agent działa tak samo. Różnica dotyczy aktualizacji: agent aktualizuje się sam, pobierając nową wersję, a bez wolumenu ta pobrana wersja przepada przy każdym restarcie poda. Wtedy uruchamia się z wersją z obrazu i chwilę trwa, zanim znów się zaktualizuje (kilka minut albo do końca trwającego wydruku).

• Zaznacz to, jeśli twój klaster ma domyślną StorageClass. Tak jest zalecane.
• Zostaw niezaznaczone, jeśli jej nie ma: wolumen, którego nie da się utworzyć, zostawia poda w oczekiwaniu na zawsze, a agent w ogóle się nie uruchamia.

Nie wiesz, czy ją masz? kubectl get storageclass oznacza ją jako (default).

---

Zastosowanie

1. Zapisz manifest w pliku, na przykład bolloprint-agent.yaml.
2. Zastosuj go:

kubectl apply -f bolloprint-agent.yaml

Jeśli wolisz osobną przestrzeń nazw:

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

(Jeśli umieścisz go w przestrzeni nazw, dodaj to samo -n bolloprint do wszystkich poleceń na tej stronie.)

---

Sprawdzenie, czy działa

W niecałą minutę agent zmienia stan z Niezainstalowany na Online na karcie Agent lokalny. Nie poprosi o autoryzację: ta instalacja jest już autoryzowana.

Jeśli się nie pojawia, sprawdź najpierw, czy pod działa, a potem jego log:

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

Co się dzieje	Co sprawdzić
Pod zostaje w stanie Pending	Prawie zawsze chodzi o trwały wolumen bez domyślnej StorageClass. Odznacz pole, skopiuj manifest jeszcze raz i zastosuj go ponownie albo utwórz StorageClass.
Pod działa, ale agent się nie pojawia	Czy manifest został zastosowany w całości, bez zmian? Czy węzeł ma dostęp do internetu? Czy jakaś polityka sieciowa nie blokuje ruchu wychodzącego?
Pojawia się, ale prosi o autoryzację	Secret nie zawiera BP_AGENT_INSTANCE_ID (był edytowany ręcznie albo jest stary). Wygeneruj klucze ponownie i zastosuj nowy manifest bez zmian.
Jest online, ale nie znajduje drukarek	Węzeł jest w innej sieci niż drukarki. Dodaj je przyciskiem Dodaj po IP albo przypnij poda do węzła w ich sieci.

Gdy agent jest online, następny krok to podłączenie drukarek: znajdziesz to w Drukarki w sieci lokalnej.

---

Aktualizacja

Od wersji 2026.1.1 agent aktualizuje się sam: gdy wychodzi nowa wersja, pobiera ją, sprawdza, że pochodzi od nas, i uruchamia się z nią ponownie. Nigdy nie robi tego, gdy któraś z jego drukarek drukuje.

Ręczna aktualizacja jest potrzebna tylko wtedy, gdy BolloPrint cię o nią poprosi: zobaczysz powiadomienie nad zakładkami w Ustawienia → Drukarki z przyciskiem Jak zaktualizować, a wersja agenta będzie pomarańczowa (albo czerwona, jeśli nie jest już obsługiwana).

Zmienia się tylko wersja w linii image:. Wszystko inne zostaje tak samo, a Secretu z kluczami się nie rusza. Właściwą wersję znajdziesz w zakładce Wdrożenie swojego agenta (menu ⋮ → Edytuj).

Zmień wersję w swoim pliku i zastosuj go ponownie:

kubectl apply -f bolloprint-agent.yaml

Albo, bez ruszania pliku, zmień bezpośrednio obraz wdrożenia:

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

Jeśli zrobisz to w ten sposób, zmień też plik — inaczej przy następnym zastosowaniu wrócisz do starej wersji.

W niecałą minutę agent znów pokazuje się jako Online, z nową wersją i bez koloru ostrzeżenia. Podczas wymiany poda drukarki mogą przez kilka sekund pokazywać Rozłączona: wracają same.

A jeśli nowa wersja sprawia ci problemy? Wpisz z powrotem poprzednią wersję i zastosuj tak samo (albo kubectl rollout undo deployment/bolloprint-agent). Potem utwórz zgłoszenie do wsparcia.

---

Przeniesienie do innego klastra lub na inny węzeł

W obrębie tego samego klastra nie trzeba nic robić: jeśli pod zmieni węzeł, nadal jest tym samym agentem, bo jego tożsamość jest w Secrecie.

Żeby przenieść go do innego klastra, usuń wdrożenie w starym i zastosuj ten sam plik w nowym:

kubectl delete deployment bolloprint-agent

Usuń je przed zastosowaniem w nowym: dwa agenty z tymi samymi kluczami jednocześnie przeszkadzają sobie w połączeniu.

---

Ponowne generowanie kluczy

W oknie agenta (menu ⋮ → Edytuj), w zakładce Wdrożenie, opcja Wygeneruj klucze ponownie tworzy nowy kod i nową tożsamość i pokazuje manifest z nimi. Używaj jej, jeśli zgubiono manifest albo podejrzewasz, że ktoś ma twoje klucze.

Natychmiast odcina agenta, dopóki nie zastosujesz nowego manifestu. Jego zastosowanie zmienia Secret, ale działający już pod nie odczyta go ponownie sam: zrestartuj go.

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

Jeśli agent nigdy się nie połączył (widać Niezainstalowany), ponowne generowanie niczego nie przerywa.

Do aktualizacji nie trzeba generować kluczy ponownie. Wystarczy zmienić wersję obrazu.

Jeśli w zakładce Stan pojawi się instalacja oczekująca na autoryzację, której nie rozpoznajesz, nie autoryzuj jej: ktoś jeszcze ma twój kod. Wygeneruj klucze ponownie.

---

Usuwanie

1. W BolloPrint, w wierszu agenta, wybierz menu ⋮ → Usuń. Jego drukarki znikają z listy razem z nim (ich historia nie przepada).
2. W klastrze usuń to, co utworzył manifest:

kubectl delete -f bolloprint-agent.yaml

Jeśli wdrożono go z trwałym wolumenem, to polecenie usuwa też wolumen.

---

Czego NIE robić

• Nie zwiększaj liczby replik. Agent to jeden pod; dwie repliki to dwa agenty z tymi samymi kluczami, które walczą o połączenie. Żeby rozdzielić flotę, utwórz w BolloPrint kolejnego agenta.
• Nie generuj kluczy ponownie, żeby zaktualizować.
• Nie stosuj manifestu z zakładki Wdrożenie agenta, który już istnieje: zawiera CHANGE_ME zamiast kluczy.

---

Najczęstsze pytania

Czy muszę otwierać porty albo tworzyć Service? Nie. To agent łączy się z BolloPrint, a nie odwrotnie, i nie nasłuchuje na żadnym porcie.

Czy działa na węzłach ARM, na przykład na Raspberry Pi z k3s? Tak. Obraz nadaje się na Intel/AMD i ARM.

Czy mogę użyć Helma albo Argo CD? Tak, pod warunkiem że do klastra trafi ten sam manifest: Secret z dwoma kluczami i Deployment z jedną repliką. Przechowuj klucze tak, jak przechowujesz inne sekrety, nigdy w publicznym repozytorium.