Authorization Policy

Server and ServerAuthorization are the two types of policy resources in Linkerd, used to control inbound access to your meshed applications.

During the linkerd install, the policyController.defaultAllowPolicy field is used to specify the default policy when no Server selects a pod. This field can be one of the following:

  • all-unauthenticated: allow all requests. This is the default.
  • all-authenticated: allow requests from meshed clients in the same or from a different cluster (with multi-cluster).
  • cluster-authenticated: allow requests from meshed clients in the same cluster.
  • cluster-unauthenticated: allow requests from both meshed and non-meshed clients in the same cluster.
  • deny: all requests are denied. (Policy resources should then be created to allow specific communications between services).

This default can be overridden by setting the annotation config.linkerd.io/default- inbound-policy on either a pod spec or its namespace.

Once a Server is configured for a pod & port, its default behavior is to deny traffic and ServerAuthorization resources must be created to allow traffic on a Server.

Server

A Server selects a port on a set of pods in the same namespace as the server. It typically selects a single port on a pod, though it may select multiple ports when referring to the port by name (e.g. admin-http). While the Server resource is similar to a Kubernetes Service, it has the added restriction that multiple Server instances must not overlap: they must not select the same pod/port pairs. Linkerd ships with an admission controller that tries to prevent overlapping servers from being created.

When a Server selects a port, traffic is denied by default and ServerAuthorizations must be used to authorize traffic on ports selected by the Server.

Spec

A Server spec may contain the following top level fields:

fieldvalue
podSelectorA podSelector selects pods in the same namespace.
portA port name or number. Only ports in a pod spec’s ports are considered.
proxyProtocolConfigures protocol discovery for inbound connections. Supersedes the config.linkerd.io/opaque-ports annotation. Must be one of unknown,HTTP/1,HTTP/2,gRPC,opaque,TLS. Defaults to unknown if not set.

podSelector

This is the same labelSelector field in Kubernetes. All the pods that are part of this selector will be part of the Server group. A podSelector object must contain exactly one of the following fields:

fieldvalue
matchExpressionsmatchExpressions is a list of label selector requirements. The requirements are ANDed.
matchLabelsmatchLabels is a map of {key,value} pairs.

See the Kubernetes LabelSelector reference for more details.

Server Examples

A Server that selects over pods with a specific label, with gRPC as the proxyProtocol.

  1. apiVersion: policy.linkerd.io/v1beta1
  2. kind: Server
  3. metadata:
  4.   namespace: emojivoto
  5.   name: emoji-grpc
  6. spec:
  7.   podSelector:
  8.     matchLabels:
  9.       app: emoji-svc
  10.   port: grpc
  11.   proxyProtocol: gRPC

A Server that selects over pods with matchExpressions, with HTTP/2 as the proxyProtocol, on port 8080.

  1. apiVersion: policy.linkerd.io/v1beta1
  2. kind: Server
  3. metadata:
  4.   namespace: emojivoto
  5.   name: backend-services
  6. spec:
  7.   podSelector:
  8.     matchExpressions:
  9.     - {key: app, operator: In, values: [voting-svc, emoji-svc]}
  10.     - {key: environment, operator: NotIn, values: [dev]}
  11.   port: 8080
  12.   proxyProtocol: "HTTP/2"

ServerAuthorization

A ServerAuthorization provides a way to authorize traffic to one or more Servers.

Spec

A ServerAuthorization spec must contain the following top level fields:

fieldvalue
clientA client describes clients authorized to access a server.
serverA server identifies Servers in the same namespace for which this authorization applies.

Server

A Server object must contain exactly one of the following fields:

fieldvalue
nameReferences a Server instance by name.
selectorA selector selects servers on which this authorization applies in the same namespace.

selector

This is the same labelSelector field in Kubernetes. All the servers that are part of this selector will have this authorization applied. A selector object must contain exactly one of the following fields:

fieldvalue
matchExpressionsmatchExpressions is a list of label selector requirements. The requirements are ANDed.
matchLabelsmatchLabels is a map of {key,value} pairs.

See the Kubernetes LabelSelector reference for more details.

client

A client object must contain exactly one of the following fields:

fieldvalue
meshTLSA meshTLS is used to authorize meshed clients to access a server.
unauthenticatedA boolean value that authorizes unauthenticated clients to access a server.

Optionally, it can also contain the networks field:

fieldvalue
networksLimits the client IP addresses to which this authorization applies. If unset, the server chooses a default (typically, all IPs or the cluster’s pod network).

meshTLS

A meshTLS object must contain exactly one of the following fields:

fieldvalue
unauthenticatedTLSA boolean to indicate that no client identity is required for communication.This is mostly important for the identity controller, which must terminate TLS connections from clients that do not yet have a certificate.
identitiesA list of proxy identity strings (as provided via MTLS) that are authorized. The prefix can be used to match all identities in a domain. An identity string of indicates that all authentication clients are authorized.
serviceAccountsA list of authorized client serviceAccounts (as provided via MTLS).

serviceAccount

A serviceAccount field contains the following top level fields:

fieldvalue
nameThe ServiceAccount’s name.
namespaceThe ServiceAccount’s namespace. If unset, the authorization’s namespace is used.

ServerAuthorization Examples

A ServerAuthorization that allows meshed clients with *.emojivoto.serviceaccount.identity.linkerd.cluster.local proxy identity i.e. all service accounts in the emojivoto namespace.

  1. apiVersion: policy.linkerd.io/v1beta1
  2. kind: ServerAuthorization
  3. metadata:
  4.   namespace: emojivoto
  5.   name: emoji-grpc
  6. spec:
  7.   # Allow all authenticated clients to access the (read-only) emoji service.
  8.   server:
  9.     selector:
  10.       matchLabels:
  11.         app: emoji-svc
  12.   client:
  13.     meshTLS:
  14.       identities:
  15.         - "*.emojivoto.serviceaccount.identity.linkerd.cluster.local"

A ServerAuthorization that allows any unauthenticated clients.

  1. apiVersion: policy.linkerd.io/v1beta1
  2. kind: ServerAuthorization
  3. metadata:
  4.   namespace: emojivoto
  5.   name: web-public
  6. spec:
  7.   server:
  8.     name: web-http
  9.   # Allow all clients to access the web HTTP port without regard for
  10.   # authentication. If unauthenticated connections are permitted, there is no
  11.   # need to describe authenticated clients.
  12.   client:
  13.     unauthenticated: true
  14.     networks:
  15.       - cidr: 0.0.0.0/0
  16.       - cidr: ::/0

A ServerAuthorization that allows meshed clients with a specific service account.

  1. apiVersion: policy.linkerd.io/v1beta1
  2. kind: ServerAuthorization
  3. metadata:
  4.   namespace: emojivoto
  5.   name: prom-prometheus
  6. spec:
  7.   server:
  8.     name: prom
  9.   client:
  10.     meshTLS:
  11.       serviceAccounts:
  12.         - namespace: linkerd-viz
  13.           name: prometheus