KubeBolt docs
ENES GitHub

Primeros pasos

Métodos de instalación

Todas las formas de ejecutar KubeBolt por tu cuenta: el chart de Helm (con Ingress o Gateway API), Docker Compose, el binario único, Homebrew, el contenedor único y el plugin de krew.

En esta página
  1. Chart de Helm (recomendado para Kubernetes)
  2. Docker Compose
  3. Binario único (macOS, Linux, Windows)
  4. Homebrew (macOS, Linux)
  5. Docker (contenedor único)
  6. Plugin de kubectl (krew)
  7. Aún sin construir
  8. Siguientes pasos

Chart de Helm (recomendado para Kubernetes)

Despliegue de producción dentro de tu clúster. Chart basado en OCI en GitHub Container Registry. También está en Artifact Hub.

helm install kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --namespace kubebolt --create-namespace

kubectl -n kubebolt port-forward svc/kubebolt 3000:80

O, en su lugar, con un Ingress y tu propia contraseña de admin (las comillas evitan que zsh expanda los corchetes):

helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --namespace kubebolt --create-namespace \
  --set auth.adminPassword=YourSecurePassword \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set 'ingress.hosts[0].host=kubebolt.example.com' \
  --set 'ingress.hosts[0].paths[0].path=/' \
  --set 'ingress.hosts[0].paths[0].pathType=Prefix'

Añade --version 2.7.0 para fijar una versión en lugar de tomar la última.

El chart despliega la API, la interfaz web y un VictoriaMetrics de un solo nodo para el historial (PVC de 10 GiB, retención de 30 días; un segundo PVC de 1 GiB guarda los datos propios de KubeBolt, ambos en la StorageClass por defecto del clúster), además de una ServiceAccount y un ClusterRole. El ClusterRole concede lectura sobre todos los tipos de recurso que muestra KubeBolt y los verbos de escritura que necesitan sus acciones (exec, port-forward, evict, scale, restart, edit, create, delete); define rbac.create=false y vincula tu propio rol si quieres uno más restringido. KubeBolt comprueba qué pueden hacer sus credenciales y oculta el resto. Entre los valores configurables están los tags de imagen, los recursos, el Ingress, la autenticación, el almacenamiento de métricas y el RBAC; la lista completa está en el README del chart. El primer inicio de sesión, la contraseña de admin generada y el Setup Wizard están en Inicio rápido.

El Ingress solo lleva la interfaz y la API. Los agentes de otros clústeres se conectan al puerto gRPC del agente, que el Ingress no enruta; consulta Exponer el puerto del agente.

Gateway API

Donde ingress-nginx no es una opción, el chart puede exponer KubeBolt mediante Gateway API (usa uno u otro, no los dos). Crea un Gateway con dos listeners HTTPS: uno para la interfaz y la API, y otro para el canal gRPC del agente, con TLS terminado en el gateway. Necesita un controlador de Gateway API y sus CRDs; los valores por defecto apuntan a Envoy Gateway (GatewayClass eg).

helm install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --namespace kubebolt --create-namespace \
  --set gatewayAPI.enabled=true \
  --set gatewayAPI.api.host=kubebolt.example.com \
  --set gatewayAPI.agent.host=agent.kubebolt.example.com \
  --set gatewayAPI.certManager.clusterIssuer=letsencrypt-prod \
  --set web.enabled=true

El chart del agente

Las métricas históricas, los flujos de red y los costos vienen del agente opcional, que se distribuye como su propio chart OCI con un ritmo de versiones independiente:

helm install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system --create-namespace \
  --set backendUrl=kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090

Ese backendUrl es el Service interno de una release llamada kubebolt en el namespace kubebolt (<release>-agent-ingest.<namespace>). Los clústeres remotos se conectan a una dirección pública; consulta Conectar clústeres.

En la práctica rara vez escribes este comando a mano: el asistente Add cluster lo genera con los valores adecuados para tu configuración (modo de Prometheus, OpenCost, mTLS).

Actualizar: primero el backend y después el agente en cada clúster que tenga uno, cada uno con -n <namespace> --reset-then-reuse-values y nunca con --reuse-values, que conserva las imágenes fijadas del chart anterior. Paso a paso en Compatibilidad → Actualización.

Docker Compose

Stack completo con contenedores separados para la API, la web y VictoriaMetrics. Compose construye las imágenes de la API y de la web a partir del repositorio clonado, así que el primer up tarda unos minutos.

deploy/docker-compose.yml y deploy/docker-kubeconfig.sh son archivos del repositorio git, no artefactos publicados, así que Compose empieza con un clon:

git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt

# El archivo de compose monta /tmp/docker-kubeconfig, así que toda instalación
# ejecuta antes el script auxiliar. En clústeres remotos no reescribe nada: solo copia.
./deploy/docker-kubeconfig.sh
cd deploy && docker compose up -d

Frontend en http://localhost:3000. Compose publica cuatro puertos en el host: 3000 (interfaz web), 8080 (API de Go, HTTP y WebSocket), 9090 (ingesta gRPC de los agentes) y 8428 (VictoriaMetrics). La contraseña de admin generada se imprime una sola vez en el log de la API en el primer arranque (docker compose logs api | grep "Generated admin password"), o fija la tuya con KUBEBOLT_ADMIN_PASSWORD en deploy/.env antes del primer up. Los usuarios, los ajustes y las métricas viven en los volúmenes kubebolt-data y kubebolt-vm-data, así que sobreviven a docker compose down (no a down -v). Un agente en un clúster local (kind, Docker Desktop) se conecta a host.docker.internal:9090.

Nota sobre EKS: el archivo de compose monta ~/.aws, pero la imagen de la API que construye no incluye la AWS CLI, así que los kubeconfigs que ejecutan aws eks get-token fallan dentro del contenedor. Para EKS, mejor el binario, Homebrew o la imagen de contenedor único (que trae aws-cli); consulta la guía de EKS.

Binario único (macOS, Linux, Windows)

Un ejecutable con el frontend integrado. API e interfaz en un solo proceso y en un solo puerto. Descárgalo de GitHub Releases.

# macOS Apple Silicon
curl -LO https://github.com/clm-cloud-solutions/kubebolt/releases/latest/download/kubebolt-darwin-arm64
chmod +x kubebolt-darwin-arm64 && sudo mv kubebolt-darwin-arm64 /usr/local/bin/kubebolt

# Linux amd64
curl -LO https://github.com/clm-cloud-solutions/kubebolt/releases/latest/download/kubebolt-linux-amd64
chmod +x kubebolt-linux-amd64 && sudo mv kubebolt-linux-amd64 /usr/local/bin/kubebolt

# Ejecutar (lee todos los contextos del kubeconfig; la contraseña de admin se imprime una vez en el log)
kubebolt --kubeconfig ~/.kube/config

Abre http://localhost:8080 (--port lo cambia, --open abre el navegador) e inicia sesión como admin. El binario guarda los usuarios y los ajustes en ./data, relativo al directorio desde el que lo arrancas (KUBEBOLT_DATA_DIR lo cambia de sitio), y escucha a los agentes en el puerto gRPC 9090.

Disponible para darwin-arm64, darwin-amd64, linux-arm64, linux-amd64 y windows-amd64 (kubebolt-windows-amd64.exe), además del servidor stdio kubebolt-mcp para cada plataforma; los archivos .tar.gz / .zip son los paquetes de krew. Para verificar una descarga, baja CHECKSUMS.txt de la misma versión y ejecuta sha256sum --ignore-missing -c CHECKSUMS.txt (macOS: shasum -a 256 --ignore-missing -c CHECKSUMS.txt).

El binario único (igual que Homebrew, krew y la imagen de contenedor único) no incluye un almacén de series temporales. Las vistas en vivo funcionan sin él. Para el historial, busca un VictoriaMetrics en http://localhost:8428: ejecuta uno ahí, apunta KUBEBOLT_METRICS_STORAGE_URL a otro, o usa el stack de Compose o el chart de Helm. El historial también necesita un agente que envíe muestras (Conectar clústeres).

Soporte de .env: el binario carga automáticamente un archivo .env del directorio desde el que lo arrancas. Pon ahí KUBEBOLT_ADMIN_PASSWORD, KUBEBOLT_AI_API_KEY, etc. Las variables de entorno del sistema y los flags de la CLI tienen prioridad; todas las variables están en Variables de entorno.

Para compilar tu propio binario desde el repositorio en lugar de descargar una versión:

make build-binary
# Genera apps/api/kubebolt (con el frontend integrado)

La ejecución desde el código fuente para desarrollo está documentada en un solo lugar, en Contribuir.

Homebrew (macOS, Linux)

Instala y actualiza con Homebrew. Instala el mismo binario de cada versión como cask, en macOS y Linux (amd64 + arm64).

# Instalar desde el tap de CLM
brew install clm-cloud-solutions/tap/kubebolt

# Ejecutar y luego abrir http://localhost:8080
kubebolt --kubeconfig ~/.kube/config

# Actualizar a la última versión
brew upgrade kubebolt

Todo lo de la sección del binario único aplica aquí: puerto, directorio de datos, historial.

Docker (contenedor único)

Una sola imagen con el frontend integrado. Sin nginx, sin compose. Multiarquitectura (amd64/arm64).

docker run -p 3000:3000 \
  -v ~/.kube/config:/kubeconfig:ro -e KUBECONFIG=/kubeconfig \
  ghcr.io/clm-cloud-solutions/kubebolt:latest

Abre http://localhost:3000 e inicia sesión como admin con la contraseña impresa en el log del contenedor (docker logs <container> | grep "Generated admin password"), o pasa la tuya con -e KUBEBOLT_ADMIN_PASSWORD=…. Las imágenes se etiquetan latest, 2.7 y 2.7.0; fija una en todo lo que vayas a mantener.

La imagen corre con un usuario no root (kubebolt), así que montar ~/.kube en /root/.kube no funciona: el proceso no puede leer /root. Monta el archivo y apunta KUBECONFIG a él, como arriba. En Linux, ese usuario tiene que poder leer el archivo kubeconfig. Un kubeconfig que apunta a 127.0.0.1 (Docker Desktop, kind) llega al propio contenedor, no a tu clúster; consulta la guía de Docker Desktop. La base de datos integrada vive en el volumen /data; monta uno (-v kubebolt-data:/data) si quieres que los usuarios y los ajustes sobrevivan a un reinicio del contenedor. Para que los agentes se conecten, publica también su puerto (-p 9090:9090).

La imagen está firmada con Cosign. Verifícala con:

cosign verify ghcr.io/clm-cloud-solutions/kubebolt:latest \
  --certificate-identity-regexp 'https://github.com/clm-cloud-solutions/kubebolt/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Nota sobre EKS: la imagen incluye aws-cli. Para clústeres EKS, monta tu configuración de AWS en el home del usuario no root (-v ~/.aws:/home/kubebolt/.aws:ro) y define AWS_PROFILE si usas uno, para que el exec aws eks get-token del kubeconfig pueda obtener tokens.

Plugin de kubectl (krew)

Ejecuta KubeBolt como subcomando de kubectl. Disponible a través del índice de krew propio de CLM.

# Requisito previo: instalar krew (una sola vez)
# https://krew.sigs.k8s.io/docs/user-guide/setup/install/

# Añadir el índice propio de CLM
kubectl krew index add clm https://github.com/clm-cloud-solutions/krew-index.git

# Instalar
kubectl krew install clm/kubebolt

# Ejecutar (usa tu kubeconfig; sirve en http://localhost:8080, Ctrl+C lo detiene)
kubectl kubebolt

# Actualizar
kubectl krew upgrade clm/kubebolt

Aún sin construir

Hay otros tres métodos de distribución diseñados pero no publicados. Todavía no hay una URL que darte para ninguno: cuando uno salga, tendrá su sección arriba, no un hueco aquí.

Sigue su avance en el roadmap público.

Siguientes pasos

Con KubeBolt en marcha, conecta tus clústeres: kubeconfig, el agente de conexión solo saliente o solo métricas.