Istio Ambient CRDs — a visual map

apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: bookinfo
spec:
  mtls:
    mode: STRICT   # PERMISSIVE | DISABLE | UNSET

What each mode does

STRICT

Reject anything that isn't mTLS. The only mode that actually enforces zero-trust on inbound — use this as the destination state for every namespace.

PERMISSIVE

Accept both mTLS and plaintext. The migration default — lets off-mesh clients keep reaching the workload while you enrol them. In Ambient, meshed → meshed is always mTLS via HBONE regardless of this setting; PERMISSIVE only affects what unenrolled / off-mesh callers can do.

DISABLE

Plaintext only — mTLS handshakes are refused. Niche (e.g. fronting a non-mesh proxy that handles TLS itself); almost never what you want in production.

UNSET

Inherit from the next-broader scope. Resolution order: workload selector → namespace default → mesh-wide istio-system/default. With nothing set anywhere, the effective default is PERMISSIVE.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: reviews-allow-productpage
  namespace: bookinfo
spec:
  selector:
    matchLabels:
      app: reviews
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - cluster.local/ns/bookinfo/sa/bookinfo-productpage

How to read this policy

selector

The workload being protected — every pod labelled app: reviews in the bookinfo namespace. The policy is enforced by ztunnel on the destination side of the connection.

action: ALLOW

Whitelist semantics. Once any ALLOW policy targets a workload, every connection that doesn't match an ALLOW rule is denied — there's an implicit "deny everything else".

from.source.principals

The allowed callers, by SPIFFE workload identity. cluster.local/ns/bookinfo/sa/bookinfo-productpage = the bookinfo-productpage ServiceAccount in the bookinfo namespace. Anything else reaching reviews is dropped at ztunnel before the connection is forwarded to the pod.

"L4" means ztunnel matches on workload identity, namespace and port — not on HTTP method, path or headers. To filter on those, target a waypoint and add a to.operation rule (see the L7 example below).

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: reviews-read-only
  namespace: bookinfo
spec:
  # Bind to the waypoint, not directly to the workload.
  targetRefs:
    - kind: Gateway
      group: gateway.networking.k8s.io
      name: reviews-waypoint
  action: ALLOW
  rules:
    - to:
        - operation:
            methods: ["GET"]
            paths:   ["/reviews/*"]

Where this is enforced — and why both fields matter

targetRefs

This is what makes the policy L7. It attaches the policy to the reviews-waypoint Gateway — the waypoint is the only thing in Ambient that parses HTTP, so it's the only enforcement point that can match on methods, paths or headers. Swap targetRefs for a selector (as in the L4 example above) and the policy lands on ztunnel instead.

to.operation

The HTTP L7 conditions themselves — methods, paths, headers, hosts. They only take effect when the enforcement point can read HTTP. Put a to.operation block on a selector-attached policy and ztunnel silently ignores those fields; the L4 parts (principals, namespaces, ports) still apply, the L7 parts don't.

Short answer: both are needed. targetRefs picks the enforcement point (waypoint = L7-capable). to.operation uses that L7 capability. Either one without the other either degrades to L4 silently, or attaches nothing meaningful. Also note: traffic must actually be routed through the waypoint (via a Gateway + HTTPRoute, or the istio.io/use-waypoint label) — a policy on a waypoint that nothing traverses is a no-op.

HTTP only. AuthorizationPolicy's to.operation is the upstream Istio schema — it understands HTTP attributes and nothing else. Same on every waypoint flavour: OSS istio-waypoint, Solo's istiod-gloo waypoint, and the enterprise-agentgateway-waypoint. For MCP tool-level or A2A skill-level enforcement, you need a separate Solo Enterprise CRD — EnterpriseAgentgatewayPolicy (enterpriseagentgateway.solo.io/v1alpha1) — which targets the agentgateway and matches on attributes like mcp.tool.name, mcp.tool.target and A2A skill names. agentgateway is the only proxy here that parses MCP/A2A frames; kgateway and native Istio waypoints speak HTTP/gRPC and use AuthorizationPolicy as shown above. See the Agentic / MCP lab for the full example.

apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: jwt-on-reviews
  namespace: bookinfo
spec:
  targetRefs:
    - kind: Gateway
      group: gateway.networking.k8s.io
      name: reviews-waypoint
  jwtRules:
    - issuer: "https://issuer.example.com"
      jwksUri: "https://issuer.example.com/.well-known/jwks.json"
      audiences: ["reviews-api"]

What this does — and what it doesn't

targetRefs

Attaches the policy to the waypoint Gateway. Same logic as the L7 AuthorizationPolicy above — JWTs live in the Authorization HTTP header, and the waypoint is the only thing in Ambient that parses HTTP. Use selector instead and ztunnel silently does nothing with it.

jwtRules.issuer

The required iss claim. A token whose iss doesn't match is rejected with a 401 from the waypoint.

jwtRules.jwksUri

Where istiod fetches the issuer's signing keys (JWKS) to verify the JWT signature. istiod caches and periodically refreshes them, so the istiod-to-issuer network path must be open — not the workload-to-issuer path.

jwtRules.audiences

Allowed aud claim values. A token whose aud isn't in this list gets a 401 even if the signature is valid — guards against replay of tokens minted for a different service that shares an issuer.

RequestAuthentication doesn't deny on its own. If a request has a token and it's invalid (bad signature, wrong issuer, wrong audience), the waypoint returns 401. But if the request has no token at all, this policy lets it through — it only validates tokens that are present. To actually require authentication, pair it with an AuthorizationPolicy that requires request.auth.principal != "" or specific claims. Valid claims surface to AuthorizationPolicy as request.auth.*. See the JWT / OIDC / on-behalf-of page for the full pairing pattern.