Agentes de IA¶

Qué garantiza kubelatch cuando un agente de IA trabaja en tus clusters a través de su servidor MCP, y dónde terminan esas garantías. Cómo conectar tu propio agente está en Agentes de IA; cómo gestionar bots, sesiones y solicitudes, en Agentes de IA para operadores.

Un solo camino hasta los clusters¶

Un agente se conecta a kubelatch en <URL base>/mcp (el Model Context Protocol sobre HTTP) y llama a herramientas: listar objetos, leer uno, leer logs, aplicar un objeto, etc. Las herramientas no hablan con los clusters por su cuenta. Cada llamada se convierte en una o más peticiones de Kubernetes que pasan por el mismo proxy que kubectl (El viaje de una petición): la misma suplantación, la misma fila de auditoría escrita antes de que la petición salga (si no se puede escribir, la petición no sale) y el RBAC del propio cluster decidiendo. kubelatch decide con qué grupos se envía al agente; el API server decide qué pueden hacer esos grupos.

flowchart LR
    a["Agente<br/>Claude Code, Cursor…"] -->|"MCP sobre HTTP"| m["kubelatch<br/>herramientas de /mcp"]
    m -->|"el mismo proxy que kubectl"| k8s["Tus clusters"]
    m --> au[("Auditoría<br/>con la sesión<br/>y la herramienta")]

Cada fila de auditoría de un agente lleva su sesión de agente y la herramienta que la hizo, así que se puede seguir todo lo que hizo un agente.

Dos formas de dar acceso a un agente¶

Un bot. Un administrador crea un bot para el agente, le concede roles y le emite una credencial, que el agente envía. Los clusters ven bot:<nombre>. Es para un agente que no es de una persona: un agente de guardia, un paso de un pipeline.

En tu nombre (delegado). Autorizas tú al agente, en el navegador. Es el gesto de «Iniciar sesión con Google»: no das tu contraseña, das un permiso limitado que puedes retirar. Los clusters te ven a ti, user:<login>, pero solo con los permisos que elegiste para el agente. Es para tu propio agente, en tu ordenador.

	Bot	Delegado
Quién es el agente en el cluster	`bot:ops-agent`	`user:sergio`
De dónde salen sus permisos	De los que un administrador concedió al bot	De los tuyos, recortados por ti
Quién decide cuánto puede hacer	Un administrador	Tú, hasta tu propio límite
Si te quitan a ti un permiso	No le afecta	El agente lo pierde al momento

Los dos a la vez. sergio es developer en shop. Su Claude Code, en modo delegado, entra como él en solo lectura. Aparte, la empresa tiene un agente de guardia que revisa alertas por la noche; usa el bot ops-agent, que es viewer en todos los namespaces porque un administrador se lo dio. Son dos identidades que no se tocan.

Las credenciales propias de una persona (un kubeconfig emitido, una sesión de kubelatch login, una credencial de CI) no valen en /mcp: el agente de una persona entra siempre por el inicio de sesión delegado, para que haya techo y consentimiento. Y los tokens de agente solo valen en /mcp: el proxy y la API los rechazan.

El techo de un agente delegado¶

Al autorizar a un agente, cada permiso tuyo que incluyes se convierte en un permiso derivado de su sesión. Juntos forman su techo:

El mismo cluster y el mismo ámbito que el tuyo, y tu rol o viewer. viewer solo se ofrece desde un rol que lo incluye (viewer, developer, admin y cluster-admin). Un permiso debugger, secrets-reader o de un rol personalizado solo se puede pasar tal cual: viewer le daría al agente lecturas que tú no tienes. La página de consentimiento los deja fuera salvo que los incluyas.
Nunca cluster-admin: un permiso cluster-admin solo se puede pasar como viewer.
Termina cuando termina la sesión o cuando termina tu permiso, lo que ocurra antes. Si revocan tu permiso, el derivado deja de contar en la siguiente llamada del agente.
Un permiso que te conceden después de autorizar al agente entra en la sesión solo como elegiste en la página de consentimiento, en «Permisos que recibas más adelante»: nada, viewer (por defecto) o el mismo rol. Vale para un permiso directo, un lote y la pertenencia a un grupo. Cada uno se convierte en un permiso derivado con las reglas de arriba: un cluster-admin que recibas después pasa como viewer, nunca como tal, y viewer solo desde un rol que lo incluye. Termina con la sesión o con el permiso del que viene, y deja un evento de control, agent.grant.follow. Para ir más allá, el agente lo pide con request_access, o lo autorizas de nuevo.

El cluster ve al agente solo con los grupos de sus permisos derivados, nunca con todos los tuyos.

Aprobaciones y acceso temporal¶

Aprobar escrituras. Es un interruptor. Para un bot, lo activa un administrador en los ajustes del bot (viene desactivado: decide solo el rol). Para un agente delegado, lo eliges tú al autorizarlo (viene activado). Con él activado:

El agente pide una escritura. kubelatch la envía primero al cluster como dry run; si el cluster la rechaza, el agente recibe esa respuesta y no se retiene nada.
kubelatch guarda la petición y enseña a una persona qué cambiaría, en la página de la solicitud: una línea que dice qué hace, y el objeto actual frente a lo que el dry run dice que será. Los valores de un Secret nunca se muestran ahí, y la página nunca dice que la escritura de un Secret no cambia nada, porque un valor oculto puede cambiar.
Decide una persona: tú, para tu agente delegado; un administrador, para un bot.
El agente vuelve a llamar. Un cliente que sabe preguntar abre la página de la solicitud y repite la llamada por sí solo; los demás entregan el enlace en texto y el agente repite la llamada con el approval_id. La llamada espera la decisión hasta un minuto. Una vez aprobada, kubelatch ejecuta la petición que guardó, una sola vez, y el resultado empieza con una línea que dice quién la aprobó. Si la segunda llamada pide otra cosa, se rechaza. Si el objeto cambió entre la aprobación y la ejecución, la escritura falla y hay que pedirla de nuevo; un borrado nunca elimina un objeto recreado con el mismo nombre.

La misma llamada repetida mientras su solicitud sigue esperando devuelve esa solicitud, no una segunda. Una escritura retenida espera 15 minutos una decisión y, aprobada, otros 15 para ejecutarse. Su cuerpo se guarda cifrado mientras espera y se borra cuando se deniega, se ejecuta o caduca. Una cuenta puede tener como mucho 20 solicitudes esperando a la vez.

Acceso temporal. Con request_access, un agente pide un rol en un namespace (o en todo el cluster) durante 1 a 480 minutos, con un motivo. Para un bot decide un administrador, y se concede un permiso normal con esa caducidad, con las reglas de siempre. Para un agente delegado decides tú, y solo un rol que tengas en ese cluster y namespace, nunca cluster-admin; se convierte en un permiso derivado. Una solicitud de acceso caduca a la hora si nadie decide.

Mientras un acceso aprobado dura, surte efecto y su rol puede escribir, las escrituras del agente en su cluster y namespace no esperan aprobación una a una: quien lo aprobó ya dijo que sí a ese rol, allí, durante ese tiempo. kubelatch no sabe qué escrituras permite cada rol, así que durante ese tiempo el agente escribe allí también con todo lo que sus otros permisos allí le permitan. Cuando termina, las escrituras vuelven a pedir aprobación. Es el camino cómodo para una tarea con varios cambios: una aprobación de «developer en shop, 30 minutos» en lugar de una por cambio.

Secrets¶

list_resources, get_resource y apply ocultan cada valor de un Secret (<redacted, N bytes>) y quitan su anotación kubectl.kubernetes.io/last-applied-configuration. En la vista previa de una escritura retenida, un valor que la escritura cambia se lee <redacted, N bytes, changed>: quien decide ve que cambia, nunca en qué se convierte. No es un control de acceso: read_secret devuelve los valores a cualquier agente cuyo rol pueda leer Secrets allí. Sirve para que un valor solo llegue al agente cuando lo pide, y para que cada lectura de valores sea una fila de auditoría propia. No se ocultan los ConfigMaps, las variables de entorno escritas en la especificación de un pod ni los logs.

Cómo inicia sesión un agente¶

Para los agentes delegados, kubelatch es el servidor de autorización OAuth 2.1, y un cliente MCP lo encuentra solo a partir del primer 401 de /mcp:

El cliente del agente se registra (con un documento de metadatos que publica, o por registro dinámico) y te lleva a la página de consentimiento de kubelatch, con PKCE (S256).
El consentimiento necesita tu sesión web y una pulsación: ningún enlace puede responderlo por ti.
El agente recibe un token de acceso de 1 hora, válido solo en /mcp y nunca más allá de la sesión, y un refresh token que cambia en cada uso. Un refresh token o un código presentado por segunda vez corta la sesión al momento.
kubelatch solo redirige a una dirección que el cliente registró; en tu propio ordenador (localhost, 127.0.0.1, [::1]), con cualquier puerto.
La página de consentimiento dice quién pide, a dónde va la respuesta, qué recibiría el agente y hasta cuándo, y avisa siempre que la respuesta fuera a salir de tu ordenador: otro host, o una aplicación que abre un esquema privado.

Servidor MCP tiene los endpoints y las reglas en detalle.

Lo que no cubre¶

kubelatch declara estos límites en lugar de esconderlos:

El contenido puede llevar instrucciones. Los logs, las anotaciones y los campos de los objetos vienen del cluster y pueden traer texto escrito para dirigir a un modelo. kubelatch no lo filtra; el techo, las aprobaciones y los valores de Secrets ocultos limitan el daño.
Un valor de Secret leído queda leído. Cuando read_secret devuelve un valor, queda en el contexto del agente y en el historial de su proveedor del modelo. Cortar la sesión no lo recupera.
Un agente que controle tu navegador podría aprobar sus propias solicitudes. Las aprobaciones dan por hecho que pulsa una persona.
Otras vías de acceso. El techo acota lo que el agente hace a través de kubelatch. Si en tu máquina tiene otra vía hacia un cluster (un kubeconfig, una sesión de kubelatch login, la CLI de una nube), puede usarla. Las reglas y el plugin de Claude Code solo lo cubren en parte: las reglas aconsejan, y el hook es una barandilla para un agente bienintencionado, no una frontera. Se puede esquivar, y solo funciona en Claude Code.
Sin exec, port-forward, watch ni logs -f. Las herramientas no los ofrecen; eso lo hace una persona con su propia credencial.