istioctl x precheck: Pre-Install Readiness
istioctl x precheck inspects the target cluster and reports whether it meets the prerequisites for installing or upgrading Istio.
Run precheck before install in a pipeline so an unready cluster fails fast with a clear reason instead of a half-applied control plane.
What it does
istioctl x precheck runs a set of environment analyzers against the cluster: Kubernetes version compatibility, required permissions (can the installer create the needed cluster-scoped resources), conflicting or leftover Istio installs, and webhook readiness. It prints blocking issues that would fail an install.
Common usage
istioctl x precheck
# check readiness for a specific revision upgrade
istioctl x precheck --revision 1-22-0Options
| Flag | What it does |
|---|---|
| --revision <name> | Check readiness for a specific control-plane revision |
| -o json | Machine-readable output for CI |
In CI
Chain istioctl x precheck && istioctl install so the install only runs on a green precheck. It catches a too-old Kubernetes version or missing RBAC before you have a partially installed mesh to clean up.
Common errors in CI
"Kubernetes version ... is not supported" means the API server is older than the Istio minimum; upgrade the cluster or pin an older Istio. "Missing Kubernetes permissions" lists the RBAC the service account lacks, common when a CI token is scoped too tightly. A warning about an existing install means a prior control plane is still present and must be removed or reconciled.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes