Indice del manuale

☸️ Agente su Kubernetes

In 30 secondi

Per chi ha già un cluster Kubernetes in laboratorio (k3s, MicroK8s o qualsiasi altro).
Lo crei in BolloPrint (Nuovo agente → Kubernetes) e copi il suo manifesto: un Secret con le chiavi e un Deployment con una sola replica. Le chiavi si mostrano una sola volta.
Lo applichi così com'è con kubectl apply -f e in meno di un minuto risulta Online.
Si aggiorna da solo. Se un giorno ti chiediamo di farlo a mano, basta cambiare la versione dell'immagine e applicarlo di nuovo.

Questa pagina è per chi usa già Kubernetes. Se non è il tuo caso, non metterlo in piedi solo per l'agente: con Docker, o con il pacchetto del tuo computer (in L'agente locale), ottieni lo stesso con meno pezzi.

Cosa ti serve

Un cluster Kubernetes e kubectl con accesso al cluster.
Che il nodo dove gira l'agente stia nella stessa rete delle stampanti. L'agente usa la rete del nodo (hostNetwork) per trovarle, come il network_mode: host di Docker.
Se vuoi il volume persistente (più in basso), una StorageClass predefinita nel cluster.

È leggero: il manifesto gli riserva 256 MB di memoria e non gli lascia superare i 512 MB.

💡 Con più nodi, fissalo a uno della rete delle stampanti

Se il tuo cluster ha nodi su reti diverse, il pod può finire su uno che non vede le stampanti. Non smette di funzionare, ma non le troverà da solo e dovrai aggiungerle tramite IP. Per evitarlo, aggiungi al Deployment un nodeSelector con un nodo di quella rete.

Crearlo in BolloPrint

Vai su Impostazioni → Stampanti e apri la scheda Agente locale.
Premi Nuovo agente. In Dove lo installerai?, scegli Kubernetes, sotto Con un container.
Dagli un nome che riconosci. Meglio dov'è che cos'è: «Rack del capannone», «Cluster ufficio».
Premi Crea agente.
Compare il manifesto, nella scheda Kubernetes, con le chiavi dell'agente già scritte dentro. Se vuoi, spunta Con volume persistente (vedi sotto). Premi Copia.
Con il manifesto salvato in un posto sicuro, premi Salva per chiudere la finestra.

🔐 Le chiavi si mostrano una volta sola

Copia il manifesto in quel momento. Le chiavi non scadono, ma non le conserviamo, quindi non possiamo mostrartele di nuovo. Se lo perdi, apri l'agente con Modifica e, in Installazione, usa Rigenera le chiavi.

Cosa contiene il manifesto

Un Secret chiamato bolloprint-agent con le due chiavi dell'agente: BP_AGENT_CODE (in quale laboratorio lavora) e BP_AGENT_INSTANCE_ID (chi è). Trattale come una password.
Un Deployment chiamato bolloprint-agent, con una sola replica, che sostituisce il pod in un colpo solo (Recreate) perché non ce ne siano mai due insieme. Gira senza privilegi, con la rete del nodo e con un limite di memoria di 512 MB.
Con Con volume persistente spuntato, in più, un PersistentVolumeClaim da 256 MB.

Non contiene namespace: si crea in quello che hai attivo. Se lo vuoi a parte, crealo e applicalo con -n.

Con volume persistente o senza?

Senza volume, l'agente funziona lo stesso. La differenza sta negli aggiornamenti: l'agente si aggiorna da solo scaricando la versione nuova, e senza volume quel download si perde ogni volta che il pod si riavvia. Allora parte con la versione dell'immagine e ci mette un po' a rimettersi in pari (qualche minuto, o finché non finisce la stampa in corso).

Spuntalo se il tuo cluster ha una StorageClass predefinita. È la scelta consigliata.
Lascialo senza spunta se non ce l'ha: un volume che non si può creare lascia il pod in attesa per sempre, e l'agente non arriva mai ad avviarsi.

Non sai se ce l'hai? kubectl get storageclass la indica con (default).

Applicarlo

Salva il manifesto in un file, per esempio bolloprint-agent.yaml.
Applicalo:

kubectl apply -f bolloprint-agent.yaml

Se preferisci un namespace tutto suo:

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

(Se lo metti in un namespace, aggiungi lo stesso -n bolloprint a tutti i comandi di questa pagina.)

Verificare che funzioni

In meno di un minuto, l'agente passa da Non installato a Online nella scheda Agente locale. Non ti chiederà l'autorizzazione: quell'installazione è già autorizzata.

Se non compare, controlla prima che il pod sia in esecuzione e poi il suo registro:

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

Cosa succede	Cosa guardare
Il pod resta in Pending	Quasi sempre è il volume persistente senza StorageClass predefinita. Togli la spunta, copia di nuovo il manifesto e riapplicalo, oppure crea la StorageClass.
Il pod è in esecuzione ma l'agente non compare	Il manifesto è stato applicato per intero, senza modifiche? Il nodo arriva a internet? C'è una network policy che blocca l'uscita?
Compare, ma chiede l'autorizzazione	Il Secret non contiene `BP_AGENT_INSTANCE_ID` (è stato modificato a mano o è di prima). Rigenera le chiavi e applica il nuovo manifesto così com'è.
È online ma non trova stampanti	Il nodo sta su un'altra rete rispetto alle stampanti. Aggiungile con Aggiungi per IP, oppure fissa il pod a un nodo della loro rete.

Con l'agente online, il passo successivo è collegare le tue stampanti: lo trovi in Stampanti in rete locale.

Aggiornarlo

Dalla versione 2026.1.1, l'agente si aggiorna da solo: quando esce una versione nuova, la scarica, verifica che sia nostra e si riavvia con essa. Non lo fa mai mentre una delle sue stampanti sta stampando.

Serve farlo a mano solo se te lo chiede BolloPrint: un avviso sopra le schede di Impostazioni → Stampanti con il pulsante Come aggiornare, e la versione dell'agente in arancione (o in rosso, se non è più supportata).

Cambia solo la versione della riga image:. Tutto il resto resta uguale, e il Secret con le chiavi non si tocca. La versione giusta la trovi nella scheda Installazione del tuo agente (menu ⋮ → Modifica).

Cambia la versione nel tuo file e applicalo di nuovo:

kubectl apply -f bolloprint-agent.yaml

Oppure, senza toccare il file, cambia direttamente l'immagine del deployment:

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

Se lo fai così, cambia anche il file, o la prossima volta che lo applichi tornerai alla versione precedente.

⚠️ Non applicare il manifesto della scheda Installazione sopra il tuo

Per un agente già esistente, BolloPrint mostra CHANGE_ME al posto delle chiavi, perché non le conserva. Se applichi quel manifesto, il Secret resta con CHANGE_ME e l'agente smette di collegarsi. Cambia solo la versione dell'immagine nel tuo file.

In meno di un minuto l'agente torna a comparire Online, con la versione nuova e senza colore di avviso. Mentre il pod viene sostituito, le stampanti possono comparire per qualche secondo come Disconnessa: tornano da sole.

E se la versione nuova ti dà problemi? Rimetti la versione precedente e applica comunque (oppure kubectl rollout undo deployment/bolloprint-agent). Poi apri una richiesta all'assistenza.

Spostarlo su un altro cluster o un altro nodo

Dentro lo stesso cluster non devi fare nulla: se il pod cambia nodo, resta lo stesso agente, perché la sua identità sta nel Secret.

Per portarlo su un altro cluster, elimina il deployment in quello vecchio e applica lo stesso file in quello nuovo:

kubectl delete deployment bolloprint-agent

Eliminalo prima di applicarlo in quello nuovo: due agenti con le stesse chiavi nello stesso momento si rubano la connessione a vicenda.

Rigenerare le chiavi

Nella finestra dell'agente (menu ⋮ → Modifica), scheda Installazione, Rigenera le chiavi crea un codice e un'identità nuovi e ti mostra il manifesto con quelli. Usalo se hai perso il manifesto o pensi che qualcuno abbia le tue chiavi.

Scollega l'agente all'istante, finché non applichi il nuovo manifesto. Applicandolo cambia il Secret, ma il pod già in esecuzione non lo rilegge da solo: riavvialo.

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

Se l'agente non si è mai collegato (risulta Non installato), rigenerare non scollega nulla.

Per aggiornare non serve rigenerare. Basta cambiare la versione dell'immagine.

Se in Stato compare un'installazione in attesa di autorizzazione che non riconosci, non autorizzarla: qualcun altro ha il tuo codice. Rigenera le chiavi.

Toglierlo

In BolloPrint, nella riga dell'agente, menu ⋮ → Elimina. Le sue stampanti escono dall'elenco insieme a lui (il loro storico non si perde).
Nel cluster, elimina quello che ha creato il manifesto:

kubectl delete -f bolloprint-agent.yaml

Se l'hai installato con il volume persistente, questo elimina anche il volume.

Cosa NON bisogna fare

Non aumentare le repliche. Un agente è un solo pod; due repliche sono due agenti con le stesse chiavi che si contendono la connessione. Per dividere la flotta, crea un altro agente in BolloPrint.
Non rigenerare le chiavi per aggiornare.
Non applicare il manifesto della scheda Installazione di un agente già esistente: contiene CHANGE_ME al posto delle chiavi.

Domande frequenti

Devo aprire porte o creare un Service? No. L'agente chiama BolloPrint, non il contrario, e non resta in ascolto su nessuna porta.

Funziona su nodi ARM, come un Raspberry Pi con k3s? Sì. L'immagine va bene per Intel/AMD e ARM.

Posso usare Helm o Argo CD? Sì, purché quello che arriva al cluster sia lo stesso manifesto: un Secret con le due chiavi e un Deployment con una replica. Conserva le chiavi come conservi gli altri tuoi segreti, mai in un repository pubblico.