How Kuma chooses the right policy to apply

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 ?

The answer depends on policy type:

  • since TrafficPermission represents a grant of access given to a particular client service, Kuma conceptually “aggregates” all such grants by applying ALL TrafficPermission policies that match a connection between sources and destinations Dataplanes
  • for other policy types - TrafficRoute, TrafficLog, HealthCheck - conceptual “aggregation” would be too complex for users to always keep in mind; that is why Kuma chooses and applies only “the most specific” matching policy in that case

Going back to 2 TrafficLog policies described above:

  • for connections between web and backend Dataplanes Kuma will choose and apply web-to-backend-policy policy as “the most specific” in that case
  • for connections between all other dataplanes Kuma will choose and apply catch-all-policy policy as “the most specific” in that case

“The most specific” policy is defined according to the following rules:

  1. a policy that matches a connection between 2 Dataplanes by a greater number of tags is “more specific”

    E.g., web-to-backend-policy policy matches a connection between 2 Dataplanes by 4 tags (3 tags on sources and 1 tag on destinations), while catch-all-policy matches only by 2 tags (1 tag on sources and 1 tag on destinations)

  2. a policy that matches by the exact tag value is more specific than policy that matches by a '*' (wildcard) tag value

    E.g., web-to-backend-policy policy matches sources by kuma.io/service: web, while catch-all-policy matches by kuma.io/service: *

  3. if 2 policies match a connection between 2 Dataplanes by the same number of tags, then the one with a greater total number of matches by the exact tag value is “more specific” than the other

  4. if 2 policies match a connection between 2 Dataplanes 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 '*' (wildcard) tag value is the same for both policies, then a “more specific” policy is the one whoose name comes first when ordered alphabetically

E.g.,

  1. match by a greater number of tags

    1. sources:
    2.   - match:
    3.       kuma.io/service: '*'
    4.       cloud:   aws
    5.       region:  us
    6. destinations:
    7.   - match:
    8.       kuma.io/service: '*'

    is “more specific” than

    1. sources:
    2.   - match:
    3.       kuma.io/service: '*'
    4. destinations:
    5.   - match:
    6.       kuma.io/service: '*'

  2. match by the exact tag value

    1. sources:
    2.   - match:
    3.       kuma.io/service: web
    4. destinations:
    5.   - match:
    6.       kuma.io/service: backend

    is “more specific” than a match by a '*' (wildcard)

    1. sources:
    2.   - match:
    3.       kuma.io/service: '*'
    4. destinations:
    5.   - match:
    6.       kuma.io/service: '*'

  3. match with a greater total number of matches by the exact tag value

    1. sources:
    2.   - match:
    3.       kuma.io/service: web
    4.       version: v1
    5. destinations:
    6.   - match:
    7.       kuma.io/service: backend

    is “more specific” than

    1. sources:
    2.   - match:
    3.       kuma.io/service: web
    4.       version: '*'
    5. destinations:
    6.   - match:
    7.       kuma.io/service: backend

  4. when 2 matches are otherwise “equally specific”

    1. name: policy-1
    2. sources:
    3.   - match:
    4.       kuma.io/service: web
    5.       version: v1
    6. destinations:
    7.   - match:
    8.       kuma.io/service: backend

    policy-1 is considered “more specific” only due to the alphabetical order of names "policy-1" and "policy-2"

    1. name: policy-2
    2. sources:
    3.   - match:
    4.       kuma.io/service: web
    5. destinations:
    6.   - match:
    7.       kuma.io/service: backend
    8.       cloud:   aws