Traffic Distribution

The networking.istio.io/traffic-distribution annotation controls how ztunnel distributes traffic across available endpoints. This is useful for keeping traffic local to reduce latency and cross-zone costs.

Supported values

Applying the annotation

The annotation can be applied to:

• Service: Affects traffic to that specific service
• Namespace: Sets the default for all services in the namespace
• ServiceEntry: Affects traffic to external services

Precedence

When multiple levels are configured, the most specific wins:

1. spec.trafficDistribution field (Service only)
2. Annotation on Service/ServiceEntry
3. Annotation on Namespace
4. Default behavior (no locality preference)

Examples

Per-service configuration

Apply to a single service:

apiVersion: v1
kind: Service
metadata:
  name: my-service
  annotations:
    networking.istio.io/traffic-distribution: PreferSameZone
spec:
  selector:
    app: my-app
  ports:
  - port: 80

Namespace-wide configuration

Apply to all services in a namespace:

apiVersion: v1
kind: Namespace
metadata:
  name: my-namespace
  annotations:
    networking.istio.io/traffic-distribution: PreferSameZone

Services in the namespace inherit this setting unless they have their own annotation.

Override namespace default

A service can override the namespace setting with its own annotation:

apiVersion: v1
kind: Namespace
metadata:
  name: my-namespace
  annotations:
    networking.istio.io/traffic-distribution: PreferSameZone
---
apiVersion: v1
kind: Service
metadata:
  name: different-service
  namespace: my-namespace
  annotations:
    networking.istio.io/traffic-distribution: PreferSameNode
spec:
  selector:
    app: different-app
  ports:
  - port: 80

Services without an annotation inherit the namespace setting.

Behavior

PreferSameZone

With PreferSameZone, ztunnel categorizes endpoints by locality and routes to the closest healthy ones:

1. Same network, region, zone, and subzone
2. Same network, region, and zone
3. Same network and region
4. Same network
5. Any available endpoint

If all endpoints in a closer locality become unhealthy, traffic automatically fails over to the next level.

For example, a service with endpoints in zones us-west, us-west, and us-east:

• Client in us-west sends all traffic to the two us-west endpoints
• If one us-west endpoint fails, traffic goes to the remaining us-west endpoint
• If both us-west endpoints fail, traffic fails over to us-east

PreferSameNode

With PreferSameNode, ztunnel prefers endpoints running on the same Kubernetes node as the client. This minimizes network hops and latency for node-local communication.

Relationship to Kubernetes trafficDistribution

Kubernetes 1.31 introduced the spec.trafficDistribution field on Services. This Istio annotation provides the same functionality with additional benefits:

When both the spec field and annotation are set on a Service, the spec field takes precedence.

Waypoints automatically configure this annotation.

See also

• Locality Load Balancing for sidecar-based locality routing
• Annotation reference