Rôles et installation des nœuds

Ces exigences de rôle s’appliquent à la fois aux nœuds enrôlés sur vos propres serveurs et aux VM créées via Opfield.

Le rôle choisi à l’enrôlement détermine les ressources que l’hôte peut contrôler, le profil logiciel installé et ce qu’affecte une panne de l’hôte. Choisissez selon la responsabilité, et non selon les paquets déjà présents sur la machine.

Avant l’enrôlement, arrêtez le rôle, le propriétaire de l’hôte, le domaine de panne, la sensibilité des données et la personne chargée de rétablir l’hôte. L’enrôlement est terminé lorsqu’une identité de nœud durable est installée sur l’hôte prévu, ne signale que les capacités attendues et réussit une vérification de recette à faible risque propre au rôle avant l’affectation de ressources de production.

Détails pour l’opérateur : prérequis des profils

Utilisez la commande d’installation générée par le processus de création du nœud. Elle contient un matériel d’enrôlement limité et l’identité Opfield épinglée.

nginx : nécessite nginx, des ports d’ingress publics le cas échéant, la validation de la configuration et l’accès aux journaux.
Docker : nécessite un Docker Engine pris en charge et les permissions pour les opérations d’exécution configurées. L’installateur installe aussi le lease watchdog, opfield-lease-watchdog, un service distinct dont le basculement du plan de données a besoin sur les nœuds qui détiennent des baux Availability. Sur un nœud installé avant l’existence du watchdog, un démon Docker qui s’exécute en root avec systemd ou OpenRC l’installe lui-même ; pour un démon installé avec --user <non-root user>, relancez l’installateur du nœud Docker avec sudo et le même --user, car une exécution non interactive bascule sinon le service du démon en root. Chaque volume managé sur image disque occupe un périphérique loop, et le démon installe une étape de démarrage, opfield-volume-images, qui monte ces volumes avant le démarrage de Docker.
storage : exécute le démon Docker en root et nécessite un stockage dédié, des périphériques loop et la prise en charge des montages ; l’installateur formate, monte, agrandit et détache une image de test avant l’enrôlement, et s’arrête si l’hôte n’y parvient pas. Chaque base de données managée, chaque membre de stockage objet et chaque sauvegarde en cours occupent un périphérique loop ; un invité LXC a donc besoin que son hôte transmette /dev/loop-control et un ensemble de périphériques loop dimensionné pour tous. Le nœud a besoin d’un accès HTTPS sortant vers ghcr.io pour l’exécuteur de sauvegardes. L’installateur installe aussi le lease watchdog, opfield-lease-watchdog, utilisé par les bases de données et le stockage sur plusieurs serveurs. L’ancien mode databases est accepté comme alias. Voir Prérequis des nœuds Storage et Docker.
builder : nécessite systemd et une capacité BuildKit/containerd dédiée, et ne doit pas disposer de socket Docker Engine. Sur un hôte sans systemd, l’installateur s’arrête avant d’installer ou de télécharger quoi que ce soit.
monitoring : fournit la collecte de supervision prise en charge.
Superviseur/worker Relay : étend la capacité et la résilience de Relay avec un placement explicite.

Après l’installation, validez le signalement des capacités au lieu de supposer que les paquets de l’hôte impliquent leur prise en charge. Les fonctionnalités GPU, Secure Runtime, builder, stockage et migration dépendent de capacités signalées comme saines.

Choisir le rôle

Ingress : termine TLS et sert les domaines et les Routes publics. Il nécessite la validation de la configuration nginx, le stockage des certificats, les journaux et des ports publics le cas échéant.
Docker : gère les charges de travail applicatives ordinaires et les ressources Docker. Il nécessite un Docker Engine pris en charge et les privilèges requis par les fonctionnalités d’exécution choisies.
Build Worker : exécute les builds Git sur des services BuildKit/containerd isolés. Il doit être dédié aux builds et ne doit pas exposer de socket Docker Engine ordinaire au profil de build.
Storage : exécute PostgreSQL, les stockages clé-valeur et ClickHouse managés, le stockage objet SeaweedFS managé et les tâches de sauvegarde des bases de données, avec une préparation de stockage dédiée et un profil de démon Docker restreint. Les conteneurs applicatifs génériques et les builds sont refusés. Les nœuds enrôlés avec l’ancien rôle Databases conservent leur identité, leur enrôlement, leur configuration et leurs données ; la mise à jour de leur démon active les capacités Storage sans réenrôlement ni déplacement des données.
Monitoring : collecte la santé et les métriques des hôtes prises en charge sans recevoir de permissions sur le cycle de vie des charges de travail.
Relay : installe le superviseur Relay, annonce une adresse joignable et rejoint le Relay Pool des Secure Links.

Processus d’enrôlement standard

Ouvrez Nodes, sélectionnez Add Node et choisissez External VM.
Sélectionnez le Node Type prévu et lisez sa description.
Saisissez un nom stable destiné aux opérateurs.
Pour Relay, saisissez l’adresse que les nœuds participants peuvent joindre sur le port TCP 9443.
Créez le nœud en attente.
Copiez la commande d’installation à usage unique générée. Elle appartient à l’installation Opfield qui l’affiche : elle télécharge l’installateur depuis la version de cette installation, ne l’exécute qu’après correspondance de sa somme de contrôle avec la version, et épingle le démon le plus récent de la même ligne de versions.
Exécutez la commande sur l’hôte Linux prévu.
Laissez la boîte de dialogue de résultat ouverte pendant l’installation et l’enrôlement du démon ; elle se ferme automatiquement lorsque ce nœud précis passe en ligne.
Ouvrez le détail du nœud et vérifiez le rôle, le nom d’hôte, la version, les capacités, les métriques et les adresses de service.

L’action Add relay node des paramètres Relay ouvre le même processus d’enrôlement avec Relay présélectionné et verrouillé. Les membres Relay n’apparaissent comme capacité du pool prête qu’une fois l’enrôlement et le signalement de santé réussis.

Préparation de l’hôte

Utilisez un hôte ou une VM dédiés chaque fois que le rôle porte une frontière de confiance forte. Vérifiez le DNS, l’heure système, la joignabilité sortante de Relay, les prérequis de paquets et d’exécution, le stockage persistant et systemd ou OpenRC avant d’exécuter l’installateur. Ne copiez pas une commande d’installation d’un enregistrement de nœud en attente à un autre.

Les nœuds Storage nécessitent les contrôles préalables de stockage de l’installateur. Les Build Workers nécessitent une capacité d’exécution et de stockage dédiée. Les nœuds Relay nécessitent une adresse annoncée joignable et doivent être placés dans des domaines de panne distincts lorsque le pool doit assurer la résilience.

Ce que vérifie l’installateur

Connexion. Une exécution de l’installateur, et chaque réexécution sur un nœud enrôlé, ne réussit que si le démon qu’elle a démarré s’exécute sous systemd ou OpenRC et qu’Opfield a accepté sa session. Sinon, elle se termine par une erreur, nomme le journal du démon et en affiche les dernières lignes ; elle attend la session jusqu’à 90 secondes. Un jeton déjà utilisé ou expiré est signalé comme refusé par Opfield. Les hôtes sans systemd ni OpenRC reçoivent un lanceur détaché qui ne survit pas à un redémarrage.
Réexécution de la commande de configuration. Réexécuter la commande de configuration propre à un nœud, avec son jeton déjà utilisé, conserve l’enrôlement et s’exécute comme une réexécution sans jeton. Un jeton différent sur un hôte enrôlé n’est pas utilisé : les installateurs Docker et de supervision s’arrêtent avec une erreur sans rien modifier (sur un nœud enrôlé avant 2.11.1, ils avertissent et poursuivent la mise à jour), et l’installateur nginx s’enrôle avec le nouveau jeton mais conserve l’enrôlement précédent si Opfield le refuse. Pour enrôler l’hôte en tant qu’autre nœud, arrêtez le démon, mettez de côté son répertoire certs et son fichier state.json, puis exécutez la nouvelle commande.
Réponses. Sans -y, l’installateur pose ses questions dans le terminal et s’arrête lorsqu’il ne peut pas lire de réponse, par exemple sans terminal ou lorsque sa sortie passe par tee ; une réponse manquante n’est jamais considérée comme un consentement. Refuser Proceed with installation? ou s’arrêter après le résumé se termine par une erreur.
Secure Runtime. Une nouvelle installation de nœud Docker configure Secure Runtime lorsque l’hôte le prend en charge. Sur un hôte sans prise en charge, ou lorsque la configuration échoue, l’installateur avertit en donnant la raison et poursuit, et le nœud signale la même raison dans ses capacités. Avec --secure-runtime, l’installation échoue à la place ; ce drapeau installe aussi Secure Runtime sur une installation existante. Dans un fichier /etc/docker/daemon.json existant, la configuration n’ajoute que runtimes.runsc, après avoir enregistré une fois l’original sous daemon.json.opfield-backup ; toutes les autres clés restent telles qu’écrites.
Version du démon. Sans --version, un installateur installe la dernière version stable du démon, mais une réexécution n’installe jamais un démon plus ancien que celui qui est installé, par exemple sur un nœud qui exécute une préversion plus récente. Il affiche alors la version installée et la version vers laquelle latest se résout, et conserve la version installée. Pour installer la version plus ancienne, nommez-la avec --version (OPFIELD_NODE_DAEMON_VERSION pour les installateurs de démons). Cela s’applique aux installateurs Docker, Build Worker, Storage, nginx, de supervision et Relay.
Sauvegardes. Lorsque les installateurs de supervision, nginx et Docker remplacent un fichier, comme le binaire du démon ou une configuration nginx, ils ne conservent que la sauvegarde la plus récente de ce fichier (<file>.backup.<timestamp>).

Exécuter un démon sans root

Les démons de supervision, Docker (profil docker), nginx et Relay peuvent s’exécuter sous un utilisateur non root existant : passez --user <user> à l’installateur de supervision, Docker ou nginx, ou définissez OPFIELD_RELAY_RUN_USER (et éventuellement OPFIELD_RELAY_RUN_GROUP) pour l’installateur Relay. L’installateur lui-même s’exécute toujours avec sudo et s’arrête avant de modifier l’hôte si l’utilisateur n’existe pas. Les nœuds Storage et les Build Workers ne s’exécutent qu’en root.

Changement d’utilisateur. Réexécutez l’installateur du nœud avec un autre --user, ou sans --user pour revenir à root. Le nœud conserve son enrôlement et l’identité de l’hôte ; un relais enrôlé n’a pas besoin de --token pour une telle réexécution. Sur les nœuds Docker et nginx, l’installateur prépare tout pendant que le démon continue de servir et ne l’arrête que juste avant le démarrage du nouveau processus ; le démon de supervision et le superviseur Relay sont arrêtés en premier. Le démon est arrêté avant que l’un de ses fichiers ne change de propriétaire. Le changement redémarre le démon une fois : les connexions passant par ses liens de bases de données, de stockage et de conteneurs sont coupées une fois pendant environ 1,5 seconde et les clients se reconnectent, comme lors de tout redémarrage du démon. Le trafic des Routes via Secure Link ne fait qu’attendre, car sous systemd le démon d’un nœud Docker ou nginx confie ses sockets de liens à systemd, qui les conserve pendant le changement. Sur un nœud Docker dont les liens de stockage utilisent encore des sidecars par lien antérieurs à 2.11.1, le changement recrée aussi ces sidecars. L’utilisateur précédent conserve les appartenances aux groupes que l’installateur lui a données, comme docker ; retirez-les avec gpasswd -d <user> docker.
Docker. L’installateur ajoute l’utilisateur au groupe docker, ce qui équivaut à root sur l’hôte. Sans root, les volumes sur image disque, le déplacement des données de volumes entre nœuds, la taille des journaux des conteneurs et l’installation de Secure Runtime depuis Opfield ne sont pas disponibles ; pour installer Secure Runtime, réexécutez l’installateur avec le même --user et --secure-runtime (Node Details affiche la commande). Le lease watchdog s’exécute toujours comme service root.
nginx. nginx doit déjà s’exécuter sous le même utilisateur avec CAP_NET_BIND_SERVICE, et l’utilisateur doit être propriétaire de /etc/nginx, /var/log/nginx et des répertoires temporaires de nginx ; utilisez --nginx-mode integrate. Exécuter nginx sous l’utilisateur de sa distribution (www-data ou nginx) et installer le démon sous cet utilisateur est la configuration la plus simple. Sous OpenRC, définissez command_user="<user>:<group>" et capabilities="^cap_net_bind_service" dans /etc/conf.d/nginx et pid /run/nginx/nginx.pid; dans nginx.conf. Lorsque nginx ne s’exécute pas sous cet utilisateur, l’installateur s’arrête avant de modifier quoi que ce soit et liste ce qu’il faut préparer. Pour revenir à root, exécutez d’abord à nouveau nginx en root.
Relay. Un port Relay inférieur à 1024 nécessite systemd ou OpenRC ; l’installateur accorde la capacité de liaison au port.
Console de l’hôte. console.user dans la configuration du démon n’exécute les sessions de console sous un autre utilisateur que sur un démon root. Un démon qui s’exécute sous son propre utilisateur refuse les sessions de console tant que console.user désigne un autre utilisateur (409 NODE_CONSOLE_USER_UNAVAILABLE), et la page du nœud indique la correction : retirer console.user ou exécuter le démon en root.

Désactiver la console et les fichiers de l’hôte

Chaque type de démon lit deux interrupteurs d’accès à l’hôte dans son fichier de configuration : console.enabled et files.enabled, tous deux à true par défaut. Avec console.enabled: false, le démon refuse la console de l’hôte, y compris les commandes ponctuelles de l’assistant et de MCP ; avec files.enabled: false, il refuse l’accès aux fichiers de l’hôte. Les installateurs Docker, nginx, de supervision et Relay les définissent avec --disable-console et --disable-files, et les boîtes de dialogue de configuration des nœuds proposent les cases Disable host console et Disable host files qui ajoutent ces drapeaux. Les nœuds commandés via un hébergeur sont installés par Opfield lui-même ; désactivez-y les interrupteurs en modifiant le fichier de configuration.

Les interrupteurs n’existent que sur le nœud ; un administrateur d’Opfield ne peut donc pas les réactiver à distance. Pour en modifier un, éditez le fichier sur le nœud et redémarrez le démon. Opfield refuse les requêtes désactivées avec 409 NODE_CONSOLE_DISABLED ou 409 NODE_FILES_DISABLED. Les consoles et fichiers des conteneurs ne sont pas concernés. Pour supprimer l’accès à l’hôte, désactivez les deux : un démon qui s’exécute en root et peut encore écrire des fichiers peut modifier l’hôte et réactiver la console. La page du nœud affiche un avertissement tant que la console est désactivée et l’accès aux fichiers activé. Pour un relais sur la machine de quelqu’un d’autre, utilisez le mode protégé.

Invités Alpine, OpenRC et LXC

Les installateurs prennent en charge OpenRC aussi bien que systemd, y compris pour les démons qui s’exécutent sous leur propre utilisateur. Un nœud Docker a besoin que Docker fournisse à ses conteneurs les contrôleurs cgroup memory, pids et cpu, car le connecteur secure-link et les charges de travail managées s’exécutent avec des limites. L’installateur le vérifie et refuse d’enrôler le nœud lorsqu’un contrôleur manque ; il ne modifie pas la configuration des cgroups de l’hôte.

Sur un invité LXC Alpine avec OpenRC, le cgroup racine ne transmet souvent aucun contrôleur, car tous les processus s’y trouvent. Laissez le service cgroups d’OpenRC sortir les processus avant d’activer les contrôleurs : exécutez rc-update add cgroups boot, placez ce qui suit dans /etc/conf.d/cgroups, puis redémarrez l’invité.

# Move every process out of the root cgroup so that the cgroups service can pass the controllers down.
start_pre() {
  [ -w /sys/fs/cgroup/cgroup.subtree_control ] || return 0
  mkdir -p /sys/fs/cgroup/init
  for pid in $(cat /sys/fs/cgroup/cgroup.procs); do
    echo "$pid" > /sys/fs/cgroup/init/cgroup.procs 2>/dev/null
  done
  return 0
}

Vérifiez ensuite avec cat /sys/fs/cgroup/cgroup.subtree_control /sys/fs/cgroup/docker/cgroup.controllers : les deux doivent lister memory, pids et cpu. La configuration du conteneur LXC sur l’hyperviseur n’a pas besoin d’être modifiée pour cela.

Vérification et nettoyage

L’enrôlement n’est terminé que lorsque le démon signale les capacités attendues et que le premier instantané d’inventaire et de métriques arrive. Si l’installation échoue avant l’enrôlement, examinez les journaux du service local et de l’installateur. Ne supprimez l’enregistrement en attente que si vous abandonnez cette identité ; le jeton d’un nœud supprimé ne doit pas être réutilisé.

Modes de défaillance de l’installation

L’installateur du nœud nginx peut être réexécuté sur le même hôte après un échec, et une réexécution conserve le mode nginx de l’installation existante. Si la commande ne parvient pas à télécharger ou à démarrer le démon, vérifiez le HTTPS sortant, le DNS, l’heure système, l’état du gestionnaire de paquets, l’architecture et l’espace disque disponible. Si le démon démarre mais que l’enrôlement n’aboutit pas, vérifiez la joignabilité de Relay, que le jeton à usage unique n’a pas déjà été consommé et que la commande a été exécutée pour le nœud en attente affiché dans la boîte de dialogue. Ne générez pas plusieurs enregistrements en attente pour essayer leurs commandes de façon interchangeable.

Un nœud qui s’enrôle sans sa capacité attendue n’est pas prêt pour ce rôle. Vérifiez le service du rôle, les permissions du socket ou du stockage, les fonctionnalités du noyau requises et les journaux de démarrage limités du démon. Corrigez le prérequis de l’hôte et laissez le signalement des capacités s’actualiser ; changer le Node Type après l’installation ne remplace pas l’installation du bon profil.

Si l’hôte a été enrôlé avec le mauvais rôle, mettez délibérément cette identité hors service et créez un nouveau nœud avec le bon rôle. Avant la suppression, assurez-vous qu’aucune ressource ni opération n’a été affectée à l’identité erronée et désinstallez son matériel de démon afin qu’il ne puisse pas se reconnecter de façon inattendue.

Sécurité après l’installation

Traitez la commande d’installation générée comme un identifiant de courte durée. Ne l’exécutez que sur l’hôte prévu, ne la collez pas dans une discussion partagée ou une automatisation shell persistante, et retirez-la des notes d’exploitation après l’enrôlement. Le certificat de démon installé devient l’identité durable et ne doit pas être copié sur une autre machine ni restauré sur deux hôtes actifs.

Limitez l’accès local à la configuration du démon, au matériel de certificats, aux identifiants de registre, au stockage des bases de données et aux sockets propres au rôle. L’enrôlement établit la confiance entre Opfield et l’hôte ; il ne durcit pas les services sans rapport du système d’exploitation. Appliquez la configuration de base des hôtes de l’organisation et gardez la surface d’attaque du rôle limitée à ses prérequis documentés.