Variáveis de ambiente e secrets no Dockup

Variáveis de ambiente e secrets conectam o código da aplicação à configuração de produção, mas têm requisitos diferentes de exposição e ciclo de vida. Uma URL base de API pública pode ser segura para exibição em logs; uma senha de banco de dados ou uma signing key, não. O Dockup representa essa distinção explicitamente e mascara os valores de secrets armazenados na saída de leitura.

As alterações de configuração também exigem um redeploy. Definir um novo valor atualiza a configuração desejada do serviço, mas o processo que já está em execução mantém o ambiente recebido na inicialização.

Qual é a diferença entre uma variável e um secret?

Ambos os valores entram no processo da aplicação como dados de ambiente, mas o tratamento operacional é diferente.

Tipo	Exemplo	Pode aparecer na saída de leitura?	Tratamento recomendado
Variável comum	NODE_ENV=production	Sim	Configuração passível de revisão
Variável comum	PUBLIC_API_URL=https://...	Sim	Pode ficar em dockup.yaml
Secret	DATABASE_URL=postgres://...	Nenhum valor armazenado	Comando de secret ou secret store de CI
Secret	JWT_SIGNING_KEY=...	Nenhum valor armazenado	Fazer rotação e restringir
Secret	DOCKUP_TOKEN=...	Nunca armazenar como configuração da aplicação, a menos que seja necessário	Autenticação no nível do processo

Marque um valor como secret quando sua exposição permitir acesso, personificação, descriptografia, assinatura ou movimentação lateral. “O frontend já o contém” é um sinal de que o valor é uma configuração pública, não um secret.

Não coloque secrets no source control, em dockup.yaml, exemplos de saída, screenshots, prompts de agentes ou descrições de issues. Um placeholder redigido é mais seguro do que um token com aparência realista, porque exemplos copiados tendem a se tornar prática de produção.

Como definir e inspecionar a configuração de ambiente?

Liste as chaves atuais para um target exato:

dockup env list -s production/api --json

A resposta inclui cada chave, informa se ela é um secret e mostra o valor apenas quando ele não está protegido.

Defina uma variável comum:

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

Defina um secret a partir do ambiente do shell atual:

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

Remova um valor obsoleto:

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

Importe em massa um arquivo no estilo .env:

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

Use --secret na importação apenas quando todos os valores importados devem ser tratados como secrets. Arquivos mistos são mais difíceis de revisar e frequentemente incentivam a classificação excessiva de configurações inofensivas ou a classificação insuficiente de credenciais. Separe-os sempre que possível.

A superfície exata de comandos é mantida na referência da CLI do Dockup.

Por que é necessário fazer um redeploy após alterações de configuração?

As variáveis de ambiente são lidas quando um processo é iniciado. Atualizar a configuração da plataforma não altera a memória de um processo Node.js, Python, Go ou de outro tipo que esteja em execução. O serviço precisa iniciar um novo container com o novo ambiente.

A sequência correta é:

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

dockup deploy production/api --wait --json

--wait torna a segunda etapa verificável. O timeout padrão é de 900 segundos, a saída 0 indica sucesso e as falhas retornam um valor diferente de zero com códigos estruturados.

O processo blue-green de zero downtime do Dockup inicia a nova versão, aplica o health gate e só então redireciona o tráfego. Isso evita reiniciar o container atual no local com uma configuração não verificada.

Se a rotação de um secret alterar o producer e o consumer, planeje a compatibilidade. Rotacionar uma senha de banco de dados antes que a aplicação receba o novo valor pode causar uma indisponibilidade. Use um período de sobreposição, suporte a dual-key ou uma alteração ordenada quando o sistema externo permitir.

A mecânica de deployment é explicada em deployments de zero downtime.

Como o mascaramento de secrets reduz o risco para agentes?

Agentes de código frequentemente resumem a saída de comandos. Uma ferramenta que retorna secrets armazenados transforma uma solicitação inofensiva de “mostrar a configuração atual” em exposição de credenciais.

O Dockup mascara os valores de secrets. O agente pode ver que DATABASE_URL existe e está marcado como secret, mas não pode ler a connection string armazenada. Ele pode substituir o valor quando o usuário fornecer um novo por meio de um ambiente seguro.

Isso permite uma instrução mais segura:

Confirme se as chaves de secret necessárias existem, mas nunca mostre seus valores. Se um valor precisar ser alterado, leia-o apenas do ambiente do processo e retorne o nome da chave, não o secret.

O mascaramento de secrets também deve se estender aos diagnósticos. Evite:

printenv

em um transcript de agente, embora o comando exec PRO possa executar comandos pontuais no container. Prefira uma verificação direcionada da aplicação que informe presença, classe de tamanho ou sucesso da conexão sem divulgar o valor.

O guia de guardrails de produção para agentes de IA aborda conjuntamente os limites de prompts e ferramentas.

Como fazer a rotação e a auditoria de secrets?

A rotação é uma alteração de produção controlada, não uma edição de texto. Use esta sequência:

1. Crie ou obtenha a nova credencial no sistema responsável por ela.
2. Armazene-a no ambiente aprovado de CI ou do operador.
3. Defina o novo secret no Dockup sem mostrá-lo.
4. Faça o deploy com --wait.
5. Verifique a saúde e o comportamento da aplicação.
6. Revogue a credencial antiga depois que a nova versão estiver ativa.
7. Revise o audit log do Dockup.
8. Registre a data e o responsável pela rotação sem registrar o valor.

dockup audit --writes --json

As evidências da auditoria devem mostrar que a configuração foi alterada e que um deployment foi realizado em seguida. Elas não devem conter o valor do secret.

Para credenciais de banco de dados, considere os connection pools. As conexões existentes podem continuar autenticadas após a rotação, enquanto novas conexões usam a nova senha. A verificação deve incluir uma conexão nova, não apenas requests atendidas por um pool antigo.

Para API keys com permissões, capture o valor gerado com segurança durante a criação. Armazene-o imediatamente no secret system aprovado, limite-o às permissões necessárias e faça a rotação sem reproduzi-lo na saída do deployment.

Que política de configuração evita drift?

Defina quais valores pertencem a cada fonte:

Fonte	Conteúdo apropriado
Código do repositório	Defaults que não são específicos do ambiente
dockup.yaml	Configuração de deployment comum e passível de revisão
Variáveis de secrets do Dockup	Credenciais de runtime
Secret store de CI	Token de deployment e valores de rotação injetados
Saída do banco de dados gerenciado	Dados de conexão fornecidos ao serviço consumidor
.env local	Valores exclusivos do desenvolvedor, excluídos do Git

O apply de dockup.yaml é aditivo por padrão. Os valores de ambiente comuns que não estão no arquivo permanecem até que --prune seja usado explicitamente, e os secrets nunca são removidos por esse caminho. Revise configuração como código com dockup.yaml antes de adotar a limpeza pelo manifest.

Use nomes de chaves consistentes entre os ambientes, mas não presuma que os valores sejam intercambiáveis. Uma chave de staging não deve conceder acesso à produção. Deployments de preview em um projeto com private networking recebem um usuário de banco de dados read-only criado automaticamente para acesso aos dados de produção; por padrão, não devem herdar credenciais de escrita.

Resposta a incidentes para um secret vazado

Se um secret aparecer em um transcript, log, commit ou screenshot, mascará-lo posteriormente não é suficiente. Considere-o comprometido:

1. Revogue ou faça a rotação no sistema de origem.
2. Atualize o secret no Dockup.
3. Faça o redeploy e verifique.
4. Remova o material exposto quando possível.
5. Pesquise os audit logs e access logs em busca de uso indevido.
6. Documente a causa e a alteração preventiva.

Reescrever o histórico do Git pode reduzir a descoberta futura, mas não pode provar que uma credencial copiada desapareceu. A revogação é a ação decisiva.

Checklist de revisão do ambiente

Antes de cada release de produção, verifique se as chaves necessárias existem, se as chaves de secret estão marcadas como secrets, se nenhum secret foi commitado, se os valores comuns correspondem ao ambiente pretendido e se um redeploy faz parte da alteração. Em seguida, verifique o status e o uptime:

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

O monitoring é executado a cada minuto e inclui o tempo de resposta p95. Mesmo um deployment de configuração bem-sucedido deve ser observado para identificar regressões em runtime.

Para a criação do serviço e a configuração inicial, siga Do repositório Git à produção.

Valide a configuração sem divulgá-la

As aplicações devem falhar de forma clara quando uma chave necessária estiver ausente, mas os diagnósticos não devem mostrar o valor. Uma verificação de inicialização pode informar uma lista como missing: ["DATABASE_URL"] ou invalid format: ["PUBLIC_URL"] e depois sair com um valor diferente de zero.

Para um valor opcional, defina o fallback no código e documente se ele é seguro em produção. Defaults silenciosos de desenvolvimento — hosts de banco de dados locais, modos de debug, CORS permissivo ou credenciais de teste — não devem ser ativados simplesmente porque uma chave de produção estava ausente.

Essa validação torna variáveis de ambiente e secrets observáveis sem transformar os logs em um inventário de credenciais.

Lide deliberadamente com vários serviços e credenciais compartilhadas

Copiar um secret para vários serviços cria uma dependência de rotação. Prefira credenciais específicas por serviço quando o sistema externo oferecer suporte. Um token comprometido de um worker não deve conceder o mesmo acesso que a API pública.

Quando um valor compartilhado for inevitável, mantenha uma lista de responsáveis e consumidores. Faça a rotação de todos os consumidores em uma janela coordenada e verifique novas conexões após cada redeploy. Não peça a um agente para “encontrar todos os serviços que provavelmente usam esta chave” com base na similaridade dos nomes; use um inventário explícito e evidências de auditoria.

O private networking pode reduzir a exposição do tráfego do banco de dados, mas não torna as credenciais desnecessárias. Os hostnames internos controlam o caminho; a autenticação controla quem pode usar o banco de dados.

Comece com um deployment verificável

Classifique cada chave antes de defini-la, verifique se as leituras de secrets estão mascaradas e inclua o redeploy necessário na mesma alteração revisada.

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

O Dockup retorna os valores armazenados dos secrets?

Não. Os valores dos secrets são mascarados na saída de leitura. As chaves e os indicadores de secret continuam visíveis para que os operadores possam verificar se a configuração necessária existe.

Por que preciso fazer um redeploy depois de alterar uma variável de ambiente?

O processo em execução recebeu seu ambiente na inicialização. Um novo deployment cria um novo container com os valores atualizados e o verifica por meio do health gate.

Posso colocar secrets em dockup.yaml?

Não. Use dockup.yaml para configurações comuns e passíveis de revisão; para credenciais, use comandos de ambiente para secrets ou a injeção de secrets pela CI.

Como importo várias variáveis de ambiente?

Use dockup env import com um arquivo no estilo .env e o target exato do serviço. Use a opção import --secret apenas quando todos os valores importados forem secrets.

O que devo fazer se um secret for exposto em um log?

Revogue-o ou faça sua rotação imediatamente, atualize o secret no Dockup, faça o redeploy, investigue os access logs e corrija o processo que permitiu a exposição.