Variabili d’ambiente e secret su Dockup

Le variabili d’ambiente e i secret collegano il codice dell’applicazione alla configurazione di produzione, ma hanno requisiti diversi in termini di divulgazione e ciclo di vita. Un URL di base per un’API pubblica può essere sicuro da mostrare nei log; una password del database o una chiave di firma no. Dockup rappresenta esplicitamente questa distinzione e maschera i valori dei secret archiviati nell’output di lettura.

Anche le modifiche alla configurazione richiedono un redeploy. L’impostazione di un nuovo valore aggiorna la configurazione desiderata del servizio, ma il processo già in esecuzione continua a utilizzare l’ambiente ricevuto all’avvio.

Qual è la differenza tra una variabile e un secret?

Entrambi i valori entrano nel processo dell’applicazione come dati d’ambiente, ma la loro gestione operativa è diversa.

Tipo	Esempio	Può comparire nell’output di lettura?	Gestione consigliata
Variabile semplice	NODE_ENV=production	Sì	Configurazione soggetta a revisione
Variabile semplice	PUBLIC_API_URL=https://...	Sì	Può risiedere in dockup.yaml
Secret	DATABASE_URL=postgres://...	Nessun valore archiviato	Comando per secret o archivio CI
Secret	JWT_SIGNING_KEY=...	Nessun valore archiviato	Ruotare e limitare l’accesso
Secret	DOCKUP_TOKEN=...	Non archiviarlo mai come configurazione dell’app, salvo necessità	Autenticazione a livello di processo

Contrassegna un valore come secret quando la sua divulgazione consentirebbe accesso, impersonificazione, decrittografia, firma o movimento laterale. Il fatto che “il frontend lo contenga già” indica che il valore è una configurazione pubblica, non un secret.

Non inserire i secret nel controllo del codice sorgente, in dockup.yaml, negli output di esempio, negli screenshot, nei prompt degli agenti o nelle descrizioni delle issue. Un placeholder oscurato è più sicuro di un token dall’aspetto realistico, perché gli esempi copiati tendono a diventare prassi di produzione.

Come si impostano e ispezionano le configurazioni d’ambiente?

Elenca le chiavi correnti per una destinazione precisa:

dockup env list -s production/api --json

La risposta include ogni chiave, indica se è un secret e mostra il valore solo quando non è protetto.

Imposta una variabile ordinaria:

dockup env set NODE_ENV=production \
  -s production/api \
  --json

Imposta un secret dall’ambiente della shell corrente:

dockup env set DATABASE_URL="$DATABASE_URL" \
  --secret \
  -s production/api \
  --json

Rimuovi un valore obsoleto:

dockup env remove OLD_FEATURE_FLAG \
  -s production/api \
  --json

Importa in blocco un file in stile .env:

dockup env import .env.production \
  -s production/api \
  --json

Usa --secret durante l’importazione solo quando ogni valore importato deve essere trattato come secret. I file misti sono più difficili da revisionare e spesso incoraggiano a classificare eccessivamente configurazioni innocue o a classificare in modo insufficiente le credenziali. Quando possibile, separali.

La sintassi esatta dei comandi è disponibile nella documentazione di riferimento della Dockup CLI.

Perché è necessario un redeploy dopo le modifiche alla configurazione?

Le variabili d’ambiente vengono lette all’avvio del processo. L’aggiornamento della configurazione della piattaforma non modifica la memoria di un processo Node.js, Python, Go o di altro tipo già in esecuzione. Il servizio deve avviare un nuovo container con il nuovo ambiente.

La sequenza corretta è:

dockup env set FEATURE_FLAG=on \
  -s production/api \
  --json

dockup deploy production/api --wait --json

--wait rende verificabile il secondo passaggio. Il timeout predefinito è di 900 secondi, l’uscita 0 indica il successo e gli errori restituiscono un valore diverso da zero insieme a codici strutturati.

Il processo blue-green di Dockup senza downtime avvia la nuova versione, applica il controllo di salute e solo dopo sposta il traffico. In questo modo si evita di riavviare direttamente il container corrente con una configurazione non verificata.

Se la rotazione di un secret modifica sia il producer sia il consumer, pianifica la compatibilità. Ruotare la password del database prima che l’applicazione riceva il nuovo valore può causare un’interruzione. Usa un periodo di sovrapposizione, il supporto per due chiavi o una modifica ordinata quando il sistema esterno lo consente.

I meccanismi di deployment sono illustrati nella guida ai deployment senza downtime.

In che modo il mascheramento dei secret riduce i rischi per gli agenti?

Gli agenti di coding riepilogano spesso l’output dei comandi. Uno strumento che restituisce i secret archiviati trasforma una richiesta innocua come “mostra la configurazione corrente” in un’esposizione di credenziali.

Dockup maschera i valori dei secret. L’agente può vedere che DATABASE_URL esiste ed è contrassegnata come secret, ma non può leggere la stringa di connessione archiviata. Può sostituire il valore quando l’utente ne fornisce uno nuovo tramite un ambiente sicuro.

Questo consente di impartire un’istruzione più sicura:

Conferma che le chiavi secret richieste esistano, ma non stamparne mai i valori. Se è necessario modificare un valore, leggilo solo dall’ambiente del processo e restituisci il nome della chiave, non il secret.

Il mascheramento dei secret dovrebbe estendersi anche alla diagnostica. Evita:

printenv

in una trascrizione dell’agente, anche se il comando exec PRO può eseguire comandi one-shot nel container. Preferisci un controllo mirato dell’applicazione che segnali la presenza, la classe di lunghezza o l’esito della connessione senza divulgare il valore.

La guida sui guardrail di produzione per gli agenti AI tratta insieme i limiti dei prompt e degli strumenti.

Come si ruotano e si sottopongono ad audit i secret?

La rotazione è una modifica di produzione controllata, non una modifica testuale. Usa questa sequenza:

1. Crea o ottieni la nuova credenziale nel sistema proprietario.
2. Archiviala nell’ambiente CI approvato o nell’ambiente dell’operatore.
3. Imposta il nuovo secret in Dockup senza stamparlo.
4. Esegui il deploy con --wait.
5. Verifica lo stato di salute e il comportamento dell’applicazione.
6. Revoca la vecchia credenziale dopo che la nuova versione è attiva.
7. Esamina l’audit log di Dockup.
8. Registra la data e il responsabile della rotazione senza registrare il valore.

dockup audit --writes --json

Le evidenze dell’audit dovrebbero mostrare che la configurazione è cambiata e che è seguito un deployment. Non devono contenere il valore del secret.

Per le credenziali del database, considera i connection pool. Le connessioni esistenti potrebbero rimanere autenticate dopo la rotazione, mentre le nuove connessioni userebbero la nuova password. La verifica dovrebbe includere una connessione nuova, non solo richieste gestite da un pool precedente.

Per le chiavi API con autorizzazioni, acquisisci il valore generato in modo sicuro durante la creazione. Archivialo immediatamente nel sistema di secret approvato, limita la chiave alle autorizzazioni necessarie e ruotala senza riprodurla nell’output del deployment.

Quale policy di configurazione previene la deriva?

Definisci quali valori appartengono a ciascuna origine:

Origine	Contenuto appropriato
Codice del repository	Valori predefiniti non specifici dell’ambiente
dockup.yaml	Configurazione di deployment semplice e soggetta a revisione
Variabili secret di Dockup	Credenziali runtime
Archivio di secret CI	Token di deployment e valori iniettati durante la rotazione
Output del database gestito	Dati di connessione forniti al servizio consumer
.env locale	Valori riservati allo sviluppatore, esclusi da Git

L’applicazione di dockup.yaml è additiva per impostazione predefinita. I valori d’ambiente semplici non presenti nel file rimangono fino all’uso esplicito di --prune, mentre i secret non vengono mai eliminati tramite questo percorso. Consulta Configurazione come codice con dockup.yaml prima di adottare la pulizia tramite manifest.

Usa nomi di chiavi coerenti tra gli ambienti, ma non presumere che i valori siano intercambiabili. Una chiave di staging non dovrebbe concedere accesso alla produzione. I deployment di preview in un progetto con rete privata ricevono un utente del database in sola lettura creato automaticamente per accedere ai dati di produzione; per impostazione predefinita non dovrebbero ereditare credenziali con permessi di scrittura.

Risposta agli incidenti per un secret divulgato

Se un secret compare in una trascrizione, in un log, in un commit o in uno screenshot, mascherarlo in un secondo momento non è sufficiente. Consideralo compromesso:

1. Revocalo o ruotalo nel sistema di origine.
2. Aggiorna il secret in Dockup.
3. Esegui il redeploy e verifica.
4. Rimuovi il materiale esposto dove possibile.
5. Cerca eventuali utilizzi impropri negli audit log e nei log di accesso.
6. Documenta la causa e la modifica preventiva.

La riscrittura della cronologia Git può ridurre la possibilità di scoperta futura, ma non può dimostrare che una credenziale copiata sia scomparsa. La revoca è l’azione decisiva.

Checklist per la revisione dell’ambiente

Prima di ogni release di produzione, verifica che le chiavi richieste esistano, che le chiavi secret siano contrassegnate come tali, che nessun secret sia stato sottoposto a commit, che i valori semplici corrispondano all’ambiente previsto e che il redeploy faccia parte della modifica. Controlla quindi lo stato e l’uptime:

dockup status production/api --json
dockup uptime production/api --hours 24 --json

Il monitoring viene eseguito ogni minuto e include il tempo di risposta p95. Anche un deployment della configurazione completato con successo dovrebbe essere monitorato per rilevare regressioni runtime.

Per la creazione del servizio e la configurazione iniziale, segui la guida Dal repository Git alla produzione.

Convalidare la configurazione senza divulgarla

Le applicazioni dovrebbero segnalare chiaramente quando manca una chiave richiesta, ma la diagnostica non deve stamparne il valore. Un controllo all’avvio può restituire un elenco come missing: ["DATABASE_URL"] o invalid format: ["PUBLIC_URL"], quindi terminare con un codice diverso da zero.

Per un valore facoltativo, definisci il fallback nel codice e documenta se tale fallback è sicuro in produzione. I default di sviluppo silenziosi, come host di database locali, modalità di debug, CORS permissivo o credenziali di test, non dovrebbero attivarsi solo perché manca una chiave di produzione.

Questa convalida rende osservabili le variabili d’ambiente e i secret senza trasformare i log in un inventario di credenziali.

Gestire deliberatamente più servizi e credenziali condivise

Copiare un secret in diversi servizi crea una dipendenza dalla rotazione. Quando il sistema esterno lo consente, preferisci credenziali specifiche per servizio. Un token di un worker compromesso non dovrebbe concedere lo stesso accesso dell’API pubblica.

Quando un valore condiviso è inevitabile, mantieni un elenco dei responsabili e dei consumer. Ruota tutti i consumer in una finestra coordinata e verifica le connessioni nuove dopo ogni redeploy. Non chiedere a un agente di “trovare ogni servizio che probabilmente usa questa chiave” basandosi sulla somiglianza dei nomi; usa un inventario esplicito e le evidenze dell’audit.

La rete privata può ridurre l’esposizione del traffico del database, ma non rende superflue le credenziali. Gli hostname interni controllano il percorso; l’autenticazione controlla chi può utilizzare il database.

Inizia con un deployment verificabile

Classifica ogni chiave prima di impostarla, verifica che le letture dei secret siano mascherate e includi il redeploy richiesto nella stessa modifica sottoposta a revisione.

Inizia gratuitamente 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

Dockup restituisce i valori dei secret archiviati?

No. I valori dei secret sono mascherati nell’output di lettura. Le chiavi e gli indicatori dei secret rimangono visibili, così gli operatori possono verificare che la configurazione richiesta esista.

Perché devo eseguire il redeploy dopo aver modificato una variabile d’ambiente?

Il processo in esecuzione ha ricevuto il proprio ambiente all’avvio. Un nuovo deployment crea un nuovo container con i valori aggiornati e lo verifica tramite il controllo di salute.

Posso inserire i secret in dockup.yaml?

No. Usa dockup.yaml per la configurazione semplice soggetta a revisione e usa i comandi per le variabili secret o l’iniezione dei secret CI per le credenziali.

Come posso importare più variabili d’ambiente?

Usa dockup env import con un file in stile .env e la destinazione esatta del servizio. Usa l’opzione import --secret solo quando tutti i valori importati sono secret.

Cosa devo fare se un secret viene esposto in un log?

Revocalo o ruotalo immediatamente, aggiorna il secret in Dockup, esegui il redeploy, analizza i log di accesso e correggi il processo che ha consentito la divulgazione.