Policies

Here you can find the list of Policies that Kuma supports.

Going forward from version 2.0, Kuma is transitioning from source/destination policies to targetRef policies.

The following table shows the equivalence between source/destination and targetRef policies:

source/destination policy	`targetRef` policy
CircuitBreaker	MeshCircuitBreaker
FaultInjection	MeshFaultInjection
HealthCheck	MeshHealthCheck
RateLimit	MeshRateLimit
Retry	MeshRetry
Timeout	MeshTimeout
TrafficLog	MeshAccessLog
TrafficMetrics	MeshMetric
TrafficPermissions	MeshTrafficPermission
TrafficRoute	MeshHTTPRoute
TrafficTrace	MeshTrace
ProxyTemplate	MeshProxyPatch

If you are new to Kuma you should only need to use targetRef policies. If you already use source/destination policies you can keep using them. Future versions of Kuma will provide a migration path. You can mix targetRef and source/destination policies as long as they are of different types. For example: You can use MeshTrafficPermission with FaultInjection but you can’t use MeshTrafficPermission with TrafficPermission.

Applying policies in shadow mode

Overview

The new shadow mode functionality allows users to mark policies with a specific label to simulate configuration changes without affecting the live environment. It enables the observation of potential impact on Envoy proxy configurations, providing a risk-free method to test, validate, and fine-tune settings before actual deployment. Ideal for learning, debugging, and migrating, shadow mode ensures configurations are error-free, improving the overall system reliability without disrupting ongoing operations.

Recommended setup

It’s not necessary but CLI tools like jq and jd can greatly improve working with Kuma resources.

How to use shadow mode

Before applying the policy, add a kuma.io/effect: shadow label.

Check the proxy config with shadow policies taken into account through the Kuma API. By using HTTP API:

 curl http://localhost:5681/meshes/${mesh}/dataplane/${dataplane}/_config?shadow=true

or by using kumactl:

 kumactl inspect dataplane ${name} --type=config --shadow

Check the diff in JSONPatch format through the Kuma API. By using HTTP API:

 curl http://localhost:5681/meshes/${mesh}/dataplane/${dataplane}/_config?shadow=true&include=diff

or by using kumactl:

 kumactl inspect dataplane ${name} --type=config --shadow --include=diff

Limitations and Considerations

Currently, the Kuma API mentioned above works only on Zone CP. Attempts to use it on Global CP lead to 405 Method Not Allowed. This might change in the future.

Examples

Apply policy with kuma.io/effect: shadow label:

Kubernetes
Universal

apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
  name: frontend-timeouts
  namespace: kuma-system
  labels:
    kuma.io/effect: shadow
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshService
    name: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
    default:
      idleTimeout: 23s

type: MeshTimeout
name: frontend-timeouts
mesh: default
labels:
  kuma.io/effect: shadow
spec:
  targetRef:
    kind: MeshService
    name: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
    default:
      idleTimeout: 23s

Check the diff using kumactl:

$ kumactl inspect dataplane frontend-dpp --type=config --include=diff --shadow | jq '.diff' | jd -t patch2jd
@ ["type.googleapis.com/envoy.config.cluster.v3.Cluster","backend_kuma-demo_svc_3001","typedExtensionProtocolOptions","envoy.extensions.upstreams.http.v3.HttpProtocolOptions","commonHttpProtocolOptions","idleTimeout"]
- "3600s"
@ ["type.googleapis.com/envoy.config.cluster.v3.Cluster","backend_kuma-demo_svc_3001","typedExtensionProtocolOptions","envoy.extensions.upstreams.http.v3.HttpProtocolOptions","commonHttpProtocolOptions","idleTimeout"]
+ "23s"

The output not only identifies the exact location in Envoy where the change will occur, but also shows the current timeout value that we’re planning to replace.