Pruébalo en local en 15 minutos¶

En este tutorial ejecutas kubelatch en tu máquina con Docker Compose, junto a un cluster kind desechable. Te darás un permiso, usarás kubectl a través de kubelatch, verás cada petición en la auditoría y revocarás la credencial. Todo con contraseñas locales, sin GitHub y sin compilar nada: usas la imagen y la CLI publicadas.

Tardarás unos 15 minutos, más las descargas de la primera vez (las imágenes de kubelatch y de Postgres y la del nodo de kind).

Antes de empezar¶

Comprueba las versiones con docker compose version, kind version y kubectl version --client. La CLI kubelatch está compilada para Linux y macOS, en amd64 y arm64; en Windows, sigue el tutorial dentro de WSL 2.

Trabaja en una sola terminal y en la misma sesión de shell de principio a fin: los pasos reutilizan variables.

1. Descarga el fichero de Compose¶

mkdir kubelatch-tutorial && cd kubelatch-tutorial
curl -fsSLO https://raw.githubusercontent.com/picaportelabs/kubelatch/main/docker-compose.yaml

docker-compose.yaml arranca Postgres, una tarea de un solo uso que escribe un certificado autofirmado para localhost, kubelatch en https://localhost:8443 y un contenedor diminuto que guarda la red de kubelatch. Keycloak, para el paso 15, solo arranca cuando lo pides. Trae configuración de prueba: una clave de cifrado a cero, la contraseña de base de datos kubelatch y las contraseñas de prueba de Keycloak. Nunca lo uses para una instalación real; para eso está el chart de Helm.

2. Descarga la CLI de kubelatch¶

export KUBELATCH_VERSION=$(curl -fsSL https://docs.kubelatch.com/releases/latest.json | sed 's/.*"version":"\([^"]*\)".*/\1/')
echo "KUBELATCH_VERSION=$KUBELATCH_VERSION" > .env
OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
REL="https://github.com/picaportelabs/kubelatch/releases/download/v$KUBELATCH_VERSION"
curl -fsSLO "$REL/kubelatch_${KUBELATCH_VERSION}_${OS}_${ARCH}.tar.gz"
curl -fsSLO "$REL/kubelatch_${KUBELATCH_VERSION}_checksums.txt"
sha256sum --ignore-missing -c "kubelatch_${KUBELATCH_VERSION}_checksums.txt"
mkdir -p bin && tar -xzf "kubelatch_${KUBELATCH_VERSION}_${OS}_${ARCH}.tar.gz" -C bin kubelatch
export PATH="$PWD/bin:$PATH"
kubelatch version

KUBELATCH_VERSION es la última versión publicada, y sha256sum comprueba la descarga contra las sumas de la versión (… OK). En macOS, compruébala con shasum -a 256 --ignore-missing -c en lugar de sha256sum. El binario se queda en bin/, dentro del directorio del tutorial, y el PATH solo lo encuentra en esta shell. El fichero .env guarda esa versión para Docker Compose, que la lee en el paso 4 y cada vez que vuelvas a arrancar kubelatch desde este directorio, así que el servidor y la CLI son de la misma versión.

3. Crea el cluster kind¶

KIND_KC="$PWD/kind.kubeconfig"
kind create cluster --name kubelatch-tutorial --kubeconfig "$KIND_KC"
kubectl --kubeconfig "$KIND_KC" label namespace default pod-security.kubernetes.io/enforce=baseline
kubectl --kubeconfig "$KIND_KC" run web --image=busybox:1.36 -- sh -c 'mkdir -p /www && echo ok > /www/index.html && exec httpd -f -p 80 -h /www'
kubectl --kubeconfig "$KIND_KC" run ticker --image=busybox:1.36 -- sh -c 'while true; do date; sleep 1; done'
kubectl --kubeconfig "$KIND_KC" wait --for=condition=Ready pod/web pod/ticker --timeout=3m

kind crea el cluster kubelatch-tutorial en medio minuto y escribe su kubeconfig de administrador en kind.kubeconfig, nunca en ~/.kube/config. Los dos pods de prueba, web y ticker, terminan en condition met.

La etiqueta pone Pod Security Admission baseline en el namespace default. La necesitas porque en el paso 8 te darás el nivel debugger, que kubelatch (igual que developer y admin) solo concede en namespaces que aplican PSA baseline o restricted. Roles de sistema explica por qué.

El cluster va antes que kubelatch porque kind también crea la red de Docker kind, y kubelatch se une a ella en el siguiente paso para llegar al cluster.

4. Arranca kubelatch¶

docker compose up -d
docker compose cp kubelatch:/tls/server.crt kubelatch-ca.crt
curl --cacert kubelatch-ca.crt https://localhost:8443/readyz    # ok

up -d arranca Postgres, escribe el certificado y deja kubelatch en marcha en segundo plano, escuchando en https://localhost:8443. Hace falta HTTPS porque kubectl solo envía tokens por HTTPS. Postgres no publica ningún puerto: solo habla con él kubelatch.

docker compose cp copia el certificado fuera, a kubelatch-ca.crt: curl, la CLI y Claude Code confían en kubelatch gracias a él. kubelatch también lo embebe como CA de los kubeconfigs que emite. Si curl aún no conecta, espera unos segundos y repítelo: kubelatch aplica sus migraciones de base de datos al arrancar.

5. Crea el primer administrador¶

La CLI de administración del servidor (kubelatch-server user …) se ejecuta dentro del contenedor de kubelatch, con la misma configuración que el servidor:

docker compose exec kubelatch /kubelatch-server user create admin --admin --display-name "Admin"

Te pide la contraseña dos veces, sin eco (Password: y Repeat password:). Debe tener al menos 12 caracteres. Termina con user admin created (id …, admin=true, break_glass=false).

6. Entra en la interfaz¶

Abre https://localhost:8443 en el navegador. Te avisará de que el certificado no es de confianza: es el autofirmado del paso 4, acéptalo para esta prueba.

La interfaz sigue el idioma de tu navegador (inglés o español); si no aparece en español, elige «Español» en el selector de la esquina superior derecha de la página (Idioma de la interfaz).

Escribe admin en «Login», tu contraseña en «Contraseña» y pulsa «Entrar». Verás «Inicio» y, a la izquierda, la barra lateral: primero «Inicio» y «Agentes», y después «Permisos», «Usuarios», «Grupos», «Roles» y «Credenciales» bajo «Acceso», «Auditoría» bajo «Registro», y «Clusters» y «CI» bajo «Plataforma». Junto al nombre, arriba, está la edición («Free»): lleva a «Edición». Al pie de la barra está tu propio nombre: púlsalo para abrir el menú con «Mi cuenta», «Edición», «Apariencia», «Idioma» y «Salir».

Usa localhost tal cual, no 127.0.0.1: kubelatch solo acepta peticiones de la interfaz desde su propia URL.

7. Registra el cluster en kubelatch¶

kubelatch necesita dos ServiceAccounts en cada cluster: una para reenviar tus peticiones y otra para mantener el RBAC. Registrar el cluster las crea y le pasa sus tokens a kubelatch.

1. Ve a «Clusters» y pulsa «Registrar un cluster»: el formulario se abre en un panel a la derecha. Escribe kind en «Identificador (slug, va en la URL del proxy)» y kind local en «Nombre», y pulsa «Registrar». Aterrizas en la página del cluster kind, con el estado «Sin enrolar» y su tarjeta «Enrolar» abierta en tres pasos: «Dónde», «Comando» y «Esperando».

2. Deja vacío «Contexto de kubectl (opcional)». Abre «Opciones avanzadas» y escribe https://kubelatch-tutorial-control-plane:6443 en «URL del API server para kubelatch». Tu kubeconfig llega al cluster por una dirección en 127.0.0.1, que dentro del contenedor de kubelatch es el propio contenedor; en la red kind, kubelatch llega al API server por el nombre del contenedor del nodo de kind.

3. Pulsa «Generar comando». El paso «Comando» muestra el «Comando de enrolamiento»: un curl … | sh que sirve una vez y durante una hora. Pulsa «Copiar» y ejecútalo así, pegándolo en lugar de <comando-de-enrolamiento>:

   ( export KUBECONFIG="$KIND_KC" CURL_CA_BUNDLE="$PWD/kubelatch-ca.crt"; <comando-de-enrolamiento> )
   

   CURL_CA_BUNDLE hace que curl confíe en el certificado autofirmado del paso 4: el script descarga con un curl y devuelve los tokens con otro, así que un -k escrito en la línea de comandos solo cubriría el primero. Con un certificado real, quítalo.

   El comando usa el contexto actual de kubectl. El export dentro de los paréntesis lo fija al cluster kind solo para esa subshell, sin tocar tu sesión ni ~/.kube/config.

4. El script imprime el contexto que va a enrolar y pregunta Continue? [y/N]. Comprueba que nombra kind-kubelatch-tutorial y responde y. Aplica el manifiesto (el namespace kubelatch-system y las dos ServiceAccounts, con permisos mínimos), lee sus tokens y se los envía a kubelatch.

kubelatch valida los tokens contra el cluster, los guarda cifrados y hace la primera reconciliación. La tarjeta dice «Enrolado. Primera reconciliación en marcha.» y el cluster pasa a «Listo». La cabecera dice primera reconciliación en marcha hasta que termina esa primera pasada: recarga la página y da la hora (reconciliado hace …). «Detalles» muestra la versión de Kubernetes en «Versión de Kubernetes», y la tarjeta «Namespaces» lista default con PSA baseline.

La tarjeta se queda en la página después de enrolar. Si te fuiste antes de ejecutar el comando, abre kind en «Clusters» otra vez: la tarjeta muestra el enlace pendiente, sin su comando (solo lo ve la pestaña que lo generó), y «Generar otro comando» te da uno nuevo. Si tu terminal no puede descargar el comando, «Hacerlo a mano», al pie de la tarjeta, tiene los pasos manuales.

8. Date un permiso¶

Ser administrador de kubelatch no da acceso a los clusters: tú también necesitas un permiso.

1. Ve a «Permisos» y pulsa «Conceder permisos»: el formulario se abre en un panel a la derecha.
2. Elige admin en «Cuentas», kind en «Cluster» y marca default (PSA baseline) en «Ámbitos». En «Qué», deja viewer seleccionado; en «Hasta cuándo», acepta el valor por defecto 30 días. Pulsa «Conceder 1 permiso».
3. Pulsa otra vez «Conceder permisos» y repite con debugger en «Qué».

El mapa muestra tu fila con una celda en kind: debugger en default, con «+1» por viewer; «Lista» tiene los dos en «Activos». viewer te deja leer casi todo en default salvo los secrets; debugger añade exec, attach y port-forward. En uno o dos segundos kubelatch crea en el cluster los RoleBindings correspondientes.

9. Entra con la CLI de kubelatch¶

1. Ve a «Inicio» y baja hasta «Mis clusters»: ahí está el cluster kind, abierto, con tus dos permisos, una línea cada uno. Pulsa un rol para ver qué permite y el grupo de Kubernetes con el que el cluster te reconocerá: kubelatch:ns:default:viewer y kubelatch:ns:default:debugger.
2. Entra con la CLI del paso 2. KUBELATCH_CONFIG_DIR guarda su sesión dentro del directorio del tutorial y -o escribe allí también el kubeconfig, así que no cambia nada tuyo en ~/.config ni en ~/.kube:

export KUBELATCH_CONFIG_DIR="$PWD/.kubelatch"
KL_KC="$PWD/tutorial.kubeconfig"
kubelatch login https://localhost:8443 --ca-file kubelatch-ca.crt -o "$KL_KC"

1. El navegador abre la pregunta «¿Aprobar el acceso desde ?». Bajo «Quién pide» aparecen el equipo («Equipo (según la CLI)»), «Desde» (la IP y si es la misma red que este navegador) y «Pedida»; bajo «Qué recibe · hasta cuándo», «Una credencial para todos tus clusters» y cuánto dura. Pulsa «Aprobar». La pestaña dice que puedes cerrarla y la terminal termina:

Approve this login in your browser:
  https://localhost:8443/cli/approve/…?state=…
Signed in to https://localhost:8443 as admin; the session expires ….
Wrote 1 context(s) to …/kubelatch-tutorial/tutorial.kubeconfig. Use it with:
…

El kubeconfig tiene un contexto, kubelatch-kind, y ningún token: kubectl se lo pide a kubelatch exec-credential en cada ejecución, por eso kubelatch tiene que estar en el PATH de la terminal donde usas kubectl. La CLI confía en el certificado autofirmado que le diste con --ca-file y lo pone en el kubeconfig. La CLI lo explica todo. Si prefieres no usarla, «Emitir una credencial» en «Inicio» emite un kubeconfig con el token dentro, como cuenta Obtener una credencial.

10. Usa kubectl a través de kubelatch¶

kubectl --kubeconfig "$KL_KC" auth whoami
kubectl --kubeconfig "$KL_KC" get pods
kubectl --kubeconfig "$KL_KC" exec web -- sh -c 'echo hola'

ATTRIBUTE   VALUE
Username    user:admin
UID         35b57553-…
Groups      [kubelatch:ns:default:debugger kubelatch:ns:default:viewer system:authenticated]
NAME     READY   STATUS    RESTARTS   AGE
ticker   1/1     Running   0          3m
web      1/1     Running   0          3m
hola

Cada petición llega a kubelatch con el token que la CLI le da a kubectl. kubelatch comprueba que la credencial vale, la registra y la reenvía al cluster con suplantación: actúa como user:admin con los grupos de tus permisos. El cluster decide con su RBAC. El viaje de una petición lo cuenta paso a paso.

11. Prueba algo que no puedes hacer¶

kubectl --kubeconfig "$KL_KC" get secrets

Error from server (Forbidden): secrets is forbidden: User "user:admin" cannot list resource "secrets" in API group "" in the namespace "default"

viewer no incluye los secrets y debugger tampoco. Es el propio cluster el que responde 403: kubelatch solo le dice quién eres.

12. Míralo en la auditoría¶

• En «Inicio», «Actividad reciente» lista tus últimas peticiones, día a día. «Ver toda mi actividad» abre «Mi actividad», que lista cada petición hecha con tus credenciales: create de selfsubjectreviews (el whoami), list de pods (default) con 200, exec de pods/exec web (default) con 101 y list de secrets (default) con 403.
• En «Mi actividad», pulsa la fecha de una fila para abrir el «Detalle de la petición» en un panel a la derecha: el «Audit-ID» (el mismo que recibe el cluster), los «Grupos suplantados», la «IP de origen» y el «User-Agent».
• En «Auditoría», la pestaña «Peticiones a los clusters» muestra lo mismo para todas las cuentas, con filtros. La pestaña «Plano de control» muestra lo que hiciste en la interfaz, una frase por evento (Cluster kind registrado, Tokens del cluster kind guardados … con su comando de enrolamiento, Inicio de sesión de la CLI aprobado en ……); al abrir uno aparece su código de acción: user.create, cluster.create, cluster.enrollment.create, cluster.tokens, grant.create, cli.approve, cli.login…

13. Revoca la credencial¶

1. En «Inicio», en «Mis credenciales», pulsa «Revocar» en la fila «Sesión de la CLI en ».
2. Un diálogo te pide un motivo (opcional). Escribe fin del tutorial y pulsa «Revocar». Un aviso dice que la credencial está revocada y la fila sale de la lista, que muestra las credenciales activas. Marca «Mostrar caducadas y revocadas» y vuelve con «Revocada el …» y tu motivo debajo.

Prueba otra vez:

kubectl --kubeconfig "$KL_KC" get pods

error: You must be logged in to the server (credential revoked)

Es un 401: la credencial dejó de valer al instante. Un exec, logs -f o port-forward que estuviera abierto con ella se habría cortado en menos de 10 segundos. kubelatch logout hace lo mismo desde la terminal.

El intento también queda en «Auditoría». Abre «Más filtros», marca «Incluir descubrimiento» y pulsa «Aplicar»: aparece una fila sin cuenta, con el prefijo del token (klt_…), el estado 401 y, debajo, credential revoked.

14. Conecta un agente de IA (opcional, 5 minutos)¶

Si usas Claude Code, deja que trabaje en el cluster como tú, a través de kubelatch. Antes date un rol que puede cambiar cosas, para ver que el agente no puede usarlo sin ti:

1. En «Permisos», pulsa «Conceder permisos» y concede a admin el rol developer en kind, default (PSA baseline), durante 30 días.

2. En la terminal, añade kubelatch a Claude Code para este directorio y arráncalo confiando en el certificado del tutorial:

   claude mcp add --transport http kubelatch-tutorial https://localhost:8443/mcp
   NODE_EXTRA_CA_CERTS="$PWD/kubelatch-ca.crt" claude
   

3. Pregúntale: Using kubelatch, who am I and which pods run in default on kind? Claude Code te dice que kubelatch necesita que inicies sesión; ejecuta /mcp, elige kubelatch-tutorial e inicia sesión.

4. El navegador abre la pregunta «¿Dejar que Claude Code actúe como tú?», con «Este agente se ejecuta en tu ordenador. Autorízalo solo si acabas de conectarlo tú.» encima de los botones. Bajo «Qué recibe · hasta cuándo» aparecen tus tres permisos en default, bajo kind. Deja debugger en «No incluir», como viene, pon viewer en «No incluir» (developer lo incluye) y developer en «Mismo rol (developer)»: el agente recibe lo que permite developer y, con «Las escrituras piden mi aprobación» activado como viene, cada una de sus escrituras te espera. Mantén la duración y pulsa «Autorizar».

5. De vuelta en Claude Code, el agente llama a whoami y a list_resources. whoami responde (los ids y las fechas cambian):

   identity: user:admin
   session:
     id: …
     mode: delegated
     expires_at: …
   on_behalf_of: user:admin
   credential_expires_at: …
   writes_need_approval: true
   permissions:
     - cluster: kind
       role: developer
       scope: default
       includes: Read plus deploying workloads in the namespace (no Secrets or exec; no writes to ServiceAccounts, roles or quotas)
       expires_at: …
   scope "*" is the whole cluster; any other scope is one namespace.
   

   y lista ticker y web.

6. Pídele: Delete the pod ticker in default. Llama a delete_resource. kubelatch comprueba con el cluster que el borrado pasaría y lo retiene en vez de ejecutarlo. Claude Code muestra Approve in kubelatch: delete_resource pods/ticker in default (kind) y te pide abrir la página de aprobación en el navegador: acepta. Si lo rechazas, o tu Claude Code es anterior a la 2.1.274, el agente recibe en su lugar agent.approval_pending con el enlace: ábrelo tú, o ve a «Agentes», la tarjeta «Te esperan».

   El título de la página dice lo que se pide en una frase (… quiere eliminar pods/ticker en default (kind)) con el estado «Pendiente», y «Cambios» dice «Este objeto se elimina.» con cada línea del pod marcada con −. Pulsa «Denegar» y confirma con «Denegar» en el diálogo. De vuelta en Claude Code, la llamada que esperaba tu decisión termina con agent.approval_denied: a person denied this write: do not try it another way. ticker sigue en marcha: nada cambia hasta que tú lo digas. Si hubieras pulsado «Aprobar», esa llamada habría ejecutado el borrado una vez, tal como lo viste.

7. En la interfaz, abre «Agentes»: «Agentes en marcha» lista tu Claude Code, delegado, con su última llamada. Ábrelo; su página muestra el agente en nombre de admin, modo «Delegado»: «Techo» lista lo que le diste y «Línea de tiempo», cada llamada, el borrado retenido incluido (su lectura del pod y su dry run, ambos bajo delete_resource). Pulsa «Cortar» y confirma. La siguiente llamada del agente falla y Claude Code te pide iniciar sesión de nuevo.

Sal de Claude Code con /exit. Agentes de IA cuenta el resto: aprobaciones, acceso temporal y el plugin de Claude Code.

15. Entra con el SSO de tu empresa (opcional, 5 minutos)¶

kubelatch puede dejar entrar a las personas con el proveedor de OpenID Connect que ya usan (Google Workspace, Microsoft Entra ID, Okta, Keycloak…), y vincula a cada una con su cuenta por el correo. El fichero de Compose trae un Keycloak para probarlo, detrás del perfil sso. Conoce a tres personas: alice@acme.test; bob@acme.test, cuya dirección Keycloak no ha verificado; y carol@other.test, fuera del dominio que vas a permitir. La contraseña de cada una es su nombre seguido de -password.

1. Con el login OIDC encendido, solo las cuentas break-glass entran con contraseña. Convierte antes a tu admin en una, para que pueda seguir entrando:

   docker compose exec kubelatch /kubelatch-server user set-break-glass admin
   

   Responde break_glass=true for admin.

2. Apunta kubelatch a Keycloak y arráncalo:

   cat >> .env <<'EOF'
   OIDC_ISSUER=http://127.0.0.1:8081/realms/kubelatch
   OIDC_CLIENT_ID=kubelatch
   OIDC_CLIENT_SECRET=kubelatch-tutorial-secret
   OIDC_ALLOWED_DOMAINS=acme.test
   EOF
   docker compose --profile sso up -d --wait
   

   La primera vez descarga la imagen de Keycloak. kubelatch se reinicia con las variables en cuanto Keycloak está listo, en menos de un minuto. Keycloak está en 127.0.0.1 y no en localhost a propósito: kubelatch, en https://localhost:8443, le pide al navegador que use solo https en localhost, y este Keycloak habla http sin cifrar.

3. En la interfaz, ve a «Usuarios», pulsa «Crear una cuenta», escribe alice en «Login» y alice@acme.test en «Correo», y pulsa «Crear e invitar». Cierra dos veces el diálogo del enlace: alice no lo va a necesitar. kubelatch nunca crea personas: la cuenta tiene que existir, con la dirección que el proveedor tiene para esa persona.

4. Abre https://localhost:8443 en una ventana privada: la pantalla de entrada ofrece ahora «Entrar con Keycloak». Púlsalo y entra en Keycloak como alice, con alice-password. Llegas a «Inicio» como Alice Acme, el nombre que Keycloak tiene para ella: su primera entrada vinculó la cuenta por su correo. De vuelta en tu ventana, «Auditoría» → «Plano de control» muestra «alice» se vinculó por correo a la identidad OIDC alice@acme.test, 1 enlace pendiente revocado (la invitación del paso anterior) y «alice» inició sesión. Al recargar, «Avisos», la campana de la barra superior, dice 1 persona ha entrado por primera vez con Keycloak y se ha vinculado por su correo esta semana.
5. Cierra todas las ventanas privadas, lo que también termina la sesión de alice en Keycloak («Salir» en kubelatch solo termina la de kubelatch), abre una nueva y prueba con carol: kubelatch responde Esa cuenta de Keycloak no es de un dominio que este kubelatch acepte. ¿Has elegido una cuenta personal?. Con bob, responde Keycloak no garantiza tu dirección de correo, así que kubelatch no puede emparejarla con una cuenta.. Cada intento deja un inicio de sesión fallido en «Plano de control», con su motivo.

kubelatch login funciona igual para alice: el navegador pasa por Keycloak camino de la aprobación. La consola de Keycloak está en http://127.0.0.1:8081, como admin con admin. Login con OIDC (SSO) explica cómo configurarlo con tu propio proveedor.

16. Limpia¶

claude mcp remove kubelatch-tutorial   # si hiciste el paso 14
docker compose --profile sso down -v   # para kubelatch, Postgres y Keycloak y borra sus datos
kind delete cluster --name kubelatch-tutorial --kubeconfig "$KIND_KC"
cd .. && rm -r kubelatch-tutorial

Si prefieres volver más tarde, páralo con docker compose --profile sso down, sin -v: los datos se quedan en volúmenes de Docker, y docker compose up -d vuelve a levantar kubelatch con tu admin (docker compose --profile sso up -d --wait si hiciste el paso 15), así que sáltate el paso 5.

Si algo falla¶

Para errores del día a día con una credencial, mira Si algo falla. Cuando termines, Próximos pasos te dice qué leer según lo que vayas a hacer.