CLI del servidor¶

Todos los subcomandos y flags del binario kubelatch-server. El mismo binario es el servidor y la herramienta de rescate de cuentas. El cliente para personas es otro binario, kubelatch: ver CLI de kubelatch.

kubelatch-server [serve]
kubelatch-server user create <login> [--admin] [--break-glass] [--display-name <nombre>] [--password-stdin]
kubelatch-server user set-password <login> [--password-stdin]
kubelatch-server user set-break-glass <login> [--off]
kubelatch-server license show
kubelatch-server license verify <fichero>
kubelatch-server version
kubelatch-server help [serve | user [<subcomando>] | license [<subcomando>]]

Cómo se ejecuta¶

Los subcomandos user leen las mismas variables de entorno que el servidor, con las mismas reglas: necesitan al menos DATABASE_URL, KUBELATCH_BASE_URL y KUBELATCH_ENCRYPTION_KEY. Aplican las migraciones pendientes, escriben directamente en la base de datos y registran la acción como evento de control sin actor. No hace falta parar el servidor, y da igual en qué réplica se ejecuten.

Nunca hablan con GitHub. Validan las variables GITHUB_* como el servidor (un bloque incompleto también las hace fallar), pero solo usan su presencia, para saber si el login con GitHub está activo.

En Kubernetes, ejecútalos dentro del pod, siempre con el kubeconfig explícito del cluster de gestión. La imagen no tiene shell: el binario está en /kubelatch-server.

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user create admin --admin

Los flags van después del login.

Binarios¶

Cada release adjunta kubelatch-server a su GitHub Release, con la interfaz web embebida, para Linux y macOS en amd64 y arm64:

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

Comprueba la descarga antes de descomprimirla, en el directorio donde estén los dos ficheros:

sha256sum --ignore-missing -c kubelatch_<versión>_checksums.txt

La imagen ghcr.io/picaportelabs/kubelatch se publica para linux/amd64 y linux/arm64 con el mismo binario en /kubelatch-server.

kubelatch-server y kubelatch-server serve¶

Arranca el servidor: plano de control, proxy, reconciliador y tareas de fondo. Sin argumentos hace lo mismo. No admite flags: todo se configura con variables de entorno. serve -h (o --help) imprime su ayuda sin arrancarlo.

kubelatch-server serve

Escribe logs en JSON por la salida estándar (o en texto clave=valor, ver KUBELATCH_LOG_FORMAT). Termina con código 1 si la configuración no es válida o si falla al arrancar. Ante SIGTERM o Ctrl-C deja de aceptar conexiones, da 3 s a las peticiones en curso, corta los streams abiertos y sale en 30 s como máximo.

kubelatch-server user create¶

Crea una persona con contraseña. Es la forma de crear el primer administrador.

El login solo admite minúsculas, dígitos, ., _ y -, de 1 a 63 caracteres. Un login no se reutiliza nunca, aunque la cuenta anterior esté deshabilitada. La contraseña debe tener de 12 a 128 caracteres y ser distinta del login.

kubelatch-server user create admin --admin
kubelatch-server user create rescate --admin --break-glass --display-name "Cuenta de rescate"

Salida:

user admin created (id 0192…, admin=true, break_glass=false)

Con GitHub activo y una cuenta que no es break-glass, añade un aviso: esa contraseña no servirá para entrar.

kubelatch-server user set-password¶

Fija una contraseña nueva a una persona existente. Además desbloquea la cuenta, revoca sus enlaces pendientes y cierra todas sus sesiones. Es la vía de rescate cuando nadie puede entrar.

kubelatch-server user set-password admin

Salida:

password set for admin; account unlocked and sessions closed

Con GitHub activo, la contraseña solo sirve si la cuenta es break-glass. Si no lo es, el comando lo avisa y sugiere kubelatch-server user set-break-glass.

kubelatch-server user set-break-glass¶

Marca una persona existente como cuenta break-glass, o la desmarca. Es la única forma de hacerlo: ni la interfaz ni la API pueden.

kubelatch-server user set-break-glass admin
kubelatch-server user set-break-glass admin --off

Salida:

break_glass=true for admin

kubelatch rechaza desmarcar al último administrador que puede entrar.

kubelatch-server license show¶

Imprime la edición en vigor: el origen de la clave (KUBELATCH_LICENSE o la pegada en «Edición»), su cliente, plazas y caducidad, los límites que aplican y lo que la instancia contiene. Lee el mismo entorno que el servidor y aplica las migraciones pendientes.

kubelatch-server license show

Salida:

edition: pro
status: pro
source: env
license: 7f3c…
customer: Acme S.L.
seats: 40
trial: false
expires: 2027-10-06T12:00:00Z
grace until: 2027-11-05T12:00:00Z
limits: clusters unlimited, people 40, custom roles unlimited, retention as configured
usage: people: 12, clusters: 4, custom roles: 2

kubelatch-server license verify <fichero>¶

Comprueba un fichero de clave contra las claves públicas incluidas en este binario, sin base de datos, e imprime lo que dice la clave. Una clave caducada también verifica, y la primera línea dice si es válida, está en su periodo de gracia o ha caducado. Código de salida 1 cuando la clave no verifica. Dale la ruta de un fichero: una clave escrita donde va la ruta es un error de uso (código de salida 2) cuyo mensaje nunca repite lo que escribiste.

kubelatch-server license verify kubelatch-pro.jwt

kubelatch-server version¶

Imprime la versión con la que se construyó la imagen (dev en un binario local).

kubelatch-server version

kubelatch-server help¶

Imprime el resumen de uso. También responde a -h y --help.

La ayuda sale con 0; un tema o subcomando desconocido, con 2.

Contraseñas por la entrada estándar¶

Sin --password-stdin, el comando pide la contraseña dos veces por la terminal, sin eco. Si la entrada estándar no es una terminal, falla y pide usar --password-stdin.

Con --password-stdin, todo lo que llega por la entrada estándar es la contraseña, menos un salto de línea final (\n o \r\n). Así echo y printf '%s\n' funcionan tal cual. Una contraseña que termine en salto de línea se pasa con dos.

printf '%s\n' "$PASSWORD" | kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -i deploy/kubelatch -- /kubelatch-server user set-password admin --password-stdin

Códigos de salida y errores¶

Mensajes de error habituales: