Overview

This check monitors Kuma, a universal open-source control plane for service mesh that supports both Kubernetes and Universal mode (VMs and standalone containers). Kuma is the open-source community version of Kong Mesh, developed by Kong.

With the Datadog Kuma integration, you can:

• Monitor the health and performance of the Kuma control plane.
• Collect logs from both the control plane and the data plane proxies.
• Gain detailed insights into the internal traffic flows within your service mesh which helps monitor performance and ensure reliability.

For monitoring the Envoy data planes (sidecars) within your Kuma mesh:

• Use the Envoy integration to collect metrics.
• Use this Kuma integration to collect logs.

Setup

The Kuma check is included in the Datadog Agent package. No additional installation is needed on your server.

Configuration

Metric collection

Metrics are collected from the Kuma control plane and the Envoy data planes.

Control plane

Autodiscovery (Kubernetes)

To configure the Agent to collect metrics from the Kuma control plane using autodiscovery, apply the following pod annotations to your kuma-control-plane deployment. This example assumes you installed Kuma using Helm. For more information about autodiscovery, see Autodiscovery Integration Templates.

# values.yaml
controlPlane:
  podAnnotations:
    ad.datadoghq.com/control-plane.checks: |
      {
        "kuma": {
          "init_config": {},
          "instances": [
            {
              "openmetrics_endpoint": "http://%%host%%:5680/metrics",
              "service": "kuma-control-plane"
            }
          ]
        }
      }      

Note: The autodiscovery annotation for Kuma has the format ad.datadoghq.com/<CONTAINER_NAME>.checks:. If your control plane has a different name, change the line accordingly. For more information, see the Datadog documentation.

Configuration file

Alternatively, you can configure the integration by editing the kuma.d/conf.yaml file in the conf.d/ folder at the root of your Agent’s configuration directory:

instances:
  - openmetrics_endpoint: http://<KUMA_CONTROL_PLANE_HOST>:5680/metrics
    service: kuma-control-plane

See the sample kuma.d/conf.yaml for all available configuration options.

Data planes (Envoy proxies)

Metrics from the data planes are collected using the Envoy integration.

1. First, enable Prometheus metrics exposition on your data planes by creating a MeshMetric policy. For more details, see the Kuma documentation.

   apiVersion: kuma.io/v1alpha1
   kind: MeshMetric
   metadata:
     name: my-metrics-policy
     namespace: kuma-system
     labels:
       kuma.io/mesh: default
   spec:
     default:
       backends:
       - type: Prometheus
         prometheus:
           port: 5670
           path: "/metrics"
   

2. Next, configure the Datadog Agent to collect these metrics by applying the following annotations to your application pods. For guidance on applying annotations, see Autodiscovery Integration Templates.

   ad.datadoghq.com/kuma-sidecar.checks: |
     {
       "envoy": {
         "instances": [
           {
             "openmetrics_endpoint": "http://%%host%%:5670/metrics",
             "collect_server_info": false
           }
         ]
       }
     }  
   

   Note: The autodiscovery annotation for Kuma has the format ad.datadoghq.com/<CONTAINER_NAME>.checks:. If your sidecar has a different name, change the line accordingly. For more information, see the Datadog documentation.

Log collection

Enable log collection in your datadog.yaml file:

logs_enabled: true

Control Plane Logs

To collect logs from the Kuma control plane, apply the following annotations to your kuma-control-plane deployment:

# values.yaml
controlPlane:
  podAnnotations:
    ad.datadoghq.com/control-plane.logs: |
      [
        {
          "source": "kuma",
          "service": "kuma-control-plane"
        }
      ]      

Note: The autodiscovery annotation for Kuma has the format ad.datadoghq.com/<CONTAINER_NAME>.logs:. If your control plane has a different name, change the line accordingly. For more information, see the Datadog documentation.

Data plane logs

Configure the Datadog Agent to collect logs from the Envoy sidecar containers by applying the following annotations to your application pods:

ad.datadoghq.com/kuma-sidecar.logs: |
  [
    {
      "source": "kuma",
      "service": "<MY_SERVICE>",
      "auto_multi_line_detection": true
    }
  ]  

Note: The autodiscovery annotation for Kuma has the format ad.datadoghq.com/<CONTAINER_NAME>.logs:. If your sidecar has a different name, change the line accordingly. For more information, see the Datadog documentation.

Replace <MY_SERVICE> with the name of your service.

Optional: Enable mesh access logs

If you want to collect access logs showing traffic between services in your mesh, you can enable them by creating a MeshAccessLog policy. For more details, see the Kuma documentation.

Enable sidecar injection for Datadog Agent pods

If you have strict mTLS enabled for your mesh, the Datadog Agent requires a Kuma sidecar to be injected into its pods to communicate with other services.

To enable sidecar injection for the Datadog Agent, add the kuma.io/sidecar-injection: enabled label to the namespace where the Agent is deployed (usually datadog):

apiVersion: v1
kind: Namespace
metadata:
  name: datadog
  labels:
    kuma.io/sidecar-injection: enabled

You also need to apply a MeshTrafficPermission policy to allow traffic between the Agent and your services. For more information, see the Kuma documentation.

Validation

Run the Agent’s status subcommand and look for kuma under the Checks section.

Data Collected

Metrics

Events

The Kuma integration does not include any events.

Troubleshooting

mTLS connection issues

If you have strict mTLS with no passthrough enabled, the Agent may fail to connect to the control plane or other services. This is because all traffic is encrypted and routed through Kuma’s data plane proxies. To resolve this, you must enable sidecar injection for the Datadog Agent pods.

Once the sidecar is injected, you should replace %%host%% with the Kubernetes service name in your autodiscovery annotations, as the %%host%% macro may no longer work correctly when traffic is routed through the mesh. This is not necessary for the Kuma control plane or sidecars.

For example, instead of:

"openmetrics_endpoint": "http://%%host%%:5670/metrics"

Use the service name:

"openmetrics_endpoint": "http://my-service.my-namespace.svc.cluster.local:5670/metrics"

When mTLS is enabled, you may want to disable auto-discovery auto-configuration since it uses %%host%% macros. For more information on how to disable auto-configuration, see the Datadog documentation.

Need help? Contact Datadog support.

Further Reading

• Kuma official documentation
• Kuma Policies Documentation