Minikube Docker Desktop Connectivity Verifier

The Incident (What Does the Error Mean?)

You restart Docker Desktop. You open a terminal. You run:

$ kubectl get nodes
NAME       STATUS     ROLES           AGE   VERSION
minikube   NotReady   control-plane   12d   v1.28.3

Followed by:

$ minikube status
minikube
type: Control Plane
host: Stopped
kubelet: Stopped
apiserver: Stopped
kubeconfig: Configured

Immediate consequence: Your entire local Kubernetes control plane is down. kubectl apply, kubectl exec, helm install — all fail. If you're running integration tests in CI against a local cluster, every pipeline job is now blocked.

The root cause is deterministic: Docker Desktop on restart tears down and recreates the minikube Docker network bridge and the Unix domain socket that the Minikube node container depends on. The kubelet process inside the minikube container loses its CRI socket path (/var/run/docker.sock or the containerd socket), cannot re-register with the API server, and the node condition Ready flips to False — then the container itself stops.

The Attack Vector / Blast Radius

This is not a security exploit, but the blast radius in a shared dev environment or a local CI runner is severe:

• Cascading test failures: Any GitHub Actions self-hosted runner or Jenkins agent using Minikube as the test cluster will produce false-negative failures across all PRs in flight.
• Stale kubeconfig corruption: If Docker Desktop assigns a new internal IP to the minikube container on restart, your ~/.kube/config still points to the old cluster IP (192.168.49.2 by default). Every kubectl call silently hits a dead endpoint — no error, just a timeout, which is the worst failure mode for debugging.
• Orphaned PVCs and PersistentVolumes: Workloads that were mid-write when Docker Desktop restarted may leave hostPath PVs in a locked state, requiring manual cleanup.
• Multi-context contamination: If you run multiple Minikube profiles (minikube -p dev, minikube -p staging), a Docker Desktop restart can corrupt all contexts simultaneously.

Prevention in CI/CD

1. Liveness Probe Script in CI Bootstrap

Add this to your .github/workflows/*.yml or Jenkinsfile before any kubectl step:

#!/bin/bash
set -euo pipefail
echo "Verifying Minikube cluster health..."
for i in {1..10}; do
  STATUS=$(kubectl get nodes --no-headers 2>/dev/null | awk '{print $2}')
  if [[ "$STATUS" == "Ready" ]]; then
    echo "Cluster Ready."
    exit 0
  fi
  echo "Attempt $i: Node not ready. Waiting 10s..."
  sleep 10
done
echo "FATAL: Cluster did not become Ready. Running minikube start."
minikube start --driver=docker

2. OPA/Conftest Policy: Enforce Driver and Static IP

If your team uses a shared minikube config file (.minikube/config/config.json), enforce it with a Conftest policy:

package minikube

deny[msg] {
  input.driver != "docker"
  msg := "Minikube must use the docker driver in this environment."
}

deny[msg] {
  not input["static-ip"]
  msg := "Minikube must be started with --static-ip to survive Docker Desktop restarts."
}

3. Docker Desktop Settings

• Enable: Settings → General → Start Docker Desktop when you log in — prevents cold-start socket races.
• Enable: Settings → Resources → WSL Integration (Windows) or ensure the Docker socket symlink is valid on macOS after every Docker Desktop upgrade.
• Disable: Settings → Experimental → Use containerd for pulling and storing images — this changes the CRI socket path and breaks Minikube's default assumptions without explicit --container-runtime=containerd flag.

4. Checkov / Pre-commit Hook

Add a pre-commit hook that validates your local kubeconfig before committing code that assumes cluster availability:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: validate-kubeconfig
      name: Validate Minikube kubeconfig
      entry: bash -c 'kubectl cluster-info --request-timeout=3s'
      language: system
      pass_filenames: false