# istioctl validate: Lint Istio YAML Offline

> istioctl validate checks Istio custom resources against their schema without a cluster. Reference for -f, referenced-resource behavior, and the schema errors seen in CI.

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

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

```Terminal
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.yaml
```

## Options

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

```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 validate: Lint Istio YAML Offline?

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.

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

---

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