KubeBolt docs
ENES GitHub

Deployment Guides

Docker Desktop Guide

Run the containerised KubeBolt, with Docker Compose or the single image, against Docker Desktop's built-in Kubernetes or a kind cluster.

On this page
  1. The Problem
  2. The Solution
  3. kind
  4. Log in
  5. Ports
  6. Metrics Server
  7. Do I need the agent?
  8. What to expect

This page is about running KubeBolt in containers (Docker Compose or the single-container image) against a cluster on your own machine: Docker Desktop’s built-in Kubernetes, or kind. Two other ways to install skip all of it:

The Problem

Docker Desktop’s Kubernetes publishes its API server at 127.0.0.1:6443. That address works from your machine, but inside a container 127.0.0.1 is the container itself, so KubeBolt cannot reach the cluster.

The Solution

deploy/docker-kubeconfig.sh copies your kubeconfig ($KUBECONFIG, or ~/.kube/config) to /tmp/docker-kubeconfig and rewrites every https://127.0.0.1 and https://localhost server to https://kubernetes.docker.internal, a name Docker Desktop resolves to the host from inside containers and that its API server certificate covers. The compose file mounts that copy, not ~/.kube.

Both the helper and the compose file live in the git repository, so the Compose path starts with a clone. Compose builds the API and web images from the checkout, so the first up takes a few minutes:

# 1. Docker Desktop → Settings → Kubernetes → Enable Kubernetes
# 2. Get the repo — deploy/docker-compose.yml and the helper live in it
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt

# 3. Make docker-desktop the current context — KubeBolt opens on it
kubectl config use-context docker-desktop

# 4. Generate the container-compatible kubeconfig
./deploy/docker-kubeconfig.sh

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

Open http://localhost:3000. The other contexts in the file are in the cluster switcher, subject to what works inside a container.

The helper is not optional, and not only for Docker Desktop. The compose file mounts /tmp/docker-kubeconfig, not ~/.kube, so every Compose install runs the script first. On a remote cluster it rewrites nothing and simply copies the file.

Keeping the copy current

/tmp/docker-kubeconfig is a snapshot. Run the helper again, then docker compose restart api, whenever you add or change a context, and after a reboot clears /tmp.

If you started Compose before ever running the helper, Docker created /tmp/docker-kubeconfig as an empty directory to satisfy the mount, and the helper then fails to write it. Remove it and start over:

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

Contexts that call a cloud CLI

The helper copies every context, but inside a container only the ones that authenticate with a certificate or a token work — Docker Desktop, kind, k3d and minikube all do. The API image Compose builds ships no cloud CLI, so a context whose user runs aws eks get-token, gke-gcloud-auth-plugin or kubelogin fails there. The single-container image ships aws-cli only (see the EKS guide). Run KubeBolt on the host for those clusters, or connect them with the agent.

The single-container image

It needs the rewritten file too — and therefore the checkout for the helper. The image runs as a non-root user, so mount the file somewhere readable and point KUBECONFIG at it rather than mounting under /root. The /data volume keeps users and settings across container restarts:

./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

API and UI are one process on port 3000. This image carries no time-series store; see Ports.

kind

kind also publishes its API server on 127.0.0.1, but on a random port and with a certificate that does not cover kubernetes.docker.internal, so the helper’s rewrite does not help. Write kind’s internal kubeconfig instead, which addresses the control-plane container by name, and add the kind overlay so the API container joins kind’s Docker network:

KIND_CLUSTER=kind   # the --name you gave `kind create cluster`; kind's default is "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

The file then holds only that cluster. Do not run docker-kubeconfig.sh afterwards: it would overwrite it with your full kubeconfig. Pass both -f files on every later docker compose up, or the API is recreated without the kind network.

Log in

Authentication is on by default. On first boot KubeBolt seeds an admin user and prints the generated password once:

docker compose logs api | grep "Generated admin password"   # single image: docker logs kubebolt 2>&1 | grep …

Set your own with KUBEBOLT_ADMIN_PASSWORD before the first start — simpler than reading the log. Export it in the shell that runs docker compose up, or put it in deploy/.env (start from deploy/.env.example). It only seeds the first boot; after that, change the password from the Account menu.

Outside Kubernetes there is no Secret to fall back on, so if you lose the password, reset it against the same data volume (the API has to be stopped first — BoltDB is single-writer):

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

The run resets the password, prints admin password reset OK and exits. See Authentication for the Kubernetes equivalents.

The first admin login opens the Setup Wizard — four optional steps you can skip.

Ports

PortService
3000Web UI, the one you open
8080Go API, HTTP and WebSocket
9090gRPC channel for the agent
8428VictoriaMetrics

Compose is the local option that bundles VictoriaMetrics, with 30 days of retention (KUBEBOLT_METRICS_RETENTION). The Homebrew, binary and docker run paths carry no time-series database: live usage from Metrics Server still shows, but history charts stay empty unless you point KUBEBOLT_METRICS_STORAGE_URL at a VictoriaMetrics. Either way, what fills history is the agent.

Metrics Server

Docker Desktop does not ship Metrics Server. Without it, the Overview’s live usage reads “no data”; resources, events and insights are unaffected. Install it, then check that kubectl top answers:

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

If kubectl top nodes keeps failing and kubectl -n kube-system logs deploy/metrics-server shows an x509 error saying the certificate doesn’t contain any IP SANs, the kubelet’s serving certificate does not cover the address metrics-server dials. On a local test cluster, let metrics-server skip that check (kind usually needs the same):

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

Do I need the agent?

Not to connect: with a kubeconfig KubeBolt talks to the cluster directly. But the agent is what fills history. Without it you get live CPU and memory from Metrics Server, and no history charts, network flows or cost.

The agent runs inside the cluster and dials the API’s gRPC port, which Compose publishes on the host as 9090. From a cluster on Docker Desktop (kind, k3d and minikube included) that address is 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

With the kind overlay, the agent can also dial the API by its container name, deploy-api-1:9090 (<project>-api-1 when the Compose project has another name). Compose leaves agent authentication off, so no token is needed; the Setup Wizard’s Agent step and Add cluster print the same command with the options you pick.

What to expect

Docker Desktop is a documented target, but treat it as a development environment rather than a production one. KubeBolt needs Kubernetes v1.24 or newer for full features, and works with degraded features on v1.20–v1.23 (see Compatibility).