Rede privada e domínios .internal no Dockup

A rede privada permite que serviços e bancos de dados gerenciados dentro de um mesmo projeto Dockup se comuniquem sem enviar o tráfego entre recursos do projeto pela internet pública. Cada recurso recebe um hostname estável no formato <slug>.internal, enquanto projetos diferentes permanecem isolados uns dos outros.

A rede é opcional. Ativá-la conecta os recursos existentes do projeto sem exigir que o tráfego da aplicação mude imediatamente, e os serviços recebem variáveis de conexão internas após um novo deployment.

Como a rede entre serviços reduz a exposição pública?

Um endpoint público de banco de dados pode ser acessado pela internet mesmo quando a autenticação impede o uso não autorizado. Uma rota privada elimina essa exposição para o tráfego da aplicação e oferece aos serviços um nome interno estável que não depende de um endereço público.

O mesmo princípio se aplica às chamadas entre serviços. Uma API pode chamar um worker, um serviço administrativo interno ou um backend pela rede do projeto, em vez de usar um domínio público personalizado.

Caminho do tráfego	Rota pública	Rota privada
API para PostgreSQL	Host e porta públicos	main-db.internal
Web para API	Domínio público personalizado	api.internal
Worker para Redis	Host e porta públicos	app-redis.internal
Preview para banco de produção	Credencial pública do banco	Usuário interno somente leitura
Chamada entre projetos	Endpoint público obrigatório	Bloqueada pelo isolamento entre projetos

Privado não significa sem autenticação. Continue usando usuários de banco de dados, autorização de serviços e secrets. A rede determina a possibilidade de conexão; as credenciais determinam a permissão.

Como ativar a rede privada de um projeto?

Ative a rede para o slug do projeto:

dockup network enable production --json

A operação conecta os serviços e bancos de dados gerenciados à rede do projeto. Os listeners públicos existentes continuam disponíveis por padrão, permitindo uma adoção gradual.

Faça um novo deployment de cada serviço de aplicação que deve receber variáveis de ambiente internas:

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

O Dockup injeta dados de conexão, como DATABASE_URL_INTERNAL, variáveis internas de URL e host específicas do banco de dados e valores de host/porta dos serviços. Inspecione as chaves do ambiente do serviço sem expor secrets:

dockup env list -s production/api --json

Não monte manualmente uma URL a partir de um nome de exibição. Os slugs dos recursos determinam o hostname <slug>.internal.

Antes de alterar a configuração da aplicação, confirme que todas as dependências estão no mesmo projeto. Projetos diferentes têm redes separadas e não podem resolver ou acessar uns aos outros pelo caminho interno.

Como os domínios .internal alteram a configuração dos serviços?

O DNS interno oferece um nome estável enquanto os containers e nós subjacentes mudam. Um serviço de API com o slug api pode ser acessado como api.internal por serviços do mesmo projeto; um banco de dados com o slug main-db pode ser acessado como main-db.internal.

Dê preferência às variáveis de conexão injetadas quando estiverem disponíveis. Elas contêm o protocolo, as credenciais, o nome do banco de dados e o formato de host corretos. Uma string montada manualmente pode omitir TLS, o encoding da senha ou parâmetros do banco de dados.

Migre uma dependência de cada vez:

1. Ative a rede.
2. Faça um novo deployment do serviço consumidor.
3. Confirme que a variável interna existe.
4. Altere a aplicação para usá-la.
5. Faça o deployment com --wait.
6. Verifique novas conexões.
7. Observe os logs de runtime e o tempo de resposta.
8. Prossiga para a próxima dependência.

Um serviço pode manter seu domínio público personalizado para o tráfego dos usuários e usar hostnames privados nas chamadas de backend. Os caminhos público e privado atendem a limites de confiança diferentes.

O guia sobre variáveis de ambiente e secrets explica por que alterações de conexão exigem um novo deployment.

Como tornar um banco de dados gerenciado acessível somente pela rede privada?

Depois que todos os consumidores necessários estiverem usando o caminho interno, remova o listener público:

dockup db private production/main-db --json

Restaure o acesso público e privado quando necessário:

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

Essa operação no banco de dados recria o container preservando os dados. Planeje uma janela de manutenção adequada à carga de trabalho, confirme a existência de um backup recente e teste a reconexão da aplicação.

Antes de torná-lo acessível somente pela rede privada, verifique:

• Todos os serviços de produção que usam o banco estão no mesmo projeto.
• As ferramentas operacionais não exigem o endpoint público.
• O acesso do preview usa o caminho privado compatível.
• Existe um backup e o processo de recuperação é conhecido.
• Os connection pools fazem novas tentativas com segurança.
• O destino exato project/db está registrado.

Um banco de dados acessível somente pela rede privada não pode ser alcançado diretamente do laptop de um operador pela internet pública. Use os recursos de acesso compatíveis da plataforma e diagnósticos no nível da aplicação, em vez de reabrir o listener sem necessidade.

Para operações de banco de dados, consulte PostgreSQL gerenciado.

Como os previews de PR acessam dados de produção com segurança?

Cada preview de PR ou branch no Dockup recebe um deployment e uma URL isolados. Em um projeto com rede privada, o preview entra na rede do projeto e consegue resolver <slug>.internal.

O Dockup cria automaticamente um usuário somente leitura para o banco de dados gerenciado de produção usado pelo preview. O preview pode consultar dados com a estrutura de produção, mas não pode gravar usando esse usuário.

Esse design reduz o risco de uma branch de funcionalidade modificar registros de clientes, mas o acesso de leitura ainda tem consequências:

• Dados pessoais ou sensíveis podem aparecer no preview.
• O novo código da aplicação pode registrar os dados consultados nos logs.
• Uma URL de preview vulnerável pode expor resultados de consultas.
• Consultas custosas podem afetar a carga de produção.
• As suposições sobre o schema podem diferir entre a branch e a produção.

Ative o deployment de previews somente de acordo com uma política revisada:

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

Use o ambiente isolado do preview para feature flags e secrets que não sejam do banco de dados. Não substitua a credencial automática de somente leitura pela credencial de gravação de produção.

Como observar e solucionar problemas na rede privada?

Comece pela topologia e pela configuração, em vez de presumir uma indisponibilidade da plataforma.

Sintoma	Área provável	Verificação
Nome não encontrado	Slug/projeto incorreto ou serviço sem novo deployment	Lista de serviços e chaves do ambiente
Conexão recusada	Recurso parado ou porta incorreta	Status e logs do banco/serviço
Falha de autenticação	Credencial incorreta	Rotação de secret e usuário
Público funciona, privado falha	Variável interna ou adoção da rede	Ativação da rede e novo deployment
Preview consegue ler, mas não gravar	Política de somente leitura esperada	Não substitua a credencial
Chamada entre projetos falha	Isolamento esperado	Use uma API pública autenticada

Inspecione os logs de runtime da aplicação:

dockup logs production/api --json

Inspecione o tamanho do banco de dados e os erros de conexão da aplicação:

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

Não registre URLs internas completas de conexão nas anotações de incidentes. Elas podem incluir credenciais, mesmo que o hostname em si não seja secreto.

Plano de migração e rollback

Mantenha o listener público durante a primeira fase. Se o deployment interno falhar, restaure a configuração anterior da aplicação e faça um novo deployment. Só torne o banco de dados acessível exclusivamente pela rede privada depois que o caminho interno estiver estável.

Para desativar toda a rede do projeto:

dockup network disable production --json

Essa deve ser uma ação de rollback deliberada, não o primeiro passo da solução de problemas. Desativar a rede afeta todos os recursos conectados no projeto.

Registre as alterações de rede no audit log:

dockup audit --writes --json

Checklist de produção da rede privada

Um runbook completo de rede privada inclui o slug do projeto, os slugs dos serviços e bancos de dados, os hostnames internos, os nomes das variáveis injetadas, a política do listener público, a política de acesso dos previews, o status dos backups, a ordem dos novos deployments e o caminho de rollback.

CPU, RAM e disco continuam sendo cobrados conforme o uso e medidos por minuto; o roteamento privado é uma escolha de arquitetura, não uma classe fixa de instância. Use Preços de PaaS explicados para modelar custos.

A referência da CLI do Dockup contém os comandos atuais de rede e banco de dados. Para conhecer o isolamento geral de deployments, consulte boas práticas de segurança.

Modele a autorização dos serviços separadamente da possibilidade de conexão

Um hostname interno prova apenas que o chamador está na rede do projeto. Ele não prova qual serviço fez a solicitação nem se esse serviço pode executar a ação. Mantenha a autenticação da aplicação para APIs internas sensíveis e as credenciais do banco de dados para o acesso aos dados.

Use secrets específicos por serviço, em vez de um único token interno compartilhado. Se um preview receber acesso somente leitura ao banco de dados, não forneça também um token de serviço de produção que possa disparar gravações por meio de uma API.

Meça o efeito da mudança

Compare a latência das conexões, a taxa de erros e o tempo de resposta p95 antes e depois da mudança para endpoints internos. O objetivo principal é o isolamento e um caminho privado estável; qualquer melhoria de latência deve ser medida, não presumida.

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

Mantenha a janela de observação e o ID do deployment. Isso dá à alteração de rede privada um critério de conclusão mensurável, em vez de terminar apenas com “o DNS foi resolvido”.

Documente a exceção ao caminho público

Algumas integrações externas, ferramentas operacionais ou serviços entre projetos ainda podem exigir um endpoint público. Liste cada exceção, sua autenticação, seu responsável e sua condição de remoção. Isso evita que o listener público permaneça indefinidamente porque ninguém se lembra do motivo de sua existência.

Uma implementação completa de rede privada pode ser parcial, mas todo caminho público deve ser intencional.

Revise as dependências internas após renomeações

Renomear ou substituir um recurso pode alterar o slug usado no endereçamento .internal. Faça um inventário dos consumidores antes de alterar os nomes, faça um novo deployment deles com as variáveis injetadas atualizadas e verifique todas as conexões privadas.

Isso mantém a rede privada estável à medida que o projeto evolui.

Comece com um deployment verificável

Ative a rede em um projeto que não seja de produção, migre uma dependência para o endpoint .internal e valide o caminho de rollback antes de remover qualquer listener público.

Comece gratuitamente em app.dockup.ai. O plano Free custa US$ 0 por mês, inclui US$ 10 em crédito inicial e oferece suporte a um workspace, três bancos de dados e três deployments.

FAQ

Qual hostname os recursos do Dockup usam na rede privada?

Cada serviço e banco de dados gerenciado do mesmo projeto pode ser acessado por um hostname estável no formato <slug>.internal.

Ativar a rede privada remove o acesso público ao banco de dados?

Não. Por padrão, a rede é aditiva. Use o comando separado de banco de dados privado para remover o listener público depois que os consumidores estiverem usando o caminho interno.

Projetos diferentes do Dockup podem acessar uns aos outros de forma privada?

Não. Cada projeto tem uma rede isolada, portanto a comunicação entre projetos deve usar uma interface pública e autenticada adequada.

Um preview de PR pode gravar no banco de dados de produção?

Em um projeto com rede privada, o Dockup provisiona automaticamente um usuário de banco de dados somente leitura para o preview, permitindo leituras, mas impedindo gravações com essa credencial.

Por que os serviços precisam de um novo deployment depois que a rede é ativada?

O novo deployment fornece ao novo container as variáveis de conexão internas e permite que a aplicação seja iniciada com a configuração do endpoint privado.