Google Cloud Platform > Kubernetes > Helm Package Manager

Desvendando o Helm

Aprenda por que o Helm foi criado, entenda a analogia da forma de bolo e veja na prática como ele gerencia o HairTime em Homologação e Produção.

Praticar no Cloud Shell →

#01A Dor: O Inferno dos YAMLs Duplicados

Imagine que a sua empresa possui uma aplicação (ex: HairTime API) e você precisa rodá-la em três ambientes: Desenvolvimento, Homologação e Produção.

✕ Sem Helm (Cópia e Cola Manual)

Você precisa de 3 arquivos deployment.yaml e 3 service.yaml quase idênticos.
A única diferença são 3 linhas: imagem Docker, memória e domínio do Ingress.
Adicionar uma variável nova exige editar todos os arquivos na mão.
Um erro de indentação em um dos arquivos derruba o ambiente.

✓ Com Helm (Parametrização Inteligente)

Você cria 1 único modelo genérico (Template) para a aplicação.
Cria um arquivo pequeno chamado values-hml.yaml e outro values-prod.yaml.
O Helm substitui as variáveis automaticamente e aplica no cluster.
Zero código duplicado e 100% à prova de inconsistências.

#02A Analogia da Forma de Bolo

Como entender a estrutura do Helm em 1 minuto:

Pense em um Helm Chart como uma confeitaria:

1. A Forma de Bolo (Templates)

É a pasta templates/. Ela define o formato exato da massa (Deployment, Service, Ingress), mas deixa buracos abertos para os recheios.

2. Os Ingredientes (values.yaml)

É o arquivo values.yaml. Ele diz qual é o sabor: para HML usamos 1 réplica; para Produção usamos 2 réplicas com alta disponibilidade!

#03Anatomia Visual de um Helm Chart

Veja abaixo como os arquivos conversam entre si na prática:

Chart.yaml (A Etiqueta)

Metadados de identificação do pacote: nome do chart, versão do chart (SemVer) e versão do app que ele empacota.

apiVersion: v2
name: hairtime-api
description: Helm chart corporativo para a API HairTime
version: 1.0.0      # Versão do pacote Helm
appVersion: "2.4.0" # Versão do software (Docker image)

values.yaml (A Lista de Ingredientes)

Onde você coloca todas as variáveis que mudam por ambiente. Em vez de mexer no YAML complexo, você altera apenas este arquivo simples!

# Número de instâncias desejadas
replicaCount: 2

# Imagem Docker a ser executada
image:
  repository: registry.gitlab.com/12labs/hairtime
  tag: "v2.4.0"
  pullPolicy: IfNotPresent

# Porta do container
service:
  type: ClusterIP
  port: 8000

# Rota pública de internet
ingress:
  enabled: true
  host: api-hml.12labs.app

templates/deployment.yaml (A Forma de Bolo)

O manifesto do Kubernetes parametrizado. Onde antes havia valores fixos, agora temos {{ .Values.chave }}. O Helm preenche automaticamente na hora de aplicar!

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}
    spec:
      containers:
      - name: api
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: {{ .Values.service.port }}

#04Os Comandos Essenciais do Dia a Dia

Auditoria Completahelm list -A

Lista todas as aplicações instaladas pelo Helm no cluster, mostrando a revisão atual e o status (deployed/failed).

O Comando de Ouro de CI/CD (Idempotente)helm upgrade --install <release> <chart> -f values.yaml

Instala se não existir, ou atualiza se já existir. Nunca dá erro de duplicidade.

O Botão de Emergência (Undo)helm rollback <release> <revisão>

Deu erro em produção após o deploy? O rollback desfaz a mudança e restaura a versão estável em menos de 5 segundos.

Simulação de Renderizaçãohelm template <release> <chart> -f values.yaml

Gera e imprime os YAMLs finais na tela sem aplicar no cluster. Perfeito para testes sintáticos e revisão de diffs.

Verificação de Boas Práticashelm lint <chart>

Analisa a sintaxe e a formatação dos templates do chart para alertar sobre erros antes de enviar ao cluster.

#05Como o Helm se Conecta ao GitOps com ArgoCD?

Zero Comandos Manuais em Produção!

Em empresas com cultura madura de DevOps (como na 12labs), você não roda helm install manualmente na linha de comando de produção.

O ArgoCD fica vigiando o seu repositório Git. Quando você comita uma alteração no values.yaml (por exemplo, subindo a tag da imagem Docker de v2.3 para v2.4), o ArgoCD renderiza o Helm Chart automaticamente e aplica no cluster sem intervenção humana manual.

#06

Caso Real 12labs: Como o Helm é Aplicado no HairTime

Vamos ver como o ecossistema real da 12labs aplica o Helm para gerenciar a aplicação HairTime (FastAPI + Next.js) nos ambientes de Homologação (hairtime-hml) e Produção (hairtime-prod) rodando na nossa VM OCI:

1. Estrutura do Helm Chart no Repositório (charts/hairtime)

Em vez de manter dezenas de manifests repetidos, o HairTime possui uma pasta de chart unificada:

charts/hairtime/
├── Chart.yaml              # Metadados do pacote (name: hairtime, version: 1.0.0)
├── values-hml.yaml         # Ingredientes de HML (api-hml.12labs.app, 1 réplica)
├── values-prod.yaml        # Ingredientes de PRD (api.12labs.app, 2 réplicas)
└── templates/
    ├── api-deployment.yaml # Template parametrizado da API Python
    ├── api-service.yaml    # Service interno ClusterIP
    └── ingress.yaml        # Ingress com Traefik e Let's Encrypt SSL

2. Os Arquivos de Valores: values-hml.yaml vs. values-prod.yaml

O código da infraestrutura é 100% reutilizado. Apenas os valores mudam:

values-hml.yamlHML (Homologação)

environment: hml
replicaCount: 1

image:
  repository: registry.gitlab.com/12labs/hairtime/backend
  tag: hml-latest
  pullPolicy: Always

ingress:
  host: api-hml.12labs.app
  tls:
    secretName: hairtime-hml-tls

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

database:
  host: postgres-hml
  name: hairtime_hml

values-prod.yamlPRD (Produção)

environment: prod
replicaCount: 2  # Alta Disponibilidade

image:
  repository: registry.gitlab.com/12labs/hairtime/backend
  tag: v2.4.0      # Tag imutável
  pullPolicy: IfNotPresent

ingress:
  host: api.12labs.app
  tls:
    secretName: hairtime-prod-tls

resources:
  requests:
    cpu: 250m
    memory: 512Mi
  limits:
    cpu: 1000m
    memory: 1024Mi

database:
  host: postgres-prod
  name: hairtime

3. Como o Template Preenche os Valores (templates/ingress.yaml)

Repare como o mesmo template atende tanto a HML quanto PRD através da sintaxe {{ .Values.ingress.host }}:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}-ingress
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  rules:
  - host: {{ .Values.ingress.host }}
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: {{ .Release.Name }}-api
            port:
              number: 8000
  tls:
  - hosts:
    - {{ .Values.ingress.host }}
    secretName: {{ .Values.ingress.tls.secretName }}

4. O ArgoCD Sincronizando Automaticamente no Cluster K3s

No ArgoCD da nossa VM OCI (152.67.32.35), declaramos a aplicação apontando para a pasta do chart e especificando o arquivo de valores:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hairtime-hml-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.com/12labs/hairtime.git
    targetRevision: hml
    path: charts/hairtime
    helm:
      valueFiles:
        - values-hml.yaml   # ArgoCD injeta as variáveis de Homologação
  destination:
    server: https://kubernetes.default.svc
    namespace: hairtime-hml
  syncPolicy:
    automated:
      selfHeal: true
      prune: true

5. Comandos de Terminal para Simulação e Deploy

Você pode testar localmente antes de comitar ou rodar manualmente caso precise:

# 1. Simular sem aplicar (ver o YAML final gerado):helm template hairtime ./charts/hairtime -f ./charts/hairtime/values-hml.yaml

# 2. Aplicar ou atualizar o ambiente no K3s:helm upgrade --install hairtime-hml ./charts/hairtime -f ./charts/hairtime/values-hml.yaml -n hairtime-hml

# 3. Se um bug subir para produção, desfazer em 3 segundos:helm rollback hairtime-prod 1 -n hairtime-prod

Treine comandos Helm no Cloud Shell!

Pratique auditoria com helm list, deploys com helm upgrade e rollbacks de emergência no simulador.

Abrir Cloud Shell