KubeBolt docs
ENES GitHub

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
  1. El interruptor es la clave de API
  2. Con Helm
  3. Con variables de entorno
  4. El proveedor de respaldo
  5. El modelo de escalamiento
  6. En la UI
  7. Comprueba que funciona
  8. Desactivarlo

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.

VariableValor de HelmPor defectoQué hace
KUBEBOLT_AI_API_KEYcopilot.existingSecret / copilot.apiKey(ninguno)Tu clave del proveedor. Si está vacía, Kobi queda desactivado.
KUBEBOLT_AI_PROVIDERcopilot.provideranthropicanthropic u openai (openai cubre todas las API compatibles con OpenAI)
KUBEBOLT_AI_MODELcopilot.modelclaude-haiku-5-5 (anthropic) · gpt-4o (openai)ID del modelo
KUBEBOLT_AI_BASE_URLcopilot.baseUrlel del proveedorURL completa del endpoint, se usa tal cual (p. ej. …/v1/chat/completions)
KUBEBOLT_AI_MAX_TOKENScopilot.maxTokenssegún el modeloTecho 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_TTLcopilot.cacheTtl1hSolo 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_ROUNDSextraEnv20Rondas 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_CALLSextraEnvtrueMuestra cada llamada a herramienta como una tarjeta en el panel
KUBEBOLT_AI_ACTIONS_ENABLEDextraEnvtrueInterruptor general de las herramientas de acción propose_*
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLEDextraEnvtrueControla específicamente la eliminación y el escalado a cero
KUBEBOLT_AI_ACTION_PROGRESS_TIMEOUTextraEnv90sCuá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:

ProveedorURL base
Anthropic (anthropic)integrada: https://api.anthropic.com/v1/messages
OpenAIintegrada: https://api.openai.com/v1/chat/completions
Azure OpenAIhttps://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<version>
xAIhttps://api.x.ai/v1/chat/completions
DeepSeekhttps://api.deepseek.com/v1/chat/completions
Groqhttps://api.groq.com/openai/v1/chat/completions
Mistralhttps://api.mistral.ai/v1/chat/completions
OpenRouterhttps://openrouter.ai/api/v1/chat/completions
Ollamahttp://<host>:11434/v1/chat/completions
vLLMhttp://<host>:8000/v1/chat/completions

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:

TarjetaCampos
Primary providerProvider, Model, Escalation model, API key, Base URL
Fallback providerProvider, Model, Fallback API key, Fallback base URL
BehaviorMax 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

  1. 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 (un model vací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.

  2. 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}'
  3. En la UI, el lanzador de Kobi aparece abajo a la derecha y ⌘J (Ctrl+J en 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).