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.

Para quitar Rancher del todo de un clúster donde estuvo instalado (irreversible, con backup hecho):

1
2
3
4

kubectl create -f https://raw.githubusercontent.com/rancher/rancher-cleanup/main/deploy/rancher-cleanup.yaml
kubectl -n kube-system logs -l job-name=cleanup-job -f
kubectl create -f https://raw.githubusercontent.com/rancher/rancher-cleanup/main/deploy/verify.yaml
kubectl -n kube-system logs -l job-name=verify-job -f      # debe salir vacío

Para arreglar una sola cosa sin arrasar, lo que sigue.

Namespace en Terminating

cattle-system, cattle-fleet-system, cattle-impersonation-system, local, los cluster-fleet-*, o cualquier namespace que Rancher creó, se quedan en Terminating para siempre:

1

kubectl get ns cattle-system -o jsonpath='{.metadata.finalizers}{"\n"}{.spec.finalizers}{"\n"}{.status.conditions}{"\n"}'

Dos casos distintos:

1. metadata.finalizers trae controller.cattle.io/namespace-auth (o cualquier *.cattle.io). Lo puso Rancher y solo Rancher lo quita; si Rancher ya no está, nadie lo hará. Quítalo tú:

   1	kubectl patch ns cattle-system --type=merge -p '{"metadata":{"finalizers":[]}}'

2. spec.finalizers trae kubernetes y status.conditions dice SomeResourcesRemain o DiscoveryFailed. El API server no borra el namespace porque dentro quedan recursos, casi siempre CRs de un API group cuyo servicio desapareció (un apiservice de Rancher). Antes de forzar, mira qué es:

   1 2 3

   kubectl api-resources --verbs=list --namespaced -o name \ | xargs -n1 kubectl -n cattle-system get --ignore-not-found --show-kind 2>/dev/null kubectl get apiservice | grep -v True # APIs muertas que rompen el discovery

   Borra el apiservice muerto o los CRs con finalizers, y el namespace cae solo. Forzar spec.finalizers a vacío es el último recurso y deja huérfanos:

   1 2	kubectl get ns cattle-system -o json | jq '.spec.finalizers=[]' \ | kubectl replace --raw /api/v1/namespaces/cattle-system/finalize -f -

Clúster que no se puede borrar

Un clúster importado que ya no existe se queda en Removing en la UI, o kubectl delete no termina. Son dos objetos con finalizers, uno por API:

1
2
3
4
5

kubectl -n fleet-default get clusters.provisioning.cattle.io
kubectl -n fleet-default patch clusters.provisioning.cattle.io my-cluster --type=merge -p '{"metadata":{"finalizers":[]}}'

kubectl get clusters.management.cattle.io          # c-m-xxxxxxxx (v2.6+) o c-xxxxx
kubectl patch clusters.management.cattle.io c-m-xxxxxxxx --type=merge -p '{"metadata":{"finalizers":[]}}'

Después limpia el namespace cluster-fleet-default-<nombre>-<hash> y los clusters.fleet.cattle.io que queden en fleet-default.

El webhook que rechaza todo

rancher-webhook valida y muta recursos de *.cattle.io (y algunos de core, como namespaces y ServiceAccounts en clústeres gestionados). Si el pod no existe o está roto, cada cambio falla con:

1

Error from server (InternalError): Internal error occurred: failed calling webhook "rancher.cattle.io": … connect: connection refused

Exporta las configuraciones, bórralas, deja que el pod vuelva sano, y restáuralas:

1
2
3
4
5
6

kubectl get validatingwebhookconfiguration rancher.cattle.io -o yaml > vwc-rancher.yaml
kubectl get mutatingwebhookconfiguration rancher.cattle.io -o yaml > mwc-rancher.yaml
kubectl delete validatingwebhookconfiguration rancher.cattle.io
kubectl delete mutatingwebhookconfiguration rancher.cattle.io
# … arreglar rancher-webhook (kubectl -n cattle-system rollout restart deploy/rancher-webhook) …
kubectl apply -f vwc-rancher.yaml -f mwc-rancher.yaml

Si estás desinstalando, no las restaures: son lo primero que hay que quitar para que el resto del borrado avance.

Recuperar el acceso

Contraseña del admin perdida, o el usuario admin desactivado por error:

1
2
3

kubectl -n cattle-system exec -it deploy/rancher -- reset-password
# New password for default administrator (user-xxxxx): …
kubectl -n cattle-system exec -it deploy/rancher -- ensure-default-admin

ensure-default-admin reactiva el usuario y le devuelve el rol de administrador; reset-password solo cambia la contraseña.

Trampas

• rancher-cleanup borra los objetos de los clústeres aguas abajo (los clústeres siguen funcionando, pero dejan de estar registrados) y todo lo que Rancher instaló: monitoring, logging, Gatekeeper. Longhorn se queda. No lo lances en el clúster de Rancher que quieres conservar.
• Backup antes: kubectl get -A -o yaml de los *.cattle.io que te importen, o el backup-operator de Rancher. Los finalizers se quitan en un segundo; lo que había detrás no vuelve.
• kubectl delete ns --force --grace-period=0 no hace nada con un namespace en Terminating: el bloqueo está en los finalizers, no en el grace period.
• Rancher vuelve a poner los finalizers mientras esté vivo: si estás limpiando un clúster que todavía está conectado a un Rancher, desconéctalo primero (borra el cattle-cluster-agent) o los patches se deshacen solos.
• Los CRDs *.cattle.io sobreviven a una desinstalación por Helm; rancher-cleanup los quita, la desinstalación manual no.

Ver también

• k3s: reset del clúster tras perder el quórum — la otra cirugía de clúster que conviene tener a mano.
• rancher-cleanup y Technical FAQ de Rancher.

1
2
3
4
5
6
7
8
9

CLUSTER=my-cluster; REGION=us-central1; NETWORK=my-vpc
MASTER_CIDR=$(gcloud container clusters describe $CLUSTER --region $REGION \
  --format='value(privateClusterConfig.masterIpv4CidrBlock)')
NODE_TAG=$(gcloud compute firewall-rules list --filter="name~^gke-$CLUSTER" \
  --format='value(targetTags.list())' | head -1)

gcloud compute firewall-rules create gke-$CLUSTER-master-to-vault-injector \
  --network=$NETWORK --direction=INGRESS --action=ALLOW \
  --source-ranges=$MASTER_CIDR --target-tags=$NODE_TAG --rules=tcp:8080

Borra un pod anotado y comprueba que el injector recibe la llamada:

1
2
3
4
5

kubectl -n app delete pod -l app=api
kubectl -n vault logs deploy/vault-agent-injector | grep mutate
# [INFO]  handler: Request received: Method=POST URL=/mutate?timeout=30s
kubectl -n app get pod -l app=api -o jsonpath='{.items[0].spec.initContainers[*].name} {.items[0].spec.containers[*].name}{"\n"}'
# vault-agent-init api vault-agent

El síntoma

• El pod lleva vault.hashicorp.com/agent-inject: "true" y el resto de anotaciones, pero arranca solo con el contenedor de la aplicación: ni vault-agent-init ni vault-agent.
• Crear el pod tarda unos 30 segundos más de lo normal.
• kubectl get events no dice nada del webhook. En los logs del injector no hay ni una línea de Request received.
• En otros clústeres (zonales públicos, kind, k3s) el mismo chart y las mismas anotaciones funcionan.

Por qué

En un clúster privado de GKE el control plane vive en una VPC de Google y llega a tus nodos a través de la regla de firewall que GKE crea sola (gke-<cluster>-<hash>-master). Esa regla solo permite TCP 443 y 10250 desde el rango del control plane hacia los nodos. Todo lo demás está cerrado.

Un webhook de admisión no pasa por el Service como lo haría un cliente normal: el API server resuelve el Service a sus endpoints y conecta directamente con la IP del pod en el targetPort. El Service del injector (vault-agent-injector-svc) publica el 443, pero el pod escucha en el 8080 (injector.port del chart), así que la conexión real es al 8080 y el firewall la descarta.

Lo que pasa después lo explican dos valores por defecto del chart de Vault:

De ahí los 30 segundos de retraso y el pod sin sidecar y sin ningún mensaje. Con failurePolicy: Fail habrías visto failed calling webhook "vault.hashicorp.com": … context deadline exceeded en los eventos del ReplicaSet, que al menos apunta al sitio correcto.

No es solo Vault

Cualquier webhook de admisión, conversión de CRDs o API agregada que escuche en un puerto que no sea 443 o 10250 falla igual en GKE privado: el operador de OpenTelemetry (9443), Kyverno (9443), Gatekeeper (8443)… cert-manager escucha en el 10250 precisamente para no necesitar esta regla. La documentación de GKE lo lista como requisito de “admission webhooks, aggregated API servers, webhook conversion”: una regla por puerto, desde masterIpv4CidrBlock hacia los tags de los nodos.

Si el clúster está en Terraform, deja la regla junto al clúster para que no se pierda al recrearlo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

resource "google_compute_firewall" "master_to_vault_injector" {
  name          = "gke-${google_container_cluster.main.name}-master-to-vault-injector"
  network       = google_compute_network.main.name
  direction     = "INGRESS"
  source_ranges = [google_container_cluster.main.private_cluster_config[0].master_ipv4_cidr_block]
  target_tags   = ["gke-${google_container_cluster.main.name}"]   # el tag que usan tus node pools
  allow {
    protocol = "tcp"
    ports    = ["8080"]
  }
}

Trampas

• El tag equivocado: los nodos llevan gke-<cluster>-<hash>-node; cópialo de las reglas gke-<cluster>-* existentes en vez de escribirlo a mano. Con varios node pools, comprueba que todos tengan el tag.
• El rango del control plane cambia si recreas el clúster; una regla escrita a mano con el CIDR viejo deja de servir sin avisar.
• failurePolicy: Fail hace visible el fallo, pero mientras el webhook esté caído no se crea ningún pod en los namespaces que casen con el namespaceSelector; el chart excluye al propio injector, pero no a Vault si comparten namespace y etiquetas. Úsalo con replicas: 2.
• El injector sí recibe la petición y sigue sin sidecar: entonces ya no es red. Mira los logs de vault-agent-init: permission denied es el rol de Kubernetes auth (bound_service_account_names, bound_service_account_namespaces) o la política; connection refused es vault.hashicorp.com/service o la dirección de Vault.
• Un solo puerto por regla no escala: si acumulas webhooks, una regla con --rules=tcp:8080,8443,9443 desde el control plane es más fácil de mantener que cinco.

Referencias: vault-k8s #46, vault-k8s #32 y reglas de firewall en clústeres privados en la documentación de GKE.

Ver también

• cert-manager: el reto HTTP-01 devuelve 308 — otro componente que “no hace nada” hasta que miras el sitio correcto.
• GitHub Actions → Google Cloud sin llaves — para desplegar en ese GKE sin llaves JSON.

1

Waiting for HTTP-01 challenge propagation: wrong status code '308', expected '200'

cert-manager crea un Ingress temporal (cm-acme-http-solver-…) para responder al reto, pero sin clase tu ingress controller no lo adopta; la petición a /.well-known/acme-challenge/… la contesta el Ingress de la aplicación, que redirige a HTTPS con 308. Pon la clase en el solver:

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

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
    - http01:
        ingress:
          ingressClassName: nginx        # cert-manager >= 1.12; antes: class: nginx

Aplica y borra el reto atascado para que lo reintente:

1

kubectl delete challenge -n <ns> --all

Diagnóstico

1
2
3
4

kubectl get certificate,certificaterequest,order,challenge -A
kubectl describe challenge -n <ns> <nombre>            # Status → Reason es la frase que buscas
kubectl get ingress -n <ns>                            # el cm-acme-http-solver-xxxx tiene CLASS <none>?
curl -i http://app.example.com/.well-known/acme-challenge/prueba   # desde fuera y desde un pod

Antes de pedirle a Let’s Encrypt que valide, cert-manager hace un self-check: intenta él mismo la URL del reto. El Reason del Challenge es el resultado de ese self-check y casi siempre apunta a la causa.

Por qué ingressClassName

Desde Kubernetes 1.18 la clase de un Ingress va en spec.ingressClassName; la anotación kubernetes.io/ingress.class quedó obsoleta y los controllers modernos (ingress-nginx 1.x, Traefik) pueden ignorarla. En cert-manager, el campo class del solver sigue escribiendo la anotación; ingressClassName (desde la 1.12) escribe el campo. Usa uno de los dos, y en 2026 el que toca es ingressClassName.

Sin clase, el Ingress temporal existe pero nadie lo sirve. El controller enruta la petición por host, encuentra el Ingress de la app, y aplica sus reglas: ssl-redirect → 308. De ahí que el error parezca de la app y no de cert-manager.

Alternativa: DNS-01 con Cloudflare

Cuando el clúster no es alcanzable desde Internet por el puerto 80, o quieres un wildcard, el reto va por DNS. Token en Cloudflare con Zone → DNS → Edit y Zone → Zone → Read sobre la zona:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-api-token
  namespace: cert-manager
type: Opaque
stringData:
  api-token: <token>
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-dns-account-key
    solvers:
    - dns01:
        cloudflare:
          apiTokenSecretRef:
            name: cloudflare-api-token
            key: api-token

Con DNS-01 no hay Ingress temporal, ni self-check por HTTP, ni hairpin; el self-check consulta el registro TXT, y si el DNS del clúster resuelve contra un servidor interno con la zona cacheada, el Reason será DNS record for … not yet propagated: paciencia o --dns01-recursive-nameservers=1.1.1.1:53 en cert-manager.

Trampas

• Staging primero. https://acme-staging-v02.api.letsencrypt.org/directory no tiene límites de emisión; producción bloquea 5 emisiones por nombre y semana, y cada Challenge fallido que llega a Let’s Encrypt cuenta como intento.
• Borrar el Challenge, no el Certificate. Borrar el Order o el Challenge fuerza un reintento con la configuración nueva; borrar el Certificate también borra el secreto y deja la app sin TLS mientras tanto.
• pathType: Exact en el Ingress del solver (cert-manager reciente) choca con algunos controllers viejos; si ves 503 en OpenShift, es eso.
• Un Issuer por namespace vs ClusterIssuer: el Ingress tiene que anotar el que exista (cert-manager.io/cluster-issuer o cert-manager.io/issuer); anotar el que no existe deja el Certificate en Issuing para siempre sin Challenge que describir.

Referencias: HTTP01 solver, Cloudflare DNS01 y Troubleshooting ACME en la documentación de cert-manager.