Configuración¶

Todas las variables de entorno que lee el binario kubelatch, 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 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. Los manifiestos de `deploy/k8s/base` usan `:8443`.
`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>/cuenta#kli_…`), el `server` de los kubeconfigs (`<base>/clusters/<id>`), la audiencia (`aud`) que deben traer los tokens de GitHub Actions y el callback de la GitHub App (`<base>/api/auth/github/callback`).
`KUBELATCH_ENCRYPTION_KEY`	Sí		Base64 estándar de exactamente 32 bytes	Clave maestra. De ella se derivan, con etiquetas distintas, la clave que firma las cookies de sesión, la que firma las cookies de estado del login con GitHub y la clave AES-256-GCM que cifra los tokens de las ServiceAccounts de cada cluster. Rotarla cierra todas las sesiones y obliga a volver a pegar 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. La limpieza sí devuelve el ClusterRole compartido `kubelatch-proxy` a la regla de solo `uids`. 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 cree `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 intercambio 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 la pareja cuando cambia en disco (comprueba como mucho cada 10 s); una pareja inválida se ignora y se registra en el log. Una pareja inválida 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.

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 nivel, además de `kube-system`, `kube-public`, `kube-node-lease` y `kubelatch-system`, que siempre lo están.
`KUBELATCH_REQUIRE_PSA`	No	`true`	Booleano	Con `false`, `developer`, `debugger` y `admin` dejan de exigir que el namespace tenga `pod-security.kubernetes.io/enforce=baseline` o `restricted`. «Permisos» lo avisa. Ver Niveles 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.

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 `audit_events` y `control_events`. Una tarea periódica en cada réplica borra cada hora (la primera pasada, un minuto después de arrancar), por lotes de 5 000 filas. `0` o `0d` desactiva el borrado. La misma tarea borra los `jti` de CI una hora después de que caduque su token, sea cual sea este valor.

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

Identidad y GitHub¶

Estas variables configuran el login con la GitHub App de tu organización (ver Login con GitHub). Sin ninguna de ellas, 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 corre cada hora; ese intervalo no es configurable.

Qué va en un Secret

En Kubernetes, DATABASE_URL, KUBELATCH_ENCRYPTION_KEY y las variables GITHUB_* sensibles van en el Secret kubelatch-secrets, que el Deployment carga entero. El resto va en deploy/k8s/base/config.env, que se convierte en el ConfigMap kubelatch-config.