istio/istio

istioctl

Active contributors: keithmattix, ramaraochavali, hzxuzhonghu, stevenctl

Purpose

istioctl is the user-facing CLI for installing, configuring, and debugging an Istio mesh. It is the only supported install path (the in-cluster operator was deprecated and removed) and the canonical tool for inspecting Envoy and ztunnel state, validating configuration, and triaging mesh problems.

The binary is built from istioctl/cmd/istioctl/. The bulk of the logic lives in istioctl/pkg/<subcommand>/.

Directory layout

istioctl/
├── cmd/
│   ├── istioctl/main.go       # entry: calls cmd.GetRootCmd
│   └── root.go                # root cobra tree (~280 lines, registers all subcommands)
├── pkg/
│   ├── analyze/               # `istioctl analyze` (config static analysis)
│   ├── authz/                 # `istioctl experimental authz`
│   ├── checkinject/           # `istioctl experimental check-inject`
│   ├── cli/                   # Shared CLI context, flags, k8s client
│   ├── completion/            # Shell completion
│   ├── config/                # `istioctl experimental config`
│   ├── dashboard/             # `istioctl dashboard <component>` (port-forward + UI)
│   ├── describe/              # `istioctl experimental describe`
│   ├── injector/              # `istioctl experimental injector`
│   ├── install/               # Helpers that link into operator/cmd/mesh
│   ├── kubeinject/            # `istioctl kube-inject`
│   ├── multicluster/          # `istioctl create-remote-secret`, `clusters`
│   ├── precheck/              # `istioctl experimental precheck`
│   ├── proxyconfig/           # `istioctl proxy-config <subres> <pod>`
│   ├── proxystatus/           # `istioctl proxy-status`
│   ├── tag/                   # `istioctl tag <set|list|generate|remove>`
│   ├── validate/              # `istioctl validate -f`
│   ├── waypoint/              # `istioctl waypoint <subcmd>` (Ambient L7 management)
│   ├── workload/              # `istioctl experimental workload` (VM onboarding)
│   ├── writer/                # Output formatters (envoy/configdump, ztunnel/configdump)
│   ├── xds/                   # Internal xDS client utility commands
│   └── ztunnelconfig/         # `istioctl ztunnel-config <subcmd>`
└── docker/

Command map

Command	What it does
`install`, `uninstall`, `upgrade`	Apply / remove / upgrade Istio. Backed by the operator renderer (`operator/cmd/mesh/`).
`manifest`	Render manifests without applying. `manifest generate`, `manifest diff`.
`tag set/list/remove/generate`	Manage revision tags for canary upgrades. `pkg/revisions/`.
`analyze`	Static analysis of a config bundle. Detects ~50 misconfiguration classes via analyzers in `pkg/config/analysis/`.
`validate`	Schema validation of YAML files (offline).
`kube-inject`	Manually inject sidecar (used for non-Kubernetes deployments).
`proxy-status` (`ps`)	Per-proxy ADS sync state across the mesh.
`proxy-config <subres> <pod>`	Dump Envoy clusters / listeners / routes / endpoints / secrets / bootstrap / log levels.
`ztunnel-config <subres>`	Same idea for ztunnel pods. Subcommands: `workload`, `service`, `policy`, `certificate`, `connections`, `log`.
`waypoint generate/apply/list/status/delete`	Manage Ambient waypoints.
`dashboard <component>`	Port-forward and open Grafana / Kiali / Jaeger / Prometheus / Envoy admin / Zipkin.
`experimental describe pod`	High-level explanation of why a pod is configured the way it is.
`experimental authz check`, `authz convert`	Inspect AuthZ rules attached to a pod.
`experimental precheck`	Pre-upgrade checks.
`experimental check-inject`	Why was/wasn't this pod injected?
`experimental workload entry/group configure`	Generate VM onboarding artifacts.
`bug-report`	Collect a tarball of cluster diagnostics (`tools/bug-report/`).
`version`	Client + control-plane version.
`admin`	Internal admin-only commands.
`create-remote-secret`	Build the kubeconfig secret used for multi-cluster service discovery.
`internal-debug`	Internal debug interface to istiod (`/debug/...`).

The full registration list is in istioctl/cmd/root.go. New commands are added there.

How it works

istioctl is a thin orchestration layer over a few capabilities:

graph TD
    user[User CLI] -->|cobra| root[root.go]
    root --> ctx[CLIContext<br/>istioctl/pkg/cli]
    ctx -->|kube client| k[Kubernetes API]
    ctx -->|MultiXDS| xds[Per-pod xDS<br/>via Istiod debug]
    root --> render[Operator renderer<br/>operator/cmd/mesh]
    root --> writer[Writers<br/>istioctl/pkg/writer]
    render -->|YAML| user
    xds -->|configdump| writer
    writer -->|json/yaml/table| user

The most distinctive piece is the xDS writer — istioctl/pkg/writer/envoy/configdump/ and .../ztunnel/configdump/. These take an Envoy or ztunnel config_dump (fetched either from the proxy admin port or via istioctl experimental internal-debug / MultiXDS) and render it as human-readable tables. This is the substance of proxy-config <subres>.

MultiXDS (istioctl/pkg/multixds/) is the abstraction that lets istioctl query Envoy state through Istiod's debug endpoints when the pod is not directly reachable. This is critical for production debugging where developer workstations rarely have direct access to data-plane pods.

Install path

istioctl install flow (in operator/cmd/mesh/install.go, called from istioctl/cmd/root.go):

Read user's overlay (-f operator.yaml, --set foo=bar, profile defaults).
Render Helm charts for each enabled component (operator/pkg/render/).
Diff against currently installed manifests (operator/pkg/manifest/).
Apply via the cluster's k8s client (with --dry-run skipping apply).
Wait for readiness.

The manifest generate command is the same pipeline minus the apply. upgrade adds revision-based canary behaviour using tag plumbing.

Analyzers

istioctl analyze runs every analyzer registered in pkg/config/analysis/analyzers/. Each analyzer is a small Go function that looks at one or more resource types and emits structured Messages with severities (Error, Warning, Info). The set is large — ~80 analyzers as of writing. Each maps to a documented config-analysis message.

You can run analysis offline (-f files.yaml) or against a live cluster (-A for all namespaces).

Integration points

Reads from: Kubernetes API (per the user's kubeconfig and --context selection) and Istiod (via debug endpoints, multixds, or direct port-forward).
Writes to: Kubernetes API (apply, delete during install); never to istiod.
Configuration: ~/.istioctl/config.yaml (path overridable via ISTIOCTL_CONFIG), $ISTIOCTL_* env vars (auto-bound through Viper). viper.SetEnvPrefix("ISTIOCTL").
External binaries: dashboard shells out to a browser opener; bug-report may invoke kubectl exec and tarball helpers.

Entry points for modification

New top-level command: add a package under istioctl/pkg/<name>/, register in istioctl/cmd/root.go. Use cli.NewCLIContext() for the kube client.
New experimental command: same as above, but register on experimentalCmd instead of rootCmd. Once stable, "graduate" it by promoting (see PR #26408 for the pattern).
New proxy-config subcommand: istioctl/pkg/proxyconfig/ — extend the cobra tree there and add a writer if the output is novel.
New analyzer: implement the analysis.Analyzer interface in pkg/config/analysis/analyzers/<name>/, add to analyzers.All, regenerate goldens.

Key source files

File	Purpose
`istioctl/cmd/istioctl/main.go`	Entry point
`istioctl/cmd/root.go`	Command registration
`istioctl/pkg/cli/context.go`	Shared CLIContext / kube client
`istioctl/pkg/proxyconfig/proxyconfig.go`	`proxy-config`
`istioctl/pkg/proxystatus/proxystatus.go`	`proxy-status`
`istioctl/pkg/ztunnelconfig/ztunnelconfig.go`	`ztunnel-config`
`istioctl/pkg/waypoint/waypoint.go`	`waypoint`
`istioctl/pkg/analyze/analyze.go`	`analyze`
`istioctl/pkg/multixds/gather.go`	The MultiXDS abstraction
`istioctl/pkg/writer/envoy/configdump/`	Envoy config-dump writers
`istioctl/pkg/writer/ztunnel/configdump/`	Ztunnel config-dump writers
`operator/cmd/mesh/install.go`	The install flow
`tools/bug-report/pkg/bugreport/bugreport.go`	The bug-report collector