Projets Compose

Opfield découvre les applications Docker Compose externes et peut gérer des projets Compose mononœuds comme des ressources durables. Un projet regroupe des services, une configuration, des révisions immuables, des opérations de cycle de vie, des journaux, des Routes et des liaisons de bases de données sous une identité stable unique.

La découverte des projets externes est disponible avec tous les plans. La création ou l’adoption d’un projet mononœud géré nécessite Personal ou supérieur. Les builds Compose adossés à Git nécessitent Business ou Enterprise et un Build Worker dédié en ligne.

Choisir entre visibilité et propriété

La découverte donne aux équipes une vue partagée d’une application Compose existante sans changer qui l’exploite. L’adoption modifie le modèle de propriété : Opfield devient l’endroit où s’effectuent les révisions de configuration et les actions de cycle de vie. Rendez ce transfert explicite avec le propriétaire de l’application, car continuer à faire tourner un processus docker compose indépendant après l’adoption crée des états souhaités concurrents.

Choisissez Compose géré lorsque plusieurs services doivent être revus, appliqués, arrêtés, rétablis et audités comme une seule application sur un seul nœud Docker. Le propriétaire du projet doit définir les dépendances entre services, la propriété des données, les sources des secrets, l’interruption acceptable et les conditions de retour arrière pour les changements de configuration. Pour les projets éligibles sans montages, Business et Enterprise peuvent activer Workload Availability (HA) pour répliquer l’ensemble du projet ou remplacer son placement actif après la perte d’un nœud. Les services d’un même placement restent sur un seul nœud ; Opfield ne répartit pas un projet Compose sur un cluster.

Un projet réussi a un seul propriétaire de configuration identifié, une révision active reproductible, des services requis sains, des volumes persistants connus, des Routes et liaisons privées qui fonctionnent, et aucune dérive inexpliquée.

Projets externes et gérés

Un projet externe est découvert à partir des labels Docker Compose canoniques de ses conteneurs, volumes et réseaux. Opfield affiche l’inventaire, l’état, la santé des services, la supervision et les journaux agrégés, et les utilisateurs autorisés peuvent ouvrir la console ou l’explorateur de fichiers d’un conteneur de service. Les projets externes sont en lecture seule : Opfield ne lit pas le fichier Compose de l’hôte et ne propose aucune action de démarrage, d’arrêt, de redémarrage, de révision, de secret ou de suppression tant qu’un opérateur n’a pas explicitement adopté le projet. Continuez à exploiter un projet externe avec son processus docker compose d’origine, ou adoptez-le. Pour la conception des accès, voir Exploiter des charges de travail sans les adopter.

Un projet géré stocke dans Opfield son YAML Compose rédigé, ses variables, ses clés de secrets protégés et ses révisions immuables. Le démon Docker applique la révision sélectionnée via l’environnement d’exécution Compose épinglé d’Opfield. Le cycle de vie mononœud est disponible à partir de Personal. Workload Availability multinœud est disponible en Business et Enterprise ; la mise à l’échelle automatique sur métriques et la mise à l’échelle des répliques sur un même nœud restent In development.

Les conteneurs enfants, les volumes nommés et les réseaux non externes appartenant au projet sont contrôlés via le projet Compose. Ils sont masqués ou protégés contre les actions de cycle de vie autonomes conflictuelles : un conteneur Compose individuel ne peut pas être démarré, arrêté, redémarré, modifié, recréé ou supprimé seul, que le projet soit externe ou géré. Les actions de cycle de vie s’appliquent à l’ensemble du projet. Les images et les ressources explicitement externes ou partagées restent des ressources Docker globales.

Créer un projet géré

1. Ouvrez Docker > Compose et sélectionnez New Project.
2. Choisissez un nœud Docker en ligne disposant de la capacité Compose.
3. Saisissez une configuration Compose complète en un seul fichier.
4. Fournissez les variables non secrètes et identifiez séparément les clés des secrets protégés.
5. Lancez la validation et résolvez les options non prises en charge, les variables manquantes, les conflits de ports ou les violations de politique.
6. Créez le projet et suivez la première opération d’application jusqu’au bout.
7. Vérifiez chaque service, état de santé, réseau, volume et flux de journaux agrégés attendu.

Les projets manuels reposent uniquement sur des images : les images doivent déjà pouvoir être récupérées par le nœud cible. Business et Enterprise peuvent rattacher une source Git figurant sur la liste d’autorisation. Les sections Compose build bornées sont alors résolues par des Build Workers isolés, la politique de vulnérabilités est appliquée, et la révision immuable obtenue épingle les empreintes d’images approuvées avant le déploiement.

Adopter un projet externe

L’adoption est un transfert de propriété explicite. Elle nécessite Personal ou supérieur ainsi que docker:compose:create et docker:compose:manage pour le projet. Ouvrez le projet découvert, choisissez Adopt into Opfield et collez la configuration complète qu’Opfield doit détenir. Opfield ne lit pas le fichier Compose sur l’hôte ; l’éditeur démarre donc vide. Opfield valide le YAML, l’enregistre comme première révision immuable, puis l’applique avec Adopt & Apply.

Vérifiez que le YAML soumis correspond aux services, volumes, réseaux, variables et secrets de l’application en cours d’exécution. Opfield ne fait jamais confiance à un chemin d’hôte fourni par un label comme entrée source. Après l’adoption, les modifications futures doivent passer par de nouvelles révisions plutôt que par la modification directe des conteneurs enfants.

Ce que l’adoption conserve et ce qu’elle modifie

• Nom du projet. Le projet adopté conserve le nom que Docker signale déjà, et Opfield exécute chaque opération avec ce nom de projet Compose. Opfield ne renomme pas et ne préfixe pas le projet, ses services ou ses volumes. Un name: de premier niveau dans le YAML est facultatif, mais s’il est présent, il doit être égal au nom du projet.
• Volumes nommés. Comme le nom du projet ne change pas, Docker Compose résout les mêmes noms de volumes qu’auparavant — <project>_<volume> par défaut, ou le name: explicite d’un volume — et réutilise les volumes existants et leurs données. Les volumes déclarés external: true sont référencés, pas créés. Avant la première application, comparez les volumes listés sur le projet découvert avec ceux vers lesquels se résout le YAML soumis ; une clé de volume renommée crée un nouveau volume vide.
• Conteneurs. Opfield ajoute ses propres labels de gestion à chaque service ; attendez-vous donc à ce que la première application recrée les conteneurs des services. Prévoyez une courte fenêtre de maintenance.
• Environnement et secrets. env_file et le fichier .env d’un projet ne sont pas utilisés. Déclarez les variables dans l’environment: de chaque service et référencez les valeurs avec ${NAME}. Opfield fournit les variables non secrètes et les secrets de projet chiffrés pour l’interpolation lorsqu’il applique une révision. Dans la Console, les onglets Variables et Secrets deviennent disponibles après l’adoption ; utilisez des espaces réservés ${NAME} pour les valeurs que vous y ajouterez.
• Montages de répertoires de l’hôte. Les bind mounts sont refusés, y compris les chemins relatifs comme ./config:/etc/app, les chemins ~ et les sources construites à partir de variables. Placez les fichiers de configuration dans l’image ou dans un volume nommé avant l’adoption.
• Tâches ponctuelles. Opfield n’a pas d’équivalent de docker compose run, ni de hook avant déploiement ou de publication. Pour une étape de migration, exécutez la commande dans un conteneur de service via la console, ce qui nécessite docker:containers:console, ou modélisez-la comme un service avec restart: "no" que les autres services attendent via depends_on. Utilisez condition: service_completed_successfully lorsque les autres services doivent attendre la fin de la tâche. Un service ponctuel qui se termine avec le code 0 est considéré comme terminé ; il ne marque donc pas le projet comme degraded.

Configuration Compose prise en charge

Les révisions manuelles et adoptées acceptent un document Compose en un seul fichier jusqu’à 1 Mio, sans ancres ni alias YAML. Les clés de premier niveau sont limitées à name, version, services, volumes et networks ; include, les secrets et configs de premier niveau et les extensions x- sont donc refusés.

Chaque service doit utiliser image et ne peut utiliser que ces clés : image, command, entrypoint, working_dir, user, hostname, environment, labels, ports, volumes, networks, depends_on, healthcheck, restart, extra_hosts, cpus, cpu_shares, mem_limit, mem_reservation, memswap_limit, pids_limit et logging. Tout le reste est refusé, y compris build, env_file, container_name, privileged, cap_add, devices, network_mode, pid, ipc, security_opt, tmpfs, ulimits, deploy, profiles, extends, les secrets et configs au niveau du service, et links.

Autres règles :

• restart doit valoir no, always, on-failure ou unless-stopped ;
• les ports ne peuvent pas utiliser de plages et doivent être TCP ou UDP ;
• une entrée de réseau d’un service ne peut définir que aliases, et chaque réseau qu’utilise un service doit être déclaré au premier niveau, à l’exception du réseau implicite default ;
• chaque volume nommé qu’un service monte doit être déclaré au premier niveau ;
• un montage de volume en syntaxe longue ne peut définir que type, source, target et read_only, doit inclure type (sinon VOLUME_TYPE_REQUIRED) et doit utiliser type: volume avec un volume nommé comme source ;
• depends_on accepte une liste de services ou un mappage en syntaxe longue ; dans ce mappage, chaque entrée ne peut définir que condition, qui est obligatoire et doit valoir service_started, service_healthy ou service_completed_successfully ; chaque dépendance doit être un service du même fichier ;
• les volumes et réseaux de premier niveau ne peuvent définir que external, name, driver et labels ; driver_opts est donc refusé ;
• logging ne peut définir que driver et options ; le pilote doit être json-file, local ou none, et les options sont limitées à max-size, max-file et compress (none n’accepte aucune option) ;
• les labels commençant par com.docker.compose. ou net.opfield., ou par les préfixes antérieurs à Opfield wiolett.gateway., net.wiolett.gateway. et com.wiolett.gateway., ainsi que le label gateway.sandbox, sont réservés, et une clé de label construite à partir d’une variable est refusée ;
• un réseau ne peut pas être le réseau de l’hôte (host ou none) ni l’un des réseaux internes d’Opfield (opfield-secure-links, opfield-db-*, opfield-storage-*, opfield-link-*, ou leurs noms gateway- antérieurs à 2.12.1), et un nom de réseau construit à partir d’une variable est refusé ;
• les variables et secrets ne peuvent pas utiliser les noms que le client Compose lit lui-même : PATH, DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY, DOCKER_TLS, DOCKER_API_VERSION, DOCKER_DEFAULT_PLATFORM, DOCKER_BUILDKIT, ainsi que tout nom commençant par BUILDKIT_ ou COMPOSE_ ; les autres noms DOCKER_* restent des variables ordinaires ;
• chaque référence ${NAME} nécessite une variable ou un secret fourni.

Un projet enregistré avant l’existence de ces règles sur les réseaux, labels et variables continue de s’exécuter et peut toujours être arrêté et démonté, mais la création d’une révision, l’application, le démarrage et le redémarrage sont refusés tant que sa configuration ne les respecte pas. Cela inclut la première application après la mise à jour du démon Docker.

Sur un nœud dont le pilote de journalisation par défaut est json-file, le démon Docker attribue à chaque service sans logging une rotation json-file de 50 Mo × 3, la même limite que celle des conteneurs autonomes. Pour conserver plus longtemps les journaux d’un service, définissez vos propres max-size et max-file ; driver: json-file sans options conserve la valeur par défaut illimitée de Docker. Docker ne peut pas modifier les paramètres de journalisation d’un conteneur existant. Après la mise à jour vers 2.11, la première application recrée donc chaque service une fois, même pour une révision inchangée : chaque service reçoit les nouveaux paramètres de journalisation et un label portant l’empreinte de sa propre configuration. Ensuite, une application ne recrée que les services dont la configuration a changé. Un nœud dont le démon Docker n’a pas encore été mis à jour applique les révisions sans leurs sections logging et conserve les valeurs par défaut de Docker.

Opfield et le démon Docker appliquent les mêmes règles ; une révision qui passe la validation n’est donc pas refusée plus tard lors de son application. Les projets Business et Enterprise disposant d’une source Git peuvent en plus utiliser une section build bornée ; voir Créer un projet géré. Les mêmes règles s’appliquent aux révisions créées via l’API, MCP ou AI Workspace. La réécriture d’un fichier Compose pour respecter ces règles fait partie de la planification de l’adoption ; faites-la donc d’abord en préproduction.

Révisions et cycle de vie

Modifier la configuration crée une nouvelle révision immuable. Utilisez Pull & Apply pour récupérer les images requises et appliquer la révision active, Start ou Stop pour le cycle de vie du projet, et Change revision pour réappliquer une révision valide antérieure. Les révisions inactives peuvent être supprimées lorsqu’aucune opération ne les utilise ; la révision active ne peut pas être supprimée.

L’application d’une révision ne recrée que les services dont la définition propre a changé — image, environnement, commande, ports, volumes, réseaux, limites, labels, journalisation ou un autre champ du service — ou dont les variables ou secrets interpolés ont changé ; les autres services continuent de s’exécuter. Une révision qui supprime un service attend l’arrêt de ce service, jusqu’à sa période de grâce d’arrêt de 10 secondes, avant le démarrage des services modifiés. Pull & Apply recrée aussi un service dont le tag d’image pointe désormais vers une image plus récente. Les placements d’un projet sous Workload Availability portent toujours l’empreinte de l’ensemble de la révision ; une nouvelle révision recrée donc tous leurs services. Une application sans récupération ne télécharge que les images absentes du nœud. Une révision dont un port TCP publié est déjà détenu sur le nœud par un Deployment, une réplique Availability, une base de données managée ou un stockage managé est refusée à sa création avec 409 COMPOSE_HOST_PORT_IN_USE ; pour un projet construit depuis Git, le build échoue avec ce message et aucune révision n’est créée. Un projet affiche degraded lorsque l’un de ses services s’arrête hors d’Opfield, et la page de statut le signale. Sur un projet doté de Workload Availability, un démarrage, un arrêt ou un redémarrage demandé pendant que l’opération Availability précédente est encore en cours est mis en file d’attente et s’exécute ensuite.

Le travail de cycle de vie est représenté par des opérations et des tâches durables. Recharger la page n’annule pas une opération. Pendant le déploiement d’un build Git sur le projet, les actions de révision, de cycle de vie, de secrets et de suppression renvoient BUILD_ROLLOUT_IN_PROGRESS jusqu’à la fin du déploiement ; l’annulation d’une opération reste possible. Pendant une mise à jour d’Opfield, les nouvelles opérations Compose sont refusées avec OPFIELD_UPDATING. Si l’annulation est disponible, actualisez l’état du projet et l’état signalé par le démon avant de lancer une action de remplacement.

Routes et liaisons de bases de données

Les Routes et les Secure Links peuvent cibler un service Compose géré par l’identité stable du projet et du service plutôt que par un nom de conteneur éphémère. Les liaisons de bases de données managées mettent à jour la révision du projet tout en préservant la configuration rédigée et les secrets protégés. La suppression d’un service ou d’une liaison doit passer par une nouvelle révision afin qu’Opfield puisse réconcilier en toute sécurité les relations dépendantes. Appliquer une révision plus ancienne conserve les liaisons actuelles ; une révision qui ne définit pas un service lié est refusée tant que cette liaison n’est pas supprimée. Via l’API, MCP ou l’assistant, un service peut être lié avant la première révision du projet ; voir Charges de travail qui ne s’exécutent pas.

Une nouvelle révision transporte chaque lien de base de données dans son intégralité — son réseau, ses variables et l’alias d’hôte du point de terminaison privé du lien — ; son application démarre donc le service avec le lien déjà résolvable, en une seule opération. Ajouter, supprimer ou réparer un lien sur un projet en cours d’exécution applique le projet une fois, sans récupérer ses images ni recréer ses autres services. Un projet construit à partir d’une source Git peut aussi recevoir et perdre des liens : Opfield applique une copie de la révision construite qui conserve le fichier Compose du dépôt et sa filiation Git, et un push ultérieur conserve le lien et ses secrets. La vue d’ensemble du projet affiche l’exécution de chaque lien : ses connexions ouvertes par rapport à la capacité du lien et les connexions qu’il a refusées ; voir Capacité des liens.

Les liaisons ne sont disponibles que pour les bases de données managées. Pour joindre une base de données externe, transmettez ses valeurs de connexion via des variables et des secrets ; voir Bases de données managées et externes. Les liens vers le stockage managé ne sont pas disponibles pour les services Compose ; fournissez plutôt à un service des identifiants S3 issus d’une clé d’accès via des variables et des secrets.

Un service Compose peut joindre un port d’une autre charge de travail, ou être joint par une autre, via un lien entre conteneurs : ajoutez-le dans le bloc Links de l’onglet Variables du projet avec Add link → Container et choisissez le service consommateur.

Dérive et dépannage

Opfield signale une dérive lorsque l’état d’exécution observé ne correspond plus à la révision active. Vérifiez l’opération en cours, la connectivité du nœud Docker, la capacité Compose, l’accès à la récupération des images, les journaux des services, les variables, les secrets et les diagnostics du démon avant de réessayer.

Ne réparez pas un projet géré en supprimant manuellement ses conteneurs enfants, ses réseaux ou les métadonnées de ses révisions. Pour un projet externe, effectuez les modifications de configuration via son processus Compose d’origine jusqu’à la fin de l’adoption.

Supprimer un projet

Démontez un projet géré et retirez les Routes ou liaisons dépendantes avant la suppression. La suppression d’un projet encore ciblé par une Route, une Additional Route ou un Additional Secure Link est refusée avec 409 PROXY_UPSTREAM_IN_USE avant toute suppression, et un projet doté de liens vers des bases de données est refusé avec 409 COMPOSE_DATABASE_BINDINGS_EXIST. La suppression d’un projet géré retire ses conteneurs, ses réseaux non externes, ses révisions, ses secrets et chaque volume qui porte les labels Docker Compose du projet, ce qui inclut les volumes nommés que Compose a créés pour le projet. Les ressources qui n’appartiennent pas au projet, comme les volumes créés séparément et déclarés external: true, ne sont pas supprimées. Sauvegardez les données persistantes avant la suppression. Les projets externes ne peuvent pas être supprimés depuis Opfield.

Détails pour l’opérateur : reprise des révisions

Avant d’appliquer une révision, comparez ses services, images, variables, secrets, volumes, réseaux et ports exposés avec la révision active. Consignez la migration propre à l’application et l’ordre de démarrage lorsque les services ne peuvent pas redémarrer ensemble sans danger. Pull & Apply peut remplacer l’exécution des services ; il ne garantit pas des connexions ininterrompues.

Si une opération est interrompue, attendez que le nœud Docker se reconnecte et actualisez l’état observé du projet avant de lancer une autre application. Utilisez les opérations récentes pour déterminer si la récupération des images, la préparation de la configuration, la création des services, la santé ou l’acquittement final a échoué. Lorsque la révision active est réputée saine et que la nouvelle révision ne convient pas, sélectionnez la révision antérieure avec Change revision et vérifiez le chemin applicatif complet.

Le retour arrière modifie la configuration et l’exécution Compose ; il n’annule pas les écritures effectuées dans des systèmes externes ou des volumes persistants. Les migrations de bases de données non rétrocompatibles nécessitent leur propre plan de reprise. Ne supprimez pas les conteneurs enfants ou les réseaux du projet pour forcer la convergence, car cela supprime des éléments de preuve et peut interférer avec le nettoyage géré.