General notes about Kuma policies

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

Policies applied to data plane proxies all follow the same basic structure:

  1. sources:
  2. - match:
  3.     kuma.io/service: ... # unique name OR '*'
  4.     ... # (optionally) other tags
  6. destinations:
  7. - match:
  8.     kuma.io/service: ... # unique name OR '*'
  9.     ... # (optionally) other tags
  11. conf:
  12.   ... # policy-specific configuration
  • sources - list of selectors that specify the dataplane objects where network traffic originates
  • destinations - list of selectors that specify the dataplane object the source traffic is sent to
  • conf - configuration to apply to network traffic between sources and destinations

Kuma assumes that every dataplane object represents a service, even if it’s a cron job that doesn’t normally handle incoming traffic. This means the kuma.io/service tag is required for sources and destinations. Note the following requirements for values:

  • The wildcard character (*) is supported only as the selector value to match all traffic.
  • Tag values can contain only alphanumeric characters, dots (.), dashes (-), colons (:), and underscores (_).
  • Selector values can contain only alphanumeric characters, dots (.), dashes (-), colons (:), underscores (_). slashes (/).

Tag and selector names can contain only alphanumeric characters, dots (.), dashes (-), colons (:), underscores (_), and slashes (/).

All policies support arbitrary tags for the sources selector, but there are tag limitations for the destinations selector. For example, policies that are applied on the client side of a connection between two dataplane objects do not support arbitrary tags in the destinations selector. Only the kuma.io/service tag is supported in this case. This includes TrafficRoute, TrafficLog, and HealthCheck.

For example, this policy applies to all network traffic between all dataplane objects:

  1. sources:
  2. - match:
  3.     kuma.io/service: '*'
  5. destinations:
  6. - match:
  7.     kuma.io/service: '*'
  9. conf:
  10.   ...

This policy applies only to network traffic between dataplane objects for the specified services:

  1. sources:
  2. - match:
  3.     kuma.io/service: web
  5. destinations:
  6. - match:
  7.     kuma.io/service: backend
  9. conf:
  10.   ...

You can provide additional tags to further limit policy scope:

  1. sources:
  2. - match:
  3.     kuma.io/service: web
  4.     cloud:   aws
  5.     region:  us
  7. destinations:
  8. - match:
  9.     kuma.io/service: backend
  10.     version: v2      # notice that not all policies support arbitrary tags in `destinations` selectors
  12. conf:
  13.   ...