KubeBolt docs
ENES GitHub

Guías de despliegue

Guía de Docker Desktop

Ejecuta KubeBolt en contenedores, con Docker Compose o la imagen única, contra el Kubernetes integrado de Docker Desktop o un clúster de kind.

En esta página
  1. El problema
  2. La solución
  3. kind
  4. Iniciar sesión
  5. Puertos
  6. Metrics Server
  7. ¿Hace falta el agente?
  8. Qué esperar

Esta página trata de ejecutar KubeBolt en contenedores (Docker Compose o la imagen de contenedor único) contra un clúster en tu propia máquina: el Kubernetes integrado de Docker Desktop, o kind. Otras dos formas de instalarlo se saltan todo esto:

El problema

El Kubernetes de Docker Desktop publica su servidor de API en 127.0.0.1:6443. Esa dirección funciona desde tu máquina, pero dentro de un contenedor 127.0.0.1 es el propio contenedor, así que KubeBolt no puede llegar al clúster.

La solución

deploy/docker-kubeconfig.sh copia tu kubeconfig ($KUBECONFIG, o ~/.kube/config) en /tmp/docker-kubeconfig y reescribe cada servidor https://127.0.0.1 y https://localhost como https://kubernetes.docker.internal, un nombre que Docker Desktop resuelve al host desde dentro de los contenedores y que cubre el certificado de su servidor de API. El archivo de Compose monta esa copia, no ~/.kube.

Tanto el script auxiliar como el archivo de Compose están en el repositorio de git, así que la vía de Compose empieza clonándolo. Compose construye las imágenes de la API y de la web a partir del código clonado, así que el primer up tarda unos minutos:

# 1. Docker Desktop → Settings → Kubernetes → Enable Kubernetes
# 2. Obtén el repo: deploy/docker-compose.yml y el script auxiliar están en él
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt

# 3. Haz que docker-desktop sea el contexto actual: KubeBolt se abre en él
kubectl config use-context docker-desktop

# 4. Genera el kubeconfig compatible con contenedores
./deploy/docker-kubeconfig.sh

# 5. Arranca
cd deploy && docker compose up -d

Abre http://localhost:3000. Los demás contextos del archivo aparecen en el selector de clústeres, con los límites de lo que funciona dentro de un contenedor.

El script auxiliar no es opcional, y no solo para Docker Desktop. El archivo de Compose monta /tmp/docker-kubeconfig, no ~/.kube, así que toda instalación con Compose ejecuta primero el script. En un clúster remoto no reescribe nada y simplemente copia el archivo.

Mantener la copia al día

/tmp/docker-kubeconfig es una instantánea. Vuelve a ejecutar el script y después docker compose restart api cada vez que añadas o cambies un contexto, y después de que un reinicio vacíe /tmp.

Si arrancaste Compose antes de ejecutar el script por primera vez, Docker creó /tmp/docker-kubeconfig como un directorio vacío para satisfacer el montaje, y entonces el script no puede escribir el archivo. Bórralo y empieza de nuevo:

# desde deploy/
docker compose down
rm -rf /tmp/docker-kubeconfig
./docker-kubeconfig.sh
docker compose up -d

Contextos que llaman a la CLI de una nube

El script copia todos los contextos, pero dentro de un contenedor solo funcionan los que se autentican con un certificado o un token (Docker Desktop, kind, k3d y minikube lo hacen). La imagen de la API que construye Compose no incluye ninguna CLI de nube, así que un contexto cuyo usuario ejecuta aws eks get-token, gke-gcloud-auth-plugin o kubelogin falla allí. La imagen de contenedor único solo incluye aws-cli (consulta la guía de EKS). Ejecuta KubeBolt en el host para esos clústeres, o conéctalos con el agente.

La imagen de contenedor único

También necesita el archivo reescrito y, por tanto, el código clonado para el script. La imagen se ejecuta como usuario no root, así que monta el archivo en algún lugar legible y apunta KUBECONFIG a él en lugar de montarlo bajo /root. El volumen /data conserva usuarios y ajustes entre reinicios del contenedor:

./deploy/docker-kubeconfig.sh
docker run -d --name kubebolt -p 3000:3000 \
  -v /tmp/docker-kubeconfig:/kubeconfig:ro -e KUBECONFIG=/kubeconfig \
  -v kubebolt-data:/data \
  ghcr.io/clm-cloud-solutions/kubebolt:latest

La API y la interfaz son un solo proceso en el puerto 3000. Esta imagen no lleva almacén de series temporales; consulta Puertos.

kind

kind también publica su servidor de API en 127.0.0.1, pero en un puerto aleatorio y con un certificado que no cubre kubernetes.docker.internal, así que la reescritura del script no sirve. En su lugar, escribe el kubeconfig interno de kind, que se dirige al contenedor del plano de control por su nombre, y añade el overlay de kind para que el contenedor de la API se una a la red de Docker de kind:

KIND_CLUSTER=kind   # el --name que diste a `kind create cluster`; el valor por defecto de kind es "kind"

kind get kubeconfig --internal --name "$KIND_CLUSTER" > /tmp/docker-kubeconfig
cd deploy && docker compose -f docker-compose.yml -f docker-compose.kind.yml up -d

El archivo contiene entonces solo ese clúster. No ejecutes docker-kubeconfig.sh después: lo sobrescribiría con tu kubeconfig completo. Pasa los dos archivos -f en cada docker compose up posterior, o la API se recreará sin la red de kind.

Iniciar sesión

La autenticación está activada por defecto. En el primer arranque, KubeBolt crea un usuario admin e imprime la contraseña generada una sola vez:

docker compose logs api | grep "Generated admin password"   # imagen única: docker logs kubebolt 2>&1 | grep …

Define la tuya con KUBEBOLT_ADMIN_PASSWORD antes del primer arranque; es más sencillo que leer el log. Expórtala en la shell que ejecuta docker compose up, o ponla en deploy/.env (parte de deploy/.env.example). Solo se aplica en el primer arranque; después, cambia la contraseña desde el menú Account.

Fuera de Kubernetes no hay ningún Secret al que recurrir, así que si pierdes la contraseña, restablécela sobre el mismo volumen de datos (primero hay que detener la API: BoltDB admite un solo escritor):

docker compose stop api
docker compose run --rm api --reset-admin-password=NEWPASS
docker compose start api

El run restablece la contraseña, imprime admin password reset OK y termina. Consulta Autenticación para los equivalentes en Kubernetes.

El primer inicio de sesión del admin abre el Setup Wizard: cuatro pasos opcionales que puedes saltarte.

Puertos

PuertoServicio
3000Interfaz web, la que abres
8080API en Go, HTTP y WebSocket
9090Canal gRPC para el agente
8428VictoriaMetrics

Compose es la opción local que incluye VictoriaMetrics, con 30 días de retención (KUBEBOLT_METRICS_RETENTION). Las vías de Homebrew, del binario y de docker run no llevan base de datos de series temporales: el uso en vivo de Metrics Server se sigue viendo, pero los gráficos de historial se quedan vacíos salvo que apuntes KUBEBOLT_METRICS_STORAGE_URL a un VictoriaMetrics. En cualquier caso, lo que llena el historial es el agente.

Metrics Server

Docker Desktop no incluye Metrics Server. Sin él, el uso en vivo de Overview muestra “no data”; los recursos, los eventos y los insights no se ven afectados. Instálalo y comprueba que kubectl top responde:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
kubectl top nodes

Si kubectl top nodes sigue fallando y kubectl -n kube-system logs deploy/metrics-server muestra un error x509 que dice que el certificado no contiene ningún IP SAN, el certificado de servicio del kubelet no cubre la dirección a la que se conecta metrics-server. En un clúster local de pruebas, deja que metrics-server se salte esa comprobación (kind suele necesitar lo mismo):

kubectl -n kube-system patch deployment metrics-server --type=json \
  -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'

¿Hace falta el agente?

Para conectar, no: con un kubeconfig, KubeBolt habla directamente con el clúster. Pero el agente es lo que llena el historial. Sin él tienes CPU y memoria en vivo de Metrics Server, pero no gráficos de historial, flujos de red ni costos.

El agente se ejecuta dentro del clúster y se conecta al puerto gRPC de la API, que Compose publica en el host como 9090. Desde un clúster en Docker Desktop (incluidos kind, k3d y minikube), esa dirección es host.docker.internal:9090:

helm install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system --create-namespace \
  --set backendUrl=host.docker.internal:9090

Con el overlay de kind, el agente también puede conectarse a la API por el nombre de su contenedor, deploy-api-1:9090 (<project>-api-1 si el proyecto de Compose tiene otro nombre). Compose deja desactivada la autenticación de agentes, así que no hace falta token; el paso Agent del Setup Wizard y Add cluster imprimen el mismo comando con las opciones que elijas.

Qué esperar

Docker Desktop es un destino documentado, pero trátalo como un entorno de desarrollo y no de producción. KubeBolt necesita Kubernetes v1.24 o posterior para todas las funciones, y funciona con funciones reducidas en v1.20–v1.23 (consulta Compatibilidad).