Gerador de Helm values.yaml

Helm values.yaml a fundo: charts, templates, overrides e boas práticas

O Helm é o package manager de facto do Kubernetes. Em vez de escrever dezenas de manifests YAML crus à mão e copiar entre ambientes, você empacota tudo num chart — um diretório com Chart.yaml (metadados), values.yaml (defaults) e uma pasta templates/ cheia de manifests templated em Go. Instalar um chart vira um comando: helm install minha-release ./mychart -f prod-values.yaml.

O arquivo values.yaml é a superfície de configuração do chart. Usuários sobrescrevem defaults no momento do install/upgrade com --set image.tag=2.0 ou, mais limpo, com um YAML próprio via -f meu-values.yaml. Múltiplos arquivos mesclam da esquerda para direita, então o último vence.

Anatomia de um chart

mychart/
├── Chart.yaml          # nome, version, appVersion, dependencies
├── values.yaml         # configuração default
├── values.schema.json  # JSON Schema (opcional, recomendado)
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── _helpers.tpl    # snippets reutilizáveis
│   └── NOTES.txt       # impresso após install
└── charts/             # sub-charts (dependências)

Sintaxe Go template que você vai usar

• {{ .Values.image.tag }} — lê uma chave do values.yaml.
• {{ .Release.Name }}, {{ .Release.Namespace }}, {{ .Chart.Version }} — objetos built-in.
• {{- if .Values.ingress.enabled }}...{{- end }} — blocos condicionais (os hífens removem whitespace ao redor).
• {{- range .Values.envVars }}...{{- end }} — itera sobre lista.
• {{ include "common.labels" . | nindent 4 }} — chama um template nomeado definido em _helpers.tpl e indenta a saída em 4 espaços.
• {{ .Values.image.tag | default .Chart.AppVersion | quote }} — pipelines: cai para AppVersion, depois envolve em aspas.

Padrões comuns de values

replicaCount: 2

image:
  repository: nginx
  tag: "1.27"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: nginx
  hosts:
    - host: app.example.com
      paths: [{ path: /, pathType: Prefix }]
  tls: []

resources:
  limits:   { cpu: 500m, memory: 512Mi }
  requests: { cpu: 100m, memory: 128Mi }

nodeSelector: {}
tolerations: []
affinity: {}

Sub-charts e dependências

Um chart pode depender de outros (declarados em Chart.yaml sob dependencies, baixados com helm dependency update). O pai passa config para baixo aninhando uma chave com o nome do sub-chart: postgresql: { auth: { password: changeme } } sobrescreve values no chart PostgreSQL embarcado. Use global: para values compartilhados por todos os sub-charts.

Hooks e ciclo de vida

Anote um template com "helm.sh/hook": pre-install (ou post-install, pre-upgrade, post-delete, test) para o Helm rodá-lo no momento certo. Uso clássico: um Job que roda migrations de banco antes do novo Deployment subir. Combine com "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded para limpar hooks antigos.

Boas práticas

• Sempre fixe versões de chart em CI (--version 1.4.2); nunca confie em "latest".
• Valide antes de aplicar: helm lint, depois helm template ou helm install --dry-run --debug para ver o YAML renderizado.
• Distribua um values.schema.json — o Helm valida no install, pegando typos antes de chegar no cluster.
• Prefira arquivos de values (-f prod.yaml) a cadeias longas de --set; arquivos são revisáveis e versionados.
• Mantenha segredos fora do values.yaml — use sealed-secrets, external-secrets-operator ou um plugin Helm secrets (helm-secrets + SOPS).
• Fatore blocos repetidos de labels/selectors em _helpers.tpl e use include — reduz drift drasticamente.

FAQ

Como faço rollback de uma release ruim? helm rollback minha-release N onde N é a revision (ache com helm history minha-release). O Helm mantém as últimas 10 revisions por default.

Arquivos de values ou flags --set? Arquivos, quase sempre. Arquivos são revisáveis, dão diff e ficam em git. --set serve para overrides pontuais em CI (--set image.tag=$SHA).

Helm vs Kustomize — qual ganha? Ferramentas diferentes. Helm é template-e-pacote (bom pra distribuir apps reutilizáveis). Kustomize é overlay (bom pra patches por ambiente em cima de uma base). Muitos times usam ambos: Helm para instalar charts terceiros, Kustomize para mexer em manifests da casa.

O que mudou do Helm v3 pro v2? O v3 removeu o Tiller (componente cluster-side que precisava de RBAC amplo), fez releases por namespace e adotou validação JSON Schema nativa. Qualquer coisa ainda no v2 precisa migrar — v2 não tem mais suporte.

Meu template renderiza string vazia em algum ponto — o que está errado? Geralmente typo no path do value. helm template . --debug mostra o YAML renderizado e o erro. Atenção também a blocos {{- with .Values.foo }}: se .Values.foo é nil eles pulam silenciosamente.