Engenharia
Do código-fonte a uma versão saudável: o que uma implantação realmente faz
Um comando de implantação atravessa várias etapas: empacotamento do código-fonte, compilação, inicialização do ambiente de execução, prontidão, promoção e roteamento público. Cada uma pode falhar de modo diferente.
Uma compilação bem-sucedida não significa que a aplicação está no ar. Entre o código-fonte na máquina do desenvolvedor e a URL pública há várias verificações independentes, cada uma com suas evidências e seu caminho de recuperação.
O limite das fontes: capturar o que será compilado
A primeira pergunta parece simples: quais arquivos esta implantação representa? Um diretório local, uma revisão Git e um espaço de trabalho aberto podem ter conteúdos diferentes. Se a plataforma não identificar exatamente o código-fonte compilado, a depuração posterior vira adivinhação. A Adios registra as fontes como um artefato, vinculando a implantação ao código que pode ser reaberto em um espaço de trabalho.
O pacote deve excluir resultados descartáveis, como node_modules e diretórios locais de compilação, mas preservar o arquivo de lock, o manifesto e os arquivos necessários para compilar. Um upload bem-sucedido só comprova que o pacote chegou. Não comprova que o código compila ou que o ambiente de execução consegue iniciar.
O limite de compilação: produzir uma saída versionada
A etapa de compilação instala dependências, executa o comando declarado e produz a saída que a carga de trabalho iniciará. Uma falha deve deixar logs e um resultado de erro, não uma versão parcialmente promovida. A Adios separa logs de compilação e execução porque os responsáveis por resolver problemas de pacotes e compilação são diferentes dos responsáveis por falhas na inicialização da aplicação.
Para uma API Go, a saída de compilação pode ser um binário. Para Next.js, inclui arquivos de servidor e recursos. Para um serviço Python, o trabalho principal pode ser instalar dependências com versões fixadas e preparar o ambiente. O formato varia, mas o princípio permanece: o ambiente de execução inicia uma saída identificada, derivada de código-fonte identificado, conforme um contrato explícito de compilação.
- —Registre o artefato de código-fonte e o identificador da compilação.
- —Mantenha o comando de compilação em adios.yaml e nos scripts do projeto.
- —Inspecione os logs de compilação quando a instalação de dependências ou a compilação falhar.
- —Não deduza a saúde do ambiente de execução de uma compilação bem-sucedida.
O limite da execução: iniciar o processo correto
Depois de concluir a compilação, o worker deve iniciar o processo de produção declarado com seu ambiente, limites de recursos e configurações de rede. Uma falha comum é escutar em uma porta diferente da definida no manifesto. Outra é escutar somente em localhost quando o gateway precisa acessar a carga de trabalho. Segredos ausentes e recursos gerenciados obrigatórios também podem fazer o processo terminar imediatamente ou parecer ativo sem atender requisições.
A Adios cria uma versão do ambiente de execução com uma ou mais réplicas. O manifesto descreve região, número de réplicas, comando de inicialização, porta e caminho de saúde. Isso permite avaliar se a nova versão pode executar com segurança sem depender de uma configuração de painel que nunca foi registrada no repositório.
A small API deploy contract
name: api
region: de
replicas: 2
build_cmd: go build -o /app/api ./cmd/api
start_cmd: /app/api
runtime:
name: go@1.25
port: 8080
health_path: /healthzO limite da prontidão: comprovar que a versão pode atender requisições
Um processo pode estar ativo enquanto suas rotas retornam erros. A prontidão verifica se essa versão pode atender uma requisição real. Um caminho de saúde útil deve falhar dentro de um prazo quando uma dependência obrigatória está indisponível e se recuperar quando ela voltar. Deve evitar trabalho caro que transforme a própria sonda em carga.
O guia de início rápido da Adios descreve a promoção após uma implantação ficar saudável. A CLI também testa um caminho público de saúde configurado e pode informar que a rota atual está saudável. São observações diferentes: a prontidão das réplicas protege a versão candidata; uma sonda pública verifica o que o cliente alcança pela entrada. Uma verificação completa precisa das duas e de uma requisição a uma rota representativa da aplicação.
O limite da promoção: tornar a nova versão atual
Uma versão de implantação e a versão atualmente em produção são conceitos distintos. Essa separação permite inspecionar uma versão com falha ou substituída sem tratá-la como a que atende os usuários. A rota deve apontar para a versão aprovada nas verificações obrigatórias, e uma candidata com falha deve manter disponível a versão atual anterior.
É aqui que o rollback ganha um significado concreto: selecionar uma versão anterior de funcionamento conhecido, verificar seus recursos e a compatibilidade do esquema e devolver a rota a ela. Uma migração do banco da aplicação pode dificultar isso, mesmo que a plataforma preserve a saída de execução antiga. Revise a compatibilidade com versões anteriores antes de considerar o rollback automático.
O limite da rota pública: testar o que os usuários veem
A requisição final passa por DNS, TLS, gateway de entrada, consulta de rota e carga de trabalho selecionada. Uma falha em qualquer ponto pode parecer ao usuário uma implantação quebrada, mesmo com o contêiner saudável. Acesse o nome de host e o caminho reais, verifique redirecionamentos e certificados e compare a resposta com a versão que você pretendia promover.
Em um domínio personalizado, a verificação DNS e a emissão de certificado são requisitos adicionais. Em um endereço Anycast, o nó de borda que recebe a requisição pode estar em uma cidade diferente da carga de trabalho. O teste básico pela rota pública serve para verificar todo esse caminho, além da verificação de saúde local.
- —Use os logs de compilação para erros de empacotamento e compilação.
- —Use os logs de execução para erros de inicialização, dependências e saúde.
- —Use uma requisição HTTPS pública para investigar erros de TLS, rota e seleção de versão.
- —Registre o artefato de código-fonte e a versão junto da resposta pública.
Uma implantação está concluída quando as evidências são consistentes
O resultado útil de uma implantação vai além de uma URL. É uma cadeia que conecta código-fonte, compilação, versão de execução, resultado de prontidão, versão promovida e resposta pública. Quando os identificadores são consistentes, o desenvolvedor sabe o que está no ar e como recuperar. Quando divergem, o ponto onde as evidências deixam de se conectar indica a próxima investigação.