Istio — API Surface#

API types#

Istio exposes five distinct API surfaces:

1. gRPC — the dominant internal API; xDS ADS is the core control-plane/data-plane protocol
2. HTTP — internal debug/monitoring endpoints and Kubernetes admission webhooks
3. Kubernetes CRD — the primary user-facing configuration API
4. CLI (istioctl) — operator tooling built on Cobra
5. Extension / Plugin — pluggable xDS generators and EnvoyFilter patching

gRPC API#

Proto files (in-repo)#

The project defines several internal proto schemas in-repo (not in istio.io/api):

Istio’s primary API proto (VirtualService, DestinationRule, etc.) lives in the external istio.io/api module (v1.29.0-alpha.0), not in this repo.

gRPC services registered#

Istiod (pilot-discovery) — port 15010 (plaintext) and 15012 (mTLS)

Sample external extension service (in samples/)

gRPC interceptors (Istiod)#

Both gRPC servers (plaintext port 15010, mTLS port 15012) use a unary interceptor chain:

• grpcprom.UnaryServerInterceptor — Prometheus metrics (request count, latency)
• Chain assembled via grpc.ChainUnaryInterceptor in pilot/pkg/bootstrap/server.go:766–822

The mTLS server (15012) enforces mutual TLS at the transport layer via credentials configured in initSecureDiscoveryService().

HTTP API#

Istiod runs three distinct HTTP/HTTPS listeners:

Port 8080 / 15014 — Admin/monitoring (plaintext)#

Handled by pilot/pkg/bootstrap/monitoring.go and extended by DiscoveryServer.AddDebugHandlers():

Auth model for debug endpoints: allowAuthenticatedOrLocalhost — requests from 127.0.0.1 pass unconditionally; remote requests must present a valid JWT verified by the configured Authenticator chain (Kubernetes JWT, OIDC, client cert, or XFCC header).

Port 15017 — HTTPS webhook server#

Serves Kubernetes admission webhook callbacks. Registered via httpsMux:

Port 15020 — Pilot-agent status server#

Each sidecar agent runs its own HTTP server at port 15020 (istio-agent), handling:

Kubernetes CRD API (user-facing configuration)#

This is the primary user-facing API for mesh configuration. All CRDs are defined in istio.io/api and reconciled via typed informers in pilot/pkg/config/kube/crdclient/.

Istio networking CRDs (networking.istio.io)#

Istio security CRDs (security.istio.io)#

Telemetry CRD (telemetry.istio.io)#

Kubernetes Gateway API (standard, gateway.networking.k8s.io)#

Istio implements the upstream Kubernetes Gateway API alongside its own CRDs:

CLI (istioctl)#

• Framework: Cobra + Viper (config from ~/.istioctl/config.yaml and ISTIOCTL_* env vars)
• Context propagation: cli.CLIContext wraps kubeconfig, namespace, and istio-namespace; passed through all commands
• Global persistent flags: --istioNamespace (default istio-system), --namespace, --kubeconfig, --context, logging flags

Top-level commands#

Experimental subcommands (istioctl experimental / istioctl x)#

Flag patterns: Cobra persistent flags at root level for namespace/kubeconfig; individual commands bind additional flags locally. Viper provides env-var overriding via ISTIOCTL_ prefix. Shell completion is registered for namespace flags.

Extension / Plugin system#

XdsResourceGenerator interface#

The core extension point for Istiod’s xDS generation pipeline:

// pilot/pkg/model/context.go:290
type XdsResourceGenerator interface {
    Generate(proxy *Proxy, w *WatchedResource, req *PushRequest) (model.Resources, model.XdsLogDetails, error)
}
type XdsDeltaResourceGenerator interface {
    XdsResourceGenerator
    GenerateDeltas(proxy *Proxy, req *PushRequest, w *WatchedResource) (model.Resources, model.DeletedResources, model.XdsLogDetails, bool, error)
}

Registered in DiscoveryServer.Generators as a map[string]model.XdsResourceGenerator keyed by xDS type URL. Adding a new xDS type (e.g., a custom extension) requires only registering a new generator — no changes to the push loop. This is how Ambient mode’s Workload, PCDS, and workload address generators were added alongside the classic LDS/CDS/RDS/EDS generators.

EnvoyFilter CRD — user-level extension#

EnvoyFilter is the primary user-facing extension mechanism. It allows operators to patch Envoy proxy configuration at predefined extension points using patch operations (MERGE, ADD, INSERT_BEFORE, INSERT_AFTER, REMOVE, REPLACE) on:

• HTTP_FILTER — add/remove/reorder HTTP filter chain entries (e.g., add Lua, Wasm, ext_authz)
• NETWORK_FILTER — patch TCP filter chains
• CLUSTER — modify cluster properties (circuit breakers, endpoints)
• LISTENER — modify listener properties
• ROUTE_CONFIGURATION / VIRTUAL_HOST / HTTP_ROUTE — modify routing tables

Implemented in pilot/pkg/networking/core/envoyfilter/.

ECDS (Extension Config Discovery Service)#

Istiod serves ECDS resources for dynamic Wasm extension delivery. The ECDS generator allows Wasm plugins to be loaded/unloaded without an Envoy restart. The WasmPlugin resource (in istio.io/api/extensions/v1alpha1) declares Wasm plugin URLs and their configuration; Istiod translates these to ECDS TypedExtensionConfig resources pushed to Envoy.

authn/authz networking plugins#

Internal plugin interfaces in pilot/pkg/networking/plugin/ allow the Istiod config generator to compose authentication and authorization configuration into listener filter chains:

• authn plugin (pilot/pkg/networking/plugin/authn/) — generates mTLS/JWT filter chains from PeerAuthentication and RequestAuthentication
• authz plugin (pilot/pkg/networking/plugin/authz/) — generates RBAC filter config from AuthorizationPolicy

These are internal plugins, not a public extension point. Third parties cannot add new networking plugins without modifying Istiod source.

Authenticator interface (control-plane auth extensibility)#

// pkg/security/security.go:389
type Authenticator interface {
    Authenticate(ctx AuthContext) (*Caller, error)
    AuthenticatorType() string
}

Implementations: KubeJWTAuthenticator (Kubernetes JWT), JwtAuthenticator (OIDC), ClientCertAuthenticator (client cert), XfccAuthenticator (XFCC header for gateway-to-istiod). The chain is used to authenticate both xDS clients (proxies connecting to ADS) and requests to debug HTTP endpoints.

ZDS protocol — CNI/ztunnel extension interface#

The zds.proto protocol (pkg/zdsapi/) defines the binary API between the Istio CNI node agent and ztunnel (Rust). This is an internal, versioned protocol that enables CNI to pass workload netns file descriptors to ztunnel, allowing transparent traffic redirection in ambient mode without sidecars.

Library API#

Istio does not publish a stable Go library API for external consumption. The module (istio.io/istio) is a monorepo of binaries and internal packages; go get of internal packages is not supported or versioned for external use. The intended library API surface lives in the separate istio.io/api and istio.io/client-go modules, which expose:

• Proto-generated Go types for all Istio CRDs
• Typed Kubernetes clients for Istio resources

The pkg/kube/krt package (Collection[T], Singleton[T]) is the one sub-library that shows signs of potential external adoption, but it carries no stability promise.

Notable API design observations#

1. xDS as the universal internal bus: Every communication channel between Istiod and data-plane components (Envoy, ztunnel, istio-agent) uses either the xDS ADS protocol or a specialized variant (SDS, NDS, PCDS, Workload API). This means Istiod’s gRPC API is effectively the entire internal control API; HTTP is only for humans (debug/webhooks).

2. Dual CRD strategy: Istio supports both its own CRDs (networking.istio.io, security.istio.io) and the upstream Kubernetes Gateway API simultaneously. The same reconciliation path handles both, with Gateway API resources translated to Istio’s internal model. This is explicitly a migration strategy — Gateway API is the future, Istio CRDs are maintained for backward compatibility.

3. EnvoyFilter as an escape hatch: The EnvoyFilter CRD is both the most powerful and most dangerous part of the API. It operates at the Envoy config level, below Istio’s abstraction layer. Istio provides no stability guarantees for the generated Envoy config it patches, making EnvoyFilter upgrade-sensitive.

4. istioctl as the operator’s window into the mesh: Unlike most control planes, Istiod has no management REST API. All operator interactions happen through istioctl, which talks to Kubernetes (for CRDs), to the Istiod debug endpoints (for state inspection), and directly to Envoy admin APIs (for per-pod proxy introspection). The debug endpoints on port 15014 serve the same role that a management API would in other systems.

5. No external plugin loading: Despite having an internal generator plugin map, Istiod has no mechanism for loading external plugins at runtime (no go-plugin, no WASM for control-plane code). Extension happens through the Kubernetes CRD API (EnvoyFilter, WasmPlugin) or by forking and recompiling Istiod.