☸️ Agent sur Kubernetes

Cette page s'adresse à ceux qui utilisent déjà Kubernetes. Si ce n'est pas votre cas, ne le mettez pas en place uniquement pour l'agent : avec Docker, ou avec le paquet de votre poste (dans L'agent local), vous avez la même chose avec moins de pièces.

---

Ce dont vous avez besoin

• Un cluster Kubernetes et kubectl avec un accès à celui-ci.
• Que le nœud sur lequel tourne l'agent soit sur le même réseau que les imprimantes. L'agent utilise le réseau du nœud (hostNetwork) pour les trouver, comme le network_mode: host de Docker.
• Si vous voulez le volume persistant (plus bas), une StorageClass par défaut dans le cluster.

Il est léger : le manifeste lui réserve 256 Mo de mémoire et ne le laisse pas dépasser 512 Mo.

---

Le créer dans BolloPrint

1. Allez dans Paramètres → Imprimantes et ouvrez l'onglet Agent local.
2. Appuyez sur Nouvel agent. Dans Où allez-vous l'installer ?, choisissez Kubernetes, sous Avec un conteneur.
3. Donnez-lui un nom que vous reconnaîtrez. Mieux vaut où il est que ce qu'il est : « Baie de l'atelier », « Cluster bureau ».
4. Appuyez sur Créer l'agent.
5. Le manifeste apparaît, dans l'onglet Kubernetes, avec les clés de l'agent déjà écrites dedans. Si vous le souhaitez, cochez Avec un volume persistant (voir plus bas). Appuyez sur Copier.
6. Une fois le manifeste mis en lieu sûr, appuyez sur Enregistrer pour fermer la fenêtre.

Ce que contient le manifeste

• Un Secret nommé bolloprint-agent avec les deux clés de l'agent : BP_AGENT_CODE (dans quel atelier il travaille) et BP_AGENT_INSTANCE_ID (qui il est). Traitez-les comme un mot de passe.
• Un Deployment nommé bolloprint-agent, d'une seule réplique, qui remplace le pod d'un coup (Recreate) pour qu'il n'y en ait jamais deux à la fois. Il tourne sans privilèges, avec le réseau du nœud et avec une limite de mémoire de 512 Mo.
• Avec Avec un volume persistant coché, en plus, un PersistentVolumeClaim de 256 Mo.

Il ne contient pas de namespace : il se crée dans celui que vous avez actif. Si vous le voulez à part, créez-le et appliquez-le avec -n.

Avec ou sans volume persistant ?

Sans volume, l'agent fonctionne pareil. La différence se joue sur les mises à jour : l'agent se met à jour tout seul en téléchargeant la nouvelle version, et sans volume ce téléchargement est perdu à chaque redémarrage du pod. Il redémarre alors avec la version de l'image et met un moment à se remettre à jour (quelques minutes, ou jusqu'à la fin de l'impression en cours).

• Cochez-le si votre cluster a une StorageClass par défaut. C'est ce qui est recommandé.
• Laissez-le décoché s'il n'en a pas : un volume qui ne peut pas être créé laisse le pod en attente pour toujours, et l'agent ne démarre jamais.

Vous ne savez pas si vous en avez une ? kubectl get storageclass la signale avec (default).

---

L'appliquer

1. Enregistrez le manifeste dans un fichier, par exemple bolloprint-agent.yaml.
2. Appliquez-le :

kubectl apply -f bolloprint-agent.yaml

Si vous préférez son propre namespace :

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

(Si vous le placez dans un namespace, ajoutez le même -n bolloprint à toutes les commandes de cette page.)

---

Vérifier que ça fonctionne

En moins d'une minute, l'agent passe de Non installé à En ligne dans l'onglet Agent local. Il ne vous demandera pas d'autorisation : cette installation est déjà autorisée.

S'il n'apparaît pas, vérifiez d'abord que le pod tourne, puis regardez son journal :

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

Ce qui se passe	Que regarder
Le pod reste en Pending	C'est presque toujours le volume persistant sans StorageClass par défaut. Décochez la case, copiez à nouveau le manifeste et réappliquez-le, ou créez la StorageClass.
Le pod tourne mais l'agent n'apparaît pas	Le manifeste a-t-il été appliqué en entier, sans modification ? Le nœud atteint-il internet ? Une politique réseau bloque-t-elle la sortie ?
Il apparaît, mais demande une autorisation	Le Secret ne contient pas BP_AGENT_INSTANCE_ID (il a été modifié à la main ou il est ancien). Régénérez les clés et appliquez le nouveau manifeste tel quel.
Il est en ligne mais ne trouve aucune imprimante	Le nœud est sur un réseau différent des imprimantes. Ajoutez-les avec Ajouter par IP, ou fixez le pod sur un nœud de leur réseau.

Une fois l'agent en ligne, l'étape suivante consiste à connecter vos imprimantes : c'est dans Imprimantes en réseau local.

---

Le mettre à jour

Depuis la version 2026.1.1, l'agent se met à jour tout seul : quand une nouvelle version sort, il la télécharge, vérifie qu'elle vient bien de nous et redémarre avec elle. Il ne le fait jamais pendant qu'une de ses imprimantes est en train d'imprimer.

Il ne faut le faire à la main que si BolloPrint vous le demande : un avertissement au-dessus des onglets de Paramètres → Imprimantes avec le bouton Comment mettre à jour, et la version de l'agent en orange (ou en rouge, si elle n'est plus prise en charge).

Seule change la version de la ligne image:. Tout le reste reste pareil, et le Secret avec les clés n'est pas touché. La version qui convient se trouve dans l'onglet Déploiement de votre agent (menu ⋮ → Modifier).

Changez la version dans votre fichier et réappliquez-le :

kubectl apply -f bolloprint-agent.yaml

Ou, sans toucher au fichier, changez directement l'image du déploiement :

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

Si vous procédez ainsi, changez aussi le fichier, sinon la prochaine fois que vous l'appliquerez vous reviendrez à l'ancienne version.

En moins d'une minute, l'agent réapparaît En ligne, avec la nouvelle version et sans couleur d'avertissement. Pendant que le pod est remplacé, les imprimantes peuvent apparaître quelques secondes comme Déconnectée : elles reviennent seules.

Et si la nouvelle version vous pose des problèmes ? Remettez la version précédente et appliquez de la même façon (ou kubectl rollout undo deployment/bolloprint-agent). Puis ouvrez une demande au support.

---

Le déplacer vers un autre cluster ou un autre nœud

Au sein du même cluster, il n'y a rien à faire : si le pod change de nœud, il reste le même agent, car son identité est dans le Secret.

Pour l'emmener vers un autre cluster, supprimez le déploiement dans l'ancien et appliquez le même fichier dans le nouveau :

kubectl delete deployment bolloprint-agent

Supprimez-le avant de l'appliquer dans le nouveau : deux agents avec les mêmes clés en même temps se disputent la connexion.

---

Régénérer les clés

Dans la fenêtre de l'agent (menu ⋮ → Modifier), onglet Déploiement, Régénérer les clés crée un nouveau code et une nouvelle identité et vous affiche le manifeste avec eux. Utilisez-le si vous avez perdu le manifeste ou si vous pensez que quelqu'un a vos clés.

Cela coupe l'agent sur-le-champ, jusqu'à ce que vous appliquiez le nouveau manifeste. En l'appliquant, le Secret change, mais le pod qui tourne déjà ne le relit pas tout seul : redémarrez-le.

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

Si l'agent ne s'est jamais connecté (il apparaît Non installé), régénérer ne coupe rien.

Pour mettre à jour, inutile de régénérer. Il suffit de changer la version de l'image.

Si une installation en attente d'autorisation que vous ne reconnaissez pas apparaît dans État, ne l'autorisez pas : quelqu'un d'autre a votre code. Régénérez les clés.

---

Le retirer

1. Dans BolloPrint, sur la ligne de l'agent, menu ⋮ → Supprimer. Ses imprimantes quittent la liste avec lui (leur historique n'est pas perdu).
2. Dans le cluster, supprimez ce que le manifeste a créé :

kubectl delete -f bolloprint-agent.yaml

Si vous l'avez déployé avec un volume persistant, cela supprime aussi le volume.

---

Ce qu'il ne faut PAS faire

• N'augmentez pas le nombre de répliques. Un agent, c'est un seul pod ; deux répliques, ce sont deux agents avec les mêmes clés qui se disputent la connexion. Pour répartir la flotte, créez un autre agent dans BolloPrint.
• Ne régénérez pas les clés pour mettre à jour.
• N'appliquez pas le manifeste de l'onglet Déploiement d'un agent qui existe déjà : il contient CHANGE_ME à la place des clés.

---

Questions fréquentes

Dois-je ouvrir des ports ou créer un Service ? Non. C'est l'agent qui appelle BolloPrint, et non l'inverse, et il n'écoute sur aucun port.

Fonctionne-t-il sur des nœuds ARM, comme un Raspberry Pi avec k3s ? Oui. L'image fonctionne sur Intel/AMD et ARM.

Puis-je utiliser Helm ou Argo CD ? Oui, du moment que ce qui arrive dans le cluster est le même manifeste : un Secret avec les deux clés et un Deployment d'une réplique. Conservez les clés comme vous conservez vos autres secrets, jamais dans un dépôt public.