Configurazione come codice con dockup.yaml: pianificare e applicare in sicurezza

dockup.yaml trasforma la configurazione dei servizi in un artifact del repository, facile da sottoporre a review. Invece di affidarsi allo stato della dashboard ricordato a memoria, un team può dichiarare in un unico file branch, porta, comandi di build e avvio, health check, valori ordinari dell'ambiente e domini.

Dockup separa l'ispezione dalle modifiche. dockup plan mostra la differenza tra il manifest e il servizio live senza modificare nulla. dockup up applica le modifiche dichiarate. La cancellazione rimane opt-in tramite --prune.

Cosa si può dichiarare in dockup.yaml?

Un manifest del servizio può contenere le impostazioni di produzione che traggono vantaggio dalla 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 }

Per impostazione predefinita, il file viene posizionato nella root del repository. È possibile selezionare un percorso diverso con --file.

Non inserire i secret nella mappa env. Il manifest viene sottoposto a commit, revisionato, memorizzato nella cache e copiato come gli altri file sorgente. Usa dockup env set --secret o un processo approvato di injection dei secret per le credenziali.

Il consumo di CPU, RAM e disco rimane basato sull'utilizzo e viene misurato al minuto in base al saldo del piano; il manifest dovrebbe descrivere la configurazione del servizio, non le ipotesi di fatturazione.

In che modo dockup plan mostra il configuration drift?

Esegui un confronto in sola lettura prima di ogni apply:

dockup plan production/api --json

Il risultato contiene le modifiche, con aspetti, campi, valori precedenti, nuovi valori e azioni. Un plan può mostrare che il branch è cambiato, che un health path è diverso, che verrà aggiunto un dominio o che un valore ordinario dell'ambiente è cambiato.

Un plan è utile in cinque situazioni:

Situazione	Cosa rivela il plan
Una pull request modifica il manifest	L'effetto previsto sulla produzione prima del merge
La dashboard è stata modificata manualmente	Il drift rispetto alla sorgente nel repository
Un agent propone un aggiornamento	I campi esatti che l'agent intende modificare
Recupero da un incidente	Se lo stato live è già diverso dalla configurazione nota
Configurazione multi-environment	Le differenze tra i manifest di produzione e staging

Il planning non blocca il servizio. Lo stato live può cambiare tra plan e apply; per questo i workflow ad alto rischio dovrebbero mantenere ravvicinati la review e up, verificando inoltre il risultato dell'apply.

Un coding agent dovrebbe restituire il JSON del plan o un riepilogo conciso campo per campo. “La configurazione sembra corretta” non è un artifact di review sufficiente.

In che modo dockup up applica la config as code?

Applica il manifest predefinito:

dockup up production/api --json

Applica il manifest e avvia quindi un deployment:

dockup up production/api --deploy --json

Usa un file diverso per staging:

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

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

Il risultato dell'apply indica quali modifiche sono state applicate o ignorate e può includere il deployment ID quando viene usato --deploy. Quando appropriato, il deployment dovrebbe comunque prevedere la verifica dello stato terminale; una modifica alla configurazione e una release di produzione funzionante sono due risultati distinti.

I valori dei secret rimangono fuori dal manifest. Impostali tramite il workflow dei secret dell'ambiente prima di applicare la configurazione, quindi esegui il deployment e verifica il container risultante senza stampare il valore memorizzato.

Perché la config as code è additiva per impostazione predefinita?

L'interpretazione più sicura di un manifest incompleto è “gestisci questi valori dichiarati”, non “elimina tutto il resto”. Per questo Dockup lascia invariati le variabili d'ambiente e i domini assenti dal file.

Questo è importante durante l'adozione graduale. Un servizio potrebbe già avere variabili secret, domini operativi o configurazioni temporanee che non sono ancora state modellate. Il primo up non dovrebbe cancellarle.

Le garanzie di sicurezza sono specifiche:

• dockup up non elimina servizi, database o volumi.
• Le variabili secret esistenti non vengono sovrascritte da valori ordinari del manifest.
• Le variabili secret non vengono sottoposte a prune.
• L'applicazione automatica del manifest durante il deploy è additiva.
• Un manifest non valido non si trasforma silenziosamente in una pulizia distruttiva.

Il comportamento additivo rende dockup.yaml adatto a un workflow GitOps incrementale. Significa anche che il manifest non è automaticamente un inventario completo, a meno che il team non scelga deliberatamente di usare il pruning per i campi supportati.

Come va revisionato --prune?

--prune rimuove i valori ordinari dell'ambiente e i domini supportati assenti dal manifest:

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

Tratta il flag come una richiesta distruttiva. Revisiona il plan, indica esplicitamente il target e ottieni l'approvazione umana quando un agent opera in produzione.

L'operazione non si applica a secret, servizi, database o volumi. Queste risorse hanno un proprio ciclo di vita e specifici percorsi di conferma. Questa separazione impedisce che una piccola modifica al manifest si trasformi in una cancellazione estesa dell'infrastruttura.

Un utile record di approvazione recita: “Applica dockup.yaml a production/api ed esegui il prune delle due variabili ordinarie e del dominio mostrati nel plan X.” Non dovrebbe essere un'autorizzazione generica e riutilizzabile per plan futuri.

Il modello più ampio delle conferme è descritto in guardrail di produzione per gli agent AI.

Come gestiscono i team un workflow GitOps con dockup.yaml?

Mantieni il workflow semplice:

1. Uno sviluppatore o un agent modifica dockup.yaml.
2. CI convalida la sintassi YAML e i test applicativi.
3. Viene eseguito un dockup plan in sola lettura sul target previsto.
4. La pull request mostra sia il diff del sorgente sia il plan dello stato live.
5. Un reviewer approva la modifica.
6. dockup up --deploy la applica.
7. Il deploy attende il completamento con esito terminale positivo.
8. Stato, log ed evidenze di audit vengono conservati.

Il manifest non dovrebbe diventare un contenitore generico. Quando appropriato, mantieni la configurazione di business dell'applicazione nell'applicazione stessa. Usa dockup.yaml per le impostazioni di deployment e runtime gestite dal perimetro del servizio.

I file specifici per environment possono essere più chiari di un unico file con un layer di templating non documentato. Ad esempio, usa dockup.staging.yaml e dockup.production.yaml, passando esplicitamente il file previsto.

Una preview di branch è un deployment isolato, mentre la configurazione di produzione rimane un target di review separato. Nei progetti con networking privato, le preview possono unirsi alla rete del progetto e ricevere accesso in sola lettura al database senza modificare il manifest di produzione.

Consulta la guida alle variabili d'ambiente e ai secret per la gestione delle credenziali e deployment zero-downtime per il readiness gate.

Playbook per la gestione del drift

Quando dockup plan segnala modifiche live impreviste, non sovrascriverle automaticamente. Determina se la modifica alla dashboard era una correzione d'emergenza, una modifica non autorizzata o un'impostazione intenzionale mai sottoposta a commit.

Poi scegli una source of truth:

• Aggiorna il manifest per conservare il valore live previsto.
• Applica il manifest per ripristinare il valore revisionato.
• Documenta un'eccezione temporanea con un owner e una scadenza.
• Analizza l'audit log quando l'origine è sconosciuta.

dockup audit --writes --json

Questo processo mantiene dockup.yaml come fonte autorevole senza cancellare il contesto dell'incidente.

La documentazione di riferimento della Dockup CLI è la fonte per i campi attuali del manifest e per le opzioni di plan/up.

Progetta modifiche al manifest facili da revisionare

Mantieni ogni modifica abbastanza piccola da dare al plan un unico scopo chiaro. Combinare in una sola pull request una modifica al branch, un aumento delle risorse, un nuovo dominio, una riscrittura dell'health check e la pulizia dell'ambiente rende più difficili sia la review sia il rollback.

Usa i commenti per spiegare valori insoliti, ma non duplicare la documentazione operativa nel file. Collega il runbook del repository al target del servizio, alla semantica dell'health check e alla policy di approvazione. Il manifest dovrebbe rimanere YAML valido, analizzabile senza un preprocessor personalizzato.

Un utile template per le pull request richiede l'output di dockup plan --json, l'effetto previsto sul deployment, l'indicazione se è richiesto --prune e il deployment ID precedente. In questo modo un agent AI o un reviewer umano dispone delle stesse evidenze.

Introduci il manifest senza modificare lo stato live

Per un servizio esistente, inizia dai campi che puoi verificare. Esegui dockup info production/api --json, scrivi un dockup.yaml minimale e confrontalo con dockup plan. Aggiungi le impostazioni per fasi invece di provare a ricostruire in una volta sola ogni scelta storica della dashboard.

Poiché l'apply è additivo, i valori ordinari e i domini non gestiti rimangono durante l'adozione. Quando il manifest rappresenta accuratamente la configurazione non-secret prevista, decidi se il team userà mai il pruning. Alcuni team mantengono la pulizia manuale; altri consentono --prune solo in una pipeline protetta dopo l'approvazione del plan.

L'obiettivo della config as code non è massimizzare il numero di righe in Git. È rendere l'intento di produzione comprensibile, revisionabile e recuperabile.

Mantieni i plan privi di materiale secret

Un plan dovrebbe poter essere allegato in sicurezza a una pull request o a un record di incidente. Poiché dockup.yaml contiene solo valori ordinari e i valori secret esistenti rimangono protetti, i reviewer possono ispezionare la configurazione prevista senza ricevere credenziali di produzione. È comunque necessario verificare i valori ordinari per individuare hostname interni, identificativi dei clienti o altri dati che non dovrebbero essere pubblici.

Mantieni sorgente e target insieme

Indica il project/service previsto nella pull request e nel job di deployment. Un dockup.yaml valido applicato al target sbagliato costituisce comunque un errore operativo. La discovery del target e la review del manifest sono due controlli obbligatori distinti.

Convalida YAML prima del plan

Analizza il manifest in CI prima di chiamare Dockup, così gli errori di indentazione o di tipo falliscono vicino alla modifica sorgente. La convalida della sintassi non sostituisce dockup plan; evita richieste non necessarie con un file illeggibile.

Preferisci una sola source of truth

Un dockup.yaml revisionato dovrebbe spiegare l'intento di produzione.

Inizia con un deployment verificabile

Aggiungi un manifest minimale a un servizio, esegui un plan in sola lettura e revisiona ogni campo segnalato prima del primo apply.

Inizia gratis su app.dockup.ai. Il piano Free costa $0 al mese, include $10 di credito iniziale e supporta un workspace, tre database e tre deployment.

FAQ

Che cos'è dockup.yaml?

È il manifest di Dockup per la config as code, con cui dichiarare branch del servizio, porta, impostazioni di build e avvio, health check, valori ordinari dell'ambiente e domini.

dockup plan modifica la produzione?

No. dockup plan è in sola lettura e mostra la differenza tra il manifest e il servizio live.

dockup up elimina la configurazione non presente nel file?

Non per impostazione predefinita. L'apply è additivo. I valori ordinari dell'ambiente e i domini supportati vengono rimossi solo quando si usa esplicitamente --prune.

È possibile salvare i secret in dockup.yaml?

Non dovrebbero essere inseriti. Esegui il commit solo dei valori ordinari; imposta i secret tramite il comando per l'ambiente dei secret o tramite runtime secret injection. I secret esistenti sono protetti dal pruning.

dockup up può eseguire il deployment dopo aver applicato la configurazione?

Sì. L'opzione documentata --deploy applica il manifest e avvia un deployment, il cui risultato terminale dovrebbe poi essere verificato.