# istioctl analyze: Validate Istio Config in CI

> istioctl analyze detects configuration problems in Istio resources before they cause outages. Reference for --recursive, --use-kube, --failure-threshold, and the analyzer error codes in CI.

Source: https://latchkey.dev/learn/command-reference/istioctl-analyze  
Updated: 2026-06-30

istioctl analyze runs Istio config analyzers over live cluster resources, local YAML files, or both, and reports problems with severity levels.

This is the single best PR gate for Istio: run analyze against your manifests and fail the build on any Error so broken routing never merges.

## What it does

istioctl analyze runs a suite of analyzers that catch misconfigured VirtualServices, missing Gateways, conflicting destination rules, unreferenced subsets, and namespaces missing sidecar injection. It can read live cluster state, local files, or a mix, and exits non-zero when it finds messages at or above the failure threshold.

## Common usage

```Terminal
# analyze live config in a namespace
istioctl analyze -n my-app
# analyze local manifests without a cluster (PR gate)
istioctl analyze --use-kube=false ./k8s/*.yaml
# analyze a whole directory recursively
istioctl analyze --recursive ./manifests/
```

## Options

| Flag | What it does |
| --- | --- |
| -n, --namespace <ns> | Namespace to analyze |
| -A, --all-namespaces | Analyze every namespace |
| --use-kube=false | Analyze only the given files, ignore the live cluster |
| --recursive, -R | Recurse into subdirectories of a path |
| --failure-threshold <level> | Exit non-zero at this severity (Info, Warning, Error) |
| -o json | Machine-readable output for CI parsing |

## In CI

Run istioctl analyze --use-kube=false on your manifests in the PR job so config errors are caught before apply, with no cluster required. Set --failure-threshold Error to fail only on real problems, or Warning for a stricter gate. Use -o json to annotate the diff.

## Common errors in CI

Analyzer messages carry codes like "IST0101: Referenced host not found" (a VirtualService points at a nonexistent host), "IST0102: The namespace is not enabled for Istio injection", and "IST0106: Schema validation error". These print with Error/Warning severity; a Warning threshold makes IST0102 fail the job. "no cluster available" when --use-kube is default means no KUBECONFIG; add --use-kube=false to analyze files only.

## 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.

```Terminal
# 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### istioctl analyze: Validate Istio Config in CI?

This is the single best PR gate for Istio: run analyze against your manifests and fail the build on any Error so broken routing never merges.

### What it does?

istioctl analyze runs a suite of analyzers that catch misconfigured VirtualServices, missing Gateways, conflicting destination rules, unreferenced subsets, and namespaces missing sidecar injection. It can read live cluster state, local files, or a mix, and exits non-zero when it finds messages at or above the failure threshold.

### In CI?

Run istioctl analyze --use-kube=false on your manifests in the PR job so config errors are caught before apply, with no cluster required. Set --failure-threshold Error to fail only on real problems, or Warning for a stricter gate. Use -o json to annotate the diff.

### Common errors in CI?

Analyzer messages carry codes like "IST0101: Referenced host not found" (a VirtualService points at a nonexistent host), "IST0102: The namespace is not enabled for Istio injection", and "IST0106: Schema validation error". These print with Error/Warning severity; a Warning threshold makes IST0102 fail the job.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt