Curso Kubernetes 21 — Helm: empacotando a aplicação

Até aqui a gente aplicou manifests na mão. Funciona para aprender, não escala: cada ambiente vira uma cópia com diferenças invisíveis, e ninguém sabe qual versão está rodando.

Helm resolve o problema de empacotar e versionar o deploy. Não é mágica — é template + values + um registro de releases.

Selo do curso: testado em Kubernetes 1.35 com Helm 3.

O problema real

Sem Helm, três ambientes costumam virar três pastas:

k8s/
  homolog/deployment.yaml
  prod/deployment.yaml
  staging/deployment.yaml

Diferenças: imagem, réplicas, recursos, variáveis. Um dia alguém corrige só em prod e o resto fica errado. É o começo do drift.

Com Helm:

chart/
  Chart.yaml
  values.yaml
  values-homolog.yaml
  values-prod.yaml
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl

Um template, três conjuntos de valores.

Estrutura mínima

Chart.yaml:

apiVersion: v2
name: portal
description: Portal Nyverra
type: application
version: 1.4.0
appVersion: "v5"

• version: versão do chart.
• appVersion: versão da aplicação (imagem).

São coisas diferentes. Confunda as duas e você perde a rastreabilidade.

Templates e values

values.yaml (padrões):

replicaCount: 2
image:
  repository: ghcr.io/example/portal-backend
  tag: v5
  pullPolicy: IfNotPresent
resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi
env:
  LOG_LEVEL: info

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "portal.fullname" . }}
  labels:
    {{- include "portal.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "portal.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "portal.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: backend
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
          env:
            {{- range $k, $v := .Values.env }}
            - name: {{ $k }}
              value: {{ $v | quote }}
            {{- end }}

_helpers.tpl centraliza nomes e labels. Sem isso, cada template inventa um nome diferente e o kubectl get vira arqueologia.

Values por ambiente

values-prod.yaml:

replicaCount: 4
image:
  tag: v5
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "2"
    memory: 1Gi

Renderize sem aplicar:

helm template portal ./chart -f values-prod.yaml
helm template portal ./chart -f values-prod.yaml --show-only templates/deployment.yaml

Sempre revise o render antes do install. É o --dry-run do Helm.

Install, upgrade, rollback

helm upgrade --install portal ./chart -n portal --create-namespace -f values-prod.yaml
helm list -n portal
helm status portal -n portal
helm history portal -n portal
helm rollback portal 3 -n portal

O Helm guarda releases como Secrets no namespace (sh.helm.release.v1.portal.v1). Não apague no dedo.

Hooks

Hooks rodam em momentos do ciclo:

• pre-install / pre-upgrade: migrations de banco.
• post-install / post-upgrade: smoke test.
• pre-delete: limpeza.

metadata:
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation

Cuidado: migration em hook roda antes do rollout. Se a nova versão do código depende da migration, ok. Se a migration quebra a versão antiga, você tem uma janela de erro.

O que não colocar no chart

• Segredos reais em values.yaml (use External Secrets ou secret manager).
• Credenciais de registry em texto.
• Configuração que muda por cluster e deveria ser GitOps (capítulo 22).

Laboratório

1. Crie o chart:

helm create portal
rm -rf portal/templates/tests

2. Ajuste values.yaml, _helpers.tpl e os templates.
3. Renderize e compare ambientes:

helm template portal ./portal -f values-homolog.yaml > /tmp/homolog.yaml
helm template portal ./portal -f values-prod.yaml > /tmp/prod.yaml
diff /tmp/homolog.yaml /tmp/prod.yaml

4. Instale em homolog e faça um upgrade com --atomic:

helm upgrade --install portal ./portal -n portal --create-namespace \
  -f values-homolog.yaml --atomic --timeout 5m

5. Force uma falha (imagem inexistente) e observe o --atomic reverter sozinho.
6. helm rollback manual e confira helm history.

Erros comuns

Sintoma	Causa
rendered manifests contain a resource that already exists	recurso criado fora do Helm
Upgrade travado em pending-upgrade	hook/rollout falhou sem timeout
Valores ignorados	-f na ordem errada ou typo na chave
nil pointer evaluating interface	chave ausente no values
Drift silencioso	recurso editado na mão depois do install
Rollback não volta a imagem	appVersion divergente do tag
Secret vazado no Git	valor sensível em values.yaml

Checklist

• [ ] Chart.yaml com version e appVersion coerentes.
• [ ] _helpers.tpl para nomes e labels.
• [ ] values-<env>.yaml por ambiente.
• [ ] helm template revisado antes do upgrade.
• [ ] --atomic e --timeout no upgrade.
• [ ] Recursos (requests/limits) vindos de values.
• [ ] Nenhum segredo em texto no chart.
• [ ] helm history e rollback testados.

Glossário

• chart: pacote Helm.
• release: instância de um chart no cluster.
• values: parâmetros do template.
• hook: recurso executado em fase do ciclo.
• atomic: reverte automaticamente em falha.
• drift: diferença entre o declarado e o que roda.

Próximo

Chart empacotado. Agora quem aplica o chart no cluster? No próximo capítulo, GitOps com ArgoCD: o Git como fonte de verdade e o cluster se corrigindo sozinho.

Próximo: Curso Kubernetes 22 — GitOps com ArgoCD