☸️ Agente en Kubernetes

Esta página es para quien ya usa Kubernetes. Si no es tu caso, no lo montes solo para el agente: con Docker, o con el paquete de tu equipo (en El agente local), tienes lo mismo con menos piezas.

---

Qué necesitas

• Un clúster de Kubernetes y kubectl con acceso a él.
• Que el nodo donde corra el agente esté en la misma red que las impresoras. El agente usa la red del nodo (hostNetwork) para encontrarlas, igual que el network_mode: host de Docker.
• Si quieres el volumen persistente (más abajo), una StorageClass por defecto en el clúster.

Es ligero: el manifiesto le reserva 256 MB de memoria y no le deja pasar de 512 MB.

---

Crearlo en BolloPrint

1. Ve a Configuración → Impresoras y abre la pestaña Agente local.
2. Pulsa Nuevo agente. En ¿Dónde lo vas a instalar?, elige Kubernetes, en Con un contenedor.
3. Ponle un nombre que reconozcas. Mejor dónde está que qué es: «Rack de la nave», «Clúster oficina».
4. Pulsa Crear agente.
5. Aparece el manifiesto, en la pestaña Kubernetes, con las claves del agente ya escritas dentro. Si lo quieres, marca Con volumen persistente (ver abajo). Pulsa Copiar.
6. Con el manifiesto guardado en lugar seguro, pulsa Guardar para cerrar la ventana.

Qué lleva el manifiesto

• Un Secret llamado bolloprint-agent con las dos claves del agente: BP_AGENT_CODE (en qué taller trabaja) y BP_AGENT_INSTANCE_ID (quién es). Trátalas como una contraseña.
• Un Deployment llamado bolloprint-agent, de una sola réplica, que cambia el pod de una vez (Recreate) para que nunca haya dos a la vez. Corre sin privilegios, con la red del nodo y con un límite de memoria de 512 MB.
• Con Con volumen persistente marcado, además, un PersistentVolumeClaim de 256 MB.

No lleva namespace: se crea en el que tengas activo. Si lo quieres aparte, créalo y aplícalo con -n.

¿Con volumen persistente o sin él?

Sin volumen, el agente funciona igual. La diferencia está en las actualizaciones: el agente se actualiza solo descargando la versión nueva, y sin volumen esa descarga se pierde cada vez que el pod se reinicia. Entonces arranca con la versión de la imagen y tarda un rato en ponerse al día otra vez (unos minutos, o hasta que acabe la impresión en curso).

• Márcalo si tu clúster tiene una StorageClass por defecto. Es lo recomendable.
• Déjalo sin marcar si no la tiene: un volumen que no se puede crear deja el pod esperando para siempre, y el agente no llega a arrancar.

¿No sabes si la tienes? kubectl get storageclass la marca con (default).

---

Aplicarlo

1. Guarda el manifiesto en un fichero, por ejemplo bolloprint-agent.yaml.
2. Aplícalo:

kubectl apply -f bolloprint-agent.yaml

Si prefieres su propio namespace:

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

(Si lo pones en un namespace, añade el mismo -n bolloprint a todos los comandos de esta página.)

---

Comprobar que funciona

En menos de un minuto, el agente pasa de Sin instalar a En línea en la pestaña Agente local. No te pedirá autorización: esa instalación ya viene autorizada.

Si no aparece, mira primero que el pod esté en marcha y después su registro:

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

Lo que pasa	Qué mirar
El pod se queda en Pending	Casi siempre es el volumen persistente sin StorageClass por defecto. Quita la casilla, copia el manifiesto otra vez y vuelve a aplicarlo, o crea la StorageClass.
El pod está en marcha pero el agente no aparece	¿Se aplicó el manifiesto entero, sin cambios? ¿El nodo llega a internet? ¿Hay una política de red que bloquee la salida?
Aparece, pero pide autorización	El Secret no lleva BP_AGENT_INSTANCE_ID (se editó a mano o es de antes). Regenera las claves y aplica el manifiesto nuevo tal cual.
Está en línea pero no encuentra impresoras	El nodo está en otra red que las impresoras. Añádelas con Añadir por IP, o fija el pod a un nodo de su red.

Con el agente en línea, el siguiente paso es conectar tus impresoras: lo tienes en Impresoras por red local.

---

Actualizarlo

Desde la versión 2026.1.1, el agente se actualiza solo: cuando sale una versión nueva, la descarga, comprueba que es nuestra y se reinicia con ella. Nunca lo hace mientras alguna de sus impresoras está imprimiendo.

Solo hace falta hacerlo a mano si BolloPrint te lo pide: un aviso encima de las pestañas de Configuración → Impresoras con el botón Cómo actualizar, y la versión del agente en naranja (o en rojo, si ya no está soportada).

Solo cambia la versión de la línea image:. Todo lo demás se queda igual, y el Secret con las claves no se toca. La versión que toca la tienes en la pestaña Despliegue de tu agente (menú ⋮ → Editar).

Cambia la versión en tu fichero y vuelve a aplicarlo:

kubectl apply -f bolloprint-agent.yaml

O, sin tocar el fichero, cambia directamente la imagen del despliegue:

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

Si lo haces así, cambia también el fichero, o la próxima vez que lo apliques volverás a la versión antigua.

En menos de un minuto el agente vuelve a salir En línea, con la versión nueva y sin color de aviso. Mientras el pod se cambia, las impresoras pueden salir unos segundos como Desconectada: vuelven solas.

¿Y si la versión nueva te da problemas? Vuelve a poner la versión anterior y aplica igual (o kubectl rollout undo deployment/bolloprint-agent). Después abre un caso en soporte.

---

Moverlo a otro clúster o a otro nodo

Dentro del mismo clúster no hay que hacer nada: si el pod cambia de nodo, sigue siendo el mismo agente, porque su identidad va en el Secret.

Para llevarlo a otro clúster, borra el despliegue en el antiguo y aplica el mismo fichero en el nuevo:

kubectl delete deployment bolloprint-agent

Bórralo antes de aplicarlo en el nuevo: dos agentes con las mismas claves a la vez se pisan la conexión.

---

Regenerar las claves

En la ventana del agente (menú ⋮ → Editar), pestaña Despliegue, Regenerar claves crea un código y una identidad nuevos y te enseña el manifiesto con ellos. Úsalo si perdiste el manifiesto o crees que alguien tiene tus claves.

Corta el agente en el momento, hasta que apliques el manifiesto nuevo. Al aplicarlo cambia el Secret, pero el pod que ya corre no lo vuelve a leer solo: reinícialo.

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

Si el agente nunca llegó a conectarse (sale Sin instalar), regenerar no corta nada.

Para actualizar no hace falta regenerar. Basta con cambiar la versión de la imagen.

Si aparece en Estado una instalación pendiente de autorizar que no reconoces, no la autorices: alguien más tiene tu código. Regenera las claves.

---

Quitarlo

1. En BolloPrint, en la fila del agente, menú ⋮ → Eliminar. Sus impresoras salen de la lista con él (no se pierde su historial).
2. En el clúster, borra lo que creó el manifiesto:

kubectl delete -f bolloprint-agent.yaml

Si lo desplegaste con volumen persistente, eso borra también el volumen.

---

Lo que NO hay que hacer

• No subas las réplicas. Un agente es un solo pod; dos réplicas son dos agentes con las mismas claves peleándose por la conexión. Para repartir la flota, crea otro agente en BolloPrint.
• No regeneres las claves para actualizar.
• No apliques el manifiesto de la pestaña Despliegue de un agente que ya existe: lleva CHANGE_ME en lugar de las claves.

---

Preguntas frecuentes

¿Tengo que abrir puertos o crear un Service? No. El agente llama a BolloPrint, no al revés, y no escucha en ningún puerto.

¿Funciona en nodos ARM, como una Raspberry Pi con k3s? Sí. La imagen sirve para Intel/AMD y ARM.

¿Puedo usar Helm o Argo CD? Sí, siempre que lo que llegue al clúster sea el mismo manifiesto: un Secret con las dos claves y un Deployment de una réplica. Guarda las claves como guardes tus otros secretos, nunca en un repositorio público.