Índice do manual

☸️ Agente no Kubernetes

Em 30 segundos

Para quem já tem um cluster de Kubernetes na oficina (k3s, MicroK8s ou qualquer outro).
Crias-o no BolloPrint (Novo agente → Kubernetes) e copias o seu manifesto: um Secret com as chaves e um Deployment de uma só réplica. As chaves só são mostradas uma vez.
Aplicas-o tal como está com kubectl apply -f e em menos de um minuto aparece Online.
Atualiza-se sozinho. Se alguma vez te pedirmos para o fazeres à mão, é mudar a versão da imagem e voltar a aplicar.

Esta página é para quem já usa Kubernetes. Se não é o teu caso, não o montes só para o agente: com Docker, ou com o pacote do teu equipamento (em O agente local), tens o mesmo com menos peças.

O que precisas

Um cluster de Kubernetes e kubectl com acesso a ele.
Que o nó onde o agente corre esteja na mesma rede que as impressoras. O agente usa a rede do nó (hostNetwork) para as encontrar, tal como o network_mode: host do Docker.
Se quiseres o volume persistente (mais abaixo), uma StorageClass predefinida no cluster.

É leve: o manifesto reserva-lhe 256 MB de memória e não o deixa passar dos 512 MB.

💡 Com vários nós, fixa-o num da rede das impressoras

Se o teu cluster tem nós em redes diferentes, o pod pode ir parar a um que não vê as impressoras. Não deixa de funcionar, mas não as vai encontrar sozinho e terás de as acrescentar por IP. Para o evitar, acrescenta ao Deployment um nodeSelector com um nó dessa rede.

Criá-lo no BolloPrint

Vai a Configurações → Impressoras e abre o separador Agente local.
Prime Novo agente. Em Onde o vais instalar?, escolhe Kubernetes, em Com um contentor.
Dá-lhe um nome que reconheças. Melhor onde está do que o que é: «Rack do pavilhão», «Cluster escritório».
Prime Criar agente.
Aparece o manifesto, no separador Kubernetes, com as chaves do agente já escritas lá dentro. Se quiseres, marca Com volume persistente (vê abaixo). Prime Copiar.
Com o manifesto guardado num sítio seguro, prime Guardar para fechar a janela.

🔐 As chaves são mostradas uma só vez

Copia o manifesto nesse momento. As chaves não expiram, mas não as guardamos, por isso não tas podemos voltar a mostrar. Se o perderes, abre o agente com Editar e, em Instalação, usa Regenerar chaves.

O que leva o manifesto

Um Secret chamado bolloprint-agent com as duas chaves do agente: BP_AGENT_CODE (em que oficina trabalha) e BP_AGENT_INSTANCE_ID (quem é). Trata-as como uma palavra-passe.
Um Deployment chamado bolloprint-agent, de uma só réplica, que troca o pod de uma vez (Recreate) para que nunca haja dois ao mesmo tempo. Corre sem privilégios, com a rede do nó e com um limite de memória de 512 MB.
Com Com volume persistente marcado, também um PersistentVolumeClaim de 256 MB.

Não leva namespace: cria-se no que tiveres ativo. Se o quiseres à parte, cria-o e aplica-o com -n.

Com volume persistente ou sem ele?

Sem volume, o agente funciona na mesma. A diferença está nas atualizações: o agente atualiza-se sozinho descarregando a versão nova, e sem volume essa transferência perde-se sempre que o pod reinicia. Nesse caso arranca com a versão da imagem e demora um bocado a pôr-se em dia outra vez (uns minutos, ou até acabar a impressão em curso).

Marca-o se o teu cluster tem uma StorageClass predefinida. É o recomendável.
Deixa-o por marcar se não a tem: um volume que não se pode criar deixa o pod à espera para sempre, e o agente não chega a arrancar.

Não sabes se a tens? kubectl get storageclass marca-a com (default).

Aplicá-lo

Guarda o manifesto num ficheiro, por exemplo bolloprint-agent.yaml.
Aplica-o:

kubectl apply -f bolloprint-agent.yaml

Se preferires o seu próprio namespace:

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

(Se o puseres num namespace, acrescenta o mesmo -n bolloprint a todos os comandos desta página.)

Confirmar que funciona

Em menos de um minuto, o agente passa de Por instalar a Online no separador Agente local. Não te vai pedir autorização: essa instalação já vem autorizada.

Se não aparecer, vê primeiro se o pod está a correr e depois o seu registo:

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

O que se passa	O que ver
O pod fica em Pending	Quase sempre é o volume persistente sem StorageClass predefinida. Desmarca a caixa, copia o manifesto outra vez e volta a aplicá-lo, ou cria a StorageClass.
O pod está a correr mas o agente não aparece	O manifesto foi aplicado por completo, sem alterações? O nó chega à internet? Há alguma política de rede a bloquear a saída?
Aparece, mas pede autorização	O Secret não leva `BP_AGENT_INSTANCE_ID` (foi editado à mão ou é antigo). Regenera as chaves e aplica o manifesto novo tal como está.
Está online mas não encontra impressoras	O nó está numa rede diferente da das impressoras. Acrescenta-as com Adicionar por IP, ou fixa o pod num nó da rede delas.

Com o agente online, o passo seguinte é ligar as tuas impressoras: tens isso em Impressoras por rede local.

Atualizá-lo

Desde a versão 2026.1.1, o agente atualiza-se sozinho: quando sai uma versão nova, descarrega-a, confirma que é nossa e reinicia-se com ela. Nunca o faz enquanto alguma das suas impressoras está a imprimir.

Só é preciso fazê-lo à mão se o BolloPrint to pedir: um aviso por cima dos separadores de Configurações → Impressoras com o botão Como atualizar, e a versão do agente em laranja (ou em vermelho, se já não for suportada).

Só muda a versão da linha image:. Tudo o resto fica igual, e o Secret com as chaves não se toca. A versão certa tens no separador Instalação do teu agente (menu ⋮ → Editar).

Muda a versão no teu ficheiro e volta a aplicá-lo:

kubectl apply -f bolloprint-agent.yaml

Ou, sem tocar no ficheiro, muda diretamente a imagem do deployment:

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

Se o fizeres assim, muda também o ficheiro, ou da próxima vez que o aplicares voltas à versão antiga.

⚠️ Não apliques o manifesto do separador Instalação por cima do teu

Num agente que já existe, o BolloPrint mostra CHANGE_ME em vez das chaves, porque não as guarda. Se aplicares esse manifesto, o Secret fica com CHANGE_ME e o agente deixa de se ligar. Muda só a versão da imagem no teu ficheiro.

Em menos de um minuto o agente volta a aparecer Online, com a versão nova e sem cor de aviso. Enquanto o pod é trocado, as impressoras podem aparecer uns segundos como Desligada: voltam sozinhas.

E se a versão nova te der problemas? Volta a pôr a versão anterior e aplica da mesma forma (ou kubectl rollout undo deployment/bolloprint-agent). Depois abre um pedido no suporte.

Mudá-lo para outro cluster ou para outro nó

Dentro do mesmo cluster não tens de fazer nada: se o pod mudar de nó, continua a ser o mesmo agente, porque a sua identidade vai no Secret.

Para o levares para outro cluster, apaga o deployment no antigo e aplica o mesmo ficheiro no novo:

kubectl delete deployment bolloprint-agent

Apaga-o antes de o aplicares no novo: dois agentes com as mesmas chaves ao mesmo tempo atropelam a ligação um do outro.

Regenerar as chaves

Na janela do agente (menu ⋮ → Editar), separador Instalação, Regenerar chaves cria um código e uma identidade novos e mostra-te o manifesto com eles. Usa-o se perdeste o manifesto ou achas que alguém tem as tuas chaves.

Desliga o agente no momento, até aplicares o manifesto novo. Ao aplicá-lo o Secret muda, mas o pod que já está a correr não o volta a ler sozinho: reinicia-o.

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

Se o agente nunca chegou a ligar-se (aparece Por instalar), regenerar não desliga nada.

Para atualizar não é preciso regenerar. Basta mudar a versão da imagem.

Se aparecer em Estado uma instalação a aguardar autorização que não reconheces, não a autorizes: mais alguém tem o teu código. Regenera as chaves.

Removê-lo

No BolloPrint, na linha do agente, menu ⋮ → Eliminar. As suas impressoras saem da lista com ele (o seu histórico não se perde).
No cluster, apaga o que o manifesto criou:

kubectl delete -f bolloprint-agent.yaml

Se o instalaste com volume persistente, isto apaga também o volume.

O que NÃO deves fazer

Não aumentes as réplicas. Um agente é um só pod; duas réplicas são dois agentes com as mesmas chaves a lutar pela ligação. Para repartir a frota, cria outro agente no BolloPrint.
Não regeneres as chaves para atualizar.
Não apliques o manifesto do separador Instalação de um agente que já existe: leva CHANGE_ME em vez das chaves.

Perguntas frequentes

Tenho de abrir portas ou criar um Service? Não. É o agente que se liga ao BolloPrint, não o contrário, e não escuta em nenhuma porta.

Funciona em nós ARM, como um Raspberry Pi com k3s? Sim. A imagem serve para Intel/AMD e ARM.

Posso usar Helm ou Argo CD? Sim, desde que o que chegue ao cluster seja o mesmo manifesto: um Secret com as duas chaves e um Deployment de uma réplica. Guarda as chaves como guardas os teus outros segredos, nunca num repositório público.