Guide to installing istioctl, preparing Minikube with ingress addon, troubleshooting macOS driver issues, downloading Istio release, adding istioctl to PATH and running prechecks
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:
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:
Copy
istiotraining@local ~ $ minikube start😄 minikube v1.16.0 on Darwin 10.15.7✨ Automatically selected the docker driver. Other choices: hyperkit, virtualbox👍 Starting control plane node minikube in cluster minikube🛟 Creating docker container (CPUs=2, Memory=1987MB) ...🐳 Preparing Kubernetes v1.20.0 on Docker 20.10.0 ... ▪ Generating certificates and keys ... ▪ Booting up control plane ... ▪ Configuring RBAC rules ... Verifying Kubernetes components... Enabled addons: storage-provisioner, default-storageclass🎉 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by defaultistiotraining@local ~ $ minikube addons enable ingress✖ Exiting due to MK_USAGE: Due to networking limitations of driver docker on darwin, ingress addon is not supported.Alternatively to use this addon you can use a vm-based driver: 'minikube start --vm=true'To track the update on this work in progress feature please check:https://github.com/kubernetes/minikube/issues/7332
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:
Copy
istiotraining@local ~ $ minikube delete🔥 Deleting "minikube" in docker ...🔥 Deleting container "minikube" ...🔥 Removing /Users/istiotraining/.minikube/machines/minikube ...💀 Removed all traces of the "minikube" cluster.istiotraining@local ~ $ minikube start --vm=true😄 minikube v1.16.0 on Darwin 10.15.7✨ Automatically selected the hyperkit driver🔥 Starting control plane node minikube in cluster minikube⚙️ Creating hyperkit VM (CPUs=2, Memory=4000MB, Disk=20000MB) ...🚜 Preparing Kubernetes v1.20.0 on Docker 20.10.0 ... ▪ Generating certificates and keys ... ▪ Booting up control plane ... ▪ Configuring RBAC rules ...● Verifying Kubernetes components...✨ Enabled addons: storage-provisioner, default-storageclass🎉 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by defaultistiotraining@local ~ $ minikube addons enable ingress● Verifying ingress addon...✨ The 'ingress' addon is enabled
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.
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:
Copy
# Download the latest Istio release (this creates a directory like istio-1.10.3)curl -L https://istio.io/downloadIstio | sh -
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:
Copy
Istio 1.10.3 Download Complete!Istio has been successfully downloaded into the istio-1.10.3 folder on your system.Next Steps:See https://istio.io/latest/docs/setup/install/ to add Istio to your Kubernetes cluster.To configure the istioctl client tool for your workstation,add the /Users/istiotraining/istio-1.10.3/bin directory to your environment path variable with: export PATH="$PATH:/Users/istiotraining/istio-1.10.3/bin"Begin the Istio pre-installation check by running: istioctl x precheckNeed more information? Visit https://istio.io/latest/docs/setup/install/istiotraining@local ~ $ cd istio-1.10.3/istiotraining@local istio-1.10.3 $ lsLICENSE README.md bin manifest.yaml manifests samples toolsistiotraining@local istio-1.10.3 $ ls bin/istioctlistiotraining@local istio-1.10.3 $ ls samples/README.md custom-bootstrap helloworld multicluster sleepaddons extauthz httpbin operator tcp-echobookinfo external jwt-server ratelimit websocketscerts health-check kubernetes-blog securityistiotraining@local istio-1.10.3 $ ls tools/_istioctl certs istioctl.bash
istiotraining@local istio-1.10.3 $ istioctl verify-install0 Istio control planes detected, checking --revision "default" onlyerror while fetching revision : the server could not find the requested resource0 Istio injectors detectedError: could not load IstioOperator from cluster: the server could not find the requested resource. Use --filename
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).
