Private networking e domini .internal su Dockup

Il private networking permette ai servizi e ai database gestiti all’interno di un progetto Dockup di comunicare senza inviare il traffico tra risorse dello stesso progetto tramite internet pubblico. Ogni risorsa riceve un hostname stabile <slug>.internal, mentre i progetti separati restano isolati tra loro.

La rete è opt-in. L’attivazione collega le risorse già esistenti del progetto senza richiedere il passaggio immediato del traffico applicativo, mentre i servizi ricevono le variabili di connessione interne dopo il redeploy.

In che modo il networking tra servizi riduce l’esposizione pubblica?

Un endpoint pubblico di un database è raggiungibile da internet anche quando l’autenticazione blocca gli accessi non autorizzati. Una route privata elimina questa esposizione per il traffico applicativo e offre ai servizi un nome interno stabile che non dipende da un indirizzo pubblico.

Lo stesso principio si applica alle chiamate tra servizi. Un’API può chiamare un worker, un servizio admin interno o un backend tramite la rete del progetto invece che attraverso un custom domain pubblico.

Percorso del traffico	Route pubblica	Route privata
API verso PostgreSQL	Host e porta pubblici	main-db.internal
Web verso API	Custom domain pubblico	api.internal
Worker verso Redis	Host e porta pubblici	app-redis.internal
Preview verso il database di produzione	Credenziale pubblica del database	Utente interno in sola lettura
Chiamata tra progetti	Endpoint pubblico obbligatorio	Bloccata dall’isolamento dei progetti

Privato non significa privo di autenticazione. Continua a usare utenti del database, autorizzazione dei servizi e secrets. La rete determina la raggiungibilità; le credenziali determinano i permessi.

Come si abilita il private networking del progetto?

Abilita la rete per lo slug del progetto:

dockup network enable production --json

L’operazione collega i servizi e i database gestiti alla rete del progetto. I listener pubblici esistenti restano disponibili per impostazione predefinita, quindi l’adozione può avvenire gradualmente.

Esegui il redeploy di ogni servizio applicativo che deve ricevere le variabili d’ambiente interne:

dockup deploy production/api --wait --json
dockup deploy production/worker --wait --json

Dockup inietta dati di connessione come DATABASE_URL_INTERNAL, le variabili URL e host interne specifiche del database e i valori host/porta dei servizi. Ispeziona le chiavi dell’ambiente del servizio senza esporre i secrets:

dockup env list -s production/api --json

Non costruire manualmente un URL a partire da un nome visualizzato. Gli slug delle risorse determinano l’hostname <slug>.internal.

Prima di modificare la configurazione dell’applicazione, verifica che ogni dipendenza risieda nello stesso progetto. I progetti separati hanno reti separate e non possono risolversi o raggiungersi tramite il percorso interno.

In che modo i domini .internal modificano la configurazione dei servizi?

Il DNS interno fornisce un nome stabile mentre container e nodi cambiano sottostante. Un servizio API con slug api è raggiungibile come api.internal dai servizi dello stesso progetto; un database con slug main-db è raggiungibile come main-db.internal.

Quando disponibili, preferisci le variabili di connessione iniettate. Contengono il protocollo, le credenziali, il nome del database e il formato dell’host corretti. Una stringa costruita manualmente potrebbe omettere TLS, l’encoding della password o i parametri del database.

Migra una dipendenza alla volta:

1. Abilita la rete.
2. Esegui il redeploy del servizio che utilizza la dipendenza.
3. Conferma che la variabile interna esista.
4. Modifica l’applicazione affinché la utilizzi.
5. Esegui il deploy con --wait.
6. Verifica le nuove connessioni.
7. Osserva i runtime logs e i tempi di risposta.
8. Passa alla dipendenza successiva.

Un servizio può mantenere il proprio custom domain pubblico per il traffico degli utenti e usare hostname privati per le chiamate backend. I percorsi pubblici e privati rispondono a trust boundary diverse.

La guida su variabili d’ambiente e secrets spiega perché le modifiche alle connessioni richiedono un redeploy.

Come si rende un database gestito accessibile solo privatamente?

Dopo che ogni consumer necessario utilizza il percorso interno, rimuovi il listener pubblico:

dockup db private production/main-db --json

Ripristina l’accesso pubblico e privato quando necessario:

dockup db private production/main-db --off --json

Questa operazione sul database ricrea il container mantenendo i dati. Pianifica una maintenance window adeguata al carico di lavoro, verifica la presenza di un backup recente e testa la riconnessione dell’applicazione.

Prima di renderlo accessibile solo privatamente, verifica che:

• Ogni servizio di produzione che usa il database appartenga allo stesso progetto.
• Gli strumenti operativi non richiedano l’endpoint pubblico.
• L’accesso dai preview utilizzi il percorso privato supportato.
• Esista un backup e che il ripristino sia stato compreso.
• I connection pool eseguano retry sicuri.
• La destinazione esatta project/db sia stata registrata.

Un database accessibile solo privatamente non può essere raggiunto direttamente dal laptop di un operatore tramite internet pubblico. Usa gli strumenti di accesso supportati dalla piattaforma e la diagnostica a livello applicativo invece di riaprire il listener senza una valutazione.

Per le operazioni sui database, consulta la guida a PostgreSQL gestito.

In che modo i PR preview accedono ai dati di produzione in sicurezza?

Ogni preview di una PR o di un branch Dockup riceve un deployment e un URL isolati. In un progetto con private networking, il preview si unisce alla rete del progetto e può risolvere <slug>.internal.

Dockup crea automaticamente un utente in sola lettura per il database gestito di produzione utilizzato dal preview. Il preview può eseguire query su dati con la struttura della produzione, ma non può scrivere utilizzando quell’utente.

Questo design riduce il rischio che un feature branch modifichi i record dei clienti, ma anche l’accesso in lettura comporta delle conseguenze:

• Nel preview potrebbero comparire dati personali o sensibili.
• Il nuovo codice applicativo potrebbe registrare nei log i dati richiesti.
• Un URL del preview vulnerabile potrebbe esporre i risultati delle query.
• Le query costose potrebbero influire sul carico di produzione.
• Le ipotesi sullo schema potrebbero differire tra branch e produzione.

Abilita il deployment dei preview solo in base a una policy verificata:

dockup pr-preview production/api --on --json
dockup preview branch feature/search production/api --json

Usa l’ambiente isolato del preview per i feature flag e i secrets non relativi al database. Non sostituire la credenziale automatica in sola lettura con la credenziale di produzione in scrittura.

Come si monitora e si fa troubleshooting del private networking?

Inizia dalla topologia e dalla configurazione invece di presumere un outage della piattaforma.

Sintomo	Area probabile	Verifica
Nome non trovato	Slug/progetto errato o servizio non sottoposto a redeploy	Elenco dei servizi e chiavi dell’ambiente
Connessione rifiutata	Risorsa arrestata o porta errata	Stato e log del database/servizio
Autenticazione non riuscita	Credenziale errata	Rotazione del secret e utente
Il pubblico funziona, il privato no	Variabile interna o adozione della rete	Abilitazione della rete e redeploy
Il preview può leggere ma non scrivere	Policy prevista di sola lettura	Non sostituire la credenziale
La chiamata tra progetti non riesce	Isolamento previsto	Usa un’API pubblica autenticata

Ispeziona i runtime logs dell’applicazione:

dockup logs production/api --json

Controlla le dimensioni del database e gli errori di connessione dell’applicazione:

dockup db size production/main-db --json
dockup logs production/api --json

Non riportare gli URL completi delle connessioni interne nelle note dell’incidente. Potrebbero contenere credenziali, anche se l’hostname in sé non è un secret.

Piano di migrazione e rollback

Mantieni il listener pubblico durante la prima fase. Se il deployment interno non riesce, ripristina la configurazione precedente dell’applicazione ed esegui il redeploy. Rendi il database accessibile solo privatamente soltanto dopo che il percorso interno è rimasto stabile.

Per disabilitare la rete dell’intero progetto:

dockup network disable production --json

Deve trattarsi di un rollback deliberato, non del primo passaggio di troubleshooting. La disabilitazione della rete influisce su ogni risorsa collegata del progetto.

Registra le modifiche alla rete tramite l’audit log:

dockup audit --writes --json

Checklist di produzione per il private networking

Un runbook completo per il private networking include lo slug del progetto, gli slug dei servizi e dei database, gli hostname interni, i nomi delle variabili iniettate, la policy dei listener pubblici, la policy di accesso ai preview, lo stato dei backup, l’ordine dei redeploy e il percorso di rollback.

CPU, RAM e disco continuano a essere basati sull’utilizzo e misurati al minuto; il routing privato è una scelta architetturale, non una classe fissa di istanza. Usa Prezzi PaaS spiegati per la stima dei costi.

La documentazione di riferimento della CLI Dockup contiene i comandi aggiornati per rete e database. Per l’isolamento generale dei deployment, consulta le best practice di sicurezza.

Modella separatamente l’autorizzazione dei servizi e la raggiungibilità

Un hostname interno dimostra soltanto che il chiamante si trova sulla rete del progetto. Non dimostra quale servizio abbia effettuato la richiesta né se quel servizio possa eseguire l’azione. Mantieni l’autenticazione applicativa per le API interne sensibili e le credenziali del database per l’accesso ai dati.

Usa secrets specifici per servizio invece di un unico token interno condiviso. Se un preview riceve l’accesso in sola lettura al database, non assegnargli anche un service token di produzione che possa attivare scritture tramite un’API.

Misura l’effetto del passaggio

Confronta latenza delle connessioni, tasso di errore e tempo di risposta p95 prima e dopo il passaggio agli endpoint interni. L’obiettivo principale è l’isolamento e un percorso privato stabile; eventuali miglioramenti della latenza devono essere misurati, non promessi.

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

Conserva la finestra di osservazione e l’ID del deployment. In questo modo la modifica al private networking avrà un criterio di completamento misurabile, invece di terminare con “il DNS ha risolto”.

Documenta l’eccezione al percorso pubblico

Alcune integrazioni esterne, strumenti per operatori o servizi tra progetti potrebbero richiedere ancora un endpoint pubblico. Elenca ogni eccezione, la relativa autenticazione, il responsabile e la condizione per la rimozione. In questo modo si evita che il listener pubblico rimanga attivo indefinitamente perché nessuno ricorda il motivo della sua esistenza.

Un rollout completo del private networking può essere parziale, ma ogni percorso pubblico deve essere intenzionale.

Rivedi le dipendenze interne dopo i rename

Il rename o la sostituzione di una risorsa può modificare lo slug utilizzato per l’indirizzamento .internal. Inventaria i consumer prima di cambiare i nomi, esegui il redeploy con le variabili iniettate aggiornate e verifica ogni connessione privata.

In questo modo il private networking rimane stabile mentre il progetto evolve.

Inizia con un deployment verificabile

Abilita il networking in un progetto non di produzione, migra una dipendenza al relativo endpoint .internal e verifica il percorso di rollback prima di rimuovere qualsiasi listener pubblico.

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

FAQ

Quale hostname usano le risorse Dockup sulla rete privata?

Ogni servizio e database gestito dello stesso progetto è raggiungibile tramite un hostname stabile nella forma <slug>.internal.

L’abilitazione del private networking rimuove l’accesso pubblico al database?

No. Per impostazione predefinita, la rete si aggiunge alla configurazione esistente. Usa il comando separato per rendere privato il database e rimuovere il listener pubblico dopo che i consumer utilizzano il percorso interno.

Progetti Dockup diversi possono raggiungersi privatamente?

No. Ogni progetto ha una rete isolata, quindi la comunicazione tra progetti deve utilizzare un’interfaccia pubblica e autenticata appropriata.

Un PR preview può scrivere nel database di produzione?

In un progetto con private networking, Dockup assegna automaticamente al preview un utente del database in sola lettura, che consente le letture ma impedisce le scritture tramite quella credenziale.

Perché i servizi devono eseguire il redeploy dopo l’abilitazione del networking?

Il redeploy fornisce al nuovo container le variabili di connessione interne e consente all’applicazione di avviarsi con la configurazione dell’endpoint privato.