Introduction

Upgrading Minikube is more than replacing one binary. You also need to validate profile startup, Kubernetes version compatibility, and addon behavior after restart. A predictable process upgrades Minikube first, then checks each active profile and related tooling.

Core Sections

1. Capture pre-upgrade cluster context

Before changing anything, record current Minikube and Kubernetes state. This gives you a baseline for troubleshooting.

1minikube version
2minikube profile list
3minikube status
4kubectl version

If you use multiple profiles for different projects, list all active profile names and drivers.

2. Upgrade the Minikube binary

Use your existing installation channel where possible.

Homebrew:

brew update
brew upgrade minikube

Chocolatey:

choco upgrade minikube -y

Manual Linux install:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Verify binary version after install:

minikube version

3. Understand Minikube versus Kubernetes version upgrades

Updating Minikube does not automatically update Kubernetes version inside existing profiles. If you need newer Kubernetes, set it explicitly when starting or recreating profile.

minikube start -p dev --kubernetes-version=v1.31.0

This distinction is important when testing version-dependent APIs or admission behavior.

4. Restart and validate each active profile

Restart each profile you care about and confirm node and system pod health.

1minikube stop -p dev
2minikube start -p dev
3kubectl get nodes
4kubectl get pods -A

If startup fails, inspect logs immediately:

minikube logs -p dev

Driver mismatches and stale VM state are frequent causes after major upgrades.

5. Verify addons and ingress behavior

If your local workflow relies on addons such as ingress or metrics-server, validate them explicitly after upgrade.

minikube addons list
minikube addons enable ingress
kubectl get pods -n ingress-nginx

Do not assume addon status from previous run remains valid after runtime or Kubernetes version changes.

6. Handle profile recreation when state is broken

For disposable development clusters, deleting and recreating profile is often faster than deep repair.

minikube delete -p dev
minikube start -p dev --driver=docker --kubernetes-version=v1.31.0

For valuable local test data, export needed manifests before deleting:

kubectl get all -A -o yaml > local-cluster-snapshot.yaml

7. Team-level compatibility discipline

When teams share local setup docs, publish tested version combinations. A compact matrix avoids onboarding drift.

Recommended doc fields:

• tested Minikube version
• tested Kubernetes version
• required driver
• required addons

Keeping this matrix current prevents repeated environment debugging across developers.

8. Post-upgrade tooling checks

Minikube upgrades can surface incompatibilities in local ecosystem tools. Validate:

• kubectl client compatibility
• Helm chart install behavior
• local image build and load workflow

Example quick check:

kubectl get ns
helm version
minikube image ls | head

These checks catch subtle breakage before daily development resumes.

9. Keep startup configuration explicit

If your team depends on specific CPU, memory, or disk settings, store them in start commands or profile configuration instead of relying on defaults. Defaults can shift between Minikube versions and produce different behavior across machines. Explicit resource settings make performance and startup behavior more predictable after upgrades.

Common Pitfalls

• Assuming Kubernetes version changed automatically after Minikube binary upgrade.
• Validating only default profile while other profiles remain broken.
• Ignoring driver compatibility after host virtualization changes.
• Forgetting addon verification and discovering failures mid-development.
• Recreating profiles without exporting local manifests that matter.

Summary

• Upgrade Minikube binary first, then validate profile runtime behavior.
• Treat Kubernetes version changes as a separate explicit action.
• Recheck node readiness, addons, and driver compatibility after restart.
• Use profile recreation for broken disposable clusters.
• Maintain a team compatibility matrix to reduce setup drift.