Helm na prática: como instalar, atualizar e reverter aplicações no Kubernetes

Aprenda Helm na prática: instalar o Helm 4, usar charts e values.yaml, atualizar, ver histórico e fazer rollback de aplicações no Kubernetes.

Para que serve

O Helm é o gerenciador de pacotes do Kubernetes. Um chart reúne todos os manifestos de uma aplicação (Deployment, Service, Ingress, PVC, ConfigMap) com variáveis que você ajusta em um arquivo values.yaml. Com ele, instalar o cert-manager, o Longhorn ou o Grafana vira um comando, e atualizar ou voltar uma versão também. Este artigo cobre o uso diário do Helm 4, lançado em novembro de 2025.

Pré-requisitos

• Cluster Kubernetes acessível pelo kubectl (veja Como instalar o k3s em servidor dedicado). O Helm usa o mesmo kubeconfig.
• Um repositório Git para guardar seus arquivos de values (recomendado).

Etapa 1: instalar o Helm

Na máquina de onde você administra o cluster (pode ser um nó servidor do k3s):

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
less get_helm.sh      # leia o script antes de executar
chmod 700 get_helm.sh
./get_helm.sh
helm version

Também há repositório APT oficial para Debian/Ubuntu, que facilita atualizar junto com o sistema (instruções na documentação do Helm). No nó do k3s, aponte o kubeconfig: export KUBECONFIG=/etc/rancher/k3s/k3s.yaml.

Etapa 2: encontrar e inspecionar um chart

Charts são distribuídos de duas formas: repositórios HTTP (helm repo add) e registries OCI (endereço oci://, sem precisar adicionar repositório). Como exemplo, usaremos o podinfo, uma aplicação de demonstração mantida pela comunidade Flux:

# ver os valores configuráveis do chart
helm show values oci://ghcr.io/stefanprodan/charts/podinfo > podinfo-defaults.yaml

# repositório HTTP: adicionar, atualizar índice e pesquisar
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm search repo jetstack --versions | head

Sempre leia o arquivo de valores padrão antes de instalar: é ali que estão réplicas, recursos, Ingress, persistência e senhas iniciais.

Etapa 3: instalar com um values.yaml próprio

Crie podinfo-values.yaml só com o que você quer mudar:

replicaCount: 2
resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    memory: 128Mi
ingress:
  enabled: true
  className: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: demo.seudominio.com.br
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: podinfo-tls
      hosts:
        - demo.seudominio.com.br

Instale fixando a versão do chart, em um namespace próprio:

helm upgrade --install podinfo oci://ghcr.io/stefanprodan/charts/podinfo \
  --version 6.15.0 \
  --namespace demo --create-namespace \
  -f podinfo-values.yaml \
  --wait --rollback-on-failure

O upgrade --install instala se não existir e atualiza se já existir, o que torna o mesmo comando seguro para usar em scripts. O --wait --rollback-on-failure espera os pods ficarem prontos e desfaz tudo se falhar. Troque 6.15.0 pela versão listada em helm show chart.

Para ver exatamente o que será aplicado, sem tocar no cluster, gere os manifestos:

helm template podinfo oci://ghcr.io/stefanprodan/charts/podinfo --version 6.15.0 -f podinfo-values.yaml | less

Etapa 4: atualizar, ver histórico e fazer rollback

helm list -A                              # todas as releases
helm -n demo get values podinfo           # values aplicados
helm -n demo history podinfo              # revisões
# mudou o values.yaml ou a versão? rode o mesmo upgrade --install
helm -n demo rollback podinfo 1           # volta para a revisão 1
helm -n demo uninstall podinfo            # remove a release

Antes de atualizar a versão de um chart, leia as notas de versão: mudanças de versão maior (ex.: 2.x para 3.x) costumam renomear valores ou exigir passos manuais. Faça backup antes (veja Backup de Kubernetes com etcd snapshot e Velero).

Etapa 5: deixar o k3s instalar charts sozinho (opcional)

O k3s tem um controlador de Helm embutido: um arquivo YAML do tipo HelmChart colocado em /var/lib/rancher/k3s/server/manifests/ é instalado e mantido automaticamente. Útil para componentes de base, como o cert-manager, que você quer recriados junto com o cluster:

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: cert-manager
  namespace: kube-system
spec:
  repo: https://charts.jetstack.io
  chart: cert-manager
  version: v1.21.2
  targetNamespace: cert-manager
  createNamespace: true
  valuesContent: |-
    crds:
      enabled: true

Não misture os dois métodos para a mesma aplicação: ou ela é gerida pelo helm na linha de comando, ou pelo arquivo no diretório de manifests.

Como saber se funcionou

helm -n demo status podinfo
kubectl -n demo get pods,svc,ingress
curl -s https://demo.seudominio.com.br | head

O status deve ser deployed, os pods Running e o endereço deve responder com o JSON do podinfo.

Problemas comuns

"another operation (install/upgrade/rollback) is in progress"

Uma operação anterior foi interrompida. Veja helm -n demo history podinfo; se a última revisão estiver em pending-upgrade, faça helm rollback para a última revisão deployed.

Imagens da Bitnami não baixam mais

Desde agosto de 2025 o catálogo gratuito da Bitnami foi reduzido, e muitas tags antigas foram movidas para um repositório legado sem atualizações. Charts que dependem dessas imagens podem falhar ou ficar desatualizados. Prefira charts mantidos pelo próprio projeto (cert-manager, Grafana, CloudNativePG, Gitea etc.).

Mudei o recurso com kubectl e o Helm desfez

O Helm considera o chart e os values como fonte da verdade. Faça a mudança no values.yaml e rode o upgrade.

Erro de CRD ao instalar

Alguns charts exigem um valor para instalar CRDs (como crds.enabled=true no cert-manager). Leia a documentação do chart.

Perguntas frequentes

Helm guarda senhas em texto puro?

Os values ficam em um Secret da release, codificados, mas acessíveis a quem tem permissão no namespace. Não versione senhas no Git: use Secrets criados à parte ou ferramentas como SOPS e External Secrets.

Preciso escrever meus próprios charts?

Não para começar. Quando suas aplicações tiverem vários ambientes, helm create minha-app gera um esqueleto para você adaptar.

Helm ou Kustomize?

Helm empacota e versiona aplicações de terceiros; Kustomize ajusta manifestos próprios sem templates. Muitas equipes usam os dois, e o Argo CD entende ambos.

Leitura complementar

• Usando o Helm (documentação oficial)
• Novidades do Helm 4
• Controlador de Helm do k3s

Precisa de ajuda?

Dúvidas sobre o servidor, a rede ou o acesso pelo IPMI/iLO podem ser enviadas por ticket. A configuração de charts e aplicações é feita por você, conforme este guia.