Authorization Policy

You are viewing docs for an older version of Linkerd. View the latest docs.

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:

A set of default policies, which can be set at the cluster, namespace, and workload level through Kubernetes annotations.
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.

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.

Note

When a Server resource is present, all traffic to the port on its pods will be denied (regardless of the default policy) unless explicitly authorized. 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:

field	value
`podSelector`	A podSelector selects pods in the same namespace.
`port`	A port name or number. Only ports in a pod spec’s `ports` are considered.
`proxyProtocol`	Configures 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:

field	value
`matchExpressions`	matchExpressions is a list of label selector requirements. The requirements are ANDed.
`matchLabels`	matchLabels 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.

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

A Server that selects over pods with matchExpressions, with HTTP/2 as the proxyProtocol, 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"

HTTPRoute

An HTTPRoute represents a subset of traffic handled by a Server. HTTPRoutes are “attached” to Servers and have match 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.

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.

HTTPRoute Spec

An HTTPRoute spec may contain the following top level fields:

field	value
`parentRefs`	A set of ParentReferences which indicate which Servers this `HTTPRoute` attach to.
`hostnames`	A set of hostnames that should match against the HTTP Host header.
`rules`	An array of HTTPRouteRules.

parentReference

A reference to the Servers this HTTPRoute is a part of.

field	value
`group`	The group of the referent. This must be set to “group.linkerd.io”.
`kind`	The kind of the referent. This must be set to “Server”.
`namespace`	The namespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route.
`name`	The name of the referent.

httpRouteRule

HTTPRouteRule defines semantics for matching an HTTP request based on conditions (matches) and processing it (filters).

field	value
`matches`	A list of httpRouteMatches. Each match is independent, i.e. this rule will be matched if any one of the matches is satisfied.
`filters`	A list of httpRouteFilters which will be applied to each request which matches this rule.

httpRouteMatch

HTTPRouteMatch defines the predicate used to match requests to a given action. Multiple match types are ANDed together, i.e. the match will evaluate to true only if all conditions are satisfied.

field	value
`path`	An httpPathMatch. If this field is not specified, a default prefix match on the “/” path is provided.
`headers`	A list of httpHeaderMatches. Multiple match values are ANDed together.
`queryParams`	A list of httpQueryParamMatches. Multiple match values are ANDed together.
`method`	When specified, this route will be matched only if the request has the specified method.

httpPathMatch

HTTPPathMatch describes how to select a HTTP route by matching the HTTP request path.

field	value
`type`	How to match against the path Value. One of: Exact, PathPrefix, RegularExpression. If this field is not specified, a default of “PathPrefix” is provided.
`value`	The HTTP path to match against.

httpHeaderMatch

HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request headers.

field	value
`type`	How to match against the value of the header. One of: Exact, RegularExpression. If this field is not specified, a default of “Exact” is provided.
`name`	The HTTP Header to be matched against. Name matching MUST be case insensitive.
`value`	Value of HTTP Header to be matched.

httpQueryParamMatch

HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP query parameters.

field	value
`type`	How to match against the value of the query parameter. One of: Exact, RegularExpression. If this field is not specified, a default of “Exact” is provided.
`name`	The HTTP query param to be matched. This must be an exact string match.
`value`	Value of HTTP query param to be matched.

httpRouteFilter

HTTPRouteFilter defines processing steps that must be completed during the request or response lifecycle.

field	value
`type`	One of: RequestHeaderModifier, RequestRedirect.
`requestHeaderModifier`	An httpRequestHeaderFilter.
`requestRedirect`	An httpRequestRedirectFilter.

httpRequestHeaderFilter

A filter which modifies request headers.

field	value
`set`	A list of httpHeaders to overwrites on the request.
`add`	A list of httpHeaders to add on the request, appending to any existing value.
`remove`	A list of header names to remove from the request.

httpHeader

HTTPHeader represents an HTTP Header name and value as defined by RFC 7230.

field	value
`name`	Name of the HTTP Header to be matched. Name matching MUST be case insensitive.
`value`	Value of HTTP Header to be matched.

httpRequestRedirectFilter

HTTPRequestRedirect defines a filter that redirects a request.

field	value
`scheme`	The scheme to be used in the value of the `Location` header in the response. When empty, the scheme of the request is used.
`hostname`	The hostname to be used in the value of the `Location` header in the response. When empty, the hostname of the request is used.
`path`	An httpPathModfier which modifies the path of the incoming request and uses the modified path in the `Location` header.
`port`	The port to be used in the value of the `Location` header in the response. When empty, port (if specified) of the request is used.
`statusCode`	The HTTP status code to be used in response.

httpPathModfier

HTTPPathModifier defines configuration for path modifiers.

field	value
`type`	One of: ReplaceFullPath, ReplacePrefixMatch.
`replaceFullPath`	The value with which to replace the full path of a request during a rewrite or redirect.
`replacePrefixMatch`	The value with which to replace the prefix match of a request during a rewrite or redirect.

HTTPRoute Examples

An HTTPRoute which matches GETs to /authors.json or /authors/*.

apiVersion: policy.linkerd.io/v1beta1
kind: HTTPRoute
metadata:
  name: authors-get-route
  namespace: booksapp
spec:
  parentRefs:
    - name: authors-server
      kind: Server
      group: policy.linkerd.io
  rules:
    - matches:
      - path:
          value: "/authors.json"
        method: GET
      - path:
          value: "/authors/"
          type: "PathPrefix"
        method: GET

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:

field	value
`targetRef`	A TargetRef which references a resource to which the authorization policy applies.
`requiredAuthenticationRefs`	A 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.

field	value
`group`	Group is the group of the target resource. For namespace kinds, this should be omitted.
`kind`	Kind is kind of the target resource.
`namespace`	The namespace of the target resource. When unspecified (or empty string), this refers to the local namespace of the policy.
`name`	Name 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.

apiVersion: policy.linkerd.io/v1alpha1
kind: AuthorizationPolicy
metadata:
  name: authors-get-policy
  namespace: booksapp
spec:
  targetRef:
    group: policy.linkerd.io
    kind: HTTPRoute
    name: authors-get-route
  requiredAuthenticationRefs:
    - name: authors-get-authn
      kind: MeshTLSAuthentication
      group: policy.linkerd.io

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

apiVersion: policy.linkerd.io/v1alpha1
kind: AuthorizationPolicy
metadata:
  name: authors-policy
  namespace: booksapp
spec:
  targetRef:
    group: policy.linkerd.io
    kind: Server
    name: authors
  requiredAuthenticationRefs:
    - name: webapp
      kind: ServiceAccount

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

apiVersion: policy.linkerd.io/v1alpha1
kind: AuthorizationPolicy
metadata:
  name: authors-policy
  namespace: booksapp
spec:
  targetRef:
    kind: Namespace
    name: booksapp
  requiredAuthenticationRefs:
    - name: webapp
      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:

field	value
`identities`	A 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.
`identityRefs`	A list of targetRefs to `ServiceAccounts` to authenticate.

MeshTLSAuthentication Examples

A MeshTLSAuthentication which authenticates the books and webapp mesh identities.

apiVersion: policy.linkerd.io/v1alpha1
kind: MeshTLSAuthentication
metadata:
  name: authors-get-authn
  namespace: booksapp
spec:
  identities:
    - "books.booksapp.serviceaccount.identity.linkerd.cluster.local"
    - "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.

apiVersion: policy.linkerd.io/v1alpha1
kind: MeshTLSAuthentication
metadata:
  name: authors-get-authn
  namespace: booksapp
spec:
  identityRefs:
    - kind: ServiceAccount
      name: books
    - kind: ServiceAccount
      name: webapp

A MeshTLSAuthentication which authenticates all meshed identities.

apiVersion: policy.linkerd.io/v1alpha1
kind: MeshTLSAuthentication
metadata:
  name: authors-get-authn
  namespace: booksapp
spec:
  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:

field	value
`networks`	A list of networks to authenticate.

network

A network defines an authenticated IP subnet.

field	value
`cidr`	A subnet in CIDR notation to authenticate.
`except`	A 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.

apiVersion: policy.linkerd.io/v1alpha1
kind: NetworkAuthentication
metadata:
  name: cluster-network
  namespace: booksapp
spec:
  networks:
  - cidr: 10.0.0.0/8
  - cidr: 100.64.0.0/10
  - cidr: 172.16.0.0/12
  - cidr: 192.168.0.0/16

ServerAuthorization

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

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:

field	value
`client`	A client describes clients authorized to access a server.
`server`	A serverRef identifies `Servers` in the same namespace for which this authorization applies.

serverRef

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

field	value
`name`	References a `Server` instance by name.
`selector`	A 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:

field	value
`matchExpressions`	A list of label selector requirements. The requirements are ANDed.
`matchLabels`	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:

field	value
`meshTLS`	A meshTLS is used to authorize meshed clients to access a server.
`unauthenticated`	A boolean value that authorizes unauthenticated clients to access a server.

Optionally, it can also contain the networks field:

field	value
`networks`	Limits 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:

field	value
`unauthenticatedTLS`	A 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.
`identities`	A 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.
`serviceAccounts`	A list of authorized client serviceAccounts (as provided via mTLS).

serviceAccount

A serviceAccount field contains the following top level fields:

field	value
`name`	The ServiceAccount’s name.
`namespace`	The 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.

apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  namespace: emojivoto
  name: emoji-grpc
spec:
  # Allow all authenticated clients to access the (read-only) emoji service.
  server:
    selector:
      matchLabels:
        app: emoji-svc
  client:
    meshTLS:
      identities:
        - "*.emojivoto.serviceaccount.identity.linkerd.cluster.local"

A ServerAuthorization that allows any unauthenticated clients.

apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  namespace: emojivoto
  name: web-public
spec:
  server:
    name: web-http
  # Allow all clients to access the web HTTP port without regard for
  # authentication. If unauthenticated connections are permitted, there is no
  # need to describe authenticated clients.
  client:
    unauthenticated: true
    networks:
      - cidr: 0.0.0.0/0
      - cidr: ::/0

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

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