Sidecar mode (the default, covered in Fundamentals):
  Every pod gets its own Envoy sidecar container injected alongside it.
  Pro: full L7 feature set, isolated per-pod.
  Con: real resource overhead per pod (one more container, one more
  memory/CPU footprint, multiplied across every pod in the mesh).

Ambient mode (newer, opt-in alternative — no sidecars at all):
  ztunnel: one small per-node proxy handling L4 (mTLS, basic routing)
    for every pod on that node — shared, not per-pod.
  waypoint proxy: a separate, optional per-namespace/per-service-account
    Envoy proxy that only gets deployed where L7 features (retries,
    fault injection, fine-grained routing) are actually needed.

Why this split exists: most services in a mesh only ever need mTLS and
basic routing (L4) — ambient mode gives them that for free via ztunnel,
with zero per-pod overhead, and only pays the full sidecar-equivalent
cost (a waypoint) for the specific services that actually use L7
features. This is a genuine architecture trade-off, not a strict
upgrade — sidecar mode is still the right default for meshes that use
L7 traffic management (canary splits, fault injection) broadly across
most services, since ambient's savings come specifically from services
that DON'T need L7.

# Enable ambient mode for a namespace (no pod restarts, no sidecar injection)
istioctl install --set profile=ambient -y
kubectl label namespace production istio.io/dataplane-mode=ambient

# Deploy a waypoint only for a service that needs L7 features
istioctl waypoint apply --service-account payment-api -n production

Why: a single mesh spanning multiple Kubernetes clusters — common for
multi-region failover, or splitting a mesh across separate teams'
clusters while still allowing cross-cluster service calls with the
same mTLS/traffic-management guarantees as within one cluster.

Primary-remote topology (most common pattern):
  One cluster runs the full istiod control plane ("primary").
  Other clusters ("remote") run only Envoy sidecars/ztunnel, with their
  configuration pushed from the primary cluster's istiod over the
  network — no separate control plane per cluster to manage.

Cross-cluster service discovery requires:
  1. A shared root CA (both clusters' workload certs must chain to the
     same root, or cross-cluster mTLS fails identity verification).
  2. East-west gateway — a dedicated Istio ingress gateway configured
     specifically for cluster-to-cluster traffic (distinct from the
     regular north-south ingress gateway handling external traffic).
  3. Remote secret — a kubeconfig for the remote cluster, applied to
     the primary so istiod can watch the remote cluster's services.

# EnvoyFilter — add a custom Lua script to modify request headers,
# for a case VirtualService's built-in fields don't cover
apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata: { name: add-request-id, namespace: production }
spec:
  workloadSelector:
    labels: { app: payment-api }
  configPatches:
    - applyTo: HTTP_FILTER
      match:
        context: SIDECAR_INBOUND
        listener:
          filterChain:
            filter: { name: envoy.filters.network.http_connection_manager }
      patch:
        operation: INSERT_BEFORE
        value:
          name: envoy.filters.http.lua
          typed_config:
            "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
            inlineCode: |
              function envoy_on_request(request_handle)
                request_handle:headers():add("x-request-id", "generated-here")
              end

# Without this, every Envoy sidecar in the mesh holds config for EVERY
# service in the mesh, even ones it never talks to -- fine for small
# meshes, a real memory/CPU cost at hundreds of services.
apiVersion: networking.istio.io/v1beta1
kind: Sidecar
metadata: { name: payment-api-sidecar, namespace: production }
spec:
  workloadSelector:
    labels: { app: payment-api }
  egress:
    - hosts:
        - "production/inventory-api.production.svc.cluster.local"
        - "production/user-api.production.svc.cluster.local"
        - "istio-system/*"   # always needed: talks to istiod