istioctl validate: Lint Istio YAML Offline
istioctl validate checks one or more Istio configuration files against the resource schemas, offline, and exits non-zero on invalid YAML.
Where analyze reasons about relationships between resources, validate is a pure schema lint of individual files. It is the lightest possible PR check because it never contacts the cluster.
What it does
istioctl validate parses the Istio custom resources in the given files (VirtualService, Gateway, DestinationRule, etc.) and checks each against its schema, reporting fields that are unknown, mistyped, or missing. It does not need a kube context and does not evaluate cross-resource references.
Common usage
istioctl validate -f virtual-service.yaml
# validate every manifest in a directory
istioctl validate -f ./manifests/
# validate multiple files
istioctl validate -f gw.yaml -f vs.yaml -f dr.yamlOptions
| Flag | What it does |
|---|---|
| -f, --filename <path> | File or directory of Istio resources to validate (repeatable) |
| --referential | Enable referential validation checks |
In CI
Run istioctl validate -f on every changed mesh manifest in the lint stage. It is faster and needs no cluster, so it belongs early in the pipeline; save istioctl analyze for the deeper cross-resource gate.
Common errors in CI
"error: resource ... is invalid" with a message like "unknown field \"spec.http[0].rutes\"" points at a typo in a field name. "no such file or directory" means -f pointed at a missing path. If the file mixes non-Istio kinds, validate reports "resource type ... not recognized"; split the mesh CRs into their own files.
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