Pruébalo en local en 15 minutos¶

En este tutorial montas kubelatch en tu máquina con 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.

Tardarás unos 15 minutos, más las descargas de la primera vez (dependencias de Go y Node, la imagen de Postgres y la del nodo de kind).

Antes de empezar¶

Comprueba las versiones con go version, node --version, kind version y kubectl version --client.

Vas a usar dos terminales, las dos en la raíz del repositorio. En la terminal 1 corre kubelatch; todo lo demás va en la terminal 2, en la misma sesión de shell, porque los pasos reutilizan variables.

1. Clona el repositorio¶

git clone <url-del-repo> kubelatch && cd kubelatch   # la URL te la da el equipo que mantiene kubelatch
cp .env.example .env

.env trae la configuración de desarrollo: Postgres en 127.0.0.1:5433 y una clave de cifrado de 32 bytes a cero. Nunca uses esos valores en un entorno real.

2. Arranca Postgres¶

make dev-db

Levanta un Postgres 17 en Docker que escucha solo en 127.0.0.1:5433, para no chocar con un Postgres local en el 5432. Los datos se guardan en un volumen de Docker.

3. Construye la interfaz web¶

make web

Instala las dependencias de la interfaz y la construye en web/dist. El binario de kubelatch la embebe al compilar, así que hazlo antes del siguiente paso.

4. Arranca kubelatch con TLS¶

En la terminal 1:

make dev-tls

Compila bin/kubelatch, genera un certificado autofirmado en .dev/tls/ y deja kubelatch escuchando en https://localhost:8443, con los logs en JSON. Hace falta HTTPS porque kubectl solo envía tokens por HTTPS. Déjalo corriendo.

Comprueba que responde desde la terminal 2:

curl --cacert .dev/tls/server.crt https://localhost:8443/readyz    # ok

5. Crea el primer administrador¶

En la terminal 2. La CLI lee las mismas variables que el servidor:

set -a && . ./.env && set +a
bin/kubelatch 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.

Escribe admin en «Usuario», tu contraseña en «Contraseña» y pulsa «Entrar». Verás «Hola, Admin» y el menú: «Inicio», «Mi cuenta», «Clusters», «Permisos», «Credenciales», «CI», «Auditoría» y «Usuarios».

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

7. Crea el cluster kind¶

e2e/kind.sh up
KIND_KC="$PWD/e2e/.kind/admin.kubeconfig"
kubectl --kubeconfig "$KIND_KC" get pods

El script crea el cluster kubelatch-e2e en medio minuto y escribe su kubeconfig de administrador en e2e/.kind/admin.kubeconfig, nunca en ~/.kube/config. También arranca dos pods de prueba en default: web y ticker. get pods los muestra en Running.

e2e/kind.sh usa ~/.local/bin/kind y ~/.local/bin/kubectl si existen y, si no, los del PATH. Para usar otros: KIND=/ruta/a/kind KUBECTL=/ruta/a/kubectl e2e/kind.sh up.

Ahora marca el namespace default con Pod Security Admission baseline:

kubectl --kubeconfig "$KIND_KC" label namespace default pod-security.kubernetes.io/enforce=baseline

Lo necesitas porque en el paso 9 te darás el nivel debugger, que kubelatch solo concede en namespaces que aplican PSA baseline o restricted. Niveles de permiso explica por qué.

8. 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». Escribe kind en «Identificador (slug, va en la URL del proxy)» y kind local en «Nombre», y pulsa «Registrar». El cluster aparece como «Sin tokens» y se abre el diálogo «Bootstrap de kind local».

2. Pulsa «descargar bootstrap.yaml». El navegador guarda kubelatch-bootstrap-kind.yaml. Aplícalo al cluster kind, cambiando la ruta si tu navegador descarga en otra carpeta:

   kubectl --kubeconfig "$KIND_KC" apply -f ~/Descargas/kubelatch-bootstrap-kind.yaml
   

   Crea el namespace kubelatch-system y las dos ServiceAccounts, con permisos mínimos.

3. Pulsa «Copiar» junto a «One-liner» y ejecútalo así, pegándolo en lugar de <one-liner>:

   ( export KUBECONFIG="$KIND_KC"; <one-liner> )
   

   El one-liner 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. Imprime una línea de JSON: {"server":"https://127.0.0.1:…","ca":"…","proxyToken":"…","reconcilerToken":"…"}.

4. Copia esa línea entera, pégala en «JSON de los tokens» y pulsa «Guardar tokens».

kubelatch valida los tokens contra el cluster, los guarda cifrados y hace la primera reconciliación. El diálogo se cierra y el cluster pasa a «Listo», con la versión de Kubernetes bajo la URL. «Última reconciliación» muestra — hasta que termina esa primera pasada: recarga la página y verás la fecha. Si pulsas «Namespaces», default aparece con PSA baseline.

Si cerraste el diálogo antes de tiempo, «Bootstrap y tokens» lo vuelve a abrir.

9. Date un permiso¶

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

1. Ve a «Permisos».
2. Elige admin (Admin) en «Sujeto», kind en «Cluster», viewer en «Nivel» y default (PSA baseline) en «Ámbito». Deja «Expira» vacío y pulsa «Conceder».
3. Repite con debugger en «Nivel».

La tabla muestra los dos permisos en estado «Activo». 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.

10. Emite tu credencial¶

1. Ve a «Inicio». En «Mis accesos» aparecen tus dos permisos, cada uno con su grupo: kubelatch:ns:default:viewer y kubelatch:ns:default:debugger.
2. En «Mis credenciales», escribe tutorial en «Nombre». Deja «Duración» en «7 días» y «Cluster» en «Todos los que tenga permitidos». Pulsa «Emitir credencial».
3. Se abre «Credencial emitida» con el token y el kubeconfig. Solo se muestran esta vez. Pulsa «Descargar kubeconfig»: el navegador guarda kubelatch-tutorial.yaml.

Guárdalo en un fichero aparte, dentro de .dev/ (git lo ignora), y añádele el certificado autofirmado:

mv ~/Descargas/kubelatch-tutorial.yaml .dev/tutorial.kubeconfig
KL_KC="$PWD/.dev/tutorial.kubeconfig"
kubectl --kubeconfig "$KL_KC" config set-cluster kind --certificate-authority="$PWD/.dev/tls/server.crt" --embed-certs=true

El kubeconfig que emite kubelatch no lleva CA, porque en un despliegue real kubelatch sirve un certificado público (o una CA privada con KUBELATCH_KUBECONFIG_CA). set-cluster solo modifica ese fichero.

11. 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 tu token. kubelatch comprueba que la credencial vale, la registra y la reenvía al cluster con impersonació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.

12. 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.

13. Míralo en la auditoría¶

• En «Inicio», «Mi actividad» 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.
• Pulsa la fecha de una fila para ver el «Detalle de la petición»: el «Audit-ID» (el mismo que recibe el cluster), los «Grupos suplantados», la IP y el User-Agent.
• En «Auditoría», la pestaña «Peticiones a los clusters» muestra lo mismo para todos los sujetos, con filtros. La pestaña «Plano de control» muestra lo que hiciste en la interfaz: user.create, cluster.create, cluster.tokens, grant.create, credential.issue…

14. Revoca la credencial¶

1. En «Inicio», en «Mis credenciales», pulsa «Revocar» en la fila tutorial.
2. El navegador te pide un motivo (opcional). Escribe fin del tutorial y acepta. El estado pasa a «Revocada el …».

Prueba otra vez:

kubectl --kubeconfig "$KL_KC" get pods

error: You must be logged in to the server (credencial revocada)

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.

El intento también queda en «Auditoría». Marca «Incluir descubrimiento» y pulsa «Buscar»: aparece una fila sin sujeto, con el prefijo del token (klt_…) y el estado 401 credencial revocada.

15. Limpia¶

Para kubelatch con Ctrl-C en la terminal 1. Después, en la terminal 2:

e2e/kind.sh down                  # borra el cluster kubelatch-e2e y e2e/.kind/
make dev-db-down                  # para Postgres; los datos se quedan en el volumen
rm .dev/tutorial.kubeconfig ~/Descargas/kubelatch-bootstrap-kind.yaml

Si repites el tutorial con la misma base de datos, tu admin ya existe: sáltate el paso 5. Para empezar de cero, borra también el volumen con docker compose down -v.

Si algo no sale¶

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 tu papel.