Imagens Distroless no Node.js contêm apenas o runtime e bibliotecas necessárias para executar a aplicação, sem shell, gerenciador de pacotes ou várias ferramentas comuns de uma distribuição Linux. Isso reduz tamanho e superfície de ataque, mas exige um processo de build e diagnóstico bem planejado.
Quando usar
Distroless é adequado para aplicações compiladas e previsíveis, com observabilidade externa e pipeline capaz de produzir todos os artefatos antes do runtime.
Dockerfile
FROM node:22-bookworm-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
RUN npm prune --omit=dev
FROM gcr.io/distroless/nodejs22-debian12:nonroot
WORKDIR /app
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./package.json
CMD ["dist/server.js"]Verifique o formato de CMD exigido pela imagem escolhida e fixe versão ou digest.
Sem shell
Comandos como sh, bash, curl e apt não estão disponíveis. Isso dificulta ataques que dependem dessas ferramentas, mas também muda a forma de investigar incidentes.
Debug
Mantenha uma variante de debug separada ou use containers efêmeros da plataforma. Não instale ferramentas de diagnóstico permanentemente na imagem de produção.
Certificados e timezone
Confirme se a imagem inclui certificados CA e dados de timezone necessários. Aplicações que dependem de arquivos específicos devem copiá-los explicitamente.
Addons nativos
Dependências nativas precisam ser compiladas para a mesma base ABI do runtime. Teste em CI e evite copiar binários produzidos em ambiente incompatível.
Usuário nonroot
Prefira a variante nonroot. Garanta que a aplicação não precise escrever no diretório do código e use volumes ou diretórios temporários autorizados.
Logs
Escreva logs estruturados em stdout e stderr. Não dependa de arquivos locais ou rotação dentro do container. Consulte Pino no Node.js.
Health checks
Como não existe curl, prefira probes HTTP executadas pela plataforma ou um endpoint de saúde. Não dependa de um comando shell dentro da imagem.
Segredos
Injete segredos em runtime pela plataforma. Nunca copie arquivos .env para a imagem. Veja Secret Management no Node.js.
SBOM e assinatura
Gere SBOM, escaneie a imagem e assine o artefato. Uma imagem menor não é automaticamente segura.
Multi-stage
Distroless depende de uma etapa anterior completa. Consulte Docker Multi-Stage no Node.js.
Erros comuns
- esperar um shell em produção;
- copiar dependências de base incompatível;
- não testar certificados;
- usar usuário root;
- não planejar debug;
- copiar segredos no build;
- assumir que imagem pequena dispensa scanner.
Conclusão
Imagens Distroless no Node.js reduzem componentes presentes no runtime e incentivam containers imutáveis. Elas funcionam melhor com multi-stage build, observabilidade externa, usuário não root e estratégia de debug separada.
Consulte a documentação oficial do Distroless e as boas práticas de multi-stage do Docker.
