Configuración¶
Todas las variables de entorno que lee el binario kubelatch-server, con su valor por defecto, su formato y lo que hacen. No hay fichero de configuración ni flags del servidor.
Al arrancar, kubelatch valida todas las variables y, si hay errores, los muestra todos juntos y no arranca. Los subcomandos de la CLI del servidor leen las mismas variables con las mismas reglas: también necesitan DATABASE_URL, KUBELATCH_BASE_URL y KUBELATCH_ENCRYPTION_KEY.
Cada variable tiene un ancla con su nombre en minúsculas: configuration.md#kubelatch_base_url, configuration.md#database_url, configuration.md#github_app_id.
Formatos comunes¶
| Formato | Qué admite |
|---|---|
| Duración | Un número de días <n>d (sin ceros a la izquierda, hasta 3650d) o una duración de Go mayor que cero (720h, 90m), hasta 10 años. |
| Lista | Valores separados por comas; se ignoran los espacios alrededor y los elementos vacíos. |
| Booleano | Exactamente true o false. Cualquier otro valor es un error. |
| URL | Absoluta, http o https, sin usuario, query (?) ni fragmento (#). |
Servidor¶
Para generar KUBELATCH_ENCRYPTION_KEY:
head -c32 /dev/urandom | base64
Base de datos¶
TLS¶
Permisos¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_PROTECTED_NAMESPACES |
No | vacío | Lista de nombres de namespace | Namespaces que no admiten permisos de ningún rol, además de kube-system, kube-public, kube-node-lease y kubelatch-system, que siempre lo están. Un nombre que no sea un nombre válido de namespace impide el arranque. |
KUBELATCH_REQUIRE_PSA |
No | true |
Booleano | Con false, developer, debugger, admin y los roles personalizados que lo exigen dejan de exigir que el namespace tenga pod-security.kubernetes.io/enforce=baseline o restricted. «Permisos» lo avisa. Ver Roles de sistema antes de cambiarlo. |
Límites y TTL¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_MAX_TTL_USER |
No | 30d |
Duración | Duración máxima de una credencial de persona. |
KUBELATCH_MAX_TTL_BOT |
No | 90d |
Duración | Duración máxima de una credencial de bot, incluidas las de CI. |
KUBELATCH_CLI_SESSION_TTL |
No | 12h |
Duración, no mayor que KUBELATCH_MAX_TTL_USER |
Duración de una sesión de kubelatch login (ver La CLI). Si KUBELATCH_MAX_TTL_USER es menor de 12 h, el valor por defecto es ese. |
Auditoría¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_AUDIT_RETENTION |
No | 90d |
Duración de al menos 1 día, o 0 / 0d |
Cuánto se conservan los eventos de auditoría y de control. Una tarea periódica borra cada hora las filas más antiguas. 0 o 0d apaga ese borrado; la tarea sigue pasando cada hora para caducar las solicitudes de agentes de IA que nadie decidió ni ejecutó a tiempo y las solicitudes de alta que nadie respondió. Las solicitudes de alta aprobadas, rechazadas, canceladas o caducadas se borran cuando son más antiguas que este valor, igual que los eventos. Una instancia que nunca tuvo clave de licencia conserva 24 horas como mucho, diga lo que diga este valor (0 incluido); ver Ediciones y licencia. Los identificadores de tokens de CI ya usados y las peticiones de acceso caducadas de la CLI también los purga la tarea, y además cada canje de CI o cada nuevo acceso desde la CLI, así que no dependen de este valor. |
Edición¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_LICENSE |
No | vacío | Una clave de licencia (un JWT) | La clave de licencia Pro. Sin ella kubelatch funciona como Free, con sus límites (ver Ediciones y licencia). La clave se verifica contra las claves públicas incluidas en el binario, al arrancar y cada hora, sin ninguna llamada de red. Una clave que no verifica deja kubelatch en Free y muestra un aviso a los administradores; nunca impide arrancar. Con esta variable puesta, la clave no se puede instalar ni quitar desde la interfaz. En Kubernetes va en el Secret kubelatch-secrets con las demás variables secretas. |
KUBELATCH_ACCESS_CONTACT |
No | vacío | Una dirección mailto:, una URL https:// o un texto corto (como mucho 200 caracteres) |
A quién pide acceso una persona. «Inicio» lo muestra junto a «Pedir acceso» y «Pedir una prórroga»: como enlace si es una dirección mailto: o una URL https://, y como texto detrás de la acción si es otra cosa. El 403 de un cluster también lo nombra donde no se puede dar un enlace para pedir (Free). Vacío: quien ha iniciado sesión recibe mailto: y la dirección del administrador habilitado más antiguo que tenga una (su propio correo o el de su identidad OIDC), y si ningún administrador tiene dirección, «Inicio» deja las frases «Pide acceso a un administrador.» y «Pide una prórroga a un administrador.» sin enlace (sus primeros pasos nombran a ese administrador: «Pide acceso a tu administrador (ana).») y un 403 dice Ask your kubelatch administrator. Con el login con OIDC, la página de login también lo muestra cuando un acceso no encuentra cuenta («Para tener cuenta, pídela a {contact}.»), así que GET /api/auth/methods lo devuelve a cualquiera; la página de login y GET /api/auth/methods solo enseñan el valor configurado, nunca la dirección de un administrador. |
KUBELATCH_TICKET_URL |
No | vacío | Una URL https:// con {key} una sola vez (como mucho 500 caracteres) |
A dónde lleva el ticket de un permiso. Un ticket es una URL https:// (siempre un enlace), una clave como INC-123 o ENG-42 (se escribe en minúsculas o mayúsculas y se guarda en mayúsculas) o un número como #512. Una clave o un número se enlazan con esta plantilla, donde {key} se sustituye por la clave o por los dígitos sin #: https://acme.atlassian.net/browse/{key} (Jira), https://linear.app/acme/issue/{key} (Linear) o https://github.com/acme/ops/issues/{key} (GitHub Issues). Vacío enseña las claves y los números como texto. Solo https: llega a ser un enlace, y kubelatch no comprueba que el ticket exista. Un valor que no sea una URL https:// con {key} una sola vez impide arrancar. |
KUBELATCH_UPDATE_CHECK |
No | true |
Booleano | En los 30 segundos siguientes al arranque y luego una vez al día (a la hora si un intento falla), kubelatch lee KUBELATCH_UPDATE_CHECK_URL para saber si hay una versión nueva publicada, y los administradores ven un aviso en la campana y la fila «Versión» de «Edición». La petición no lleva identificador, ni versión, ni nada de la instancia. false lo desactiva; un binario sin versión (dev) nunca comprueba. |
KUBELATCH_UPDATE_CHECK_URL |
No | https://docs.kubelatch.com/releases/latest.json |
Una URL http(s) absoluta |
De dónde lee la comprobación de versión la última publicada ({"version", "published_at", "url"}). En una instalación aislada de internet, apúntala a un espejo interno. De ese documento kubelatch lee version, y url solo si es un enlace https en el mismo host que esta URL: con un espejo que sirve el fichero de la documentación, la versión se muestra sin ese enlace y «Cómo actualizar» lleva a la guía de actualización de docs.kubelatch.com. Una URL de espejo con usuario o contraseña va en el Secret: el chart de Helm la rechaza en config.updateCheckURL, que acaba en un ConfigMap. |
Correo¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_RESEND_API_KEY |
No | vacío | Una API key de Resend | Permite a kubelatch enviar correo a través de Resend: los enlaces de invitación y de restablecimiento que los administradores copiarían si no (invitaciones por correo), y el correo que avisa a cada persona con dirección antes de que termine uno de sus permisos, que puede apagar (avisos). Usa una clave con Sending access solamente, limitada al dominio de envío. Es un secreto: en Kubernetes va en el Secret kubelatch-secrets, y kubelatch nunca la escribe en los logs. Sin ella, los enlaces se copian a mano y nadie recibe correos; los demás avisos siguen funcionando. Necesita KUBELATCH_MAIL_FROM, y kubelatch no arranca con una y sin la otra. |
KUBELATCH_MAIL_FROM |
Con KUBELATCH_RESEND_API_KEY |
vacío | Una dirección de correo, con o sin nombre, como kubelatch <noreply@example.com> |
El remitente de esos correos, en un dominio verificado en Resend. Un valor que no sea una sola dirección impide arrancar. En el chart de Helm es mail.from. |
Webhooks¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_WEBHOOK_ALLOW_PRIVATE |
No | false |
Booleano | Con true, los webhooks de Pro pueden llegar a direcciones que no son públicas: localhost, loopback, privadas (RFC 1918 y fc00::/7), link-local y los demás rangos reservados, para un receptor dentro de tu red. Solo levanta esa comprobación: la URL sigue siendo solo https, las redirecciones siguen sin seguirse y HTTPS_PROXY sigue sin tenerse en cuenta. En el chart de Helm es config.webhookAllowPrivate. |
Logs¶
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
KUBELATCH_LOG_LEVEL |
No | info |
debug, info, warn o error, sin distinguir mayúsculas |
Nivel mínimo de lo que escribe kubelatch. debug añade una línea por cada petición a /healthz y /readyz. |
KUBELATCH_LOG_FORMAT |
No | json |
json o text, sin distinguir mayúsculas |
json escribe un objeto JSON por línea en la salida estándar; text, pares clave=valor. Qué lleva cada línea está en El log del servidor. |
Interfaz¶
CI¶
Agentes de IA¶
El servidor MCP para agentes de IA y el inicio de sesión de los agentes delegados (Agentes de IA).
Identidad y GitHub¶
Estas variables configuran el login con la GitHub App de tu organización (ver Login con GitHub). Sin ninguna de ellas, y sin el login con OIDC, kubelatch funciona solo con contraseñas locales.
Las cinco variables núcleo (GITHUB_APP_ID, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY, GITHUB_ORG) van juntas. Con cualquiera de ellas presente, o con GITHUB_WEBHOOK_SECRET, las cinco son obligatorias y kubelatch no arranca si falta alguna. GITHUB_REQUIRE_ORG_2FA, GITHUB_URL y GITHUB_API_URL solas no activan nada. A todas se les quitan los espacios alrededor.
La sincronización de miembros se ejecuta cada hora; ese intervalo no es configurable.
Login con OIDC¶
Estas variables configuran el login con el proveedor de identidad de tu empresa por OpenID Connect: Google Workspace, Microsoft Entra ID, Okta, Keycloak, Authentik, Auth0 o cualquier proveedor que publique su documento de descubrimiento (ver Login con OIDC (SSO)). Puede estar activo a la vez que el login con GitHub. En el chart de Helm son los values de config.oidc, salvo OIDC_CLIENT_ID y OIDC_CLIENT_SECRET, que van en el Secret.
Las cuatro variables núcleo (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ALLOWED_DOMAINS) lo activan. Con cualquiera de ellas presente, OIDC_ISSUER, OIDC_CLIENT_ID y OIDC_ALLOWED_DOMAINS son obligatorias, y kubelatch no arranca mientras falte alguna; el error nombra todas las que faltan. Por eso un OIDC_CLIENT_SECRET suelto también impide el arranque. OIDC_DISPLAY_NAME, OIDC_SCOPES, OIDC_SUBJECT_CLAIM, OIDC_EMAIL_VERIFIED_CLAIM, OIDC_AUTOLINK y OIDC_ICON solas no activan nada. A todas se les quitan los espacios alrededor.
| Variable | Obligatoria | Por defecto | Formato | Qué hace |
|---|---|---|---|---|
OIDC_ISSUER |
Con OIDC | URL; http solo en un host loopback; se guarda tal cual, con la barra final |
El issuer del proveedor, exactamente como lo trae su documento de descubrimiento, con la barra final si la lleva (Auth0 y Authentik acaban en /). kubelatch lee <OIDC_ISSUER>/.well-known/openid-configuration y solo acepta ID tokens cuyo iss sea este valor. Un issuer de Microsoft Entra ID (login.microsoftonline.com, login.microsoftonline.us, login.partner.microsoftonline.cn o sts.windows.net) tiene que llevar el id del tenant, un GUID: con common, organizations, consumers o un nombre de dominio, kubelatch no arranca. |
|
OIDC_CLIENT_ID |
Con OIDC | Texto | Client id de la aplicación registrada en el proveedor. Los ID tokens tienen que nombrarlo en aud. |
|
OIDC_CLIENT_SECRET |
No | vacío | Texto | Client secret de un cliente confidencial, para canjear el código del login en el servidor. Vacío significa un cliente público, solo con PKCE. |
OIDC_ALLOWED_DOMAINS |
Con OIDC | Lista de nombres de dominio (acme.com, acme.org), al menos uno |
Los dominios de correo que se aceptan, en minúsculas y exactos: un subdominio tiene que ir en la lista por su cuenta, y los comodines se rechazan. Un acceso con una dirección de cualquier otro dominio se rechaza. | |
OIDC_DISPLAY_NAME |
No | SSO |
Texto, de 1 a 40 caracteres, sin caracteres de control | El nombre del proveedor en la interfaz: el botón dice «Entrar con {name}» y los mensajes de la página de login lo nombran. |
OIDC_ICON |
No | la que se deduce de OIDC_ISSUER |
google, microsoft, okta, auth0 o generic, sin distinguir mayúsculas |
El logo del botón de acceso. Vacía, kubelatch reconoce el proveedor por el host del issuer: Google, Microsoft Entra ID, Okta y Auth0. Cualquier otro issuer lleva una llave genérica. Defínela si tu issuer está en un dominio propio, como sso.acme.com delante de Okta. Con cualquier otro valor, kubelatch no arranca. |
OIDC_SCOPES |
No | openid email profile |
Scopes separados por espacios o comas | Los scopes que pide kubelatch. Sin openid o sin email, kubelatch no arranca. |
OIDC_SUBJECT_CLAIM |
No | sub |
Nombre de claim: una letra o _, y después letras, dígitos, _, ., : o -, hasta 64 caracteres |
El claim que identifica a la persona. Tiene que nombrar un claim que sea de una sola persona y que no cambie nunca ni pase a otra: sub, u oid en Microsoft Entra ID. Con un claim que guarde una dirección o un nombre (email, upn, preferred_username, name…), uno que compartan muchas personas (tid, hd, iss, aud, idp, locale…), uno del token o de la sesión (nonce, sid, jti…) o el claim de OIDC_EMAIL_VERIFIED_CLAIM, kubelatch no arranca. Forma parte de la identidad, como OIDC_ISSUER: tras cambiar cualquiera de los dos, el siguiente acceso de cada persona sustituye su identidad por correo, según permita OIDC_AUTOLINK (Cambiar de proveedor o de claim de identidad). |
OIDC_EMAIL_VERIFIED_CLAIM |
No | email_verified |
Nombre de claim, con el mismo formato | El claim que dice que el proveedor verificó la dirección de correo; tiene que valer true. Microsoft Entra ID usa xms_edov. |
OIDC_AUTOLINK |
No | all |
all, invited u off, sin distinguir mayúsculas |
Qué cuentas vincula un primer acceso por su dirección de correo: all, cualquier cuenta habilitada con esa dirección; invited, solo una que no ha entrado nunca o tiene un enlace de invitación o de restablecimiento pendiente; off, ninguna, y cada cuenta se vincula con su enlace de invitación o de vinculación (La política de vinculación). |
Qué va en un Secret
En Kubernetes, DATABASE_URL, KUBELATCH_ENCRYPTION_KEY, KUBELATCH_LICENSE, KUBELATCH_RESEND_API_KEY, las variables GITHUB_* sensibles, OIDC_CLIENT_ID y OIDC_CLIENT_SECRET van en el Secret kubelatch-secrets, que el Deployment carga entero. El resto va en los values config del chart, que se convierten en el ConfigMap kubelatch-config (con el nombre de release sugerido, kubelatch): ver Values de Helm.