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
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
web.enabled=truees obligatorio para una instalación autocontenida: sin él, la ruta va directa al Service de la API y la interfaz no se sirve. No aparece envalues.yaml.- Sin
certManager.clusterIssuer, aporta tú los Secrets de TLS (gatewayAPI.api.tlsSecretName,gatewayAPI.agent.tlsSecretName). - Mantén
gatewayAPI.forceHTTP1=true(el valor por defecto) en Envoy Gateway: su HTTP/2 por defecto rompe el upgrade a WebSocket (actualizaciones en vivo, terminal de pod). Ponlo enfalsecon otro controlador. - Los agentes remotos se conectan entonces a
agent.kubebolt.example.com:443contls.enabled=true. Si un CDN hace de proxy de tu DNS, deja ese hostname en modo solo DNS (DNS-only).
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í.
- Script de instalación en una línea. Un
curl … | shque detecta el sistema operativo y la arquitectura y deja el binario en su sitio. Hoy no existe ese script en el repositorio; hasta que exista, usa la descarga del binario único o Homebrew. - krew-index oficial. Cuando
kubeboltse acepte en elkubernetes-sigs/krew-indexoficial,kubectl krew install kubeboltfuncionará sin añadir el índice propio de CLM. Hasta entonces, usa el índice propio de arriba. - Operador de Kubernetes. Gestión declarativa del ciclo de vida mediante un
CRD
KubeBolten un controlador Kubebuilder aparte, que se encarga de las actualizaciones y de la autorreparación. Hoy, el chart de Helm es la forma soportada de gestionar el ciclo de vida dentro del clúster.
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.