Konfigurácia služby ako kód pomocou dockup.yaml: bezpečný plan a apply

dockup.yaml mení konfiguráciu služby na artefakt v repository, ktorý možno kontrolovať a pripomienkovať. Namiesto spoliehania sa na stav dashboardu, ktorý si niekto pamätá, môže tím v jednom súbore deklarovať branch, port, príkazy na build a spustenie, health checky, bežné environment values a domény.

Dockup oddeľuje kontrolu od zmien. dockup plan zobrazí rozdiel medzi manifestom a živou službou bez toho, aby čokoľvek zmenil. dockup up aplikuje deklarované zmeny. Odstránenie zostáva voliteľné a vyžaduje --prune.

Čo môže dockup.yaml deklarovať?

Manifest služby môže obsahovať produkčné nastavenia, ktorým prospieva 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 }

Súbor sa predvolene umiestňuje do koreňa repository. Inú cestu môžete zvoliť pomocou --file.

Do mapovania env nevkladajte secrets. Manifest sa commituje, kontroluje, cachuje a kopíruje rovnako ako ostatné source files. Na credentials použite dockup env set --secret alebo schválený proces injectovania secretov.

Spotreba CPU, RAM a disku sa naďalej účtuje podľa využitia a meria sa po minútach voči zostatku plánu; manifest by mal opisovať konfiguráciu služby, nie predpoklady týkajúce sa billing-u.

Ako dockup plan zobrazuje drift v konfigurácii?

Pred každým apply spustite porovnanie v režime read-only:

dockup plan production/api --json

Výsledok obsahuje zmeny s aspektmi, poľami, starými a novými hodnotami a akciami. Plan môže ukázať, že sa zmenil branch, líši sa health path, pridá sa doména alebo sa zmenila bežná environment value.

Plan je užitočný v piatich situáciách:

Situácia	Čo plan odhalí
Pull request mení manifest	Zamýšľaný vplyv na produkciu pred merge
Dashboard bol upravený manuálne	Drift oproti zdroju v repository
Agent navrhuje update	Presné polia, ktoré chce agent zmeniť
Obnova po incidente	Či sa živý stav už líši od známej konfigurácie
Nastavenie viacerých prostredí	Rozdiely medzi production a staging manifestmi

Plan službu nezamyká. Živý stav sa môže medzi plan a apply zmeniť, preto by rizikové workflow mali držať review a up čo najbližšie pri sebe a skontrolovať výsledok apply.

Coding agent by mal vrátiť JSON plánu alebo stručné zhrnutie po jednotlivých poliach. „Konfigurácia vyzerá dobre“ nie je dostatočný artefakt na review.

Ako dockup up aplikuje config as code?

Aplikujte predvolený manifest:

dockup up production/api --json

Aplikujte zmeny a následne spustite deployment:

dockup up production/api --deploy --json

Pre staging použite iný súbor:

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

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

Výsledok apply informuje o tom, ktoré zmeny boli aplikované alebo preskočené, a pri použití --deploy môže obsahovať ID deploymentu. Súvisiaci deployment by mal podľa potreby stále používať overenie terminálneho stavu; zmena konfigurácie a zdravý production release sú dva samostatné výsledky.

Hodnoty secretov zostávajú mimo manifestu. Pred aplikovaním konfigurácie ich nastavte prostredníctvom workflow pre secret environment, potom vykonajte deployment a overte výsledný container bez vypísania uloženej hodnoty.

Prečo je config as code predvolene aditívne?

Najbezpečnejšia interpretácia neúplného manifestu znie: „spravuj tieto deklarované hodnoty“, nie „vymaž všetko ostatné“. Dockup preto ponecháva environment variables a domény, ktoré v súbore chýbajú, nezmenené.

Je to dôležité pri postupnom zavádzaní. Služba už môže obsahovať secret variables, prevádzkové domény alebo dočasnú konfiguráciu, ktoré ešte neboli zapísané v manifeste. Prvé up by ich nemalo vymazať.

Bezpečnostné záruky sú konkrétne:

• dockup up nemaže služby, databázy ani volumes.
• Existujúce secret variables sa neprepíšu bežnými hodnotami z manifestu.
• Secret variables sa neprune-ujú.
• Automatické použitie manifestu počas deploymentu je aditívne.
• Neplatný manifest sa potichu nezmení na deštruktívne čistenie.

Aditívne správanie robí z dockup.yaml vhodný nástroj pre inkrementálne GitOps workflow. Zároveň to znamená, že manifest nie je automaticky úplným inventárom, pokiaľ tím zámerne nezavedie pruning pre podporované polia.

Ako by sa malo kontrolovať --prune?

--prune odstráni podporované bežné environment values a domény, ktoré v manifeste chýbajú:

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

Tento flag považujte za deštruktívnu požiadavku. Skontrolujte plan, uveďte presný cieľ a ak agent pracuje s produkciou, vyžiadajte si schválenie človekom.

Operácia sa nevzťahuje na secrets, služby, databázy ani volumes. Tieto resources majú vlastný lifecycle a vlastné cesty na potvrdenie. Toto oddelenie zabraňuje tomu, aby sa malá úprava manifestu zmenila na rozsiahle mazanie infraštruktúry.

Užitočný záznam o schválení znie: „Aplikujte dockup.yaml na production/api a prune-ujte dve bežné premenné a jednu doménu uvedené v plane X.“ Nemal by ísť o opakovane použiteľné všeobecné povolenie pre budúce plány.

Širší model potvrdzovania je opísaný v článku production guardrails pre AI agentov.

Ako tímy používajú GitOps workflow s dockup.yaml?

Udržujte workflow jednoduchý:

1. Developer alebo agent upraví dockup.yaml.
2. CI overí syntax YAML a aplikačné testy.
3. Nad zamýšľaným targetom sa spustí read-only dockup plan.
4. Pull request zobrazí source diff aj plan živého stavu.
5. Reviewer zmenu schváli.
6. dockup up --deploy ju aplikuje.
7. Deployment počká na úspešný terminálny stav.
8. Zachová sa status, logs a audit evidence.

Manifest by sa nemal stať odkladiskom všetkého. Business konfiguráciu aplikácie ponechajte v aplikácii, ak je to vhodné. dockup.yaml používajte pre deployment a runtime settings, za ktoré zodpovedá hranica služby.

Súbory špecifické pre jednotlivé prostredia môžu byť prehľadnejšie než jeden súbor s nedokumentovanou templating vrstvou. Použite napríklad dockup.staging.yaml a dockup.production.yaml a zamýšľaný súbor odovzdajte explicitne.

Branch preview je izolovaný deployment, zatiaľ čo production konfigurácia zostáva samostatným targetom na review. V projektoch s private networking sa previews môžu pripojiť do projektovej siete a získať read-only prístup k databáze bez zmeny production manifestu.

Pri práci s credentials použite príručku k environment variables a secretom a pri readiness gate si prečítajte deploymenty bez výpadku.

Playbook pre riešenie driftu

Keď dockup plan nahlási neočakávané zmeny v živom stave, neprepisujte ich automaticky. Zistite, či úprava v dashboarde bola núdzovou opravou, neoprávnenou zmenou alebo zamýšľaným nastavením, ktoré sa nikdy necommitlo.

Potom vyberte jeden source of truth:

• Aktualizujte manifest, aby zachoval zamýšľanú hodnotu v živom stave.
• Aplikujte manifest a obnovte skontrolovanú hodnotu.
• Zdokumentujte dočasnú výnimku s vlastníkom a dátumom expirácie.
• Ak pôvod nie je známy, preskúmajte audit log.

dockup audit --writes --json

Tento proces udržiava dockup.yaml ako autoritatívny zdroj bez vymazania kontextu incidentu.

Referenčná príručka Dockup CLI je zdrojom aktuálnych polí manifestu a možností plan/up.

Navrhujte zmeny manifestu, ktoré sa dajú kontrolovať

Každú zmenu udržujte dostatočne malú na to, aby mal plan jeden jasný účel. Kombinovať zmenu branchu, navýšenie resources, novú doménu, úpravu health checku a čistenie environmentu v jednom pull requeste sťažuje review aj rollback.

Na vysvetlenie nezvyčajných hodnôt používajte comments, ale neduplikujte v súbore prevádzkovú dokumentáciu. Runbook repository prepojte s targetom služby, významom health checku a schvaľovacou politikou. Manifest by mal zostať platným YAML, ktorý možno parsovať bez custom preprocessora.

Užitočná šablóna pull requestu si vyžiada výstup dockup plan --json, očakávaný vplyv na deployment, informáciu, či sa požaduje --prune, a ID predchádzajúceho deploymentu. Agent AI aj human reviewer tak dostanú rovnaké podklady.

Zaveďte manifest bez narušenia živého stavu

Pri existujúcej službe začnite poľami, ktoré dokážete overiť. Spustite dockup info production/api --json, vytvorte minimálny dockup.yaml a porovnajte ho pomocou dockup plan. Nastavenia pridávajte po etapách namiesto toho, aby ste sa naraz pokúšali zrekonštruovať každú historickú voľbu z dashboardu.

Keďže apply je aditívny, nespravované bežné hodnoty a domény zostávajú zachované, kým prebieha adopcia. Keď manifest začne presne reprezentovať zamýšľanú non-secret konfiguráciu, rozhodnite sa, či tím niekedy použije pruning. Niektoré tímy ponechávajú cleanup na manuálne vykonanie, iné povoľujú --prune iba v chránenom pipeline po schválení plánu.

Cieľom config as code nie je maximalizovať počet riadkov v Git-e. Ide o to, aby bol produkčný zámer zrozumiteľný, kontrolovateľný a obnoviteľný.

Udržiavajte plány bez secret materiálu

Plan by malo byť bezpečné priložiť k pull requestu alebo záznamu o incidente. Keďže dockup.yaml obsahuje iba bežné hodnoty a existujúce secret values zostávajú chránené, revieweri môžu kontrolovať zamýšľanú konfiguráciu bez získania production credentials. Bežné hodnoty však stále kontrolujte kvôli interným hostname, identifikátorom zákazníkov alebo iným údajom, ktoré by nemali byť verejné.

Udržujte source a target spolu

V pull requeste a deployment jobe uveďte zamýšľaný project/service. Platný dockup.yaml aplikovaný na nesprávny target je stále prevádzkové zlyhanie. Discovery targetu a review manifestu sú dve samostatné povinné kontroly.

Pred plan overte YAML

Pred volaním Dockup parsujte manifest v CI, aby chyby v odsadení alebo typoch zlyhali čo najbližšie pri source change. Validácia syntaxe nenahrádza dockup plan; zabráni zbytočným requestom s nečitateľným súborom.

Uprednostnite jeden source

Skontrolovaný dockup.yaml by mal vysvetľovať produkčný zámer.

Začnite s overiteľným deploymentom

Pridajte minimálny manifest k jednej službe, spustite read-only plan a pred prvým apply skontrolujte každé nahlásené pole.

Začnite bezplatne na app.dockup.ai. Plán Free stojí $0 mesačne, obsahuje úvodný kredit $10 a podporuje jeden workspace, tri databázy a tri deploymenty.

FAQ

Čo je dockup.yaml?

Je to manifest Dockup typu config as code na deklarovanie branchu služby, portu, nastavení buildu a spustenia, health checkov, bežných environment values a domén.

Mení dockup plan produkciu?

Nie. dockup plan je read-only a zobrazuje rozdiel medzi manifestom a živou službou.

Maže dockup up konfiguráciu, ktorá nie je v súbore?

Predvolene nie. Apply je aditívny. Podporované bežné environment values a domény sa odstránia iba pri explicitnom použití --prune.

Môžu byť secrets uložené v dockup.yaml?

Nemali by byť. Commitujte iba bežné hodnoty; secrets nastavujte pomocou secret environment príkazu alebo runtime secret injection. Existujúce secrets sú chránené pred pruningom.

Môže dockup up po aplikovaní konfigurácie spustiť deployment?

Áno. Zdokumentovaná možnosť --deploy aplikuje manifest a spustí deployment, ktorého terminálny výsledok by sa následne mal overiť.