Dockerfiles enxutos e pontos de entrada do Shell

Em ambientes de produção, cada megabyte em uma imagem Docker tem um custo: downloads mais lentos, superfícies de ataque maiores e espaço desperdiçado no registro. Dockerfiles enxutos, combinados com scripts robustos de ponto de entrada no interpretador de comandos, são uma característica de uma prática madura de DevOps.

• Compilações em várias etapas separam as ferramentas usadas durante a compilação da imagem final de execução, reduzindo drasticamente o tamanho.
• Adaptadores de ponto de entrada são pequenos scripts de interpretador de comandos que inicializam contêineres: eles geram arquivos de configuração a partir de modelos, validam variáveis de ambiente, tratam sinais e, por fim, executam o processo principal.
• Juntos, eles formam a base de cargas de trabalho de contêineres confiáveis e portáveis no Kubernetes, no ECS e em ambientes de servidores físicos.

Esta lição aborda ambas as práticas de ponta a ponta, com padrões prontos para produção que você pode inserir diretamente em seus pipelines.

Um Dockerfile com várias etapas usa várias instruções FROM. Cada etapa é um conjunto isolado de camadas; você copia apenas os artefatos necessários para a etapa seguinte.

• Etapa 0 (compilador): instala compiladores, executores de testes e dependências de compilação.
• Etapa 1 (execução): começa com uma base mínima (por exemplo, alpine, distroless) e copia apenas binários compilados ou pacotes da aplicação.
• A imagem final nunca contém gcc, make ou código-fonte, a menos que você os copie explicitamente.

Use --from=<stage> em COPY para copiar arquivos entre os limites das etapas. Dê nomes às etapas com AS <name> para facilitar a leitura e permitir a seleção específica com docker build --target.

Cada instrução RUN, COPY e ADD cria uma nova camada. Instruções mal ordenadas invalidam o cache da compilação sem necessidade, tornando lentos os pipelines de CI.

• Copie os manifestos de dependências (package.json, go.mod, requirements.txt) antes de copiar o código-fonte, para que a instalação das dependências seja armazenada em cache de forma independente.
• Encadeie comandos relacionados com && e faça a limpeza na mesma camada RUN para evitar deixar o cache de pacotes em camadas intermediárias.
• Use --no-cache nos gerenciadores de pacotes e remova os arquivos de listas após a instalação.

Registros privados, chaves SSH e tokens de API nunca devem aparecer nas camadas da imagem. O Docker BuildKit oferece dois mecanismos seguros:

• --secret: monta um arquivo secreto dentro de uma única etapa RUN, sem incorporá-lo a uma camada. Acesse-o por meio de /run/secrets/<id>.
• --ssh: encaminha o soquete do agente SSH do host para a compilação, para que git clone possa se autenticar sem incorporar chaves privadas.

Ative o BuildKit com DOCKER_BUILDKIT=1 ou por meio de docker buildx build. A diretiva # syntax=docker/dockerfile:1 habilita esses recursos.

O adaptador de ponto de entrada é um script de interpretador de comandos definido como ENTRYPOINT no Dockerfile. Sua função é preparar o ambiente de execução antes de transferir o controle ao processo principal.

Um adaptador bem estruturado segue esta ordem:

• Etapa 1: Defina set -euo pipefail para que qualquer falha interrompa a execução imediatamente.
• Etapa 2: Valide as variáveis de ambiente obrigatórias e falhe rapidamente com uma mensagem útil.
• Etapa 3: Gere arquivos de configuração a partir de modelos com base nas variáveis de ambiente.
• Etapa 4: Registre manipuladores de sinais para um encerramento normal.
• Etapa 5: exec "$@" — substitua o interpretador de comandos pelo processo principal, para que o PID 1 seja a aplicação, e não o adaptador.

O exec final é fundamental: sem ele, os sinais enviados pelo Kubernetes ou pelo ambiente de execução do Docker não são encaminhados ao processo filho.

envsubst (do pacote GNU gettext, presente no Alpine como gettext) substitui os marcadores ${VAR} em um arquivo de modelo pelos valores atuais das respectivas variáveis de ambiente.

• Inclua um modelo de configuração *.tmpl na imagem; o ponto de entrada o renderiza na inicialização.
• Informe explicitamente a lista de variáveis a envsubst, para que ele não expanda acidentalmente cifrões não relacionados (por exemplo, em uma expressão regular do nginx).
• Grave o arquivo renderizado em um caminho gravável, como /tmp, ou em um volume de configuração dedicado.

Os contêineres recebem SIGTERM quando são interrompidos pelo Kubernetes, pelo ECS ou por docker stop. Se o adaptador de ponto de entrada for o PID 1 e não encaminhar os sinais, o processo principal será encerrado com SIGKILL após o período de tolerância — causando perda de solicitações ou corrupção de dados.

• Use trap para capturar SIGTERM e SIGINT no adaptador.
• Encaminhe o sinal ao PID filho usando kill -TERM "$child".
• Use wait "$child" para bloquear até o encerramento do filho e, em seguida, repasse o código de saída dele.
• Como alternativa, use exec para substituir completamente o interpretador de comandos — assim, o sistema operacional entrega os sinais diretamente ao processo filho, sem necessidade de trap. Esse é o padrão preferido para casos simples.

Quando o contêiner cria processos filhos (por exemplo, um interpretador de comandos que cria trabalhadores), você precisa de uma inicialização real para recolher processos zumbis. tini é um pequeno binário de inicialização desenvolvido especificamente para contêineres.

• Adicione tini à imagem e defina-o como o adaptador do ponto de entrada.
• Ele recolhe processos filhos zumbis, encaminha sinais corretamente e encerra com o código de status do filho.
• O Docker inclui um tini integrado, ativado com docker run --init, mas incorporá-lo à imagem garante um comportamento consistente entre os ambientes de execução (Kubernetes, ECS etc.).

Contêineres executados como root (UID 0) representam um grande risco de segurança: uma fuga do contêiner concede acesso total ao host. Sempre mude para um usuário sem privilégios antes de executar o processo principal.

• Crie um usuário e um grupo de sistema dedicados no Dockerfile com addgroup / adduser (Alpine) ou groupadd / useradd (Debian).
• Altere o proprietário dos arquivos da aplicação com COPY --chown=appuser:appgroup — isso é mais eficiente do que uma camada RUN chown separada.
• Troque para o usuário com a instrução USER. O ponto de entrada e o CMD herdam esse usuário.
• securityContext.runAsNonRoot: true do Kubernetes se recusará a iniciar uma imagem que ainda seja executada como root.

As sondas de atividade e prontidão do Kubernetes são definidas nos manifestos, mas você também pode incorporar um HEALTHCHECK ao Dockerfile para ambientes autônomos de docker run e Docker Compose.

• HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 CMD ...
• Use curl --fail ou wget -qO- para serviços HTTP; para processos do sistema que não usam HTTP, verifique um soquete com /dev/tcp/localhost/PORT.
• Instale apenas o necessário: em imagens distroless, evite adicionar curl apenas para verificações de integridade — use um binário de sondagem específico ou o próprio binário de integridade da aplicação.

A seguir, há um adaptador de ponto de entrada completo e pronto para produção, que combina todos os padrões desta lição: validação do ambiente, geração de configurações a partir de modelos, encaminhamento de sinais e transferência com exec. Esse padrão é usado em microsserviços reais de Node.js, Python e Go implantados no Kubernetes.

• Cada seção é comentada para servir como um modelo autoexplicativo.
• O adaptador tem menos de 50 linhas — os pontos de entrada devem ser simples e fáceis de auditar.
• Observe o exec "$@" final: depois que toda a configuração estiver concluída, o interpretador de comandos é substituído pelo processo da aplicação, que se torna o PID 1 e recebe diretamente todos os sinais do sistema operacional.

Teste sua compreensão sobre o tratamento de sinais em scripts de ponto de entrada de contêineres.

Você abordou toda a estrutura da criação de contêineres para produção:

• Compilações em várias etapas usam várias instruções FROM para manter compiladores e ferramentas de compilação fora da imagem final, produzindo camadas de execução enxutas e mínimas.
• Ordenação das camadas — copie os manifestos de dependências antes do código-fonte — maximiza os acertos do cache e acelera os pipelines de CI.
• Segredos e montagens SSH do BuildKit mantêm as credenciais fora do histórico da imagem sem interromper compilações autenticadas.
• Adaptadores de ponto de entrada validam variáveis de ambiente, geram arquivos de configuração a partir de modelos com envsubst e transferem o controle para a aplicação por meio de exec "$@".
• O tratamento de sinais exige exec (para que a aplicação seja o PID 1) ou um padrão explícito de trap + kill + wait quando são usados trabalhos em segundo plano.
• tini adiciona o recolhimento de processos zumbis e o encaminhamento correto de sinais quando o contêiner cria vários processos.
• Usuários não root e instruções HEALTHCHECK completam uma imagem segura e observável, pronta para cargas de trabalho de produção no Kubernetes.

Combine esses padrões de forma consistente e suas imagens serão menores, mais rápidas de implantar e significativamente mais robustas em condições de produção.