Proposal: `minikube doctor` command to diagnose a profile and its host
Problem
When minikube start or a running cluster breaks, users have to work out the cause from several commands (minikube status, minikube profile list, docker info, kubectl) and from error text that often names a symptom rather than the cause. Many issues in this repository start with the same questions from maintainers: which driver, is it installed and running, does the profile exist, is the container still there, how much memory was allocated.
Proposal
A read-only minikube doctor command that checks one profile (-p, default minikube) and the host it depends on, and prints each problem with a fix. It never changes anything.
Checks, all using existing minikube code paths:
| Section | Check | Source |
|---|---|---|
| Configuration | Invalid profiles (warning) | config.ListProfiles |
| Configuration | Selected profile exists and loads | config.Load |
| Host | Driver installed and healthy | the driver's registry StatusChecker, as minikube start uses, with the same 20s timeout |
| Host | kubectl on PATH (warning; points to minikube kubectl) |
exec.LookPath |
| Cluster | Host running, API server, kubelet on each node, kubeconfig | one cluster.GetStatus call; Irrelevant (workers, --no-kubernetes) respected |
| Resources | CPUs and memory against the limits minikube start enforces |
minUsableMem, minRecommendedMem, minimumCPUS; no-limit accepted |
Design points:
- Works when things are broken. A missing profile, stale profile or stopped cluster is a finding. Dependent checks are reported as skipped instead of failing in a cascade.
- Consistent with
minikube start. No new thresholds; a freshly started default cluster reports no warnings. - Scriptable.
-o jsonprints a structured report, and the exit code is non-zero when a check fails.
Example output
A profile whose container was removed outside minikube (seen on macOS after reinstalling Docker Desktop):
* Profile: minikube
- Driver: docker, container runtime: docker, Kubernetes: v1.34.0
Configuration
* Profiles: all profile configurations are valid
* Profile: "minikube" loaded
Host
* kubectl: kubectl is on PATH
* Driver: docker is healthy
Cluster
X Cluster status: the cluster's container no longer exists (it was removed outside minikube)
- host: state: unknown state "minikube": docker container inspect minikube --format={{.State.Status}}: exit status 1
* Recreate it with: minikube delete -p minikube && minikube start -p minikube
* API server: skipped: cluster status unavailable
* Nodes: skipped: cluster status unavailable
* Kubeconfig: skipped: cluster status unavailable
Resources
* CPUs: 2 CPUs
* Memory: 3072 MB
* 6 passed, 0 warnings, 1 failed, 3 skippedScope
The first PR would contain only the checks above, as a new pkg/minikube/doctor package with unit tests. Possible follow-ups, each as a separate PR if wanted: host disk space for VM drivers, container runtime health inside the node, and add-on status.
Questions for maintainers
- Is a new top-level command acceptable, or would you prefer this as a flag on an existing command (for example
minikube status --diagnose)? - Which command group should it appear in?
- Any checks you would add or remove for a first version?
An implementation is ready (#23366, to be updated with the version described here).
Source: kubernetes/minikube