Authorization Policy

Linkerd’s authorization policy allows you to control which types of traffic are allowed to meshed pods. See the Authorization Policy feature description for more information on what this means.

Linkerd’s policy is configured using two mechanisms:

  1. A set of default policies, which can be set at the cluster, namespace, and workload level through Kubernetes annotations.
  2. A set of CRDs that specify fine-grained policy for specific ports, routes, workloads, etc.

Default policies

During a Linkerd install, the proxy.defaultInboundPolicy field is used to specify the cluster-wide default policy. This field can be one of the following:

  • all-unauthenticated: allow all traffic. This is the default.
  • all-authenticated: allow traffic from meshed clients in the same or from a different cluster (with multi-cluster).
  • cluster-authenticated: allow traffic from meshed clients in the same cluster.
  • cluster-unauthenticated: allow traffic from both meshed and non-meshed clients in the same cluster.
  • deny: all traffic are denied.
  • audit: Same as all-unauthenticated but requests get flagged in logs and metrics.

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

Dynamic policy resources

For dynamic control of policy, and for finer-grained policy than what the default polices allow, Linkerd provides a set of CRDs which control traffic policy in the cluster: Server, HTTPRoute, ServerAuthorization, AuthorizationPolicy, MeshTLSAuthentication, and NetworkAuthentication.

The general pattern for authorization is:

  • A Server describes a set of pods, and a single port on those pods.
  • Optionally, an HTTPRoute references that Server and describes a subset of HTTP traffic to it.
  • A MeshTLSAuthentication or NetworkAuthentication decribes who is allowed access.
  • An AuthorizationPolicy references the HTTPRoute or Server (the thing to be authorized) and the MeshTLSAuthentication or NetworkAuthentication (the clients that have authorization).

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 prevents overlapping Servers from being created.

Authorization Policy - 图1

Note

When a Server resource is present, all traffic to the port on its pods will be denied unless explicitly authorized or audit mode is enabled (with accessPolicy:audit). Thus, Servers are typically paired with e.g. an AuthorizationPolicy that references the Server, or that reference an HTTPRoute that in turn references the Server.

Server Spec

A Server spec may contain the following top level fields:

fieldvalue
accessPolicyaccessPolicy declares the policy applied to traffic not matching any associated authorization policies (defaults to deny).
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.

accessPolicy

Traffic that doesn’t conform to the authorization policies associated to the Server are denied by default. You can alter that behavior by overriding the accessPolicy field, which accepts the same values as the default policies. Of particular interest is the audit value, which enables audit mode, that you can use to test policies before enforcing them.

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"

HTTPRoute

When attached to a Server, an HTTPRoute resource represents a subset of the traffic handled by the ports on pods referred in that Server, by declaring a set of rules which determine which requests match. Matches can be based on path, headers, query params, and/or verb. AuthorizationPolicies may target HTTPRoute resources, thereby authorizing traffic to that HTTPRoute only rather than to the entire Server. HTTPRoutes may also define filters which add processing steps that must be completed during the request or response lifecycle.

Authorization Policy - 图2

Note

A given HTTP request can only match one HTTPRoute. If multiple HTTPRoutes are present that match a request, one will be picked according to the Gateway API rules of precendence.

Please refer to HTTPRoute’s full spec.

Authorization Policy - 图3

Note

Two versions of the HTTPRoute resource may be used with Linkerd:

  • The upstream version provided by the Gateway API, with the gateway.networking.k8s.io API group
  • A Linkerd-specific CRD provided by Linkerd, with the policy.linkerd.io API group

The two HTTPRoute resource definitions are similar, but the Linkerd version implements experimental features not yet available with the upstream Gateway API resource definition. See the HTTPRoute reference documentation for details.

AuthorizationPolicy

An AuthorizationPolicy provides a way to authorize traffic to a Server or an HTTPRoute. AuthorizationPolicies are a replacement for ServerAuthorizations which are more flexible because they can target HTTPRoutes instead of only being able to target Servers.

AuthorizationPolicy Spec

An AuthorizationPolicy spec may contain the following top level fields:

fieldvalue
targetRefA TargetRef which references a resource to which the authorization policy applies.
requiredAuthenticationRefsA list of TargetRefs representing the required authentications. In the case of multiple entries, all authentications must match.

targetRef

A TargetRef identifies an API object to which this AuthorizationPolicy applies. The API objects supported are:

  • A Server, indicating that the AuthorizationPolicy applies to all traffic to the Server.
  • An HTTPRoute, indicating that the AuthorizationPolicy applies to all traffic matching the HTTPRoute.
  • A namespace (kind: Namespace), indicating that the AuthorizationPolicy applies to all traffic to all Servers and HTTPRoutes defined in the namespace.
fieldvalue
groupGroup is the group of the target resource. For namespace kinds, this should be omitted.
kindKind is kind of the target resource.
namespaceThe namespace of the target resource. When unspecified (or empty string), this refers to the local namespace of the policy.
nameName is the name of the target resource.

AuthorizationPolicy Examples

An AuthorizationPolicy which authorizes clients that satisfy the authors-get-authn authentication to send to the authors-get-route HTTPRoute.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: AuthorizationPolicy
  3. metadata:
  4. name: authors-get-policy
  5. namespace: booksapp
  6. spec:
  7. targetRef:
  8. group: policy.linkerd.io
  9. kind: HTTPRoute
  10. name: authors-get-route
  11. requiredAuthenticationRefs:
  12. - name: authors-get-authn
  13. kind: MeshTLSAuthentication
  14. group: policy.linkerd.io

An AuthorizationPolicy which authorizes the webapp ServiceAccount to send to the authors Server.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: AuthorizationPolicy
  3. metadata:
  4. name: authors-policy
  5. namespace: booksapp
  6. spec:
  7. targetRef:
  8. group: policy.linkerd.io
  9. kind: Server
  10. name: authors
  11. requiredAuthenticationRefs:
  12. - name: webapp
  13. kind: ServiceAccount

An AuthorizationPolicy which authorizes the webapp ServiceAccount to send to all policy “targets” within the booksapp namespace.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: AuthorizationPolicy
  3. metadata:
  4. name: authors-policy
  5. namespace: booksapp
  6. spec:
  7. targetRef:
  8. kind: Namespace
  9. name: booksapp
  10. requiredAuthenticationRefs:
  11. - name: webapp
  12. kind: ServiceAccount

MeshTLSAuthentication

A MeshTLSAuthentication represents a set of mesh identities. When an AuthorizationPolicy has a MeshTLSAuthentication as one of its requiredAuthenticationRefs, this means that clients must be in the mesh and must have one of the specified identities in order to be authorized to send to the target.

MeshTLSAuthentication Spec

A MeshTLSAuthentication spec may contain the following top level fields:

fieldvalue
identitiesA list of mTLS identities to authenticate. The prefix can be used to match all identities in a domain. An identity string of indicates that all meshed clients are authorized.
identityRefsA list of targetRefs to ServiceAccounts to authenticate.

MeshTLSAuthentication Examples

A MeshTLSAuthentication which authenticates the books and webapp mesh identities.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: MeshTLSAuthentication
  3. metadata:
  4. name: authors-get-authn
  5. namespace: booksapp
  6. spec:
  7. identities:
  8. - "books.booksapp.serviceaccount.identity.linkerd.cluster.local"
  9. - "webapp.booksapp.serviceaccount.identity.linkerd.cluster.local"

A MeshTLSAuthentication which authenticate thes books and webapp mesh identities. This is an alternative way to specify the same thing as the above example.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: MeshTLSAuthentication
  3. metadata:
  4. name: authors-get-authn
  5. namespace: booksapp
  6. spec:
  7. identityRefs:
  8. - kind: ServiceAccount
  9. name: books
  10. - kind: ServiceAccount
  11. name: webapp

A MeshTLSAuthentication which authenticates all meshed identities.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: MeshTLSAuthentication
  3. metadata:
  4. name: authors-get-authn
  5. namespace: booksapp
  6. spec:
  7. identities: ["*"]

NetworkAuthentication

A NetworkAuthentication represents a set of IP subnets. When an AuthorizationPolicy has a NetworkAuthentication as one of its requiredAuthenticationRefs, this means that clients must be in one of the specified networks in order to be authorized to send to the target.

NetworkAuthentication Spec

A NetworkAuthentication spec may contain the following top level fields:

fieldvalue
networksA list of networks to authenticate.

network

A network defines an authenticated IP subnet.

fieldvalue
cidrA subnet in CIDR notation to authenticate.
exceptA list of subnets in CIDR notation to exclude from the authentication.

NetworkAuthentication Examples

A NetworkAuthentication that authenticates clients which belong to any of the specified CIDRs.

  1. apiVersion: policy.linkerd.io/v1alpha1
  2. kind: NetworkAuthentication
  3. metadata:
  4. name: cluster-network
  5. namespace: booksapp
  6. spec:
  7. networks:
  8. - cidr: 10.0.0.0/8
  9. - cidr: 100.64.0.0/10
  10. - cidr: 172.16.0.0/12
  11. - cidr: 192.168.0.0/16

ServerAuthorization

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

Authorization Policy - 图4

Note

AuthorizationPolicy is a more flexible alternative to ServerAuthorization that can target HTTPRoutes as well as Servers. Use of AuthorizationPolicy is preferred, and ServerAuthorization will be deprecated in future releases.

ServerAuthorization Spec

A ServerAuthorization spec must contain the following top level fields:

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

serverRef

A serverRef 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
matchExpressionsA list of label selector requirements. The requirements are ANDed.
matchLabelsA 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