Si algo falla¶

Los errores más habituales al usar kubectl, k9s, Lens, Helm o la CLI kubelatch a través de kubelatch, y qué hacer con cada uno. Los errores de un job de GitHub Actions están en Credenciales para GitHub Actions.

Toda respuesta del proxy, también los errores, lleva la cabecera Audit-ID: dásela a un administrador (o mírala con kubectl -v=8) si necesitas que investigue una petición concreta.

401 — no autenticado¶

• a kubelatch token is required …: tu kubeconfig no lleva token, o no es el de kubelatch. Revisa que apuntas al fichero correcto (KUBECONFIG o --kubeconfig).
• unknown credential: el token no existe en kubelatch (por ejemplo, lo escribiste a mano y te equivocaste, o es de otra instancia).
• credential revoked: alguien (tú o un administrador) la revocó. Emite una nueva: Caducidad y revocación.
• credential expired: pasó su fecha de caducidad. Las credenciales no se reactivan; emite otra: Obtener una credencial.

403 — sin permiso¶

• the account is disabled: un administrador deshabilitó tu cuenta (o la de un bot). Pídele que la reactive si corresponde.
• this credential is restricted to cluster ...: la emitiste para un solo cluster y estás usándola contra otro. Emite una sin restricción de cluster, o una para ese cluster en concreto.
• ... has no active permissions on cluster ...: no te queda ningún permiso vigente en ese cluster (caducado o revocado). El mensaje termina diciendo dónde pedir uno: Ask for access: y un enlace a kubelatch en Pro, o a quién pedírselo.

• Forbidden del propio cluster (sin ese texto de kubelatch delante): tienes permisos, pero tu rol no cubre ese verbo, recurso o namespace. Cuando kubelatch conoce un rol que lo permitiría, el mensaje termina con ese rol y dónde pedirlo:

  Error from server (Forbidden): pods "web" is forbidden: User "user:alice" cannot create resource "pods/exec" in API group "" in the namespace "pagos" kubelatch: the debugger role in namespace pagos allows this. Ask for it: https://kubelatch.acme.com/request?cluster=prod&namespace=pagos&role=debugger&from=create+pods%2Fexec
  

  El enlace abre el formulario de solicitud con el cluster, el namespace y el rol ya puestos (Pedir acceso). En Free, la frase nombra a quién pedírselo en lugar del enlace. Si no hay frase, revisa qué permite tu rol en Roles de sistema o, si es un rol personalizado, pregunta a un administrador qué incluye.

404 — cluster desconocido¶

unknown cluster significa que el id del cluster en tu kubeconfig (https://<kubelatch>/clusters/<id>) no existe en kubelatch, por ejemplo porque un administrador lo borró. Comprueba el nombre del contexto con kubectl config get-contexts.

400 — petición no válida¶

• kubelatch does not accept Impersonate-* headers (kubectl --as is not supported): usaste --as o --as-group. kubelatch no te deja actuar como otro usuario; ya actúas como el tuyo. Quita el flag.
• invalid path: empty segments, '.' or '..' or escaped characters are not allowed: la petición lleva algo codificado (%XX) o una barra doble. kubectl normal nunca genera esto; revisa si usas curl u otra herramienta con el nombre de un recurso mal codificado.

502 y 503 — el cluster o kubelatch no responden¶

• 502 could not talk to the cluster's API server: kubelatch no llega al cluster real. No es un problema de tu credencial; avisa a un administrador.
• 503 the cluster has no tokens configured yet: el cluster está registrado en kubelatch pero aún no está enrolado (su estado dice «Sin enrolar»): un administrador todavía tiene que ejecutar su comando de enrolamiento.
• 503 kubelatch is restarting: kubelatch está en medio de un despliegue. Reintenta en unos segundos; un watch lo reintenta solo.

La CLI de kubelatch¶

Cuando la sesión de la CLI falta o se ha terminado, kubectl falla con uno de estos mensajes (los imprime la CLI y kubectl los repite):

• no kubelatch session: run "kubelatch login": no has entrado en esta máquina, o has cerrado la sesión. Ejecuta kubelatch login.
• the kubelatch session expired: run "kubelatch login": la sesión de 12 h se ha terminado. Ejecuta kubelatch login; el kubeconfig no cambia.
• the kubelatch session is no longer valid (revoked or expired on the server): run "kubelatch login": la credencial de la sesión se revocó desde la web, o tu cuenta está deshabilitada. Entra otra vez; si se repite, pregunta a un administrador.
• cannot listen on 127.0.0.1 for the browser …: use kubelatch login --device: la CLI no puede abrir un puerto local al que vuelva el navegador. Usa kubelatch login --device y teclea el código en un navegador.
• no approval came from the browser within 5m0s …: nadie pulsó «Aprobar» a tiempo. Ejecuta kubelatch login otra vez.
• the first login needs kubelatch's URL: kubelatch login https://kubelatch.example.com: esta máquina aún no conoce tu kubelatch. Dale la URL una vez.

El resto de la CLI está en La CLI.

Login con GitHub¶

Si no consigues entrar con GitHub, la pantalla de login muestra un mensaje concreto (no eres miembro activo de la organización, cuenta no vinculada, la organización no exige doble factor, enlace caducado...). El listado completo, con qué hacer en cada caso, está en Errores.

Entrar con la cuenta de tu empresa¶

Si no consigues entrar con la cuenta de tu empresa («Entrar con {name}», donde {name} es el nombre que tus administradores dieron al proveedor), la pantalla de login muestra un mensaje concreto: la cuenta no es de un dominio que este kubelatch acepte (quizá has elegido una cuenta personal: «Probar con otra cuenta»), ninguna cuenta de kubelatch tiene su dirección de correo, tu cuenta está vinculada a otra identidad, el enlace ha caducado... El listado completo, con qué hacer en cada caso, está en Errores, y qué pasa la primera vez, en Tu primer acceso con la cuenta de tu empresa.

Certificado (x509) al conectar con un cluster o con kubelatch¶

Si kubectl responde algo como x509: certificate signed by unknown authority o certificate is not trusted:

• Contra kubelatch: tu kubeconfig no lleva la CA correcta. Con la CLI, entra otra vez con kubelatch login <url> --ca-file <ca.crt>. Con un kubeconfig descargado desde la web, añade la CA a ese fichero: kubectl --kubeconfig <fichero-descargado> config set-cluster <id> --certificate-authority=<ca.crt> --embed-certs=true. Un administrador también puede configurar kubelatch para que los kubeconfigs nuevos ya incluyan la CA.
• Tu kubeconfig habla solo con kubelatch, nunca con el cluster de Kubernetes real, así que un error de certificado del cluster en sí no es algo que puedas arreglar desde tu lado: repórtaselo a un administrador.

Si nada de esto encaja, pasa a un administrador el Audit-ID de la respuesta (kubectl -v=8 lo muestra): con él encuentra tu petición en «Auditoría».