Understanding Linkerd Service Mesh Authorization: Server and ServerAuthorization Policies

Introduction

Linkerd defines two policy resources— Server and ServerAuthorization —to control inbound access to mesh applications.

Default Inbound Policy

During installation, the policyController.defaultAllowPolicy field sets the default behavior when no Server selects a pod. Options include: all-unauthenticated: allow all requests (default). all-authenticated: allow requests from any mesh client, including multi‑cluster. cluster-authenticated: allow requests from mesh clients in the same cluster. cluster-unauthenticated: allow requests from both mesh and non‑mesh clients in the same cluster. deny: reject all requests; a Policy must then be created to permit specific communication.

The default can be overridden by adding the annotation config.linkerd.io/default-inbound-policy to a pod spec or its namespace.

Server Resource

A Server selects a set of pods in the same namespace and a port (usually a single pod port, but multiple ports can be selected by name, e.g., admin-http). It behaves like a Kubernetes Service but enforces that Server instances do not overlap on the same pod/port. Linkerd includes an admission controller to prevent overlapping servers.

When a server selects a port, traffic is denied by default; a corresponding ServerAuthorization must be created to allow traffic.

Spec Fields

podSelector

: selects pods in the same namespace (uses Kubernetes label selector semantics). Must contain either matchExpressions (AND‑combined list) or matchLabels (key‑value map). port: name or number of a port defined in the pod spec. proxyProtocol: protocol for inbound connections; one of unknown, HTTP/1, HTTP/2, gRPC, opaque, TLS. Defaults to unknown if omitted.

Server Example

apiVersion: policy.linkerd.io/v1beta1
kind: Server
metadata:
  namespace: emojivoto
  name: emoji-grpc
spec:
  podSelector:
    matchLabels:
      app: emoji-svc
  port: grpc
  proxyProtocol: gRPC

Another example using matchExpressions and HTTP/2 on port 8080:

apiVersion: policy.linkerd.io/v1beta1
kind: Server
metadata:
  namespace: emojivoto
  name: backend-services
spec:
  podSelector:
    matchExpressions:
    - {key: app, operator: In, values: [voting-svc, emoji-svc]}
    - {key: environment, operator: NotIn, values: [dev]}
  port: 8080
  proxyProtocol: "HTTP/2"

ServerAuthorization Resource

ServerAuthorization

authorizes traffic to one or more Server instances.

Spec Fields

client

: describes authorized clients. Sub‑fields include meshTLS (authorized mesh client identities) and unauthenticated (boolean to allow unauthenticated clients). server: identifies the target servers, either by name (reference a specific Server) or selector (label selector matching multiple Servers).

Client Selector

meshTLS

: can contain identities (list of authorized MTLS identity strings, supporting * wildcard) or serviceAccounts (list of serviceAccount objects with name and optional namespace). networks: optional list of IP CIDR ranges limiting which client IPs may connect.

Server Selector

matchExpressions

and matchLabels follow the same label‑selector rules as Kubernetes.

ServerAuthorization Examples

Allow all authenticated mesh clients to access the emoji-svc server using any service‑account identity in the emojivoto namespace:

apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  namespace: emojivoto
  name: emoji-grpc
spec:
  server:
    selector:
      matchLabels:
        app: emoji-svc
  client:
    meshTLS:
      identities:
      - "*.emojivoto.serviceaccount.identity.linkerd.cluster.local"

Allow any unauthenticated client to access the web-http server:

apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  namespace: emojivoto
  name: web-public
spec:
  server:
    name: web-http
  client:
    unauthenticated: true
    networks:
    - cidr: 0.0.0.0/0
    - cidr: ::/0

Allow only a specific service‑account ( prometheus in linkerd-viz namespace) to access the prom server:

apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  namespace: emojivoto
  name: prom-prometheus
spec:
  server:
    name: prom
  client:
    meshTLS:
      serviceAccounts:
      - namespace: linkerd-viz
        name: prometheus