Skip to main content
This guide walks you through installing the Istio client (istioctl) and preparing a local Minikube cluster that supports the ingress addon. It preserves key troubleshooting output and step-by-step commands so you can reproduce the process and verify your environment. Prerequisites:
  • Minikube installed locally. See Minikube docs: https://minikube.sigs.k8s.io/docs/.
  • kubectl configured to use your Minikube cluster.
  • Docker is optional — you may use a VM-based driver instead.

​
1) Start Minikube (driver selection)

When you run minikube start without specifying a driver, Minikube automatically selects a default driver. If Docker is running it may choose the Docker driver and run the cluster inside a Docker container. On macOS, the Docker driver has a networking limitation: the Minikube ingress addon is not supported for the Docker driver on Darwin (macOS). An example session that demonstrates this limitation:
On macOS, if you need the ingress addon, use a VM-based driver (for example, hyperkit) rather than the Docker driver.
If you encounter this limitation, delete the Docker-based Minikube cluster and start Minikube using a VM-based driver (for example, hyperkit). Example: delete the Docker-based cluster and restart with a VM-based driver:
Switching drivers will recreate the Minikube VM. Delete the existing cluster if you want to change drivers (minikube delete). Back up any local resources you need before deleting.

​
2) Download the Istio release (installs istioctl)

A convenient way to get the latest Istio release (and the istioctl binary) is to use the official Istio download script. This script downloads a release archive into a directory named istio-<version> in your current folder:
Be aware: this downloads the Istio release into your current directory, so run it from a location where you want the release folder to be created. Sample download output and inspection of the folder:

​
3) Add istioctl to your PATH

Add the release bin directory to your PATH (example for Linux/macOS):
Confirm the istioctl client is available and check its version:
The client reports its version (here 1.10.3) and notes whether it sees any running Istio pods in the cluster.

​
4) Verify the cluster is ready for Istio

Run verification and preflight checks:
Explanation:
  • istioctl verify-install attempts to detect an installed control plane and will fail if no control plane manifests have been applied.
  • After download, you should run istioctl x precheck to confirm cluster prerequisites and then install a control plane (for example, using istioctl install or the Istio Operator).

​
Quick reference table

  1. Run istioctl x precheck to ensure your cluster meets prerequisites.
  2. Install an Istio control plane:
    • Use istioctl install for a quick, configurable install, or
    • Use the Istio Operator for lifecycle management.
  3. Follow the official Istio installation guide: https://istio.io/latest/docs/setup/install/
  4. If you ran into a Minikube ingress limitation on macOS, follow the related issue for updates: https://github.com/kubernetes/minikube/issues/7332
Related resources:

Watch Video