Kobi
Activar Kobi
Enciende Kobi Copilot con tu propia clave: los valores copilot.* de Helm, las variables de entorno KUBEBOLT_AI_* y la página Configuration, que tiene prioridad sobre ambos.
En esta página
Kobi Copilot viene en todas las ediciones, pero arranca desactivado cuando lo autoalojas. En esta página te explicamos cómo encenderlo. Lo que puede hacer Kobi una vez encendido (las herramientas, los proveedores, el servidor MCP) está en Kobi Copilot.
En KubeBolt Cloud no hay nada que configurar. La IA la gestiona la plataforma: el proveedor, el modelo y la clave son nuestros, y el uso se descuenta de los créditos de tu plan, que es también la unidad en la que lo muestra la app. Kobi está disponible desde el plan Free. Aun así, un administrador de la organización puede desactivar las propuestas de Kobi, o solo las destructivas, y ajustar las tarjetas de llamadas a herramientas y el tiempo límite de las acciones en Administration › AI & Autopilot › Kobi Copilot. Si no lo autoalojas, puedes dejar de leer aquí.
El interruptor es la clave de API
Kobi está encendido siempre que haya una clave de proveedor configurada: ya sea
KUBEBOLT_AI_API_KEY en el contenedor de la API o una clave guardada en
Administration → AI (Kobi) → Configuration. Sin ninguna de las dos, Kobi está
apagado. No hay un flag de “encendido” aparte en tiempo de ejecución:
copilot.enabled en el chart solo decide si el chart genera o no el bloque de
entorno de la IA.
Cuando lo autoalojas, KubeBolt funciona con tu propia clave. Le pagas directamente a tu proveedor; KubeBolt no factura la IA y nunca envía tu clave a ningún sitio salvo al endpoint del proveedor que configuraste. Lo que Kobi le envía a ese proveedor está en Qué llega al modelo.
Con Helm
El bloque copilot del chart viene por defecto con enabled: false. Guarda la
clave en un Secret en lugar de pasarla en línea:
kubectl create secret generic kubebolt-copilot-key -n kubebolt \
--from-literal=api-key=$ANTHROPIC_API_KEY
helm upgrade --install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --create-namespace \
--set copilot.enabled=true \
--set copilot.provider=anthropic \
--set copilot.existingSecret=kubebolt-copilot-key
El bloque completo, con sus valores por defecto:
copilot:
enabled: false # debe ser true o no se genera ningún entorno de IA
provider: anthropic # anthropic | openai
model: "" # vacío = el modelo por defecto del proveedor
baseUrl: "" # URL completa del endpoint, se usa tal cual
maxTokens: "" # vacío = según el modelo (ver abajo)
cacheTtl: "" # caché de prompts de Anthropic: vacío = 1h, "5m" = el valor por defecto de la API
apiKey: "" # clave en línea; mejor usa existingSecret
existingSecret: "" # Secret que contiene la clave en `api-key`
fallback:
enabled: false
provider: "" # vacío = el mismo que el principal
model: ""
baseUrl: ""
apiKey: ""
existingSecret: ""
escalation:
model: "" # consulta "El modelo de escalamiento" más abajo
Solo anthropic y openai son proveedores válidos; cualquier otro valor falla.
Toda API compatible con OpenAI (Azure OpenAI, xAI, DeepSeek, Groq, Mistral,
Ollama, vLLM) usa openai con un baseUrl. La URL base es la URL completa
de la petición y se usa literalmente: en los endpoints compatibles con OpenAI
tiene que terminar en la ruta de chat-completions
(http://ollama.internal:11434/v1/chat/completions, no …/v1).
existingSecret tiene prioridad sobre apiKey. El Secret debe guardar la clave
en api-key; el chart la monta como variable de entorno, así que el valor nunca
aparece en tu archivo de valores ni en helm get values.
El chart solo tiene valores para los ajustes anteriores. Los demás de la sección
siguiente (los interruptores de acciones, el máximo de pasos con herramientas,
las tarjetas de llamadas a herramientas, el tiempo límite de las acciones y la
memoria de la conversación) se configuran con extraEnv o en la página
Configuration:
extraEnv:
- name: KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED
value: "false"
Con variables de entorno
Las instalaciones con Docker Compose y con el binario directo configuran las
mismas variables directamente. Copia deploy/.env.example a deploy/.env y
rellénalas.
| Variable | Valor de Helm | Por defecto | Qué hace |
|---|---|---|---|
KUBEBOLT_AI_API_KEY | copilot.existingSecret / copilot.apiKey | (ninguno) | Tu clave del proveedor. Si está vacía, Kobi queda desactivado. |
KUBEBOLT_AI_PROVIDER | copilot.provider | anthropic | anthropic u openai (openai cubre todas las API compatibles con OpenAI) |
KUBEBOLT_AI_MODEL | copilot.model | claude-haiku-5-5 (anthropic) · gpt-4o (openai) | ID del modelo |
KUBEBOLT_AI_BASE_URL | copilot.baseUrl | el del proveedor | URL completa del endpoint, se usa tal cual (p. ej. …/v1/chat/completions) |
KUBEBOLT_AI_MAX_TOKENS | copilot.maxTokens | según el modelo | Techo por respuesta. Sin definir, es 16384 donde el razonamiento cuenta para ese techo (Claude, modelos de razonamiento de OpenAI) y 4096 en el resto. Defínelo solo para cambiarlo |
KUBEBOLT_AI_CACHE_TTL | copilot.cacheTtl | 1h | Solo Anthropic: cuánto tiempo viven en caché el prompt del sistema y las definiciones de las herramientas. 5m vuelve al valor por defecto de la API, más barato solo cuando las preguntas son poco frecuentes |
KUBEBOLT_AI_MAX_ROUNDS | extraEnv | 20 | Rondas de llamadas a herramientas por respuesta, acotadas a 2–40. En la última, Kobi resume lo que encontró en lugar de fallar |
KUBEBOLT_AI_SHOW_TOOL_CALLS | extraEnv | true | Muestra cada llamada a herramienta como una tarjeta en el panel |
KUBEBOLT_AI_ACTIONS_ENABLED | extraEnv | true | Interruptor general de las herramientas de acción propose_* |
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED | extraEnv | true | Controla específicamente la eliminación y el escalado a cero |
KUBEBOLT_AI_ACTION_PROGRESS_TIMEOUT | extraEnv | 90s | Cuánto tiempo se sigue el rollout de una acción aprobada antes de preguntarle a Kobi por qué se estancó. Mínimo 10s |
Las variables del proveedor de respaldo (KUBEBOLT_AI_FALLBACK_*) y del
escalamiento (KUBEBOLT_AI_ESCALATION_*) están más abajo. Las variables de
memoria de la conversación (KUBEBOLT_AI_AUTO_COMPACT y compañía) están
documentadas en Kobi Copilot, y las del
historial de conversaciones (KUBEBOLT_COPILOT_CONVERSATION_*) en
Conversaciones.
Docker Compose solo pasa las variables que lista su archivo. El
deploy/docker-compose.yml de serie reenvía la clave, el proveedor, el modelo,
la URL base, el máximo de tokens, el TTL de caché, el máximo de rondas, las
tarjetas de llamadas a herramientas, el tiempo límite de las acciones y las
variables de respaldo y de escalamiento. Los dos interruptores de acciones y las
variables de memoria de la conversación no se reenvían: configúralos en la
página Configuration o añádelos al environment del servicio api.
Configura KUBEBOLT_AI_ACTIONS_ENABLED=false para usar Kobi como asesor de solo
lectura, o solo KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED=false para mantener
todas las propuestas menos las eliminaciones y el escalado a cero. La primera
quita las herramientas de propuesta de lo que el backend ofrece al modelo; la
segunda, además, hace que los endpoints de acciones rechacen con un 403 una
eliminación o un escalado a cero propuestos por Kobi. Consulta
Acciones y gobernanza.
Endpoints de los proveedores
Anthropic y OpenAI no necesitan URL base. Todos los demás usan
KUBEBOLT_AI_PROVIDER=openai y su URL completa de chat-completions:
| Proveedor | URL base |
|---|---|
Anthropic (anthropic) | integrada: https://api.anthropic.com/v1/messages |
| OpenAI | integrada: https://api.openai.com/v1/chat/completions |
| Azure OpenAI | https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<version> |
| xAI | https://api.x.ai/v1/chat/completions |
| DeepSeek | https://api.deepseek.com/v1/chat/completions |
| Groq | https://api.groq.com/openai/v1/chat/completions |
| Mistral | https://api.mistral.ai/v1/chat/completions |
| OpenRouter | https://openrouter.ai/api/v1/chat/completions |
| Ollama | http://<host>:11434/v1/chat/completions |
| vLLM | http://<host>:8000/v1/chat/completions |
- El adaptador
openaienvía la clave comoAuthorization: Bearer <key>. La cabeceraapi-keyde Azure OpenAI no se envía: un recurso que solo la acepte necesita un gateway delante. En una URL de Azure, el deployment decide el modelo; aun así, configuraKUBEBOLT_AI_MODELcon el modelo que hay detrás, porque KubeBolt lo usa para la ventana de contexto y la estimación de costos. - El modelo tiene que admitir llamadas a herramientas: Kobi lee todos los datos
del clúster a través de herramientas. vLLM necesita
--enable-auto-tool-choicey un parser de llamadas a herramientas. - En cualquier endpoint que no sea el propio OpenAI, configura
KUBEBOLT_AI_COMPACT_MODELcon un modelo económico que sirva ese endpoint: el valor por defecto,gpt-4o-mini, solo existe en OpenAI. - Los modelos Pro de OpenAI no son compatibles: OpenAI solo los sirve a través de
/v1/responses.
El proveedor de respaldo
El respaldo responde cuando el principal falla con un error recuperable: 429, 5xx, 404 (modelo o endpoint no disponible para tu cuenta) o un fallo de red. Cualquier otro 4xx de tu proveedor (clave incorrecta, petición incorrecta) se te devuelve tal cual, porque al reintentarlo fallaría igual.
Puede ser un modelo más barato del mismo proveedor, otro proveedor o un endpoint
autoalojado. Lo que lo activa es su propia clave: con Helm, configura
copilot.fallback.enabled=true más una clave; sin Helm, configura
KUBEBOLT_AI_FALLBACK_API_KEY. Las otras tres variables
(KUBEBOLT_AI_FALLBACK_PROVIDER, _MODEL, _BASE_URL) son opcionales; el
proveedor, por defecto, es el del principal.
copilot:
enabled: true
provider: anthropic
existingSecret: anthropic-key
fallback:
enabled: true
provider: openai
existingSecret: openai-key
model: gpt-4o-mini
Cuando una respuesta viene del respaldo, el panel del chat la marca con la insignia “Answered by the fallback model”, para que un principal mal configurado nunca quede oculto en silencio.
El modelo de escalamiento
Kobi puede funcionar con un modelo pequeño y pasar a uno más potente, durante el
resto de la conversación, la primera vez que la investigación sale del clúster
seleccionado: una llamada a un conector de nube, o
una respuesta de get_external_connections que apunta a una dependencia en la
nube que uno de tus conectores puede leer. Una conversación abierta al cambiar a
otro clúster empieza en el modelo de escalamiento. Las preguntas dentro de un
clúster se quedan al costo del modelo pequeño, y la página de uso calcula cada
modelo con su propia tarifa.
copilot:
enabled: true
provider: anthropic
model: claude-haiku-5-5
existingSecret: anthropic-key
escalation:
model: claude-sonnet-5-5
Con Helm comparte el proveedor y la clave del principal. Sin Helm, configura
KUBEBOLT_AI_ESCALATION_MODEL, y también KUBEBOLT_AI_ESCALATION_PROVIDER,
_API_KEY y _BASE_URL si funciona en otro sitio; con el mismo proveedor, la
clave y la URL base son por defecto las del principal. Un modelo de escalamiento
igual al principal no hace nada. En la UI es Escalation model, en la tarjeta
del proveedor principal.
En la UI
Administration → AI (Kobi) → Configuration (/admin/ai, rol Admin) edita
los mismos ajustes sin volver a desplegar:
| Tarjeta | Campos |
|---|---|
| Primary provider | Provider, Model, Escalation model, API key, Base URL |
| Fallback provider | Provider, Model, Fallback API key, Fallback base URL |
| Behavior | Max tokens, Tool calls, Kobi actions, Destructive actions, Action timeout, Max tool steps, Auto-compact, Session budget, Compact threshold, Compact model, Preserve turns |
El selector de modelo ofrece un catálogo seleccionado por proveedor y Custom para cualquier otro ID de modelo. El asistente de configuración inicial ofrece el proveedor, el modelo y la clave en su paso AI Copilot.
El orden de las capas importa. Las variables de entorno son la base en el arranque; un valor guardado en la UI se persiste y tiene prioridad en cada lectura posterior, en caliente, sin reiniciar. Así, una instalación configurada solo desde Helm sigue funcionando, y en cuanto alguien guarda un campo en la página Configuration, ese valor es el que manda (los campos que nadie toca siguen el entorno). Reset to env defaults borra todos los valores guardados, claves incluidas. Las claves se cifran en reposo y nunca se devuelven al navegador: el formulario usa el patrón de revelar y reemplazar, así que un campo de clave vacío significa “sin cambios”, no “bórrala”.
Los ajustes guardados desde la UI viven en la base de datos BoltDB de KubeBolt,
así que esto requiere la autenticación activada (lo está por defecto). Las claves
guardadas se cifran con una clave derivada del secreto JWT: si el secreto cambia
(por ejemplo, se generó automáticamente y la API se reinició), no se pueden
descifrar y KubeBolt vuelve a la clave del entorno. Configura un
KUBEBOLT_JWT_SECRET estable (o auth.jwtSecret / auth.existingSecret en
Helm).
Administration → AI (Kobi) → Usage muestra sesiones, tokens, tasa de aciertos de caché y una estimación de costos; Health muestra cómo terminan las respuestas y las valoraciones que reciben.
Comprueba que funciona
-
Reinicia el pod de la API después de cambiar el entorno o los valores de Helm, y revisa el log:
kubectl -n <namespace> logs deployment/kubebolt-api | grep -i "AI copilot"AI copilot enabled provider=... model=...significa que el entorno lleva una clave (unmodelvacío significa el modelo por defecto del proveedor).AI copilot disabled (KUBEBOLT_AI_API_KEY not set)significa que no; esa línea solo refleja el entorno, así que una clave guardada en la UI sigue activando Kobi. -
Pregúntale a la API qué ha resuelto, ajustes guardados desde la UI incluidos. El endpoint no necesita token y nunca devuelve una clave:
curl -s https://kubebolt.example.com/api/v1/copilot/config | jq '{enabled, provider, model}' -
En la UI, el lanzador de Kobi aparece abajo a la derecha y
⌘J(Ctrl+Jen Linux y Windows) abre y cierra el panel. Pregunta “¿cuántos pods hay en ejecución?”: si aparece una tarjeta de herramienta, Kobi llegó al clúster.
Si Kobi responde pero dice que no hay ningún clúster que inspeccionar, el copiloto está bien y lo que no está conectado es el clúster: las herramientas de Kobi leen a través del conector del clúster. Consulta Solución de problemas.
Desactivarlo
helm upgrade kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --reset-then-reuse-values --set copilot.enabled=false
Si se guardó una clave desde la UI, haz clic también en Reset to env defaults
en Administration → AI (Kobi) → Configuration: la clave guardada tiene
prioridad sobre el chart. Sin ninguna clave, el lanzador y ⌘J desaparecen. Para
mantener Kobi pero en solo lectura, desactiva Kobi actions en esa página (o
configura KUBEBOLT_AI_ACTIONS_ENABLED=false).