Serviceconfiguratie beheren met dockup.yaml: veilig plannen en toepassen

dockup.yaml maakt van serviceconfiguratie een repository-artifact dat eenvoudig kan worden gereviewd. In plaats van te vertrouwen op de onthouden status van een dashboard, kan een team branch, poort, build- en startcommando's, health checks, gewone environmentwaarden en domeinen in één bestand vastleggen.

Dockup scheidt inspectie van wijzigingen. dockup plan toont het verschil tussen het manifest en de actieve service zonder iets te wijzigen. dockup up past de gedeclareerde wijzigingen toe. Verwijderen blijft opt-in via --prune.

Wat kan dockup.yaml declareren?

Een servicemanifest kan de productie-instellingen bevatten die baat hebben bij 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 }

Het bestand wordt standaard in de root van de repository geplaatst. Met --file kun je een ander pad selecteren.

Plaats geen secrets in de env-mapping. Het manifest wordt net als andere sourcebestanden gecommit, gereviewd, gecachet en gekopieerd. Gebruik dockup env set --secret of een goedgekeurd proces voor secretinjectie.

Het CPU-, RAM- en schijfverbruik blijft usage-based en wordt per minuut verrekend met het plansaldo; het manifest moet serviceconfiguratie beschrijven, niet aannames over facturering.

Hoe toont dockup plan configuratiedrift?

Voer vóór elke apply een alleen-lezenvergelijking uit:

dockup plan production/api --json

Het resultaat bevat wijzigingen met aspecten, velden, oude waarden, nieuwe waarden en acties. Een plan kan laten zien dat de branch is gewijzigd, dat een health-pad afwijkt, dat een domein wordt toegevoegd of dat een gewone environmentwaarde is veranderd.

Een plan is waardevol in vijf situaties:

Situatie	Wat het plan laat zien
Een pull request wijzigt het manifest	Het beoogde effect op productie vóór de merge
Het dashboard is handmatig aangepast	Drift ten opzichte van de bron in de repository
Een agent stelt een update voor	De exacte velden die de agent wil wijzigen
Herstel na een incident	Of de actieve status al afwijkt van de bekende configuratie
Multi-environmentconfiguratie	Verschillen tussen productie- en staging-manifesten

Plannen vergrendelen de service niet. De actieve status kan tussen plan en apply veranderen. Risicovolle workflows moeten de review en up daarom kort na elkaar uitvoeren en het resultaat van de apply controleren.

Een coding agent moet de plan-JSON of een beknopt overzicht per veld teruggeven. “De configuratie ziet er goed uit” is geen toereikend review-artifact.

Hoe past dockup up config as code toe?

Pas het standaardmanifest toe:

dockup up production/api --json

Pas het manifest toe en start daarna een deployment:

dockup up production/api --deploy --json

Gebruik een ander bestand voor staging:

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

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

Het apply-resultaat vermeldt welke wijzigingen zijn toegepast of overgeslagen en kan de deployment-ID bevatten wanneer --deploy wordt gebruikt. De omliggende deployment moet waar nodig nog steeds worden gecontroleerd op de terminale status; een configuratiewijziging en een gezonde productierelease zijn afzonderlijke uitkomsten.

Secretwaarden blijven buiten het manifest. Stel ze in via de secret-environmentworkflow voordat je de configuratie toepast, en deploy en controleer daarna de resulterende container zonder de opgeslagen waarde af te drukken.

Waarom is config as code standaard additive?

De veiligste interpretatie van een onvolledig manifest is: “beheer deze gedeclareerde waarden”, niet: “verwijder al het andere”. Daarom laat Dockup environmentvariabelen en domeinen die niet in het bestand staan ongewijzigd.

Dit is belangrijk bij een geleidelijke invoering. Een service kan al secretvariabelen, operationele domeinen of tijdelijke configuratie bevatten die nog niet in kaart is gebracht. De eerste up mag deze niet wissen.

De veiligheidswaarborgen zijn specifiek:

• dockup up verwijdert geen services, databases of volumes.
• Bestaande secretvariabelen worden niet overschreven door gewone manifestwaarden.
• Secretvariabelen worden niet gepruned.
• Automatische toepassing van het manifest tijdens deploy is additive.
• Een ongeldig manifest wordt niet stilzwijgend geïnterpreteerd als destructieve cleanup.

Additive gedrag maakt dockup.yaml geschikt voor een incrementele GitOps-workflow. Het betekent ook dat het manifest niet automatisch een volledige inventaris is, tenzij het team bewust pruning invoert voor ondersteunde velden.

Hoe moet je --prune reviewen?

--prune verwijdert ondersteunde gewone environmentwaarden en domeinen die niet in het manifest staan:

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

Behandel de flag als een destructief verzoek. Review het plan, benoem het exacte doel en vraag menselijke goedkeuring wanneer een agent op productie werkt.

De bewerking geldt niet voor secrets, services, databases of volumes. Deze resources hebben hun eigen lifecycle en bevestigingsproces. Door die scheiding kan een kleine wijziging in het manifest niet leiden tot grootschalige verwijdering van infrastructuur.

Een bruikbaar goedkeuringsrecord zegt: “Pas dockup.yaml toe op production/api en prune de twee gewone variabelen en het ene domein dat in plan X wordt getoond.” Het mag geen algemene toestemming zijn die herbruikbaar is voor toekomstige plannen.

Het bredere bevestigingsmodel wordt besproken in productiebeveiligingsmaatregelen voor AI-agents.

Hoe gebruiken teams een GitOps-workflow met dockup.yaml?

Houd de workflow eenvoudig:

1. Een developer of agent bewerkt dockup.yaml.
2. CI valideert de YAML-syntaxis en applicatietests.
3. Er wordt een alleen-lezendockup plan uitgevoerd tegen het beoogde doel.
4. De pull request toont zowel de bronwijziging als het plan voor de actieve status.
5. Een reviewer keurt de wijziging goed.
6. dockup up --deploy past de wijziging toe.
7. De deploy wacht op terminale success.
8. Status, logs en auditbewijs worden bewaard.

Het manifest mag geen vergaarbak worden. Bewaar applicatiegerichte businessconfiguratie waar passend in de applicatie. Gebruik dockup.yaml voor deployment- en runtime-instellingen die onder de verantwoordelijkheid van de service vallen.

Omgevingsspecifieke bestanden zijn soms duidelijker dan één bestand met een niet-gedocumenteerde templatinglaag. Gebruik bijvoorbeeld dockup.staging.yaml en dockup.production.yaml, en geef het beoogde bestand expliciet mee.

Een branch-preview is een geïsoleerde deployment, terwijl de productieconfiguratie een afzonderlijk reviewdoel blijft. In projecten met private networking kunnen previews deelnemen aan het projectnetwerk en read-only toegang tot databases krijgen zonder het productiemanifest te wijzigen.

Gebruik de gids voor environmentvariabelen en secrets voor credentialbeheer en zero-downtime deployments voor de readiness gate.

Draaiboek voor het afhandelen van drift

Wanneer dockup plan onverwachte wijzigingen in de actieve omgeving meldt, moet je ze niet automatisch overschrijven. Bepaal of de dashboardwijziging een noodoplossing, een ongeautoriseerde wijziging of een beoogde instelling was die nooit is gecommit.

Kies vervolgens één bron van waarheid:

• Werk het manifest bij om de beoogde actieve waarde te behouden.
• Pas het manifest toe om de gereviewde waarde te herstellen.
• Documenteer een tijdelijke uitzondering met een eigenaar en vervaldatum.
• Onderzoek het auditlog wanneer de oorsprong onbekend is.

dockup audit --writes --json

Zo blijft dockup.yaml leidend zonder de context van het incident te wissen.

De Dockup CLI-referentie is de bron voor de actuele manifestvelden en opties voor plan/up.

Ontwerp manifestwijzigingen die eenvoudig te reviewen zijn

Houd elke wijziging klein genoeg om het plan één duidelijk doel te geven. Een branchwijziging, resourceverhoging, nieuw domein, aangepaste health check en environmentcleanup in één pull request combineren maakt zowel review als rollback lastiger.

Gebruik comments om ongebruikelijke waarden toe te lichten, maar dupliceer operationele documentatie niet in het bestand. Link vanuit de repository-runbook naar het servicetarget, de health-semantiek en het goedkeuringsbeleid. Het manifest moet geldige YAML blijven die zonder een custom preprocessor kan worden geparsed.

Een bruikbaar pull-requesttemplate vraagt om de uitvoer van dockup plan --json, het verwachte deploymenteffect, of --prune wordt aangevraagd en de vorige deployment-ID. Zo beschikt een AI-agent of menselijke reviewer over hetzelfde bewijs.

Introduceer het manifest zonder de actieve status te verstoren

Begin bij een bestaande service met de velden die je kunt verifiëren. Voer dockup info production/api --json uit, schrijf een minimaal dockup.yaml en vergelijk dit met dockup plan. Voeg instellingen gefaseerd toe in plaats van alle historische dashboardkeuzes in één keer te reconstrueren.

Omdat apply additive is, blijven niet-beheerde gewone waarden en domeinen behouden tijdens de invoering. Zodra het manifest de beoogde niet-geheime configuratie correct weergeeft, bepaal je of het team ooit pruning zal gebruiken. Sommige teams houden cleanup handmatig; andere staan --prune alleen toe in een beschermde pipeline na goedkeuring van het plan.

Het doel van config as code is niet om het aantal regels in Git te maximaliseren. Het doel is productie-intentie begrijpelijk, reviewbaar en herstelbaar te maken.

Houd plannen vrij van secretmateriaal

Een plan moet veilig aan een pull request of incidentregistratie kunnen worden toegevoegd. Omdat dockup.yaml alleen gewone waarden bevat en bestaande secretwaarden beschermd blijven, kunnen reviewers de beoogde configuratie inspecteren zonder productiecredentials te ontvangen. Controleer gewone waarden nog steeds op interne hostnames, klant-ID's of andere gegevens die niet openbaar mogen worden.

Houd bron en doel bij elkaar

Vermeld het beoogde project/service in de pull request en deploymentjob. Een geldig dockup.yaml dat op het verkeerde doel wordt toegepast, is nog steeds een operationele fout. Target discovery en manifestreview zijn twee afzonderlijke, verplichte controles.

Valideer YAML vóór plan

Parse het manifest in CI voordat je Dockup aanroept, zodat fouten in inspringing of typen dicht bij de bronwijziging falen. Syntaxisvalidatie vervangt dockup plan niet; ze voorkomt vermijdbare requests met een onleesbaar bestand.

Geef de voorkeur aan één bron

Een gereviewd dockup.yaml moet de productie-intentie uitleggen.

Begin met een verifieerbare deployment

Voeg een minimaal manifest toe aan één service, voer een alleen-lezenplan uit en review elk gerapporteerd veld vóór de eerste apply.

Start gratis op app.dockup.ai. Het Free-plan kost $0 per maand, bevat $10 starttegoed en ondersteunt één workspace, drie databases en drie deployments.

FAQ

Wat is dockup.yaml?

Het is het config-as-code-manifest van Dockup voor het declareren van de servicebranch, poort, build- en startinstellingen, health checks, gewone environmentwaarden en domeinen.

Wijzigt dockup plan de productie?

Nee. dockup plan is alleen-lezen en toont het verschil tussen het manifest en de actieve service.

Verwijdert dockup up configuratie die niet in het bestand staat?

Niet standaard. Apply is additive. Ondersteunde gewone environmentwaarden en domeinen worden alleen verwijderd wanneer --prune expliciet wordt gebruikt.

Kunnen secrets in dockup.yaml worden opgeslagen?

Dat wordt afgeraden. Commit alleen gewone waarden; stel secrets in via het secret-environmentcommando of runtime-secretinjectie. Bestaande secrets zijn beschermd tegen pruning.

Kan dockup up na het toepassen van de configuratie deployen?

Ja. De gedocumenteerde optie --deploy past het manifest toe en start een deployment, waarvan je vervolgens de terminale status moet verifiëren.