Saltar a contenido

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

Variable Obligatoria Por defecto Formato Qué hace
KUBELATCH_LISTEN No :8080 host:puerto Dirección y puerto de escucha. El chart de Helm pone :8443 (:8080 con exposure: ingress).
KUBELATCH_BASE_URL Sí URL URL pública con la que se llega a kubelatch. Se normaliza: sin barra final, esquema y host en minúsculas, sin el puerto por defecto. Decide el atributo Secure de las cookies (si es https), el único origen de confianza para la protección contra peticiones de otro origen, la URL de los enlaces de invitación (<base>/account-link#kli_…), el server de los kubeconfigs (<base>/clusters/<id>), la audiencia (aud) que deben traer los tokens de GitHub Actions, el callback de la GitHub App (<base>/api/auth/github/callback) y la URI de redirección del login con OIDC (<base>/api/auth/oidc/callback).
KUBELATCH_ENCRYPTION_KEY Sí Base64 estándar de exactamente 32 bytes Clave maestra. Protege las cookies de sesión y los tokens guardados de cada cluster. Rotarla cierra todas las sesiones y obliga a rotar los tokens de cada cluster.
KUBELATCH_INSTANCE_ID No default Valor de etiqueta de Kubernetes: alfanumérico, -, _, ., hasta 63 caracteres Valor de la etiqueta kubelatch.io/instance de los objetos que kubelatch crea en los clusters. La limpieza y el recolector de esa instancia solo tocan sus propios objetos, lo que permite mover un cluster a otra instancia. No sirve para que dos instancias compartan un cluster a la vez.
KUBELATCH_TRUSTED_PROXIES No vacío Lista de CIDR (10.0.0.1/32 para un solo host) Redes desde las que se acepta X-Forwarded-For, leído de derecha a izquierda hasta el primer salto que no es de confianza. Afecta a la IP de origen de la auditoría y del plano de control y a los límites por IP del login, del acceso desde la CLI, del canje de CI y de los fallos del proxy. Una IP suelta es un error, y también un prefijo más amplio que /8 (IPv4) o /16 (IPv6). Vacío detrás de un LoadBalancer L4; obligatorio detrás de un Ingress.

Para generar KUBELATCH_ENCRYPTION_KEY:

head -c32 /dev/urandom | base64

Base de datos

Variable Obligatoria Por defecto Formato Qué hace
DATABASE_URL Sí Cadena de conexión de Postgres (postgres://usuario:clave@host:5432/kubelatch?sslmode=require) Base de datos con todo el estado. kubelatch aplica sus migraciones al arrancar, y también cada subcomando de la CLI.

TLS

Variable Obligatoria Por defecto Formato Qué hace
KUBELATCH_TLS_CERT Con KUBELATCH_TLS_KEY vacío Ruta a un fichero PEM Certificado del servidor. Con las dos variables, kubelatch sirve HTTPS (TLS 1.2 o superior, HTTP/2 y HTTP/1.1). Recarga el par certificado-clave cuando cambia en disco (comprueba como mucho cada 10 s); un par inválido se ignora y se registra en el log. Un par inválido al arrancar impide el arranque. Cada hora avisa si quedan menos de 30 días de validez. Sin ellas, kubelatch sirve HTTP plano.
KUBELATCH_TLS_KEY Con KUBELATCH_TLS_CERT vacío Ruta a un fichero PEM Clave privada del certificado. Las dos variables van juntas: una sin la otra es un error.
KUBELATCH_KUBECONFIG_CA No vacío Ruta a un fichero PEM regular, solo bloques CERTIFICATE, hasta 1 MiB CA que se embebe como certificate-authority-data en cada kubeconfig emitido. Solo hace falta con una CA privada. Un bloque que no sea un certificado (una clave pegada por error) impide el arranque.
KUBELATCH_CLUSTER_CA_FILE No vacío (lo pone el chart) Ruta absoluta a un fichero PEM CA del cluster donde se ejecuta kubelatch, que se lee cada vez que hace falta. Con ella, enrolar ese cluster con tu identidad no pide pegar nada. El chart monta ahí el ConfigMap kube-root-ca.crt (clusterCA.mount). Si el fichero no existe, kubelatch arranca igual.

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

Variable Obligatoria Por defecto Formato Qué hace
KUBELATCH_PROVIDER_LOGOS No published published, all o none, sin distinguir mayúsculas Qué logos de proveedor dibujan «Clusters» y la ficha del cluster. published dibuja una parte, all los de todos los proveedores y none solo las marcas de Kubernetes y k3s. El nombre del proveedor se muestra siempre en texto.

CI

Variable Obligatoria Por defecto Formato Qué hace
KUBELATCH_CI_TOKEN_TTL No 1h Duración, no mayor que KUBELATCH_MAX_TTL_BOT Duración de las credenciales que obtiene un workflow de GitHub Actions al canjear su token OIDC.
KUBELATCH_GITHUB_ACTIONS_ISSUER No https://token.actions.githubusercontent.com URL; http solo en un host loopback Emisor (iss) de los tokens OIDC de GitHub Actions. Sus claves se leen de <issuer>/.well-known/jwks. Para GitHub Enterprise Server: https://<host>/_services/token.

Agentes de IA

El servidor MCP para agentes de IA y el inicio de sesión de los agentes delegados (Agentes de IA).

Variable Obligatoria Por defecto Formato Qué hace
KUBELATCH_MCP_ENABLED No true true o false Sirve el servidor MCP para agentes de IA en /mcp y los endpoints por los que inician sesión los agentes delegados (/oauth/…, /.well-known/…). Con false todos responden 404.
KUBELATCH_MCP_RATE_LIMIT No 120 Número del 1 al 10000 Peticiones que una credencial puede enviar a /mcp por minuto; en un agente delegado, una sesión. Por encima, la respuesta es 429 hasta que acaba el minuto. Cada réplica lleva su propia cuenta.
KUBELATCH_AGENT_SESSION_TTL No 8h Duración, al menos 5m Duración que se propone cuando una persona autoriza a un agente de IA a actuar en su nombre. Como mucho, KUBELATCH_AGENT_SESSION_MAX_TTL.
KUBELATCH_AGENT_SESSION_MAX_TTL No 24h Duración, al menos 5m Duración más larga que una persona puede elegir al autorizar a un agente de IA. Como mucho, KUBELATCH_MAX_TTL_USER.
KUBELATCH_AGENT_APPROVAL_WAIT No 50s Duración de 0 a 4m Cuánto espera la llamada de un agente de IA a que una persona decida una escritura retenida antes de volver a responder pendiente. 0 responde al instante. Mantenla por debajo del timeout de lectura de cualquier proxy delante de kubelatch.

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.

Variable Obligatoria Por defecto Formato Qué hace
GITHUB_APP_ID Con GitHub Entero positivo App ID de la GitHub App. Firma el JWT con el que kubelatch obtiene tokens de instalación.
GITHUB_APP_CLIENT_ID Con GitHub Texto (Iv1.…, Iv23…) Client ID de la App, para el login OAuth.
GITHUB_APP_CLIENT_SECRET Con GitHub Texto Client secret de la App, para canjear el código del login en el servidor.
GITHUB_APP_PRIVATE_KEY Con GitHub PEM RSA completo (PKCS#1 RSA PRIVATE KEY o PKCS#8 PRIVATE KEY), de 2048 a 8192 bits; se admite en una línea con \n literales Clave privada de la App. Es el contenido del fichero, no una ruta.
GITHUB_ORG Con GitHub Login de organización de GitHub (acme-corp) Solo los miembros activos de esta organización pueden entrar. La sincronización horaria de miembros la recorre.
GITHUB_WEBHOOK_SECRET No vacío Texto Activa POST /v1/github/webhook (firma HMAC-SHA256 en X-Hub-Signature-256), que deshabilita al momento a quien sale de la organización. Su presencia activa el modo GitHub.
GITHUB_REQUIRE_ORG_2FA No true Booleano Rechaza los logins con GitHub mientras kubelatch sepa que la organización no exige doble factor. Solo puede saberlo si la App tiene Organization → Administration: read; si no, deja entrar y avisa en cada sincronización.
GITHUB_URL No https://github.com URL; http solo en un host loopback Solo para GitHub Enterprise Server: https://<host>. Base de las rutas de autorización OAuth.
GITHUB_API_URL No https://api.github.com URL; http solo en un host loopback Solo para GitHub Enterprise Server: https://<host>/api/v3.

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.