Configuração como código com dockup.yaml: planeje e aplique com segurança

dockup.yaml transforma a configuração de serviços em um artefato do repositório que pode ser revisado. Em vez de depender do estado do dashboard, guardado apenas na memória da equipe, é possível declarar branch, porta, comandos de build e start, verificações de saúde, valores comuns de ambiente e domínios em um único arquivo.

O Dockup separa inspeção de mutação. dockup plan mostra a diferença entre o manifest e o serviço em execução sem fazer alterações. dockup up aplica as mudanças declaradas. A exclusão continua sendo opcional por meio de --prune.

O que o dockup.yaml pode declarar?

Um manifest de serviço pode conter as configurações de produção que se beneficiam de 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 }

Por padrão, o arquivo é colocado na raiz do repositório. É possível selecionar outro caminho com --file.

Não coloque secrets no mapeamento env. O manifest é commitado, revisado, armazenado em cache e copiado como qualquer outro arquivo-fonte. Use dockup env set --secret ou um processo aprovado de injeção de secrets para credenciais.

O consumo de CPU, RAM e disco continua sendo baseado no uso e é medido por minuto em relação ao saldo do plano; o manifest deve descrever a configuração do serviço, e não premissas de cobrança.

Como o dockup plan mostra o drift de configuração?

Execute uma comparação somente leitura antes de cada apply:

dockup plan production/api --json

O resultado contém alterações com aspectos, campos, valores antigos, novos valores e ações. Um plan pode mostrar que a branch mudou, que o path de healthcheck é diferente, que um domínio será adicionado ou que um valor comum de ambiente sofreu drift.

Um plan é valioso em cinco situações:

Situação	O que o plan revela
Pull request altera o manifest	Efeito pretendido em produção antes do merge
Dashboard foi editado manualmente	Drift em relação à fonte no repositório
Um agente propõe uma atualização	Campos exatos que o agente pretende alterar
Recuperação de incidente	Se o estado atual já difere da configuração conhecida
Configuração de múltiplos ambientes	Diferenças entre os manifests de produção e staging

O planning não bloqueia o serviço. O estado atual pode mudar entre o plan e o apply; por isso, workflows de alto risco devem manter a revisão e o up próximos e inspecionar o resultado do apply.

Um coding agent deve retornar o JSON do plan ou um resumo conciso campo a campo. “A configuração parece boa” não é um artefato de revisão suficiente.

Como o dockup up aplica configuração como código?

Aplique o manifest padrão:

dockup up production/api --json

Aplique e, em seguida, inicie um deployment:

dockup up production/api --deploy --json

Use outro arquivo para staging:

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

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

O resultado do apply informa quais alterações foram aplicadas ou ignoradas e pode incluir o ID do deployment quando --deploy é usado. O deployment associado ainda deve usar verificação do estado terminal quando apropriado; uma mutação de configuração e um release saudável em produção são resultados distintos.

Os valores de secrets continuam fora do manifest. Defina-os pelo workflow de ambiente de secrets antes de aplicar a configuração; depois, faça o deploy e verifique o container resultante sem imprimir o valor armazenado.

Por que a configuração como código é aditiva por padrão?

A interpretação mais segura para um manifest incompleto é “gerencie estes valores declarados”, e não “exclua todo o resto”. Por isso, o Dockup mantém inalteradas as variáveis de ambiente e os domínios ausentes do arquivo.

Isso é importante durante uma adoção gradual. Um serviço pode já ter variáveis secretas, domínios operacionais ou uma configuração temporária que ainda não foi modelada. O primeiro up não deve apagá-los.

As garantias de segurança são específicas:

• dockup up não exclui serviços, bancos de dados ou volumes.
• Variáveis secretas existentes não são sobrescritas por valores comuns do manifest.
• Variáveis secretas não são removidas pelo prune.
• A aplicação automática do manifest durante o deploy é aditiva.
• Um manifest inválido não se transforma silenciosamente em uma limpeza destrutiva.

O comportamento aditivo torna o dockup.yaml adequado para um workflow GitOps incremental. Isso também significa que o manifest não é automaticamente um inventário completo, a menos que a equipe adote deliberadamente o prune para os campos compatíveis.

Como o --prune deve ser revisado?

--prune remove valores comuns de ambiente e domínios compatíveis que estejam ausentes do manifest:

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

Trate a flag como uma solicitação destrutiva. Revise o plan, indique o alvo exato e obtenha aprovação humana quando um agente estiver operando em produção.

A operação não se estende a secrets, serviços, bancos de dados ou volumes. Esses recursos têm seu próprio ciclo de vida e fluxos de confirmação. Essa separação evita que uma pequena edição no manifest se transforme em uma exclusão ampla de infraestrutura.

Um registro de aprovação útil diz: “Aplique o dockup.yaml a production/api e faça prune das duas variáveis comuns e de um domínio exibidos no plan X.” Isso não deve ser uma autorização ampla e reutilizável para planos futuros.

O modelo mais amplo de confirmação é discutido em guardrails de produção para AI agents.

Como as equipes operam um workflow GitOps com dockup.yaml?

Mantenha o workflow simples:

1. Um desenvolvedor ou agente edita o dockup.yaml.
2. O CI valida a sintaxe do YAML e os testes da aplicação.
3. Um dockup plan somente leitura é executado no alvo pretendido.
4. O pull request mostra tanto o diff do código-fonte quanto o plan do estado atual.
5. Um reviewer aprova a alteração.
6. dockup up --deploy aplica a alteração.
7. O deploy aguarda o sucesso terminal.
8. Status, logs e evidências de auditoria são mantidos.

O manifest não deve virar um depósito de informações. Mantenha a configuração de negócio da aplicação na própria aplicação quando apropriado. Use o dockup.yaml para configurações de deployment e runtime pertencentes à fronteira do serviço.

Arquivos específicos por ambiente podem ser mais claros do que um único arquivo com uma camada de templating não documentada. Por exemplo, use dockup.staging.yaml e dockup.production.yaml, passando explicitamente o arquivo pretendido.

Um preview de branch é um deployment isolado, enquanto a configuração de produção continua sendo um alvo de revisão separado. Em projetos com private networking, os previews podem ingressar na rede do projeto e receber acesso somente leitura ao banco de dados sem alterar o manifest de produção.

Use o guia de variáveis de ambiente e secrets para gerenciar credenciais e deployments sem downtime para o readiness gate.

Playbook de resposta a drift

Quando o dockup plan relatar alterações inesperadas no estado atual, não as sobrescreva automaticamente. Determine se a edição no dashboard foi uma correção emergencial, uma alteração não autorizada ou uma configuração intencional que nunca foi commitada.

Em seguida, escolha uma fonte de verdade:

• Atualize o manifest para preservar o valor atual pretendido.
• Aplique o manifest para restaurar o valor revisado.
• Documente uma exceção temporária com responsável e prazo de expiração.
• Investigue o audit log quando a origem for desconhecida.

dockup audit --writes --json

Esse processo mantém o dockup.yaml como fonte de autoridade sem apagar o contexto do incidente.

A referência do Dockup CLI é a fonte dos campos atuais do manifest e das opções de plan/up.

Crie alterações de manifest fáceis de revisar

Mantenha cada alteração pequena o suficiente para que o plan tenha um único objetivo claro. Combinar uma mudança de branch, aumento de recursos, novo domínio, reescrita do health check e limpeza de ambiente em um único pull request dificulta tanto a revisão quanto o rollback.

Use comentários para explicar valores incomuns, mas não duplique a documentação operacional dentro do arquivo. Faça um link para o runbook do repositório com o target do serviço, a semântica de saúde e a política de aprovação. O manifest deve continuar sendo um YAML válido que possa ser analisado sem um preprocessor personalizado.

Um template útil de pull request solicita a saída de dockup plan --json, o efeito esperado no deployment, se --prune foi solicitado e o ID do deployment anterior. Isso fornece as mesmas evidências a um AI agent ou a um reviewer humano.

Introduza o manifest sem interromper o estado atual

Para um serviço existente, comece pelos campos que você consegue verificar. Execute dockup info production/api --json, escreva um dockup.yaml mínimo e compare-o com o dockup plan. Adicione as configurações em etapas, em vez de tentar reconstruir de uma só vez cada escolha histórica feita no dashboard.

Como o apply é aditivo, os valores comuns e domínios não gerenciados permanecem enquanto a adoção avança. Quando o manifest representar corretamente a configuração não secreta pretendida, decida se a equipe usará pruning. Algumas equipes mantêm a limpeza manual; outras permitem --prune apenas em um pipeline protegido após a aprovação do plan.

O objetivo da configuração como código não é maximizar o número de linhas no Git. É tornar a intenção de produção compreensível, revisável e recuperável.

Mantenha os plans livres de material secreto

Um plan deve ser seguro para ser anexado a um pull request ou registro de incidente. Como o dockup.yaml contém apenas valores comuns e os valores de secrets existentes permanecem protegidos, os reviewers podem inspecionar a configuração pretendida sem receber credenciais de produção. Ainda assim, revise valores comuns em busca de hostnames internos, identificadores de clientes ou outros dados que não devem ser públicos.

Mantenha a origem e o alvo juntos

Nomeie o project/service pretendido no pull request e no job de deployment. Um dockup.yaml válido aplicado ao alvo errado ainda é uma falha operacional. A descoberta do alvo e a revisão do manifest são verificações obrigatórias e separadas.

Valide o YAML antes do plan

Analise o manifest no CI antes de chamar o Dockup para que erros de indentação ou de tipo falhem próximos da alteração de origem. A validação de sintaxe não substitui o dockup plan; ela evita requests desnecessários com um arquivo ilegível.

Prefira uma única fonte

Um dockup.yaml revisado deve explicar a intenção de produção.

Comece com um deployment verificável

Adicione um manifest mínimo a um serviço, execute um plan somente leitura e revise cada campo informado antes do primeiro apply.

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

FAQ

O que é o dockup.yaml?

É o manifest de configuração como código do Dockup para declarar a branch, a porta, as configurações de build e start, os health checks, os valores comuns de ambiente e os domínios do serviço.

O dockup plan altera a produção?

Não. O dockup plan é somente leitura e mostra a diferença entre o manifest e o serviço atual.

O dockup up exclui configurações que não estão no arquivo?

Não por padrão. O apply é aditivo. Valores comuns de ambiente e domínios compatíveis só são removidos quando --prune é usado explicitamente.

É possível armazenar secrets no dockup.yaml?

Não é recomendável. Faça commit apenas de valores comuns; defina os secrets pelo comando de ambiente de secrets ou por injeção de secrets em runtime. Os secrets existentes são protegidos contra pruning.

O dockup up pode fazer deploy depois de aplicar a configuração?

Sim. A opção documentada --deploy aplica o manifest e inicia um deployment, cujo resultado terminal deve ser verificado em seguida.