Kustomize para Node.js

O Kustomize para Node.js mantém manifestos Kubernetes em YAML puro e aplica customizações por ambiente sem usar templates. Uma base descreve Deployment, Service, ConfigMap e HPA; overlays de desenvolvimento, homologação e produção adicionam patches, imagens, namespaces e configurações.

A vantagem é visualizar recursos próximos ao formato final da API do Kubernetes. O risco é criar overlays profundos e patches difíceis de rastrear. Uma estrutura simples, com bases estáveis e pequenas alterações por ambiente, torna o resultado previsível.

Neste guia, você aprenderá a organizar base e overlays, alterar imagem e réplicas, gerar ConfigMaps, aplicar patches, validar a saída, integrar com CI e evitar secrets no Git.

O que é Kustomize?

A documentação oficial de Kustomize no Kubernetes define a ferramenta como um mecanismo declarativo para customizar objetos por meio de um arquivo kustomization.yaml. O suporte está integrado ao kubectl:

kubectl kustomize overlays/production
kubectl apply -k overlays/production

Estrutura do projeto

k8s/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── hpa.yaml
│   └── kustomization.yaml
└── overlays/
    ├── development/
    │   ├── kustomization.yaml
    │   └── patch-deployment.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── patch-deployment.yaml
    └── production/
        ├── kustomization.yaml
        ├── patch-deployment.yaml
        └── patch-hpa.yaml

A base deve ser utilizável e segura. Overlays representam diferenças reais, não cópias completas.

Deployment base

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: orders-api
  template:
    metadata:
      labels:
        app: orders-api
    spec:
      containers:
        - name: api
          image: registry.example.com/orders-api:1.0.0
          ports:
            - name: http
              containerPort: 3000
          readinessProbe:
            httpGet:
              path: /health/ready
              port: http
          livenessProbe:
            httpGet:
              path: /health/live
              port: http
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 1
              memory: 512Mi

Veja Kubernetes Deployment no Node.js e Probes Kubernetes em Node.js.

Service base

apiVersion: v1
kind: Service
metadata:
  name: orders-api
spec:
  type: ClusterIP
  selector:
    app: orders-api
  ports:
    - name: http
      port: 80
      targetPort: http

Kustomization da base

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - hpa.yaml

commonLabels:
  app.kubernetes.io/name: orders-api
  app.kubernetes.io/managed-by: kustomize

Versões atuais também oferecem sintaxes de labels mais granulares. Fixe uma versão de kubectl e valide a compatibilidade no CI.

Overlay de produção

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: production
namePrefix: prod-

resources:
  - ../../base

images:
  - name: registry.example.com/orders-api
    newName: registry.example.com/orders-api
    newTag: 1.4.3

patches:
  - path: patch-deployment.yaml
  - path: patch-hpa.yaml

Kustomize atualiza referências conhecidas quando nomes recebem prefixo ou sufixo.

Patch do Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
spec:
  replicas: 3
  template:
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: api
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: 2
              memory: 1Gi

Mantenha patches pequenos. Um patch para recursos e outro para segurança são mais fáceis de revisar do que um arquivo que reescreve todo o Deployment.

Patch inline

patches:
  - target:
      kind: Deployment
      name: orders-api
    patch: |-
      - op: add
        path: /spec/template/spec/securityContext
        value:
          runAsNonRoot: true
          seccompProfile:
            type: RuntimeDefault

JSON Patch é preciso para listas e campos específicos. Verifique o caminho no YAML renderizado.

Alterando imagens

images:
  - name: registry.example.com/orders-api
    newTag: 1.4.4

Esse recurso evita patches apenas para a imagem. Em produção, prefira digest imutável quando o fluxo de entrega suportar.

ConfigMap generator

configMapGenerator:
  - name: orders-api-config
    literals:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info

Kustomize adiciona um hash ao nome gerado. O Deployment referencia o nome lógico:

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

Na saída, a referência recebe o mesmo sufixo. Quando o conteúdo muda, o nome muda e o Deployment inicia um rollout.

ConfigMap por arquivo

configMapGenerator:
  - name: orders-api-config
    envs:
      - application.env

Não coloque credenciais no arquivo. Consulte ConfigMaps e Secrets no Node.js.

Secret generator

secretGenerator:
  - name: orders-api-secrets
    envs:
      - secrets.env

O valor ainda fica em base64 no manifesto renderizado e pode aparecer no Git, terminal e CI. Para ambientes reais, use External Secrets, Sealed Secrets ou um cofre. Não versione secrets.env.

Generator options

generatorOptions:
  labels:
    app.kubernetes.io/part-of: orders-platform
  annotations:
    owner: backend-team

Evite disableNameSuffixHash: true sem necessidade, porque o hash ajuda a propagar mudanças de configuração.

HPA na base

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: orders-api
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: orders-api
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60

O overlay de produção pode aumentar limites:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: orders-api
spec:
  minReplicas: 3
  maxReplicas: 30

Veja Kubernetes HPA no Node.js.

Replacements

Replacements copiam valores entre recursos. Um caso é usar o nome de um Service em argumentos ou annotations. Use com moderação, pois muitas substituições escondem dependências.

replacements:
  - source:
      kind: Service
      name: orders-api
      fieldPath: metadata.name
    targets:
      - select:
          kind: Deployment
          name: orders-api
        fieldPaths:
          - spec.template.spec.containers.0.env.0.value

Components

Components representam recursos opcionais reutilizáveis, como um sidecar ou NetworkPolicy. Eles são úteis quando vários overlays compartilham um recurso opcional, mas não devem substituir bases claras.

Namespaces

namespace: production

Kustomize aplica namespace a recursos namespaced. Namespace, CRDs e recursos cluster-wide precisam de revisão especial.

Prefixo e sufixo

namePrefix: prod-
nameSuffix: -v1

Prefixos evitam colisões, mas podem quebrar integrações que esperam nomes fixos. Use labels e namespaces quando possível.

Annotations comuns

commonAnnotations:
  app.example.com/source-revision: "abc123"
  app.example.com/owner: "backend"

Metadados de commit, ambiente e owner ajudam na auditoria. Não inclua dados sensíveis.

Renderizando

kubectl kustomize k8s/overlays/production

Salve a saída em um arquivo temporário para validar:

kubectl kustomize k8s/overlays/production > rendered.yaml

Diff

kubectl diff -k k8s/overlays/production

O diff consulta o cluster e mostra mudanças. Em CI, controle acesso e não exponha Secrets.

Aplicando

kubectl apply -k k8s/overlays/production

Use um contexto e namespace explícitos. A pipeline deve acompanhar o rollout:

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

Validação no CI

kubectl kustomize k8s/overlays/production \
  | kubeconform -strict -summary

Adicione política e segurança:

kubectl kustomize k8s/overlays/production \
  | conftest test -

Confira APIs depreciadas antes de atualizar o cluster.

Teste de todos os overlays

for overlay in k8s/overlays/*; do
  kubectl kustomize "$overlay" | kubeconform -strict -summary
done

Um overlay pouco usado pode quebrar silenciosamente se não for renderizado no CI.

Remote bases

Kustomize aceita bases remotas, mas referências sem versão tornam builds não reproduzíveis. Fixe commit ou tag e considere espelhar dependências:

resources:
  - github.com/example/platform/base?ref=v1.3.0

Kustomize ou Helm?

Kustomize modifica YAML com bases e overlays. Helm gera recursos por templates e values, além de gerenciar releases. Kustomize é simples para poucas variações; Helm é útil para distribuir uma aplicação parametrizável. Consulte Helm para Node.js.

GitOps

Ferramentas GitOps conseguem aplicar diretórios Kustomize diretamente. O repositório registra a imagem desejada, patches e configuração. Evite mudanças manuais no cluster que gerem drift.

Segurança

• Não versione secrets em texto ou base64.
• Fixe versões de bases remotas.
• Valide imagens e digests.
• Revise recursos cluster-wide.
• Aplique policies no YAML renderizado.
• Restrinja a conta usada pela pipeline.
• Não permita patches que removam probes ou limites sem revisão.

Observabilidade

Inclua labels de ambiente, versão e serviço. Depois do apply, acompanhe Deployment, HPA, Pods, eventos, latência e erros. Kustomize produz manifests; ele não monitora a aplicação.

Erros comuns

• Overlays copiam tudo: a base deixa de ter valor.
• Patches gigantes: o resultado fica difícil de entender.
• Secret generator no Git: base64 não protege credenciais.
• Base remota sem ref: o build muda sozinho.
• Hash desativado: configuração muda sem rollout.
• Nome prefixado inesperado: integrações deixam de localizar o Service.
• Não renderizar no CI: erros aparecem apenas no deploy.
• Alteração manual no cluster: o estado diverge do repositório.

Conclusão

O Kustomize para Node.js organiza YAML Kubernetes em bases reutilizáveis e overlays por ambiente. Imagens, namespaces, recursos, HPA e configurações podem variar sem duplicar todos os manifestos.

Mantenha a base segura, crie patches pequenos e valide a saída final no CI. Proteja secrets, fixe dependências remotas e acompanhe rollouts. Assim, Kustomize mantém a configuração declarativa sem transformar YAML em uma coleção de cópias inconsistentes.