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
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:
- En el host (Homebrew, krew, el binario único): KubeBolt llega a
127.0.0.1:6443como cualquier otra herramienta. - Dentro del clúster (el chart de Helm):
usa su propia ServiceAccount, y la StorageClass
hostpathpor defecto de Docker Desktop cubre los dos volúmenes del chart.
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
| Puerto | Servicio |
|---|---|
| 3000 | Interfaz web, la que abres |
| 8080 | API en Go, HTTP y WebSocket |
| 9090 | Canal gRPC para el agente |
| 8428 | VictoriaMetrics |
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).