Istio traffic management

As of Istio 1.31 · Edition 2026.11 · Release data checked on 30 October 2026

Gateway

Binds ports/hosts/TLS at the edge proxy. servers[].port + tls.mode: SIMPLE, MUTUAL, PASSTHROUGH, ISTIO_MUTUAL. credentialName points to a Secret in the same namespace as the gateway pod.

apiVersion: networking.istio.io/v1
kind: Gateway
metadata: {name: web-gw, namespace: istio-system}
spec:
  selector: {istio: ingressgateway}
  servers:
  - port: {number: 443, name: https, protocol: HTTPS}
    hosts: ["www.istio-quickref.de"]
    tls:
      mode: SIMPLE
      credentialName: web-cert

VirtualService

Routing rules. Binds hosts to gateways (or mesh for east-west). Match order is significant, the first matching rule wins. Header names must be lowercase; exact/prefix matches on header values and URI are case-sensitive (URI: ignoreUriCase: true, regex: (?i)). Without a retries block: 2 retries on connect-failure, refused-stream, unavailable, cancelled (no longer on a plain 503 since 1.24); attempts: 0 disables them.

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata: {name: reviews}
spec:
  hosts: [reviews]
  http:
  - match:
    - headers: {end-user: {exact: jason}}
    route:
    - destination: {host: reviews, subset: v2}
  - route:
    - destination: {host: reviews, subset: v1}
      weight: 90
    - destination: {host: reviews, subset: v3}
      weight: 10
    retries:
      attempts: 3
      perTryTimeout: 2s
      retryOn: gateway-error,connect-failure,refused-stream
    timeout: 10s

DestinationRule

Subsets (versions) + traffic policy (LB, connection pool, outlier detection, TLS). Takes effect only after VirtualService routing. host: FQDN or short name in the DR’s namespace. 1.31+: meshConfig.defaultTrafficPolicy sets a mesh-wide connectionPool/outlierDetection baseline; a DR block overrides it per block.

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata: {name: reviews}
spec:
  host: reviews
  trafficPolicy:
    connectionPool:
      tcp: {maxConnections: 100}
      http:
        http1MaxPendingRequests: 64
        http2MaxRequests: 1000
        maxRequestsPerConnection: 10
    outlierDetection:
      consecutive5xxErrors: 5
      interval: 30s
      baseEjectionTime: 60s
    loadBalancer:
      consistentHash:
        httpHeaderName: x-user-id
  subsets:
  - name: v1
    labels: {version: v1}
  - name: v2
    labels: {version: v2}

ServiceEntry

Pull external hosts into the mesh registry (DB, SaaS, REST APIs). MESH_EXTERNAL + DNS resolution is the clean default combo. With outboundTrafficPolicy: REGISTRY_ONLY, egress without a ServiceEntry lands in BlackHoleCluster. 1.31: mode ALLOW_ANY_DYNAMIC_DNS (MeshConfig only, not settable per Sidecar resource; sidecar proxies only) resolves unknown plaintext-HTTP hosts via Envoy DFP; TLS/TCP stays PassthroughCluster.

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata: {name: stripe-api}
spec:
  hosts: ["api.stripe.com"]
  ports:
  - {number: 443, name: https, protocol: HTTPS}
  resolution: DNS
  location: MESH_EXTERNAL

Sidecar

Limits what a workload sees of the mesh registry, critical for memory footprint and push latency in large clusters. Default: every sidecar gets config for all services. 1.31+: ~ns/* subtracts from the import set (*/* + ~legacy/*).

apiVersion: networking.istio.io/v1
kind: Sidecar
metadata: {name: default, namespace: prod}
spec:
  egress:
  - hosts:
    - "./*"             # own namespace only
    - "istio-system/*"
    - "shared/*"