Kubernetes Deployment no Node.js

Um Kubernetes Deployment no Node.js mantém réplicas da aplicação, substitui Pods durante atualizações e permite acompanhar ou desfazer rollouts. Ele é o controlador mais comum para APIs e workers sem estado, porque descreve o estado desejado e deixa o cluster convergir até esse estado.

O Deployment não transforma automaticamente uma aplicação em um serviço resiliente. A imagem precisa iniciar corretamente, a API deve responder a sinais, os probes devem refletir a saúde real e os recursos precisam ser dimensionados. Sem isso, o controlador apenas recria Pods que continuam falhando.

Neste guia, você aprenderá a criar um Deployment para Node.js, definir réplicas, selectors, strategy, probes, recursos, variáveis, segurança, rollout, rollback, histórico e práticas para evitar indisponibilidade.

O que é um Deployment?

A documentação oficial de Deployments no Kubernetes define o recurso como um controlador que gerencia Pods e ReplicaSets de forma declarativa. Quando o template do Pod muda, um novo ReplicaSet é criado e o antigo é reduzido de acordo com a estratégia configurada.

O Deployment é adequado para aplicações sem estado persistente no filesystem local. Bancos e serviços com identidade estável normalmente usam StatefulSet.

Manifesto básico

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
  namespace: production
  labels:
    app.kubernetes.io/name: orders-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: orders-api
  template:
    metadata:
      labels:
        app.kubernetes.io/name: orders-api
    spec:
      containers:
        - name: api
          image: registry.example.com/orders-api:1.4.2
          ports:
            - name: http
              containerPort: 3000

O selector do Deployment precisa corresponder às labels do template. Esse selector é imutável depois da criação; planeje labels antes de publicar.

Use imagens imutáveis

Evite tags como latest. Use uma versão ou digest:

image: registry.example.com/orders-api@sha256:abc123...

Uma imagem imutável torna o rollback previsível e permite provar exatamente qual artefato foi executado. Veja Docker Multi-stage para Node.js.

Réplicas

spec:
  replicas: 3

Três réplicas toleram a indisponibilidade de um Pod sem eliminar toda a capacidade. O número real depende de tráfego, limites, zonas e orçamento. Uma única réplica não oferece continuidade durante rollout ou manutenção de nó.

RollingUpdate

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 0
    maxSurge: 1

maxUnavailable: 0 tenta preservar todas as réplicas disponíveis durante a atualização. maxSurge: 1 permite um Pod adicional temporário. Isso reduz risco de indisponibilidade, mas exige capacidade extra no cluster.

Os valores devem considerar o tempo de inicialização, os recursos do Pod e a quantidade de réplicas. Em cargas grandes, porcentagens podem ser mais adequadas.

Recreate

strategy:
  type: Recreate

Recreate encerra os Pods antigos antes de iniciar os novos. Essa estratégia causa indisponibilidade e deve ser reservada a casos em que duas versões não podem coexistir.

Readiness probe

readinessProbe:
  httpGet:
    path: /health/ready
    port: http
  initialDelaySeconds: 2
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 3

O Pod só recebe tráfego quando a readiness passa. O endpoint deve verificar se a aplicação consegue atender requisições, sem realizar operações lentas ou dependências irrelevantes.

Consulte Probes Kubernetes em Node.js.

Liveness probe

livenessProbe:
  httpGet:
    path: /health/live
    port: http
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3

Liveness responde se o processo está irrecuperavelmente travado. Não inclua banco, fila e APIs externas nesse teste, porque uma falha remota faria o Kubernetes reiniciar todos os Pods sem corrigir a causa.

Startup probe

startupProbe:
  httpGet:
    path: /health/live
    port: http
  periodSeconds: 2
  failureThreshold: 30

Startup oferece até sessenta segundos para a aplicação iniciar antes de liveness começar. Isso evita reinícios durante warm-up, carregamento de módulos ou conexão inicial.

Requests e limits

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 1
    memory: 512Mi

Requests influenciam scheduling; limits restringem consumo. Memória insuficiente causa OOMKilled. CPU limitada pode gerar throttling e aumentar a latência do event loop.

A documentação de recursos de containers explica como requests e limits são aplicados. Meça heap, Buffers, código nativo e overhead, não apenas heapUsed.

ConfigMap e Secret

envFrom:
  - configMapRef:
      name: orders-api-config
  - secretRef:
      name: orders-api-secrets

Configurações públicas podem ficar em ConfigMap. Credenciais devem vir de Secret ou de um provedor externo. Veja ConfigMaps e Secrets no Node.js.

ServiceAccount

serviceAccountName: orders-api
automountServiceAccountToken: false

Desative o token quando a aplicação não acessa a API do Kubernetes. Se precisar, crie uma ServiceAccount específica e conceda apenas as permissões necessárias.

Security context

securityContext:
  runAsNonRoot: true
  runAsUser: 10001
  seccompProfile:
    type: RuntimeDefault
containers:
  - name: api
    securityContext:
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: true
      capabilities:
        drop: ["ALL"]

O container Node.js normalmente não precisa de root, privilégios ou capabilities adicionais. Monte um volume temporário somente para os diretórios graváveis.

Filesystem temporário

volumeMounts:
  - name: tmp
    mountPath: /tmp
volumes:
  - name: tmp
    emptyDir:
      sizeLimit: 128Mi

Não armazene uploads ou dados críticos em emptyDir. O conteúdo desaparece quando o Pod é substituído.

Graceful shutdown

terminationGracePeriodSeconds: 30

Quando um Pod é removido, o kubelet envia SIGTERM. A aplicação deve:

1. marcar readiness como falsa;
2. parar de aceitar novas requisições;
3. concluir requisições em andamento;
4. parar consumidores de fila;
5. fechar conexões;
6. sair antes do período terminar.

Consulte Graceful Shutdown no Node.js.

preStop

lifecycle:
  preStop:
    exec:
      command: ["sh", "-c", "sleep 5"]

Uma pequena espera pode permitir que alterações de endpoints se propaguem antes de o processo parar. Ela consome o mesmo período de terminação; não use como substituto para shutdown correto.

MinReadySeconds

minReadySeconds: 10

Uma réplica precisa permanecer pronta durante esse intervalo antes de ser considerada disponível. Isso ajuda a detectar processos que passam readiness e falham imediatamente.

ProgressDeadlineSeconds

progressDeadlineSeconds: 600

O Deployment registra falha de progresso quando o rollout não avança dentro do prazo. O controlador não executa rollback automático por padrão; a pipeline precisa observar o status e decidir.

Histórico

revisionHistoryLimit: 5

Limitar ReplicaSets antigos reduz objetos acumulados. Mantenha revisões suficientes para rollback operacional.

Publicando uma versão

kubectl set image deployment/orders-api \
  api=registry.example.com/orders-api:1.4.3 \
  -n production

Em GitOps, altere o manifesto no repositório em vez de editar diretamente o cluster.

Acompanhando o rollout

kubectl rollout status deployment/orders-api \
  -n production \
  --timeout=5m

A pipeline deve falhar se o comando atingir timeout. Não considere o deploy concluído apenas porque o kubectl apply retornou sucesso.

Diagnóstico

kubectl get deployment orders-api -n production
kubectl describe deployment orders-api -n production
kubectl get rs -n production
kubectl get pods -l app.kubernetes.io/name=orders-api -n production
kubectl events -n production --for deployment/orders-api

Investigue ImagePullBackOff, CrashLoopBackOff, probes, falta de recursos, quotas e permissões.

Rollback

kubectl rollout history deployment/orders-api -n production
kubectl rollout undo deployment/orders-api -n production
kubectl rollout undo deployment/orders-api \
  --to-revision=7 \
  -n production

Rollback altera o template do Pod. Ele não reverte migrations, mensagens já processadas ou mudanças externas. Use compatibilidade entre versões e estratégias de banco seguras.

Pause e resume

kubectl rollout pause deployment/orders-api -n production
kubectl rollout resume deployment/orders-api -n production

Pause permite acumular alterações antes de iniciar o rollout. Evite deixar Deployments pausados sem monitoramento.

PodDisruptionBudget

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: orders-api
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: orders-api

O PDB reduz indisponibilidade em interrupções voluntárias, como drain de nó. Ele não impede falhas de hardware nem substitui réplicas distribuídas.

Distribuição entre nós

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        app.kubernetes.io/name: orders-api

Espalhar Pods evita concentrar todas as réplicas no mesmo nó. Para alta disponibilidade regional, considere zonas.

Deploy canário

Um Deployment comum executa rolling update, mas não controla porcentagem de tráfego com precisão. Para canário, use dois Deployments ou uma ferramenta de progressive delivery. Veja Canary Deploy no Node.js.

Observabilidade

Durante o rollout, monitore:

• réplicas desired, updated, ready e available;
• reinícios e OOMKilled;
• falhas de readiness e liveness;
• latência e taxa de erro por versão;
• event loop lag;
• CPU e memória;
• fila e conexões abertas;
• tempo total do rollout.

Associe versão, digest e revision aos logs e traces.

Erros comuns

• Selector inconsistente: o Deployment não gerencia os Pods esperados.
• Latest: o mesmo manifesto executa artefatos diferentes.
• Sem readiness: tráfego chega antes da inicialização.
• Liveness depende do banco: uma falha externa reinicia toda a aplicação.
• Uma réplica: rollout pode interromper o serviço.
• Sem recursos: scheduling e capacidade ficam imprevisíveis.
• Ignorar SIGTERM: requisições e jobs são interrompidos.
• Rollback sem considerar banco: a versão anterior não entende o schema novo.

Conclusão

O Kubernetes Deployment no Node.js oferece réplicas, rollout declarativo, histórico e rollback para APIs e workers sem estado. A segurança do processo depende de imagens imutáveis, probes corretos, recursos, labels e shutdown gracioso.

Comece com pelo menos duas réplicas, rolling update conservador e observabilidade do rollout. Distribua Pods, limite privilégios e teste rollback junto com mudanças de banco. Assim, o Deployment deixa de ser apenas um YAML e se torna um mecanismo controlado de entrega.