Applying Policies

Once installed, Kuma can be configured via its policies. You can apply policies with kumactl on Universal, and with kubectl on Kubernetes. Regardless of what environment you use, you can always read the latest Kuma state with kumactl on both environments.

We follow the best practices. You should always change your Kubernetes state with CRDs, that’s why Kuma disables kumactl apply [..] when running in K8s environments.

  1. echo "
  2.   apiVersion: kuma.io/v1alpha1
  3.   kind: ..
  4.   spec: ..
  5. " | kubectl apply -f -
  1. echo "
  2.   type: ..
  3.   spec: ..
  4. " | kumactl apply -f -

In addition to kumactl, you can also retrieve the state via the Kuma HTTP API.

Applying policies on Zone and Global Control Planes

Multi-zone deployment consists of Global Control Plane (Global CP) deployment with one or many Zone Control Planes (Zone CP) connected to it. Each Zone CP represents a single cluster (i.e. Kubernetes or Universal cluster). Policies can be applied on both Global and Zone CPs.

When policy is applied on Global CP:

  • it is propagated to all Zone CPs and applied to all matched data plane proxies in all zones
  • Global CP is a source of truth for the policy (when Global CP is down it’s not possible to create/update those policies)
  • You cannot manage this policy (modify / delete) on Zone CP

When policy is applied on Zone CP:

  • it is applied only to matched data plane proxies in the same zone
  • Zone CP is a source of truth for the policy (when Global CP is down it’s still possible to create/update zone-originated policies)
  • you cannot manage this policy (modify / delete) on Global CP
  • it is synced to Global CP to be visible in the UI and API calls

Applying policy on Zone CP requires setting kuma.io/origin label to zone (zone is a keyword, not a name of the zone):

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshTimeout
  3. metadata:
  4.   name: timeout-on-zone-cp
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/origin: zone
  8.     kuma.io/mesh: default
  9. spec:
  10.   targetRef:
  11.     kind: Mesh
  12.   to:
  13.   - targetRef:
  14.       kind: Mesh
  15.     default:
  16.       idleTimeout: 20s
  17.       connectionTimeout: 2s
  18.       http:
  19.         requestTimeout: 2s
  1. type: MeshTimeout
  2. name: timeout-on-zone-cp
  3. mesh: default
  4. labels:
  5.   kuma.io/origin: zone
  6. spec:
  7.   targetRef:
  8.     kind: Mesh
  9.   to:
  10.   - targetRef:
  11.       kind: Mesh
  12.     default:
  13.       idleTimeout: 20s
  14.       connectionTimeout: 2s
  15.       http:
  16.         requestTimeout: 2s

Validation of the origin label can be disabled by configuring a zone CP with KUMA_MULTIZONE_ZONE_DISABLE_ORIGIN_LABEL_VALIDATION: "true".

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.

It’s not necessary but CLI tools like jq and jd can greatly improve the UX.

How to use shadow mode

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

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

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

    or by using kumactl:

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

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

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

    or by using kumactl:

    1.  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:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshTimeout
  3. metadata:
  4.   name: frontend-timeouts
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/effect: shadow
  8.     kuma.io/mesh: default
  9. spec:
  10.   targetRef:
  11.     kind: MeshService
  12.     name: frontend
  13.   to:
  14.   - targetRef:
  15.       kind: MeshService
  16.       name: backend
  17.     default:
  18.       idleTimeout: 23s
  1. type: MeshTimeout
  2. name: frontend-timeouts
  3. mesh: default
  4. labels:
  5.   kuma.io/effect: shadow
  6. spec:
  7.   targetRef:
  8.     kind: MeshService
  9.     name: frontend
  10.   to:
  11.   - targetRef:
  12.       kind: MeshService
  13.       name: backend
  14.     default:
  15.       idleTimeout: 23s

Check the diff using kumactl:

  1. $ kumactl inspect dataplane frontend-dpp --type=config --include=diff --shadow | jq '.diff' | jd -t patch2jd
  2. @ ["type.googleapis.com/envoy.config.cluster.v3.Cluster","backend_kuma-demo_svc_3001","typedExtensionProtocolOptions","envoy.extensions.upstreams.http.v3.HttpProtocolOptions","commonHttpProtocolOptions","idleTimeout"]
  3. - "3600s"
  4. @ ["type.googleapis.com/envoy.config.cluster.v3.Cluster","backend_kuma-demo_svc_3001","typedExtensionProtocolOptions","envoy.extensions.upstreams.http.v3.HttpProtocolOptions","commonHttpProtocolOptions","idleTimeout"]
  5. + "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.