Configuration as Code avec dockup.yaml : planifier et appliquer en toute sécurité

dockup.yaml transforme la configuration d’un service en un artefact du repository qui peut être relu et révisé. Plutôt que de dépendre de l’état mémorisé d’un dashboard, une équipe peut déclarer dans un même fichier la branche, le port, les commandes de build et de démarrage, les health checks, les variables d’environnement ordinaires et les domaines.

Dockup sépare l’inspection de la modification. dockup plan affiche les différences entre le manifest et le service en production sans rien modifier. dockup up applique les changements déclarés. La suppression reste soumise à une activation explicite via --prune.

Que peut déclarer dockup.yaml ?

Un manifest de service peut contenir les paramètres de production qui gagnent à être soumis à une code review :

service:
  branch: main
  port: 3000
  dockerfile: Dockerfile
  build: npm run build
  start: npm start
  healthcheck:
    path: /health
    interval: 5
    timeout: 3
    retries: 5
  env:
    NODE_ENV: production
    API_URL: https://api.example.com
  domains:
    - api.example.com
    - { domain: admin.example.com, port: 4000 }

Par défaut, le fichier est placé à la racine du repository. Vous pouvez sélectionner un autre chemin avec --file.

Ne placez pas de secrets dans le mapping env. Le manifest est commité, révisé, mis en cache et copié comme les autres fichiers source. Utilisez dockup env set --secret ou un processus approuvé d’injection des secrets pour les identifiants.

La consommation de CPU, de RAM et de disque reste basée sur l’usage et est mesurée à la minute en fonction du solde du plan ; le manifest doit décrire la configuration du service plutôt que des hypothèses de facturation.

Comment dockup plan permet-il d’identifier la configuration qui a dérivé ?

Exécutez une comparaison en lecture seule avant chaque application :

dockup plan production/api --json

Le résultat contient les changements, avec leurs aspects, leurs champs, les anciennes et nouvelles valeurs, ainsi que les actions à effectuer. Un plan peut indiquer que la branche a changé, que le chemin du health check diffère, qu’un domaine sera ajouté ou qu’une valeur d’environnement non secrète a dérivé.

Un plan est particulièrement utile dans cinq situations :

Situation	Ce que révèle le plan
La pull request modifie le manifest	L’effet attendu sur la production avant la fusion
Le dashboard a été modifié manuellement	La dérive par rapport à la source du repository
Un agent propose une mise à jour	Les champs exacts que l’agent souhaite modifier
Récupération après un incident	Si l’état réel diffère déjà de la configuration connue
Configuration multi-environnements	Les différences entre les manifests de production et de staging

La planification ne verrouille pas le service. L’état réel peut changer entre le plan et l’application ; les workflows à haut risque doivent donc maintenir la review et up rapprochés dans le temps et examiner le résultat de l’application.

Un agent de coding doit renvoyer le JSON du plan ou un résumé concis champ par champ. « La configuration semble correcte » ne constitue pas un artefact de review suffisant.

Comment dockup up applique-t-il la config as code ?

Appliquez le manifest par défaut :

dockup up production/api --json

Appliquez le manifest, puis déclenchez un déploiement :

dockup up production/api --deploy --json

Utilisez un autre fichier pour staging :

dockup plan production/api \
  --file dockup.production.yaml \
  --json

dockup up production/api \
  --file dockup.production.yaml \
  --deploy \
  --json

Le résultat de l’application indique les changements appliqués ou ignorés et peut inclure l’ID du déploiement lorsque --deploy est utilisé. Le déploiement qui suit doit néanmoins utiliser une vérification de l’état terminal lorsque cela est pertinent ; une modification de configuration et une release saine en production sont deux résultats distincts.

Les valeurs secrètes restent en dehors du manifest. Définissez-les via le workflow d’environnement secret avant d’appliquer la configuration, puis déployez et vérifiez le conteneur obtenu sans afficher la valeur enregistrée.

Pourquoi la config as code est-elle additive par défaut ?

L’interprétation la plus sûre d’un manifest incomplet est « gérer les valeurs déclarées », et non « tout supprimer ». Dockup laisse donc inchangés les variables d’environnement et les domaines absents du fichier.

C’est important lors d’une adoption progressive. Un service peut déjà contenir des variables secrètes, des domaines opérationnels ou une configuration temporaire qui n’a pas encore été modélisée. Le premier up ne doit pas les supprimer.

Les garanties de sécurité sont les suivantes :

• dockup up ne supprime ni services, ni bases de données, ni volumes.
• Les variables secrètes existantes ne sont pas écrasées par des valeurs non secrètes du manifest.
• Les variables secrètes ne sont pas supprimées par prune.
• L’application automatique du manifest pendant un déploiement est additive.
• Un manifest invalide ne se transforme pas silencieusement en nettoyage destructif.

Le comportement additif rend dockup.yaml adapté à un workflow GitOps progressif. Cela signifie également que le manifest ne constitue pas automatiquement un inventaire exhaustif, sauf si l’équipe adopte délibérément le pruning pour les champs pris en charge.

Comment réviser --prune ?

--prune supprime les valeurs d’environnement non secrètes et les domaines pris en charge qui sont absents du manifest :

dockup plan production/api --json
dockup up production/api --prune --json

Considérez ce flag comme une demande destructive. Révisez le plan, indiquez précisément la cible et obtenez une validation humaine lorsqu’un agent intervient sur la production.

L’opération ne s’étend pas aux secrets, aux services, aux bases de données ni aux volumes. Ces ressources ont leur propre cycle de vie et leurs propres parcours de confirmation. Cette séparation empêche une petite modification du manifest de se transformer en suppression étendue de l’infrastructure.

Un enregistrement d’approbation utile indique : « Appliquer dockup.yaml à production/api et supprimer les deux variables non secrètes et le domaine affichés dans le plan X. » Il ne doit pas constituer une autorisation générale réutilisable pour les plans futurs.

Le modèle général de confirmation est présenté dans les garde-fous de production pour les agents IA.

Comment les équipes mettent-elles en place un workflow GitOps avec dockup.yaml ?

Gardez le workflow simple :

1. Un développeur ou un agent modifie dockup.yaml.
2. La CI valide la syntaxe YAML et les tests de l’application.
3. Un dockup plan en lecture seule s’exécute sur la cible prévue.
4. La pull request affiche à la fois le diff source et le plan de l’état réel.
5. Un reviewer approuve le changement.
6. dockup up --deploy l’applique.
7. Le déploiement attend une réussite à l’état terminal.
8. Le statut, les logs et les éléments de preuve d’audit sont conservés.

Le manifest ne doit pas devenir un fourre-tout. Conservez la configuration métier de l’application dans l’application lorsque cela est pertinent. Utilisez dockup.yaml pour les paramètres de déploiement et d’exécution dont le service est responsable.

Des fichiers propres à chaque environnement peuvent être plus clairs qu’un fichier unique associé à une couche de templating non documentée. Par exemple, utilisez dockup.staging.yaml et dockup.production.yaml, puis transmettez explicitement le fichier souhaité.

Une preview de branche est un déploiement isolé, tandis que la configuration de production reste une cible de review distincte. Dans les projets utilisant un réseau privé, les previews peuvent rejoindre le réseau du projet et recevoir un accès en lecture seule à la base de données sans modifier le manifest de production.

Consultez le guide des variables d’environnement et des secrets pour la gestion des identifiants et les déploiements sans interruption pour la readiness gate.

Runbook de réponse aux dérives

Lorsque dockup plan signale des changements inattendus dans l’état réel, ne les écrasez pas automatiquement. Déterminez si la modification du dashboard était une correction d’urgence, une modification non autorisée ou un paramètre souhaité qui n’a jamais été commité.

Choisissez ensuite une source de vérité :

• Mettez à jour le manifest pour conserver la valeur réelle souhaitée.
• Appliquez le manifest pour restaurer la valeur révisée.
• Documentez une exception temporaire avec un responsable et une date d’expiration.
• Examinez l’audit log lorsque l’origine est inconnue.

dockup audit --writes --json

Ce processus maintient dockup.yaml comme source d’autorité sans effacer le contexte de l’incident.

La référence de la CLI Dockup constitue la source de référence pour les champs actuels du manifest et les options de plan/up.

Concevoir des changements de manifest faciles à réviser

Gardez chaque changement suffisamment ciblé pour que le plan ait un objectif clair. Combiner une modification de branche, une augmentation des ressources, un nouveau domaine, une réécriture du health check et un nettoyage de l’environnement dans une seule pull request complique à la fois la review et le rollback.

Utilisez des commentaires pour expliquer les valeurs inhabituelles, mais ne dupliquez pas la documentation opérationnelle dans le fichier. Reliez le runbook du repository à la cible du service, à la sémantique du health check et à la politique d’approbation. Le manifest doit rester un YAML valide, analysable sans preprocessor personnalisé.

Un template de pull request utile demande la sortie de dockup plan --json, l’effet attendu sur le déploiement, si --prune est demandé et l’ID du déploiement précédent. Un agent IA ou un reviewer humain dispose ainsi des mêmes éléments de preuve.

Introduire le manifest sans perturber l’état réel

Pour un service existant, commencez par les champs que vous pouvez vérifier. Exécutez dockup info production/api --json, écrivez un dockup.yaml minimal et comparez-le avec dockup plan. Ajoutez les paramètres par étapes plutôt que d’essayer de reconstituer d’un coup tous les choix historiques du dashboard.

Comme l’application est additive, les valeurs non secrètes et les domaines non gérés restent en place pendant l’adoption. Une fois que le manifest représente correctement la configuration non secrète souhaitée, décidez si l’équipe utilisera un jour le pruning. Certaines équipes gardent le nettoyage manuel ; d’autres n’autorisent --prune que dans une pipeline protégée après approbation du plan.

L’objectif de la config as code n’est pas de maximiser le nombre de lignes dans Git. Il est de rendre l’intention de production compréhensible, révisable et récupérable.

Garder les plans exempts de données secrètes

Un plan doit pouvoir être joint à une pull request ou à un dossier d’incident en toute sécurité. Comme dockup.yaml ne contient que des valeurs non secrètes et que les valeurs secrètes existantes restent protégées, les reviewers peuvent examiner la configuration souhaitée sans recevoir les identifiants de production. Vérifiez toutefois les valeurs ordinaires afin d’identifier les hostnames internes, les identifiants client ou toute autre donnée qui ne devrait pas être publique.

Garder la source et la cible ensemble

Indiquez le project/service ciblé dans la pull request et le job de déploiement. Un dockup.yaml valide appliqué à la mauvaise cible reste un incident opérationnel. La découverte de la cible et la review du manifest sont deux vérifications obligatoires distinctes.

Valider le YAML avant le plan

Analysez le manifest dans la CI avant d’appeler Dockup afin que les erreurs d’indentation ou de type échouent au plus près de la modification source. La validation de syntaxe ne remplace pas dockup plan ; elle évite les requêtes inutiles avec un fichier illisible.

Préférer une source unique

Un dockup.yaml révisé doit exprimer l’intention de production.

Commencer par un déploiement vérifiable

Ajoutez un manifest minimal à un service, exécutez un plan en lecture seule et examinez chaque champ signalé avant la première application.

Commencez gratuitement sur app.dockup.ai. Le plan Free coûte 0 $ par mois, comprend un crédit initial de 10 $ et prend en charge un workspace, trois bases de données et trois déploiements.

FAQ

Qu’est-ce que dockup.yaml ?

Il s’agit du manifest de config as code de Dockup, qui permet de déclarer la branche et le port du service, les paramètres de build et de démarrage, les health checks, les valeurs d’environnement non secrètes et les domaines.

dockup plan modifie-t-il la production ?

Non. dockup plan est en lecture seule et affiche les différences entre le manifest et le service réel.

dockup up supprime-t-il les éléments de configuration absents du fichier ?

Pas par défaut. L’application est additive. Les valeurs d’environnement non secrètes et les domaines pris en charge ne sont supprimés que lorsque --prune est utilisé explicitement.

Les secrets peuvent-ils être stockés dans dockup.yaml ?

Ils ne devraient pas l’être. Commitez uniquement les valeurs non secrètes ; définissez les secrets via la commande d’environnement secret ou l’injection de secrets à l’exécution. Les secrets existants sont protégés contre le pruning.

dockup up peut-il déployer après l’application de la configuration ?

Oui. L’option documentée --deploy applique le manifest et déclenche un déploiement, dont le résultat à l’état terminal doit ensuite être vérifié.