mTLS & Authorization Policy

## What the resource actually configures `PeerAuthentication` is a `security.istio.io` CRD that answers one narrow question: **when a connection arrives at this workload's proxy, what transport-level authentication is required?** "Peer" means the calling workload, as opposed to the end user — end-user credentials are a different resource entirely. A minimal namespace-wide policy looks like this: ```yaml apiVersion: security.istio.io/v1 kind: PeerAuthentication metadata: name: default namespace: payments spec: mtls: mode: STRICT ``` Adding `spec.selector.matchLabels` narrows it to specific workloads; omitting the selector applies it to every workload in the namespace. ## The three modes **STRICT** — the proxy's inbound listener only completes a handshake with a peer that presents a valid mesh-issued client certificate. A plaintext TCP connection is closed; the caller typically sees a connection reset rather than an HTTP status, because the rejection happens below HTTP. **PERMISSIVE** — the proxy accepts both on the same port. It inspects the beginning of the connection and routes it either through the mTLS transport path or through a plaintext path. This exists precisely so that a mesh can be turned on incrementally: workloads already in the mesh start talking mTLS to each other, while callers that have not been onboarded keep working. It is the default posture for a fresh installation, and it is a **migration state, not a destination** — a service in PERMISSIVE mode is still reachable by anything that can route a packet to the pod. **DISABLE** — no peer authentication; the sidecar expects plaintext. Real uses are narrow: a port that speaks a protocol the proxy should not wrap, or an endpoint deliberately exposed to a non-mesh scraper. `UNSET` also exists and means "inherit from the next level up". There is also `spec.portLevelMtls`, which overrides the mode for individual ports of the selected workloads — the usual reason a single port needs to stay plaintext without downgrading the whole workload. ## Precedence Three scopes exist, and the most specific wins: 1. **Workload** — a policy with a `selector`, in the workload's own namespace. 2. **Namespace** — a policy with no selector, in that namespace. 3. **Mesh-wide** — a policy with no selector in the mesh's *root namespace* (`istio-system` in a default install). They do not merge or accumulate. A namespace policy replaces the mesh default for that namespace; a workload policy replaces the namespace policy for that workload. This is a frequent source of confusion: someone sets a mesh-wide STRICT policy and is surprised that one namespace still accepts plaintext, because a namespace-level policy is quietly shadowing it. ## Why the application never sees a certificate The proxy is in the network path for the pod, so the mesh TLS session begins and ends at the two proxies. The receiving proxy terminates it and hands the request to the application over the pod's loopback interface as an ordinary plaintext connection. The application keeps listening on a plain socket, its client libraries keep making plain calls, and nothing in the code base learns about keys, chains or handshakes. That is the entire selling point of transport security in the mesh: it is a property of the deployment, not of the code. The consequence people miss is the direction of control. **PeerAuthentication is inbound only.** It says nothing about how this workload calls others. Outbound is decided on the client side: since automatic mutual TLS was introduced, a sidecar originates mTLS by itself when it knows the destination workload has a proxy, and that behaviour is overridden through a `DestinationRule` traffic policy rather than through `PeerAuthentication`. So a policy applied "to service A" protects calls *into* A, not calls *out of* A. ## Where it stops Mutual TLS gives you an authenticated, encrypted channel and a verified peer identity. It does not decide who is *allowed* to call what — every authenticated workload in the mesh can still reach every other one until an authorization policy says otherwise. Turning on STRICT and calling the job done is the single most common misreading of what this resource buys you.