Overview

The DatadogInstrumentation custom resource (CR) lets you configure Autodiscovery checks and logs with a single Kubernetes resource instead of pod annotations. With this approach, you can enable, update, and remove integration configurations without editing your Agent or application and triggering a rollout.

Use the DatadogInstrumentation CR when you want to:

• Configure checks and logs without modifying workload manifests or adding annotations.
• Use a structured resource spec with validation instead of raw JSON in annotations.
• Centrally manage per-workload Autodiscovery configuration as a dedicated, version-controlled Kubernetes resource.
• Update or remove Autodiscovery configuration without restarting your application pods.

When you create or update a DatadogInstrumentation resource, the Datadog Cluster Agent validates the target, reports resource status, and applies the Autodiscovery configuration to the targeted workload.

Requirements

Upgrade to v7.82+ of the Datadog Agent and Cluster Agent and install the DatadogInstrumentation CRD with one of the following:

• Datadog Operator v1.29 or later.
• Datadog Helm chart v3.236.0 or later.

Setup

To use DatadogInstrumentation (DDI), a controller in your Agent must be enabled to track and reconcile each CR.

helm repo update

helm upgrade datadog-operator datadog/datadog-operator

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
  annotations:
    agent.datadoghq.com/instrumentation-crd-enabled: "true"
spec:
  global:
    [...]

kubectl apply -f datadog-agent.yaml

helm repo update

datadog:
  instrumentationCrd:
    enabled: true

helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog

Make sure the DatadogInstrumentation CRD is installed before creating resources:

kubectl get crd datadoginstrumentations.datadoghq.com

If you manage Datadog CRDs separately, install or upgrade the Datadog CRDs Helm chart:

helm upgrade --install datadog-crds datadog/datadog-crds

Target workloads

DatadogInstrumentation (DDI) for Autodiscovery has three parts:

• spec.targetRef: identifies the workload to configure, by apiVersion, kind, and name. Your custom resource and target workload must be in the same namespace.
• spec.config.checks: defines integration checks to run against your workload.
• spec.config.logs: defines logs to collect from your workload.

You can target the following Kubernetes resources:

This example configures a Redis integration for a StatefulSet named redis, mirroring this annotation-based example.

apiVersion: datadoghq.com/v1alpha1
kind: DatadogInstrumentation
metadata:
  name: <YOUR_CR_NAME>
  namespace: <YOUR_TARGETS_NAMESPACE>
spec:
  targetRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: redis
  config:
    checks:
      - integration: redisdb
        containerName: redis
        initConfig: {}
        instances:
          - host: "%%host%%"
            port: "6379"
            password: "%%env_REDIS_PASSWORD%%"
    logs:
      - containerName: redis
        tags:
          - env:demo

Apply the resource:

kubectl apply -f redis-instrumentation.yaml

Check the resource status:

kubectl describe datadoginstrumentation <YOUR_CR_NAME> -n <YOUR_TARGETS_NAMESPACE>

Each entry in checks accepts the following fields:

integration

Required. The name of the Datadog integration to run, for example redisdb.

containerName

Required for workload targets. The value must match a container name in the pod. Omit this field for Service targets.

initConfig

Optional. The init_config section for the integration.

instances

Optional. Check instance settings. Each instance can use Autodiscovery template variables, including %%host%%.

Each entry in logs accepts the same log collection options as Autodiscovery log annotations, such as tags, type, and path. Each entry requires a containerName matching a container in the pod.

Target services

Targeting a Service configures an endpoint check similar to an annotation on a Kubernetes service.

• Datadog schedules one endpoint check for each endpoint of the Service.
• %%host%% resolves to the endpoint IP.
• If an endpoint is backed by a Kubernetes Pod, Datadog adds the Pod tags collected for that Pod.
• If an endpoint is not backed by a Pod, Datadog converts the check into a regular cluster check without Pod-specific tags.

Below is an example configuring a nginx check against a Kubernetes Service:

apiVersion: datadoghq.com/v1alpha1
kind: DatadogInstrumentation
metadata:
  name: <YOUR_CR_NAME>
  namespace: <YOUR_SERVICES_NAMESPACE>
spec:
  targetRef:
    apiVersion: v1
    kind: Service
    name: nginx
  config:
    checks:
      - integration: nginx
        initConfig: {}
        instances:
          - name: "My NGINX Service Endpoints"
            nginx_status_url: "http://%%host%%:%%port%%/status/"

Precedence

When more than one configuration source applies to a workload, the Datadog Agent resolves them in the following order (highest precedence first):

1. Pod annotations
2. DatadogInstrumentation custom resource
3. Static configuration, such as auto-configuration or mounted files

If a workload already has annotation-based Autodiscovery configuration for a check or log collection, your DatadogInstrumentation configuration does not override it.

One resource per target

A workload or Service can be the target of only one DatadogInstrumentation resource within a namespace. A validation webhook rejects a resource whose targetRef already belongs to another resource, or whose targetRef points to an unsupported kind.

Verify scheduled checks

The resource status shows whether the Cluster Agent accepted the configuration. To verify that the checks are scheduled, run agent configcheck on the Node Agent where the target workload runs.

Checks configured through a DatadogInstrumentation resource list instrumentation-checks as the configuration provider and datadoginstrumentation:<NAMESPACE>/<CR_NAME> as the configuration source. The following example shows the output for a redisdb check scheduled from a resource that targets a Redis workload:

> agent configcheck
# other configs...

=== redisdb check ===
Configuration provider: instrumentation-checks
Configuration source: datadoginstrumentation:cache/redis-instrumentation
Config for instance ID: redisdb:d5dd267b580bc10e
host: 10.244.0.7
password: "********"
port: 6379
Init Config:
{}
Log Config:
- tags:
  - env:demo
Auto-discovery IDs:
* redis

Further reading

Additional helpful documentation, links, and articles:

Configure integrations with AutodiscoveryDOCUMENTATION Getting Started with AutodiscoveryDOCUMENTATION Autodiscovery scenarios and examplesDOCUMENTATION Datadog Cluster AgentDOCUMENTATION