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.