1
2
3
4
5
6

export HELM_DIFF_THREE_WAY_MERGE=true        # diff contra lo que hay en el clúster, no contra el último release
export HELM_DIFF_NORMALIZE_MANIFESTS=true    # quita ruido de formato del diff
export HELMFILE_GOCCY_GOYAML=true            # helmfile 0.x: evita "key already set in map"

helmfile -e prod -l name=rabbitmq diff        # una sola release
helmfile -e prod apply --skip-diff-on-install # primera instalación gigante sin diff

Y en CI, versiones fijas de las tres piezas (helm, helmfile, helm-diff): la mitad de los errores raros de helmfile son combinaciones que no se han probado juntas.

Los errores y qué los arregla

Adoptar recursos que ya existen

El caso típico: alguien instaló ArgoCD (o lo que sea) con kubectl apply -f, y ahora quieres que lo gestione una release de helmfile. Helm se niega a instalar sobre recursos que no son suyos (rendered manifests contain a resource that already exists … invalid ownership metadata). Desde Helm 3.2 basta con marcarlos como suyos antes de instalar:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

NS=argocd; REL=argocd
for kind in deploy sts svc cm secret sa ingress role rolebinding networkpolicy; do
  kubectl -n $NS get $kind -o name 2>/dev/null | while read -r r; do
    kubectl -n $NS label "$r" app.kubernetes.io/managed-by=Helm --overwrite
    kubectl -n $NS annotate "$r" meta.helm.sh/release-name=$REL meta.helm.sh/release-namespace=$NS --overwrite
  done
done
# recursos de clúster: mismas etiquetas, sin -n
for r in $(kubectl get crd,clusterrole,clusterrolebinding -o name | grep -i argo); do
  kubectl label "$r" app.kubernetes.io/managed-by=Helm --overwrite
  kubectl annotate "$r" meta.helm.sh/release-name=$REL meta.helm.sh/release-namespace=$NS --overwrite
done
helmfile -e prod -l name=$REL diff     # debería ser casi vacío
helmfile -e prod -l name=$REL apply

Solo marca lo que el chart va a renderizar: un recurso etiquetado que el chart no incluye no pasa nada, pero uno que el chart renderiza con otro nombre acaba duplicado.

helmfile 1.x y Helm 4

Si vienes de 0.x, esto es lo que cambia al actualizar:

• Un helmfile.yaml con plantillas Go tiene que llamarse helmfile.yaml.gotmpl; el .yaml a secas ya no se renderiza.
• environments: y releases: van en partes separadas por --- dentro del mismo archivo.
• helmfile delete desaparece (es destroy), helmfile charts también, y --args se elimina.
• HELMFILE_SKIP_INSECURE_TEMPLATE_FUNCTIONS pasa a ser HELMFILE_DISABLE_INSECURE_FEATURES.
• helmfile 1.x funciona con Helm 3 y Helm 4. Con Helm 4, instala helm-diff con helm plugin install https://github.com/databus23/helm-diff --verify=false (Helm 4 verifica la procedencia de los plugins y helm-diff no la publica).

Trampas

• apply sin diff previo en CI: helmfile apply ya hace el diff y solo aplica si hay cambios; sync aplica siempre. En pipelines, diff en la PR y apply en main.
• installed: false desinstala la release en el siguiente apply; útil para retirar cosas por Git, peligroso si lo copias de otro entorno.
• Secretos en values: helmfile los deja en el manifiesto del release (Secret de Helm en el namespace); usa helm-secrets con SOPS o referencias externas.
• --skip-diff-on-install no es --skip-diff: solo se salta el diff en releases que aún no existen. Las actualizaciones siguen mostrando su diff.
• Tres binarios, tres versiones: helm version, helmfile version y helm plugin list en el primer paso del pipeline, y en la imagen de CI fijadas por tag.

Referencias: helm-diff, helmfile y la propuesta de cambios para 1.0.

Ver también

• k3s: importar imágenes sin registro — cuando la release depende de una imagen que no está en ningún registro.