How Kuma chooses the right policy to apply

New to Kuma? You don’t need this, check TargetRef policies instead.

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

  1. type: TrafficLog
  2. mesh: default
  3. name: catch-all-policy
  4. sources:
  5.   - match:
  6.       kuma.io/service: '*'
  7. destinations:
  8.   - match:
  9.       kuma.io/service: '*'
  10. conf:
  11.   backend: logstash

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

  1. type: TrafficLog
  2. mesh: default
  3. name: web-to-backend-policy
  4. sources:
  5.   - match:
  6.       kuma.io/service: web
  7.       cloud: aws
  8.       region: us
  9. destinations:
  10.   - match:
  11.       kuma.io/service: backend
  12. conf:
  13.   backend: splunk

What does Kuma do when it encounters multiple matching policies?

General rules

Kuma always picks the single most specific policy.

  1. A policy that matches by a greater number of tags

    1. - match:
    2.     kuma.io/service: '*'
    3.     cloud:   aws
    4.     region:  us

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

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

  2. A policy that matches by the exact tag value

    1. - match:
    2.     kuma.io/service: web

    is “more specific” than the one that matches by a '*' (wildcard)

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

  3. 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

    1. - match:
    2.     kuma.io/service: web
    3.     version: v1

    is “more specific” than the other

    1. - match:
    2.     kuma.io/service: web
    3.     version: '*'

  4. 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

    1. modificationTime: "2020-01-01T20:00:00.0000Z"
    2. ...
    3. - match:
    4.     kuma.io/service: web
    5.     version: v1

    is “more specific” policy than the older one

    1. modificationTime: "2019-01-01T20:00:00.0000Z"
    2. ...
    3. - match:
    4.     kuma.io/service: web
    5.     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:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: TrafficPermission
  3. mesh: default
  4. metadata:
  5.   name: allow-b-to-a
  6. spec:
  7.   sources:
  8.     - match:
  9.         kuma.io/service: b
  10.   destinations:
  11.     - match:
  12.         kuma.io/service: a
  1. apiVersion: kuma.io/v1alpha1
  2. kind: TrafficPermission
  3. mesh: default
  4. metadata:
  5.   name: allow-c-to-a
  6. spec:
  7.   sources:
  8.     - match:
  9.         kuma.io/service: c
  10.   destinations:
  11.     - match:
  12.         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:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: TrafficPermission
  3. mesh: default
  4. metadata:
  5.   name: allow-b-c-to-a
  6. spec:
  7.   sources:
  8.     - match:
  9.         kuma.io/service: b
  10.     - match:
  11.         kuma.io/service: c
  12.   destinations:
  13.     - match:
  14.         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

  1. type: Dataplane
  2. mesh: default
  3. name: web-1
  4. networking:
  5.   address: 192.168.0.1
  6.   inbound:
  7.      - port: 9000
  8.        servicePort: 6379
  9.        tags:
  10.          kuma.io/service: web

and a ProxyTemplate which is an example of a Dataplane Policy

  1. type: ProxyTemplate
  2. mesh: default
  3. name: custom-template-1
  4. selectors:
  5.   - match:
  6.       kuma.io/service: web
  7. conf:
  8.   imports:
  9.     - 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:

  1. type: Dataplane
  2. mesh: default
  3. name: web-1
  4. networking:
  5.   address: 192.168.0.1
  6.   inbound:
  7.      - port: 9000
  8.        servicePort: 6379
  9.        tags:
  10.          kuma.io/service: web
  11.   outbound:
  12.      - port: 1234
  13.        tags:
  14.           kuma.io/service: backend
  15.      - port: 1234
  16.        tags:
  17.           kuma.io/service: admin
  1. type: Dataplane
  2. mesh: default
  3. name: backend-1
  4. networking:
  5.    address: 192.168.0.2
  6.    inbound:
  7.       - port: 9000
  8.         servicePort: 6379
  9.         tags:
  10.            kuma.io/service: backend

and a HealthCheck which is an example of Outbound Connection Policy

  1. type: HealthCheck
  2. mesh: default
  3. name: catch-all-policy
  4. sources:
  5.   - match:
  6.       kuma.io/service: web
  7. destinations:
  8.   - match:
  9.       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:

  1. type: Dataplane
  2. mesh: default
  3. name: web-1
  4. networking:
  5.   address: 192.168.0.1
  6.   inbound:
  7.      - port: 9000
  8.        servicePort: 6379
  9.        tags:
  10.          kuma.io/service: web
  11.   outbound:
  12.      - port: 1234
  13.        tags:
  14.           kuma.io/service: backend
  1. type: Dataplane
  2. mesh: default
  3. name: backend-1
  4. networking:
  5.    address: 192.168.0.2
  6.    inbound:
  7.       - port: 9000
  8.         servicePort: 6379
  9.         tags:
  10.            kuma.io/service: backend
  11.       - port: 9000
  12.         servicePort: 6379
  13.         tags:
  14.            kuma.io/service: backend-api

and a TrafficPermission which is an example of Inbound Connection Policy

  1. type: TrafficPermission
  2. mesh: default
  3. name: catch-all-policy
  4. sources:
  5.   - match:
  6.       kuma.io/service: web
  7. destinations:
  8.   - match:
  9.       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.