How Kuma chooses the right policy to apply

This only applies to source/destination policies. If you are unfamiliar with these, checkout introduction to policies.

At any single moment, there might be multiple policies (of the same type) that match a connection between sources and destinations Dataplanes.

E.g., there might be a catch-all policy that sets the baseline for your organization

type: TrafficLog
mesh: default
name: catch-all-policy
sources:
  - match:
      kuma.io/service: '*'
destinations:
  - match:
      kuma.io/service: '*'
conf:
  backend: logstash

Additionally, there might be a more focused use case-specific policy, e.g.

type: TrafficLog
mesh: default
name: web-to-backend-policy
sources:
  - match:
      kuma.io/service: web
      cloud: aws
      region: us
destinations:
  - match:
      kuma.io/service: backend
conf:
  backend: splunk

What does Kuma do when it encounters multiple matching policies?

General rules

Kuma always picks the single most specific policy.

A policy that matches by a greater number of tags

- match:
    kuma.io/service: '*'
    cloud:   aws
    region:  us

is “more specific” than the one with the less number of tags

- match:
    kuma.io/service: '*'

A policy that matches by the exact tag value
```
- match:
    kuma.io/service: web
```
is “more specific” than the one that matches by a '*' (wildcard)
```
- match:
    kuma.io/service: '*'
```
If 2 policies match by the same number of tags, then the one with a greater total number of matches by the exact tag value
```
- match:
    kuma.io/service: web
    version: v1
```
is “more specific” than the other
```
- match:
    kuma.io/service: web
    version: '*'
```
If 2 policies are equal (match by the same number of tags, and the total number of matches by the exact tag value is the same for both policies, and the total number of matches by a '*' tag value is the same for both policies) then the latest one
```
modificationTime: "2020-01-01T20:00:00.0000Z"
...
- match:
    kuma.io/service: web
    version: v1
```
is “more specific” policy than the older one
```
modificationTime: "2019-01-01T20:00:00.0000Z"
...
- match:
    kuma.io/service: web
    cloud: aws
```

Only one policy of a given type is matched to a particular inbound. If multiple matches are desired, they must be combined into a single policy.

To see which policies were matched for the specific data plane proxy you can use Inspect API.

Combine Policies to Avoid Overriding

If the following two policies are applied, the most recent one will override the other:

apiVersion: kuma.io/v1alpha1
kind: TrafficPermission
mesh: default
metadata:
  name: allow-b-to-a
spec:
  sources:
    - match:
        kuma.io/service: b
  destinations:
    - match:
        kuma.io/service: a

apiVersion: kuma.io/v1alpha1
kind: TrafficPermission
mesh: default
metadata:
  name: allow-c-to-a
spec:
  sources:
    - match:
        kuma.io/service: c
  destinations:
    - match:
        kuma.io/service: a

This is because both destinations match the same inbound with the same specificity, and Kuma selects exactly one policy of a given type.

If it is desired that both policies be applied, they must be combined:

apiVersion: kuma.io/v1alpha1
kind: TrafficPermission
mesh: default
metadata:
  name: allow-b-c-to-a
spec:
  sources:
    - match:
        kuma.io/service: b
    - match:
        kuma.io/service: c
  destinations:
    - match:
        kuma.io/service: a

Dataplane Policy

Dataplane policy is a policy that matches group of data plane proxies, not a connection between multiple proxies.

Assuming we have the following data plane proxy

type: Dataplane
mesh: default
name: web-1
networking:
  address: 192.168.0.1
  inbound:
     - port: 9000
       servicePort: 6379
       tags:
         kuma.io/service: web

and a ProxyTemplate which is an example of a Dataplane Policy

type: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      kuma.io/service: web
conf:
  imports:
    - default-proxy

then the policy is appplied on the web-1 data plane proxy.

Connection policies

The policy can be applied either on inbound connections that a data plane proxy receives or outbound connections that data plane proxy creates, therefore there are two types of connection policies. It is indicated at the beginning of each policy doc whether they are inbound or outbounds.

Outbound Connection Policy

This kind of policy is enforced on the outbound connections initiated by the data plane proxy defined in sources section and then is applied only if the target data plane proxy matches tags defined in destination.

Assuming we have the following data plane proxies:

type: Dataplane
mesh: default
name: web-1
networking:
  address: 192.168.0.1
  inbound:
     - port: 9000
       servicePort: 6379
       tags:
         kuma.io/service: web
  outbound:
     - port: 1234
       tags:
          kuma.io/service: backend
     - port: 1234
       tags:
          kuma.io/service: admin

type: Dataplane
mesh: default
name: backend-1
networking:
   address: 192.168.0.2
   inbound:
      - port: 9000
        servicePort: 6379
        tags:
           kuma.io/service: backend

and a HealthCheck which is an example of Outbound Connection Policy

type: HealthCheck
mesh: default
name: catch-all-policy
sources:
  - match:
      kuma.io/service: web
destinations:
  - match:
      kuma.io/service: backend

then the health checking is applied only on the first outbound listener of the web-1 data plane proxy. The configuration of backend-1 data plane proxy is not changed in any way.

Inbound Connection Policy

This kind of policy is enforced on the inbound connections received by the data plane proxy defined in destination section and then is applied only if the data plane proxy that initiated this connection matches tags defined in sources.

Assuming we have the following data plane proxies:

type: Dataplane
mesh: default
name: web-1
networking:
  address: 192.168.0.1
  inbound:
     - port: 9000
       servicePort: 6379
       tags:
         kuma.io/service: web
  outbound:
     - port: 1234
       tags:
          kuma.io/service: backend

type: Dataplane
mesh: default
name: backend-1
networking:
   address: 192.168.0.2
   inbound:
      - port: 9000
        servicePort: 6379
        tags:
           kuma.io/service: backend
      - port: 9000
        servicePort: 6379
        tags:
           kuma.io/service: backend-api

and a TrafficPermission which is an example of Inbound Connection Policy

type: TrafficPermission
mesh: default
name: catch-all-policy
sources:
  - match:
      kuma.io/service: web
destinations:
  - match:
      kuma.io/service: backend

then the TrafficPermission is enforced only on the first inbound listener of the backend-1 data plane proxy. The configuration of web-1 data plane proxy is not changed in any way.