La CLI¶

La CLI kubelatch te hace entrar una vez y les da a kubectl, k9s, Lens y Helm su credencial por sí sola. No copias tokens ni descargas kubeconfigs: la CLI escribe un kubeconfig sin ningún secreto y kubectl le pide el token cada vez que lo necesita.

Instalarla¶

Cada release trae kubelatch para Linux y macOS, en amd64 y arm64:

• kubelatch_<versión>_<os>_<arch>.tar.gz, con el binario dentro;
• kubelatch_<versión>_checksums.txt, el SHA-256 de cada fichero de la release.

Comprueba la descarga y pon el binario en tu PATH. Por ejemplo, en Linux amd64:

VERSION=0.2.0   # la release que descargaste, sin la v
sha256sum --ignore-missing -c kubelatch_${VERSION}_checksums.txt
tar -xzf kubelatch_${VERSION}_linux_amd64.tar.gz kubelatch
install -m 0755 kubelatch ~/.local/bin/kubelatch
kubelatch version

En macOS, compruébala con shasum -a 256 --ignore-missing -c en vez de sha256sum.

kubectl ejecuta kubelatch por su nombre, así que tiene que estar en el PATH de la shell donde usas kubectl.

Entrar¶

La primera vez, dale la URL de kubelatch, la que abres en el navegador:

kubelatch login https://kubelatch.example.com

La CLI abre tu navegador en una página que pregunta «¿Aprobar el acceso desde laptop-alice?». Si no has entrado en la web, primero te pide entrar. La página detalla la petición que apruebas. Responde como tú («Respondes como alice. ¿No eres tú?», con un enlace «Salir» para quien comparta tu navegador). Bajo «Quién pide» muestra el nombre de tu equipo («Equipo (según la CLI)»), «Desde» qué IP llegó la petición y si es la «misma red que este navegador» u «otra red que la de este navegador», y cuándo fue «Pedida», con una cuenta atrás. Bajo «Qué recibe · hasta cuándo» dice lo que emite al aprobar: «Una credencial para todos tus clusters», «Durante» 12 h. Pulsa «Aprobar» solo si acabas de ejecutar kubelatch login tú: la línea sobre los botones lo dice, y cuando la petición viene de otra red que la de tu navegador esa línea pasa a ser un aviso destacado. Si la cuenta atrás llega a cero, los botones dan paso a «Esta petición caducó: vuelve a ejecutar kubelatch login.» El navegador vuelve a la CLI, que termina sola:

Approve this login in your browser:
  https://kubelatch.example.com/cli/approve/0192…?state=…
Signed in to https://kubelatch.example.com as alice; the session expires 2026-09-28 08:12 CEST.
Wrote 2 context(s) to /home/alice/.kube/kubelatch.yaml. Use it with:
  export KUBECONFIG=/home/alice/.kube/kubelatch.yaml
  kubectl get pods
or merge them into your kubeconfig with "kubelatch kubeconfig --merge".

Si el navegador no se abre, abre tú la URL que imprimió la CLI; la CLI espera 5 minutos. Si por el camino tienes que entrar, con contraseña o con GitHub, la web te devuelve después a la página de aprobación. La URL de kubelatch queda guardada, así que los siguientes logins son solo kubelatch login. Cada login sustituye a la sesión anterior en esta máquina: la sesión antigua se revoca, aunque fuera en otro kubelatch.

Sin navegador en esta máquina¶

En un servidor por SSH, o donde la CLI no pueda abrir un navegador, usa --device:

kubelatch login --device

Open https://kubelatch.example.com/cli/device in a browser where you are signed in to kubelatch and enter the code:

  BCDF-GHJK

Waiting for the approval...

Abre esa página en cualquier dispositivo, escribe el código en «Código que muestra la terminal» y pulsa «Continuar». La página muestra entonces la misma petición de arriba, con el nombre del equipo y la red de la que viene: compruébalos y pulsa «Aprobar». El código dura 10 minutos. Si la página muestra una petición que no es tuya (un código mal escrito), pulsa «Usar otro código» para escribirlo de nuevo; «Cancelar», en cambio, rechaza esa petición.

Un certificado privado¶

Si kubelatch usa un certificado de una CA privada, dale esa CA a la CLI una vez:

kubelatch login https://kubelatch.example.com --ca-file ca-empresa.pem

La CLI la guarda con la URL, confía en ella además de en las del sistema y la pone en el kubeconfig cuando kubelatch no publica una CA propia. La CLI solo habla HTTPS; http:// solo se acepta en localhost y 127.0.0.1, para desarrollo.

Apunta tus herramientas al kubeconfig¶

kubelatch login escribe ~/.kube/kubelatch.yaml, con un contexto por cada cluster al que tienes acceso, llamado kubelatch-<cluster>, todos con el usuario kubelatch (abreviado):

users:
- name: kubelatch
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: kubelatch
      args:
      - exec-credential
      interactiveMode: Never

En el fichero no hay ningún token. Cada vez que kubectl necesita uno, ejecuta kubelatch exec-credential, que lo lee de tu sesión. Apunta tus herramientas al fichero:

export KUBECONFIG=~/.kube/kubelatch.yaml
kubectl config get-contexts
kubectl --context kubelatch-prod get pods

k9s y Helm leen el mismo KUBECONFIG. Lens también, pero como aplicación de escritorio puede no ver el PATH de tu shell y no encontrar kubelatch; si pasa, dale a Lens un kubeconfig emitido desde la web (Obtener una credencial). Lo que no funciona a través de kubelatch está en kubectl, k9s, Lens y Helm.

Fusionarlo con tu kubeconfig de siempre¶

Para tener los contextos junto a los demás:

kubelatch kubeconfig --merge

Escribe en el fichero que indique KUBECONFIG (el primero que exista, como hace kubectl) o en ~/.kube/config. Solo añade o reemplaza los clusters y contextos kubelatch-* y el usuario kubelatch, quita los kubelatch-* de clusters que ya no tienes y nunca cambia current-context. Cambia de contexto con kubectl config use-context kubelatch-<cluster>.

Después de un permiso nuevo¶

Los contextos se fijan al escribir el fichero. Cuando un administrador te da acceso a otro cluster, vuelve a escribirlos:

kubelatch kubeconfig            # o: kubelatch kubeconfig --merge

-o <fichero> lo escribe en otro sitio.

Ver tu sesión¶

kubelatch status

Server:   https://kubelatch.example.com
User:     alice
Session:  expires 2026-09-28 08:12 CEST (in 11h58m)

CONTEXT         CLUSTER      ACCESS
kubelatch-kind  kind local   viewer (default), debugger (default)
kubelatch-prod  Production   viewer (whole cluster)

En «Inicio», la línea bajo el título dice lo mismo: «Conectada desde» laptop-alice, hasta cuándo dura la sesión, con «Cerrar sesión» y «Conectar un agente» al lado; el contexto de cada cluster está en su cabecera de «Mis accesos». kubelatch credentials lista tus credenciales (la de la sesión tiene el tipo cli y un * junto a su id), y kubelatch credentials revoke <id> revoca una de ellas.

Salir¶

kubelatch logout

Revoca en kubelatch la credencial de la sesión y la borra de tu máquina. Si no consigue hablar con kubelatch, borra la sesión local de todos modos y te pide revocar la credencial desde la web, donde sigue siendo válida hasta que caduque. Desde entonces kubectl falla con:

error: no kubelatch session: run "kubelatch login"

Cuando caduca la sesión¶

La sesión dura 12 h (un administrador lo cambia con KUBELATCH_CLI_SESSION_TTL) y no se renueva sola. Al caducar, kubectl muestra error: the kubelatch session expired: run "kubelatch login". Ejecuta kubelatch login y sigue: el kubeconfig no cambia.

Revocar la credencial desde la web (en «Inicio», «Cerrar sesión» en la línea bajo el título, o «Revocar» en la fila «Sesión de la CLI en …» de «Mis credenciales») o deshabilitar tu cuenta también cierra la sesión: la siguiente petición recibe un 401 y el siguiente comando de kubelatch te pide entrar de nuevo.

Dónde guarda las cosas¶

KUBELATCH_CONFIG_DIR cambia la carpeta de los dos primeros. Lo que puede y lo que no puede hacer el token de la sesión está en el modelo de seguridad; todos los comandos y flags, en la referencia de la CLI de kubelatch.