DataDog · Mathew-Estafanous · Jun 15, 2026
@@ -17,6 +17,9 @@ further_reading:
 - link: "/agent/kubernetes/tag/"
   tag: "Documentation"
   text: "Assign tags to all data emitted by a container"
+- link: "/containers/guide/configure-autodiscovery-with-the-datadoginstrumentation-crd/"
+  tag: "Documentation"
+  text: "Configure Autodiscovery with the DatadogInstrumentation CRD"
 ---
 
 This page contains detailed example templates for configuring integrations in containerized environments in the following scenarios:
@@ -28,6 +31,8 @@ For more information about containers and integrations, see [Docker and Integrat
 
 All examples make use of Datadog's Autodiscovery feature, which allows you to define configuration templates for Agent Checks on designated sets of containers. For more information about Autodiscovery, see [Getting Started with Containers: Autodiscovery][1].
 
+To configure these checks for a specific workload without using pod annotations, see [Configure Autodiscovery with the DatadogInstrumentation CRD][13] (beta).
+
 ## Redis integration for all Redis containers
 
 In this example scenario, you have a containerized environment in which you want to set up and configure the [Datadog-Redis integration][5] for all containers that match the name `redis`. You have one container named `redis` and another named `my-custom-redis`, and you want to configure the Redis integration for **both** containers.
@@ -635,4 +640,5 @@ All of these examples use [Autodiscovery template variables][7]:
 [9]: /integrations/http_check/
 [10]: https://github.com/DataDog/integrations-core/blob/master/apache/datadog_checks/apache/data/conf.yaml.example
 [11]: /extend/write_agent_check/#updating-the-collection-interval
-[12]: https://github.com/DataDog/integrations-core/blob/master/http_check/datadog_checks/http_check/data/conf.yaml.example
+[12]: https://github.com/DataDog/integrations-core/blob/master/http_check/datadog_checks/http_check/data/conf.yaml.example
+[13]: /containers/guide/configure-autodiscovery-with-the-datadoginstrumentation-crd/
@@ -0,0 +1,198 @@
+---
+title: Configure Autodiscovery with the DatadogInstrumentation CRD
+description: Configure Autodiscovery checks for Kubernetes workloads through the DatadogInstrumentation custom resource instead of pod annotations.
+further_reading:
+- link: "/containers/kubernetes/integrations/"
+  tag: "Documentation"
+  text: "Configure integrations with Autodiscovery"
+- link: "/getting_started/containers/autodiscovery/"
+  tag: "Documentation"
+  text: "Getting Started with Autodiscovery"
+- link: "/containers/guide/autodiscovery-examples/"
+  tag: "Documentation"
+  text: "Autodiscovery scenarios and examples"
+- link: "/containers/cluster_agent/"
+  tag: "Documentation"
+  text: "Datadog Cluster Agent"
+---
+
+<div class="alert alert-info">Configuring Autodiscovery with the <code>DatadogInstrumentation</code> custom resource is in beta.</div>
+
+## Overview
+
+The `DatadogInstrumentation` custom resource (CR) lets you configure [Autodiscovery][1] checks for specific Kubernetes workloads through a single Kubernetes resource, instead of [pod annotations][2]. With this approach, you can enable, update, and roll back integration configurations without editing pod specs or triggering Agent or application rollouts.
+
+Use the `DatadogInstrumentation` CR when you want to:
+
+- Configure Autodiscovery checks without modifying workload manifests or adding annotations.
+- Centrally manage per-workload check configuration as a dedicated, version-controlled Kubernetes resource.
+- Update or remove check configuration without restarting your application pods.
+
+The configuration is reconciled by a controller in the [Datadog Cluster Agent][3]. When you create or update a `DatadogInstrumentation` resource, the Cluster Agent generates the corresponding check configurations and applies them to the matching workload's containers.
+
+## Requirements
+
+- Datadog Agent and Cluster Agent v7.81 or later.
+- To install the CRD and enable the controller, Datadog Operator v1.28 or later, or Datadog Helm chart v2.223.0 or later.
+
+## Enable the controller
+
+The `DatadogInstrumentation` controller runs in the Cluster Agent and is disabled by default. Enable it with the Datadog Operator or Helm.
+
+{{< tabs >}}
+{{% tab "Datadog Operator" %}}
+
+While the feature is in beta, opt in by adding the `agent.datadoghq.com/instrumentation-crd-enabled` annotation to your `DatadogAgent` resource. The Cluster Agent must be v7.81.0 or later.
+
+```yaml
+apiVersion: datadoghq.com/v2alpha1
+kind: DatadogAgent
+metadata:
+  name: datadog
+  annotations:
+    agent.datadoghq.com/instrumentation-crd-enabled: "true"
+spec:
+  global:
+    [...]
+```
+
+Apply the change:
+
+```shell
+kubectl apply -f datadog-agent.yaml
+```
+
+The Operator sets the required environment variables and RBAC on the Cluster Agent automatically.
+
+{{% /tab %}}
+{{% tab "Helm" %}}
+
+In your `datadog-values.yaml` file, enable the controller:
+
+```yaml
+datadog:
+  instrumentationCrd:
+    enabled: true
+```
+
+Upgrade your release:
+
+```shell
+helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+When the controller is enabled, it waits for the `DatadogInstrumentation` CRD to be installed in the cluster before it starts reconciling resources.
+
+## Configure a check
+
+A `DatadogInstrumentation` resource has two main parts:
+
+- `spec.targetRef`: identifies the workload to configure, by `apiVersion`, `kind`, and `name`. The resource and the target workload must be in the same namespace.
+- `spec.config.checks`: a list of Autodiscovery check configurations to apply to the target workload's containers.
+
+The following example configures the [Redis integration][4] for a `Deployment` named `redis`, including log collection. It mirrors the [annotation-based example][2], using the same [template variables][5] such as `%%host%%`:
+
+```yaml
+apiVersion: datadoghq.com/v1alpha1
+kind: DatadogInstrumentation
+metadata:
+  name: redis-instrumentation
+  namespace: default
+spec:
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: redis
+  config:
+    checks:
+      - integration: redisdb
+        containerImage:
+          - redis
+        initConfig: {}
+        instances:
+          - host: "%%host%%"
+            port: "6379"
+            password: "%%env_REDIS_PASSWORD%%"
+        logs:
+          - type: file
+            path: /var/log/redis_6379.log
+            source: redis
+            service: redis_service
+```
+
+Apply the resource:
+
+```shell
+kubectl apply -f redis-instrumentation.yaml
+```
+
+Each entry in `checks` accepts the following fields:
+
+`integration`
+: The name of the Datadog integration to run, such as `redisdb`.
+
+`containerImage`
+: A list of container image identifiers to match against the target workload's containers. The check is applied to containers whose image matches an entry in this list.
+
+`initConfig`
+: The `init_config` section for the integration. This section is usually empty (`{}`).
+
+`instances`
+: A list of instance configurations for the check. Each instance supports [Autodiscovery template variables][5], such as `%%host%%`.
+
+`logs`
+: The log collection configuration for the matching containers.
+
+### Endpoint and cluster checks
+
+To configure an [endpoint check][6], set `targetRef` to a `Service`:
+
+```yaml
+spec:
+  targetRef:
+    apiVersion: v1
+    kind: Service
+    name: my-service
+```
+
+## Precedence
+
+When more than one configuration source applies to a workload, Datadog resolves them in the following order (highest precedence first):
+
+1. Pod annotations
+2. `DatadogInstrumentation` resources
+3. Static configuration (such as auto-configuration or mounted files)
+
+If a workload already has annotation-based Autodiscovery configuration for a check, the `DatadogInstrumentation` configuration does not override it.
+
+## One resource per workload
+
+A workload can be the target of only one `DatadogInstrumentation` resource within a namespace. A validating admission webhook rejects a resource whose `targetRef` already belongs to another resource, or whose `targetRef` points to an unsupported kind.
+
+## Check the status
+
+The controller reports the result of reconciling each resource through Kubernetes status conditions. To view the status, including whether the configuration was applied and the resolved target workload:
+
+```shell
+kubectl describe datadoginstrumentation redis-instrumentation
+```
+
+## Limitations
+
+- This capability is in beta.
+- The `DatadogInstrumentation` CRD is served at `apiVersion: datadoghq.com/v1alpha1`.
+- This page covers Autodiscovery checks only. Configuring APM Single Step Instrumentation through the `DatadogInstrumentation` resource is tracked separately.
+
+## Further reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: /getting_started/containers/autodiscovery/
+[2]: /containers/kubernetes/integrations/
+[3]: /containers/cluster_agent/
+[4]: /integrations/redisdb/
+[5]: /containers/guide/template_variables/
+[6]: /containers/cluster_agent/endpointschecks/
@@ -52,7 +52,7 @@ Some commonly-used integrations come with default configuration for Autodiscover
 
 Otherwise:
 
-1. Choose a configuration method (Kubernetes pod annotations, a local file, a ConfigMap, a key-value store, a Datadog Operator manifest, or a Helm chart) that suits your use case.
+1. Choose a configuration method (Kubernetes pod annotations, a local file, a ConfigMap, a key-value store, a Datadog Operator manifest, a Helm chart, or the `DatadogInstrumentation` custom resource) that suits your use case.
 2. Reference the template format for your chosen method. Each format contains placeholders, such as `<CONTAINER_NAME>`.
 3. [Supply values](#placeholder-values) for these placeholders.
 
@@ -350,6 +350,40 @@ See [Cluster Checks][3] for more context.
 [2]: https://github.com/DataDog/helm-charts/blob/92fd908e3dd7b7149ce02de1fe859ae5ac717d03/charts/datadog/values.yaml#L680-L689
 [3]: /agent/cluster_agent/clusterchecks
 {{% /tab %}}
+{{% tab "DatadogInstrumentation CRD" %}}
+
+<div class="alert alert-info">Configuring Autodiscovery with the <code>DatadogInstrumentation</code> custom resource is in beta.</div>
+
+You can configure Autodiscovery checks for a specific workload through the `DatadogInstrumentation` custom resource, instead of pod annotations. This lets you update or remove check configuration without editing pod specs or restarting your application pods.
+
+```yaml
+apiVersion: datadoghq.com/v1alpha1
+kind: DatadogInstrumentation
+metadata:
+  name: <NAME>
+  namespace: default
+spec:
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: <WORKLOAD_NAME>
+  config:
+    checks:
+      - integration: <INTEGRATION_NAME>
+        containerImage:
+          - <CONTAINER_IMAGE>
+        initConfig:
+          <INIT_CONFIG>
+        instances:
+          - <INSTANCES_CONFIG>
+        logs:
+          - <LOGS_CONFIG>
+```
+
+For setup steps, the full resource schema, and precedence rules, see [Configure Autodiscovery with the DatadogInstrumentation CRD][29].
+
+[29]: /containers/guide/configure-autodiscovery-with-the-datadoginstrumentation-crd/
+{{% /tab %}}
 
 {{< /tabs >}}
 

@@ -9,6 +9,9 @@ further_reading:
 - link: "/agent/kubernetes/integrations/"
   tag: "Documentation"
   text: "Create and load an Autodiscovery Integration Template"
+- link: "/containers/guide/configure-autodiscovery-with-the-datadoginstrumentation-crd/"
+  tag: "Documentation"
+  text: "Configure Autodiscovery with the DatadogInstrumentation CRD"
 - link: "/agent/guide/ad_identifiers/"
   tag: "Documentation"
   text: "Match a container with the corresponding Integration Template"
@@ -140,6 +143,8 @@ Once Autodiscovery is enabled, the Datadog Agent automatically attempts Autodisc
 
 You can define an integration template in multiple forms: as Kubernetes pod annotations, Docker labels, a configuration file mounted within the Agent, a ConfigMap, and key-value stores. See the [Autodiscovery Integration Templates][4] documentation for further details.
 
+On Kubernetes, you can also configure checks for a specific workload through the `DatadogInstrumentation` custom resource, instead of pod annotations. See [Configure Autodiscovery with the DatadogInstrumentation CRD][5] (beta).
+
 ### Notes
 
 If you are using Autodiscovery and an application is deployed on a new node, you may experience some delay in seeing metrics appear in Datadog. When you switch to a new node, it takes time for the Datadog Agent to collect metadata from your application.
@@ -152,3 +157,4 @@ If you are using Autodiscovery and an application is deployed on a new node, you
 [2]: /agent/faq/template_variables/
 [3]: /agent/faq/auto_conf/
 [4]: /agent/kubernetes/integrations/
+[5]: /containers/guide/configure-autodiscovery-with-the-datadoginstrumentation-crd/