Helmify: Convertendo Manifestos Kubernetes em Helm Charts

No mundo do DevOps moderno, a orquestração de contêineres tornou-se uma habilidade essencial. O Kubernetes emergiu como a plataforma padrão para gerenciamento de aplicações em contêineres, mas sua complexidade pode ser complexa e um pouco assustadora para iniciantes.

Em ambientes Kubernetes, você descreve como quer que suas aplicações sejam executadas através de manifestos, arquivos de texto geralmente escritos em YAML (ou JSON) que especificam o “estado desejado” dos recursos do cluster e o Kubernetes trabalha continuamente para manter esse estado.

Neste artigo vamos explorar um pouco do Helmify, uma ferramenta CLI que simplifica a criação de Helm Charts a partir de manifestos Kubernetes existentes.

O Desafio: Gerenciando Múltiplos Manifestos

À medida que suas aplicações crescem, você se depara com desafios significativos ao trabalhar com manifestos Kubernetes:

1. Proliferação de arquivos: Uma aplicação simples pode exigir dezenas de manifestos YAML
2. Duplicação de configuração: Ambientes diferentes (desenvolvimento, teste, produção) requerem variações dos mesmos manifestos
3. Gerenciamento de versões: Rastrear quais versões de manifestos foram implantadas torna-se complexo
4. Atualizações e rollbacks: Reverter uma implantação problemática exige manter histórico de todas as configurações
5. Reutilização limitada: Manifestos puros são difíceis de compartilhar e reutilizar entre projetos

O que é Helm?

O helm é um gerenciador de pacote com controle de estado para Kubernetes que surgiu com o intuito de resolver os desafios mencionados anteriormente. Ele funciona de maneira similar a gerenciadores de pacotes como APT (Ubuntu), YUM (RedHat) ou Homebrew (macOS), mas especificamente para aplicações Kubernetes.

O Helm revolucionou o gerenciamento de aplicações Kubernetes ao tratar múltiplos manifestos como uma unidade atômica versionada, oferecendo controle completo do ciclo de vida através de comandos simples. Enquanto manifestos tradicionais exigem aplicar, rastrear e remover dezenas de arquivos YAML individualmente com kubectl apply, os Helm Charts permitem instalar, atualizar e fazer rollback de aplicações inteiras com um único comando, mantendo histórico completo de todas as versões implantadas. Isso elimina o problema comum onde recursos órfãos permanecem no cluster após remoções manuais de manifestos, além de possibilitar reversões instantâneas quando algo dá errado em produção.​

O Helm introduz o conceito de Charts — pacotes que contêm todos os recursos necessários para executar uma aplicação no Kubernetes. Um Helm Chart inclui templates de manifestos, valores configuráveis e metadados sobre a aplicação.

Componentes de um Helm Chart

Um Helm Chart típico possui a seguinte estrutura:

mychart/
├── Chart.yaml          <span class="hljs-meta"># Metadados sobre o chart</span>
├── values.yaml         <span class="hljs-meta"># Valores de configuração padrão</span>
├── charts/             <span class="hljs-meta"># Dependências (subcharts)</span>
└── templates/          <span class="hljs-meta"># Templates de manifestos Kubernetes</span>
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    └── _helpers.tpl    <span class="hljs-meta"># Helpers de template reutilizáveis</span>

Chart.yaml contém informações como nome, versão, descrição e dependências do chart. values.yaml centraliza todas as configurações customizáveis, permitindo que você sobrescreva valores sem modificar os templates.

Helmify: Automatizando a Criação de Charts

O Helmify é uma ferramenta CLI open-source que lê manifestos Kubernetes (YAML) e os converte automaticamente em Helm Charts. Desenvolvido pela comunidade e disponível no GitHub, o Helmify é especialmente útil quando você:

• Já possui manifestos Kubernetes funcionais e quer migrá-los para Helm
• Está trabalhando com operadores Kubernetes gerados pelo Operator SDK ou Kubebuilder
• Precisa converter rapidamente a saída do Kustomize em um Helm Chart
• Quer economizar tempo na criação manual de templates Helm

O Helmify suporta uma ampla gama de recursos Kubernetes:

• Workloads: Deployment, DaemonSet, StatefulSet, Job, CronJob
• Networking: Service, Ingress
• Storage: PersistentVolumeClaim
• RBAC: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding
• Configuration: ConfigMap, Secret
• Webhooks: Certificate, Issuer, ValidatingWebhookConfiguration
• CRDs: CustomResourceDefinition

Limitações Conhecidas

É importante estar ciente de algumas limitações:

• O Helmify não sobrescreve o arquivo Chart.yaml se ele já existir
• O Helmify não deleta arquivos de template existentes, apenas os sobrescreve
• Todas as modificações manuais nos templates serão perdidas em execuções subsequentes
• É recomendável deletar e regenerar o chart do zero ao alternar o uso da flag -crd-dir

Guia de Instalação do Helmify

Instalação no macOS ou Linux

1. Acesse a página de releases do Helmify no GitHub:

https://github.com/arttor/helmify/releases

1. Baixe o binário apropriado para seu sistema operacional e arquitetura:
   • Para Linux AMD64: helmify_Linux_x86_64.tar.gz
   • Para Linux ARM64: helmify_Linux_arm64.tar.gz
   • Para macOS AMD64: helmify_Darwin_x86_64.tar.gz
   • Para macOS ARM64 (M1/M2): helmify_Darwin_arm64.tar.gz
2. Extraia o arquivo:

tar -zxvf helmify_*.tar.gz

1. Mova o binário para um diretório no seu PATH:

sudo mv helmify /usr/local/bin/

1. Torne o binário executável:

chmod +x /usr/local/bin/helmify

Verificando a Instalação

Independentemente do sistema operacional, verifique se a instalação foi bem-sucedida:

helmify -version

Você deve ver a versão instalada do Helmify.

Convertendo Manifestos em Helm Charts: Passo a Passo

Exemplo 1: Convertendo um Deployment Simples

Vamos começar com um exemplo básico de uma aplicação Nginx.

Passo 1: Crie os manifestos Kubernetes

Crie um diretório para seus manifestos:

mkdir nginx-manifests
cd nginx-manifests

Crie o arquivo deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25.0
        ports:
        - containerPort: 80

Crie o arquivo service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    app: nginx
spec:
  type: ClusterIP
  selector:
    app: nginx
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80

Passo 2: Converta usando Helmify via pipe (stdin)

cat deployment.yaml service.yaml | helmify nginx-chart

Passo 3: Converta usando Helmify a partir do filesystem

Alternativamente, se você tiver múltiplos arquivos YAML pode utilizar diretamente o binário do Helmify para ler diretamente do filesystem:

helmify -f {PATH dos seus arquivos YAML} {NOME DO CHART}

Se você tiver múltiplos arquivos YAML no diretório atual, pode utilizar o seguinte comando:

helmify -f . nginx-chart

Se você precisa processar subdiretórios recursivamente:

helmify -f . -r nginx-chart

Passo 4: Explore o chart gerado

O Helmify criará a estrutura conforme o padrão do Helm que exploramos anteriormente:

nginx-chart/
├── Chart<span class="hljs-selector-class">.yaml</span>
├── values<span class="hljs-selector-class">.yaml</span>
└── templates/
    ├── deployment<span class="hljs-selector-class">.yaml</span>
    └── service.yaml

Examine o values.yaml gerado:

deployment:
  nginx:
    image:
      repository: nginx
      tag: 1.25.0
    replicas: 3

service:
  nginx:
    ports:
    - port: 80
      protocol: TCP
      targetPort: 80
    type: ClusterIP

E o template deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "nginx-chart.fullname" . }}-nginx
  labels:
    app: nginx
  {{- include "nginx-chart.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.deployment.nginx.replicas }}
  selector:
    matchLabels:
      app: nginx
    {{- include "nginx-chart.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        app: nginx
      {{- include "nginx-chart.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - image: {{ .Values.deployment.nginx.image.repository }}:{{ .Values.deployment.nginx.image.tag }}
        name: nginx
        ports:
        - containerPort: 80

Passo 5: Valide o chart

Antes de instalar, valide o chart gerado:

helm lint nginx-chart

Visualize os manifestos que serão gerados:

helm template nginx-chart

Passo 6: Instale o chart no cluster

helm install my-nginx nginx-chart

Verifique a instalação:

helm list
kubectl get deployments
kubectl get services

Exemplo 2: Convertendo Saída do Kustomize

Para projetos que usam Kustomize, o Helmify pode converter a saída diretamente em um chart:

Passo 1: Gere a saída do Kustomize

kustomize build ./my-kustomize-dir > kustomize-output.yaml

Passo 2: Converta para Helm Chart

cat kustomize-output.yaml | helmify my-operator-chart

Exemplo 3: Separando CRDs em Diretório Próprio

Para operadores Kubernetes que incluem Custom Resource Definitions (CRDs), use a flag -crd-dir:

cat operator-manifests.yaml | helmify -crd-dir my-operator-chart

Isso criará a estrutura:

<span class="hljs-keyword">my</span>-operator-chart/
├── Chart.yaml
├── values.yaml
├── crds/                    <span class="hljs-comment"># CRDs em diretório separado</span>
│   └── mycrd.yaml
└── templates/
    ├── deployment.yaml
    ├── rbac.yaml
    └── service.yaml

É importante ressaltar que o Helm não suporta templating de CRDs, então eles são armazenados sem processamento de template.

Exemplo 4: Preservando Namespaces Originais

Por padrão, o Helmify remove namespaces dos manifestos para que o chart possa ser instalado em qualquer namespace. Para preservar os namespaces originais você pode utilizar o parâmetro -preserve-ns:

cat manifests.yaml | helmify -preserve-ns my-chart

Opções Avançadas do Helmify

O Helmify oferece várias flags para customizar a conversão:

Boas Práticas ao Usar Helmify

1. Versione Seu Chart

Após gerar o chart, edite o Chart.yaml para definir uma versão inicial adequada:

apiVersion: v2
name: my-app
description: Minha aplicação convertida
type: application
version: 0.1.0
appVersion: "1.0.0"

2. Revise e Customize os Templates

O Helmify faz um excelente trabalho inicial, mas sempre revise os templates gerados:

• Adicione helpers customizados em templates/_helpers.tpl
• Ajuste labels e annotations conforme suas convenções
• Adicione condicionais para recursos opcionais

3. Organize Seus Values

Reorganize o values.yaml para agrupamentos lógicos:

# Imagem da aplicação
image:
  repository: nginx
  tag: 1.25.0
  pullPolicy: IfNotPresent

# Réplicas e recursos
replicaCount: 3
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

# Configurações de serviço
service:
  type: ClusterIP
  port: 80

# Ingress
ingress:
  enabled: false
  className: nginx
  annotations: {}
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific

4. Teste em Múltiplos Ambientes

Crie arquivos de valores específicos para cada ambiente:

# Desenvolvimento
helm install myapp ./my-chart -f values-dev.yaml

# Staging
helm install myapp ./my-chart -f values-staging.yaml

# Produção
helm install myapp ./my-chart -f values-prod.yaml

5. Use Controle de Versão

Mantenha seus charts em um repositório Git separado dos manifestos originais:

charts/
├── my-app/
│   ├── Chart<span class="hljs-selector-class">.yaml</span>
│   ├── values<span class="hljs-selector-class">.yaml</span>
│   ├── values-dev<span class="hljs-selector-class">.yaml</span>
│   ├── values-prod<span class="hljs-selector-class">.yaml</span>
│   └── templates/
└── README.md

6. Documente Suas Customizações

Adicione um README.md ao chart explicando:

• Parâmetros importantes do values.yaml
• Requisitos de pré-instalação
• Exemplos de uso
• Troubleshooting comum

Comparação: Helmify vs. Conversão Manual

Quando Usar Helmify

O Helmify é ideal para:

• Migração de projetos legados: Você tem manifestos funcionais e quer adotar Helm
• Prototipagem rápida: Precisa de um chart funcional rapidamente
• Operadores Kubernetes: Convertendo saída do Operator SDK ou Kubebuilder
• Projetos Kustomize: Migrando de Kustomize para Helm
• Aprendizado: Estudar como manifestos são convertidos em templates Helm

Helmify pode não ser ideal quando:

• Você precisa de lógica de template muito complexa desde o início
• Seu projeto tem requisitos altamente específicos de estruturação
• Você está criando um chart para distribuição pública que requer documentação extensiva

Conclusão

O gerenciamento de aplicações Kubernetes evoluiu significativamente desde os primeiros dias dos manifestos YAML manuais. O Helm emergiu como o padrão de fato para empacotamento e distribuição de aplicações Kubernetes, oferecendo versionamento, reutilização e gerenciamento de ciclo de vida que são essenciais em ambientes de produção modernos.

O Helmify democratiza a adoção do Helm ao eliminar a barreira inicial de converter manifestos existentes em charts. Com uma simples linha de comando, você pode transformar dezenas de arquivos YAML dispersos em um chart Helm organizado, versionado e reutilizável.

Para administradores de clusters Kubernetes, dominar tanto o Helm quanto ferramentas como o Helmify significa:

• Maior eficiência operacional: Menos tempo lidando com arquivos de configuração individuais
• Redução de erros: Padronização e automação minimizam erros humanos
• Melhor colaboração: Charts compartilháveis facilitam o trabalho em equipe
• Operações mais seguras: Rollbacks atômicos reduzem riscos de implantação

À medida que você avança na sua jornada DevOps, lembre-se de que ferramentas como o Helmify são meios para um fim — facilitar a gestão de infraestrutura complexa. Comece convertendo projetos simples, ganhe confiança e gradualmente incorpore práticas mais avançadas de Helm em seu fluxo de trabalho.

O ecossistema Kubernetes está em constante evolução, mas os princípios fundamentais de automação, padronização e reutilização permanecem atemporais. O Helmify é mais uma ferramenta poderosa no arsenal do administrador moderno de Kubernetes, simplificando a transição para práticas de gerenciamento de aplicações mais maduras e escaláveis.