Konfigurace jako kód v dockup.yaml: bezpečné plánování a aplikace

dockup.yaml převádí konfiguraci služby na artefakt v repository, který lze kontrolovat a připomínkovat. Místo spoléhání na stav dashboardu, který si někdo pamatuje, může tým v jednom souboru deklarovat branch, port, příkazy pro build a spuštění, health checky, běžné hodnoty prostředí a domény.

Dockup odděluje inspekci od změn. dockup plan zobrazí rozdíl mezi manifestem a běžící službou, aniž by cokoli měnil. dockup up deklarované změny aplikuje. Mazání zůstává volitelné a vyžaduje --prune.

Co může dockup.yaml deklarovat?

Manifest služby může obsahovat produkční nastavení, u kterých je užitečný 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 }

Soubor se ve výchozím nastavení umisťuje do kořene repository. Jinou cestu lze zvolit pomocí --file.

Do mapování env nevkládejte secrets. Manifest se commitují, kontrolují, cachují a kopírují stejně jako ostatní zdrojové soubory. Pro credentials použijte dockup env set --secret nebo schválený proces injection secrets.

Spotřeba CPU, RAM a disku se i nadále řídí skutečným využitím a měří se po minutách proti kreditu plánu; manifest by měl popisovat konfiguraci služby, nikoli předpoklady týkající se účtování.

Jak dockup plan zobrazí drift konfigurace?

Před každým apply spusťte porovnání pouze pro čtení:

dockup plan production/api --json

Výsledek obsahuje změny s jejich aspekty, poli, starými a novými hodnotami a akcemi. Plan může ukázat, že se změnila branch, liší se health path, bude přidána doména nebo došlo k driftu běžné hodnoty prostředí.

Plan je cenný v těchto situacích:

Situace	Co plan odhalí
Pull request mění manifest	Zamýšlený dopad na produkci před mergem
Dashboard byl upraven ručně	Drift oproti zdroji v repository
Agent navrhuje update	Přesná pole, která chce agent změnit
Obnova po incidentu	Zda se aktuální stav již liší od známé konfigurace
Nastavení více prostředí	Rozdíly mezi production a staging manifesty

Plánování službu nezamyká. Stav se může mezi plan a apply změnit, proto by u workflow s vysokým rizikem měla kontrola a up následovat co nejdříve po sobě a výsledek apply je třeba zkontrolovat.

Coding agent by měl vrátit JSON plánu nebo stručné shrnutí po jednotlivých polích. „Konfigurace vypadá dobře“ není dostatečný podklad pro review.

Jak dockup up aplikuje konfiguraci jako kód?

Aplikujte výchozí manifest:

dockup up production/api --json

Proveďte apply a následně spusťte deployment:

dockup up production/api --deploy --json

Pro staging použijte jiný soubor:

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

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

Výsledek apply informuje o tom, které změny byly aplikovány nebo přeskočeny, a při použití --deploy může obsahovat ID deploymentu. Navazující deployment by měl podle potřeby stále používat ověření koncového stavu; změna konfigurace a zdravé produkční vydání jsou dva oddělené výsledky.

Hodnoty secrets zůstávají mimo manifest. Před aplikací konfigurace je nastavte prostřednictvím workflow pro secret environment, poté proveďte deploy a ověřte výsledný kontejner, aniž byste vypsali uloženou hodnotu.

Proč je konfigurace jako kód ve výchozím nastavení aditivní?

Nejbezpečnější interpretací neúplného manifestu je „spravuj tyto deklarované hodnoty“, nikoli „všechno ostatní smaž“. Dockup proto ponechává beze změny environment variables a domény, které v souboru chybí.

To je důležité při postupném zavádění. Služba již může obsahovat secret variables, provozní domény nebo dočasnou konfiguraci, které zatím nebyly zaneseny do manifestu. První up by je neměl odstranit.

Bezpečnostní záruky jsou konkrétní:

• dockup up nemaže služby, databáze ani volumes.
• Stávající secret variables nejsou přepsány běžnými hodnotami z manifestu.
• Secret variables se neprunují.
• Automatická aplikace manifestu během deploy je aditivní.
• Neplatný manifest se tiše nezmění v destruktivní cleanup.

Aditivní chování činí dockup.yaml vhodným pro inkrementální GitOps workflow. Zároveň to znamená, že manifest není automaticky úplným inventářem, pokud tým záměrně nezavede pruning pro podporovaná pole.

Jak by se mělo reviewovat --prune?

--prune odstraní podporované běžné hodnoty prostředí a domény, které v manifestu chybí:

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

Tento flag považujte za destruktivní požadavek. Zkontrolujte plan, přesně uveďte cíl a pokud agent pracuje s produkcí, vyžádejte si schválení člověkem.

Operace se netýká secrets, služeb, databází ani volumes. Tyto resources mají vlastní lifecycle a procesy pro potvrzení. Toto oddělení brání tomu, aby se malá změna manifestu změnila v rozsáhlé smazání infrastruktury.

Užitečný záznam o schválení zní: „Aplikovat dockup.yaml na production/api a prunovat dvě běžné proměnné a jednu doménu uvedené v plánu X.“ Neměl by představovat obecné oprávnění použitelné pro budoucí plány.

Širší model potvrzování popisuje článek ochranná opatření pro AI agenty v produkci.

Jak týmy používají GitOps workflow s dockup.yaml?

Udržujte workflow jednoduché:

1. Developer nebo agent upraví dockup.yaml.
2. CI ověří syntaxi YAML a aplikační testy.
3. Nad zamýšleným cílem se spustí dockup plan pouze pro čtení.
4. Pull request zobrazí diff zdrojových souborů i plan aktuálního stavu.
5. Reviewer změnu schválí.
6. dockup up --deploy ji aplikuje.
7. Deployment počká na úspěšný koncový stav.
8. Stav, logy a auditní podklady se uchovají.

Manifest by se neměl stát odkladištěm. Konfiguraci aplikační business logiky ponechte podle potřeby v aplikaci. dockup.yaml používejte pro deployment a runtime nastavení, za která odpovídá hranice služby.

Soubory specifické pro jednotlivá prostředí mohou být přehlednější než jeden soubor s nedokumentovanou templating vrstvou. Použijte například dockup.staging.yaml a dockup.production.yaml a zamýšlený soubor předejte explicitně.

Branch preview je izolovaný deployment, zatímco produkční konfigurace zůstává samostatným cílem pro review. V projektech s private networking se mohou preview deployments připojit k projektové síti a získat read-only přístup k databázi, aniž by měnily produkční manifest.

Pro práci s credentials použijte průvodce environment variables a secrets a pro readiness gate článek o zero-downtime deploymentech.

Playbook pro řešení driftu

Když dockup plan nahlásí neočekávané změny aktuálního stavu, nepřepisujte je automaticky. Zjistěte, zda byla úprava v dashboardu nouzovou opravou, neoprávněnou změnou nebo zamýšleným nastavením, které nikdy nebylo commitováno.

Poté zvolte jeden zdroj pravdy:

• Aktualizujte manifest, aby zachoval zamýšlenou aktuální hodnotu.
• Aplikujte manifest a obnovte kontrolovanou hodnotu.
• Zdokumentujte dočasnou výjimku s vlastníkem a datem vypršení.
• Pokud není původ známý, prošetřete audit log.

dockup audit --writes --json

Tento proces udržuje dockup.yaml jako autoritativní zdroj, aniž by mazal kontext incidentu.

Referenční dokumentace Dockup CLI je zdrojem aktuálních polí manifestu a voleb plan/up.

Navrhujte změny manifestu tak, aby se dobře reviewovaly

Každou změnu udržujte dostatečně malou, aby měl plan jeden jasný účel. Kombinace změny branch, navýšení resources, nové domény, úpravy health checku a čištění prostředí v jednom pull requestu ztěžuje review i rollback.

Neobvyklé hodnoty vysvětlete pomocí komentářů, ale nekopírujte do souboru provozní dokumentaci. Do runbooku repository odkažte informace o cíli služby, významu health checku a schvalovací politice. Manifest by měl zůstat platným YAML, který lze parsovat bez vlastního preprocessor.

Užitečná šablona pull requestu vyžaduje výstup dockup plan --json, očekávaný dopad na deployment, informaci, zda je požadován --prune, a ID předchozího deploymentu. AI agent i lidský reviewer tak mají k dispozici stejné podklady.

Zaveďte manifest bez narušení aktuálního stavu

U existující služby začněte poli, která dokážete ověřit. Spusťte dockup info production/api --json, vytvořte minimální dockup.yaml a porovnejte jej pomocí dockup plan. Nastavení přidávejte postupně, místo abyste se najednou pokoušeli rekonstruovat všechny historické volby z dashboardu.

Protože apply je aditivní, nespravované běžné hodnoty a domény během zavádění zůstanou zachovány. Jakmile manifest přesně popisuje zamýšlenou konfiguraci bez secrets, rozhodněte, zda tým někdy použije pruning. Některé týmy ponechávají cleanup jako manuální proces, jiné povolují --prune pouze v chráněném pipeline po schválení plánu.

Cílem konfigurace jako kódu není maximalizovat počet řádků v Gitu. Jde o to, aby byl produkční záměr srozumitelný, kontrolovatelný a obnovitelný.

Udržujte plány bez secrets

Plan by měl být bezpečný pro přiložení k pull requestu nebo záznamu o incidentu. Protože dockup.yaml obsahuje pouze běžné hodnoty a stávající hodnoty secrets zůstávají chráněné, mohou revieweři kontrolovat zamýšlenou konfiguraci, aniž by získali produkční credentials. Běžné hodnoty přesto kontrolujte kvůli interním hostname, identifikátorům zákazníků nebo jiným údajům, které by neměly být veřejné.

Udržujte zdroj a cíl pohromadě

V pull requestu a deployment jobu uveďte zamýšlený project/service. Platný dockup.yaml aplikovaný na nesprávný cíl je stále provozní selhání. Ověření cíle a review manifestu jsou dvě samostatné povinné kontroly.

Ověřte YAML před plan

Před voláním Dockup manifest v CI parsujte, aby chyby v odsazení nebo typech selhaly co nejblíže změně zdrojového souboru. Ověření syntaxe nenahrazuje dockup plan; zabraňuje zbytečným requestům s nečitelným souborem.

Upřednostněte jeden zdroj

Kontrolovaný dockup.yaml by měl vysvětlovat produkční záměr.

Začněte ověřitelným deploymentem

Přidejte minimální manifest k jedné službě, spusťte plan pouze pro čtení a před prvním apply zkontrolujte každé nahlášené pole.

Začněte zdarma na app.dockup.ai. Tarif Free stojí 0 $ měsíčně, zahrnuje počáteční kredit 10 $ a podporuje jeden workspace, tři databáze a tři deploymenty.

Časté dotazy

Co je dockup.yaml?

Jde o manifest Dockupu pro konfiguraci jako kód, který deklaruje branch služby, port, nastavení buildu a spuštění, health checky, běžné hodnoty prostředí a domény.

Mění dockup plan produkci?

Ne. dockup plan je pouze pro čtení a zobrazuje rozdíl mezi manifestem a aktuální službou.

Maže dockup up konfiguraci, která není v souboru?

Ve výchozím nastavení ne. Apply je aditivní. Podporované běžné hodnoty prostředí a domény se odstraní pouze při explicitním použití --prune.

Lze secrets uložit do dockup.yaml?

Neměly by se tam ukládat. Commitujte pouze běžné hodnoty; secrets nastavujte pomocí příkazu pro secret environment nebo runtime injection secrets. Stávající secrets jsou před pruningem chráněné.

Může dockup up po aplikaci konfigurace spustit deployment?

Ano. Dokumentovaná volba --deploy aplikuje manifest a spustí deployment, jehož koncový stav je následně třeba ověřit.