Config as Code cu dockup.yaml: planificare și aplicare în siguranță

dockup.yaml transformă configurația serviciilor într-un artifact al repository-ului care poate fi verificat prin review. În loc să depindă de starea dashboard-ului reținută de cineva, o echipă poate declara într-un singur fișier branch-ul, portul, comenzile de build și start, health check-urile, valorile obișnuite de environment și domeniile.

Dockup separă inspecția de modificare. dockup plan afișează diferențele dintre manifest și serviciul activ fără să schimbe nimic. dockup up aplică modificările declarate. Ștergerea rămâne o acțiune opțională, activată prin --prune.

Ce poate declara dockup.yaml?

Un manifest de serviciu poate conține setările de producție care beneficiază de 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 }

Fișierul este plasat implicit în rădăcina repository-ului. Poți selecta o altă cale folosind --file.

Nu introduce secrete în mapping-ul env. Manifestul este versionat, analizat, memorat în cache și copiat la fel ca celelalte fișiere sursă. Folosește dockup env set --secret sau un proces aprobat de injectare a secretelor pentru credențiale.

Consumul de CPU, RAM și disk rămâne bazat pe utilizare și este măsurat pe minut în raport cu soldul planului; manifestul ar trebui să descrie configurația serviciului, nu presupuneri despre facturare.

Cum afișează dockup plan diferențele de configurație?

Rulează o comparație read-only înainte de fiecare aplicare:

dockup plan production/api --json

Rezultatul conține modificări cu aspecte, câmpuri, valori vechi, valori noi și acțiuni. Un plan poate arăta că s-a schimbat branch-ul, că diferă calea unui health check, că urmează să fie adăugat un domeniu sau că o valoare obișnuită de environment nu mai corespunde configurației dorite.

Un plan este valoros în cinci situații:

Situație	Ce evidențiază planul
Un pull request modifică manifestul	Efectul intenționat asupra producției înainte de merge
Dashboard-ul a fost modificat manual	Diferențele față de sursa din repository
Un agent propune o actualizare	Câmpurile exacte pe care agentul intenționează să le modifice
Recuperarea după un incident	Dacă starea activă diferă deja de configurația cunoscută
Configurație cu mai multe environment-uri	Diferențele dintre manifesturile de producție și staging

Planificarea nu blochează serviciul. Starea activă se poate schimba între plan și aplicare, așa că fluxurile cu risc ridicat ar trebui să păstreze review-ul și up cât mai apropiate și să verifice rezultatul aplicării.

Un coding agent ar trebui să returneze JSON-ul planului sau un rezumat concis, câmp cu câmp. „Configurația arată bine” nu este un artifact de review suficient.

Cum aplică dockup up configurația ca și cod?

Aplică manifestul implicit:

dockup up production/api --json

Aplică modificările și apoi declanșează un deployment:

dockup up production/api --deploy --json

Folosește un alt fișier pentru staging:

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

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

Rezultatul aplicării indică ce modificări au fost aplicate sau omise și poate include deployment ID-ul atunci când se folosește --deploy. Deployment-ul ar trebui în continuare să includă, atunci când este cazul, verificarea stării terminale; o modificare de configurație și un release de producție sănătos sunt rezultate distincte.

Valorile secretelor rămân în afara manifestului. Setează-le prin workflow-ul pentru environment secrets înainte de aplicarea configurației, apoi efectuează deployment-ul și verifică containerul rezultat fără să afișezi valoarea stocată.

De ce este config as code aditivă în mod implicit?

Cea mai sigură interpretare a unui manifest incomplet este „gestionează aceste valori declarate”, nu „șterge tot ce lipsește”. Prin urmare, Dockup păstrează neschimbate variabilele de environment și domeniile care nu apar în fișier.

Acest lucru este important în timpul adoptării progresive. Un serviciu poate avea deja variabile secrete, domenii operaționale sau configurații temporare care nu au fost încă modelate. Primul up nu ar trebui să le șteargă.

Garanțiile de siguranță sunt specifice:

• dockup up nu șterge servicii, baze de date sau volume.
• Variabilele secrete existente nu sunt suprascrise de valorile obișnuite din manifest.
• Variabilele secrete nu sunt eliminate prin prune.
• Aplicarea automată a manifestului în timpul deployment-ului este aditivă.
• Un manifest invalid nu devine în tăcere o operațiune distructivă de cleanup.

Comportamentul aditiv face ca dockup.yaml să fie potrivit pentru un workflow GitOps incremental. În același timp, acest lucru înseamnă că manifestul nu este automat un inventar complet, decât dacă echipa adoptă în mod deliberat pruning-ul pentru câmpurile acceptate.

Cum ar trebui analizat --prune în review?

--prune elimină valorile obișnuite de environment și domeniile acceptate care lipsesc din manifest:

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

Consideră flag-ul o solicitare distructivă. Analizează planul, precizează ținta exactă și obține aprobarea unui om atunci când un agent operează în producție.

Operațiunea nu se extinde la secrete, servicii, baze de date sau volume. Aceste resurse au propriul lifecycle și propriile căi de confirmare. Această separare împiedică o modificare minoră a manifestului să ducă la ștergerea extinsă a infrastructurii.

Un record de aprobare util spune: „Aplică dockup.yaml în production/api și elimină prin prune cele două variabile obișnuite și domeniul afișate în planul X.” Nu ar trebui să fie o permisiune generală, reutilizabilă pentru planuri viitoare.

Modelul mai larg de confirmare este prezentat în guardrails pentru agenții AI în producție.

Cum operează echipele un workflow GitOps cu dockup.yaml?

Păstrează workflow-ul simplu:

1. Un developer sau un agent editează dockup.yaml.
2. CI validează sintaxa YAML și testele aplicației.
3. Se rulează un dockup plan read-only pentru ținta dorită.
4. Pull request-ul afișează atât diff-ul sursei, cât și planul stării active.
5. Un reviewer aprobă modificarea.
6. dockup up --deploy o aplică.
7. Deployment-ul așteaptă succesul stării terminale.
8. Starea, logurile și dovezile de audit sunt păstrate.

Manifestul nu ar trebui să devină un depozit de lucruri disparate. Păstrează configurația de business a aplicației în aplicație, atunci când este potrivit. Folosește dockup.yaml pentru setările de deployment și runtime deținute de granița serviciului.

Fișierele specifice fiecărui environment pot fi mai clare decât un singur fișier cu un layer de templating nedocumentat. De exemplu, folosește dockup.staging.yaml și dockup.production.yaml și transmite explicit fișierul dorit.

Un branch preview este un deployment izolat, în timp ce configurația de producție rămâne o țintă separată pentru review. În proiectele cu private networking, preview-urile se pot conecta la network-ul proiectului și pot primi acces read-only la baza de date fără să modifice manifestul de producție.

Folosește ghidul pentru variabile de environment și secrete pentru gestionarea credențialelor și deployment-urile zero-downtime pentru readiness gate.

Playbook pentru gestionarea diferențelor

Când dockup plan raportează modificări neașteptate în starea activă, nu le suprascrie automat. Stabilește dacă modificarea din dashboard a fost o remediere de urgență, o schimbare neautorizată sau o setare intenționată care nu a fost niciodată versionată.

Apoi alege o singură sursă de adevăr:

• Actualizează manifestul pentru a păstra valoarea activă dorită.
• Aplică manifestul pentru a restaura valoarea analizată și aprobată.
• Documentează o excepție temporară, cu un owner și o dată de expirare.
• Investighează audit log-ul atunci când originea este necunoscută.

dockup audit --writes --json

Acest proces păstrează dockup.yaml ca sursă autoritară fără să șteargă contextul incidentului.

Referința Dockup CLI este sursa pentru câmpurile actuale ale manifestului și opțiunile plan/up.

Creează modificări de manifest ușor de analizat

Păstrează fiecare modificare suficient de restrânsă pentru ca planul să aibă un singur scop clar. Combinarea unei schimbări de branch, a unei creșteri de resurse, a unui domeniu nou, a unei rescrieri a health check-ului și a unei curățări de environment într-un singur pull request îngreunează atât review-ul, cât și rollback-ul.

Folosește comentarii pentru a explica valorile neobișnuite, dar nu duplica documentația operațională în fișier. Leagă runbook-ul repository-ului de ținta serviciului, semantica health check-ului și politica de aprobare. Manifestul ar trebui să rămână YAML valid, care poate fi parsat fără un preprocessor custom.

Un template util pentru pull request solicită rezultatul dockup plan --json, efectul așteptat al deployment-ului, dacă se solicită --prune și deployment ID-ul anterior. Astfel, un agent AI sau un reviewer uman beneficiază de aceleași dovezi.

Introdu manifestul fără să perturbi starea activă

Pentru un serviciu existent, începe cu câmpurile pe care le poți verifica. Rulează dockup info production/api --json, scrie un dockup.yaml minimal și compară-l folosind dockup plan. Adaugă setările în etape, în loc să încerci să reconstruiești dintr-o dată fiecare alegere istorică din dashboard.

Deoarece aplicarea este aditivă, valorile obișnuite și domeniile neadministrate rămân disponibile pe durata adoptării. După ce manifestul reprezintă corect configurația non-secretă dorită, decide dacă echipa va folosi vreodată pruning. Unele echipe păstrează cleanup-ul manual; altele permit --prune doar într-un pipeline protejat, după aprobarea planului.

Scopul config as code nu este să maximizeze numărul de linii din Git. Scopul este ca intenția pentru producție să fie ușor de înțeles, analizat și recuperat.

Păstrează planurile fără materiale secrete

Un plan ar trebui să poată fi atașat în siguranță unui pull request sau unui record de incident. Deoarece dockup.yaml conține doar valori obișnuite, iar valorile secrete existente rămân protejate, reviewerii pot analiza configurația dorită fără să primească credențiale de producție. Totuși, verifică valorile obișnuite pentru hostname-uri interne, identificatori de clienți sau alte date care nu ar trebui să fie publice.

Păstrează sursa și ținta împreună

Numește project/service vizat în pull request și în job-ul de deployment. Un dockup.yaml valid aplicat țintei greșite rămâne un incident operațional. Descoperirea țintei și review-ul manifestului sunt verificări separate și obligatorii.

Validează YAML înainte de plan

Parsează manifestul în CI înainte de a apela Dockup, astfel încât erorile de indentare sau de tip să eșueze cât mai aproape de modificarea sursă. Validarea sintaxei nu înlocuiește dockup plan; ea previne request-urile evitabile cu un fișier care nu poate fi citit.

Preferă o singură sursă

Un dockup.yaml analizat și aprobat ar trebui să explice intenția pentru producție.

Începe cu un deployment verificabil

Adaugă un manifest minimal pentru un serviciu, rulează un plan read-only și analizează fiecare câmp raportat înainte de prima aplicare.

Începe gratuit pe app.dockup.ai. Planul Free costă $0 pe lună, include un credit inițial de $10 și permite un workspace, trei baze de date și trei deployment-uri.

Întrebări frecvente

Ce este dockup.yaml?

Este manifestul config-as-code al Dockup pentru declararea branch-ului serviciului, a portului, a setărilor de build și start, a health check-urilor, a valorilor obișnuite de environment și a domeniilor.

Modifică dockup plan producția?

Nu. dockup plan este read-only și afișează diferența dintre manifest și serviciul activ.

Șterge dockup up configurația care nu apare în fișier?

Nu în mod implicit. Aplicarea este aditivă. Valorile obișnuite de environment și domeniile acceptate sunt eliminate doar când se folosește explicit --prune.

Pot fi stocate secrete în dockup.yaml?

Nu ar trebui. Versionează doar valorile obișnuite; setează secretele prin comanda pentru secret environment sau prin injectare de secrete la runtime. Secretele existente sunt protejate împotriva pruning-ului.

Poate dockup up să declanșeze un deployment după aplicarea configurației?

Da. Opțiunea documentată --deploy aplică manifestul și declanșează un deployment, al cărui rezultat terminal ar trebui apoi verificat.