Note: AD Annotations v2 was introduced in Datadog Agent 7.36 to simplify integration configuration. For previous versions of the Datadog Agent, use AD Annotations v1.
Integration templates can be stored in your Kubernetes pod annotations. With Autodiscovery, the Agent detects if it’s running on Kubernetes and automatically searches all pod annotations for integration templates.
To apply a specific configuration to a given container, Autodiscovery identifies containers by name, NOT image. It tries to match <CONTAINER_IDENTIFIER>
to .spec.containers[0].name
, not .spec.containers[0].image
. To configure your Datadog integration Autodiscovery on a given <CONTAINER_IDENTIFIER>
within your pod, add the following annotations to your pod:
apiVersion: v1
kind: Pod
# (...)
metadata:
name: '<POD_NAME>'
annotations:
ad.datadoghq.com/<CONTAINER_IDENTIFIER>.checks: |
{
"<INTEGRATION_NAME>": {
"init_config": <INIT_CONFIG>,
"instances": [<INSTANCE_CONFIG>]
}
}
# (...)
spec:
containers:
- name: '<CONTAINER_IDENTIFIER>'
# (...)
init_config
is usually an empty {}
. In AD Annotations v2, it is optional.
To apply two different integration templates to two different containers: <CONTAINER_IDENTIFIER_1>
and <CONTAINER_IDENTIFIER_2>
within your pod, add the following annotations to your pod:
apiVersion: v1
kind: Pod
# (...)
metadata:
name: '<POD_NAME>'
annotations:
ad.datadoghq.com/<CONTAINER_IDENTIFIER_1>.checks: |
{
"<INTEGRATION_NAME_1>": {
"init_config": <INIT_CONFIG_1>,
"instances": [<INSTANCE_CONFIG_1>]
}
}
ad.datadoghq.com/<CONTAINER_IDENTIFIER_2>.checks: |
{
"<INTEGRATION_NAME_2>": {
"init_config": <INIT_CONFIG_2>,
"instances": [<INSTANCE_CONFIG_2>]
}
}
spec:
containers:
- name: '<CONTAINER_IDENTIFIER_1>'
# (...)
- name: '<CONTAINER_IDENTIFIER_2>'
# (...)
If you define your Kubernetes pods directly with kind: Pod
, add each pod’s annotations directly under its metadata
section. If you define pods indirectly with replication controllers, replica sets, or deployments, add pod annotations under .spec.template.metadata
.
Note: As a best practice in containerized environments, Datadog recommends using unified service tagging when assigning tags. Unified service tagging ties Datadog telemetry together through the use of three standard tags: env
, service
, and version
. To learn how to configure your environment with unified tagging, refer to the dedicated unified service tagging documentation.
Integration templates can be stored in your Kubernetes pod annotations. With Autodiscovery, the Agent detects if it’s running on Kubernetes and automatically searches all pod annotations for integration templates.
To apply a specific configuration to a given container, Autodiscovery identifies containers by name, NOT image. It tries to match <CONTAINER_IDENTIFIER>
to .spec.containers[0].name
, not .spec.containers[0].image
. To configure your Datadog integration Autodiscovery on a given <CONTAINER_IDENTIFIER>
within your pod, add the following annotations to your pod:
apiVersion: v1
kind: Pod
# (...)
metadata:
name: '<POD_NAME>'
annotations:
ad.datadoghq.com/<CONTAINER_IDENTIFIER>.check_names: '[<INTEGRATION_NAME>]'
ad.datadoghq.com/<CONTAINER_IDENTIFIER>.init_configs: '[<INIT_CONFIG>]'
ad.datadoghq.com/<CONTAINER_IDENTIFIER>.instances: '[<INSTANCE_CONFIG>]'
# (...)
spec:
containers:
- name: '<CONTAINER_IDENTIFIER>'
# (...)
To apply two different integration templates to two different containers: <CONTAINER_IDENTIFIER_1>
and <CONTAINER_IDENTIFIER_2>
within your pod, add the following annotations to your pod:
apiVersion: v1
kind: Pod
# (...)
metadata:
name: '<POD_NAME>'
annotations:
ad.datadoghq.com/<CONTAINER_IDENTIFIER_1>.check_names: '[<INTEGRATION_NAME_1>]'
ad.datadoghq.com/<CONTAINER_IDENTIFIER_1>.init_configs: '[<INIT_CONFIG_1>]'
ad.datadoghq.com/<CONTAINER_IDENTIFIER_1>.instances: '[<INSTANCE_CONFIG_1>]'
# (...)
ad.datadoghq.com/<CONTAINER_IDENTIFIER_2>.check_names: '[<INTEGRATION_NAME_2>]'
ad.datadoghq.com/<CONTAINER_IDENTIFIER_2>.init_configs: '[<INIT_CONFIG_2>]'
ad.datadoghq.com/<CONTAINER_IDENTIFIER_2>.instances: '[<INSTANCE_CONFIG_2>]'
spec:
containers:
- name: '<CONTAINER_IDENTIFIER_1>'
# (...)
- name: '<CONTAINER_IDENTIFIER_2>'
# (...)
If you define your Kubernetes pods directly with kind: Pod
, add each pod’s annotations directly under its metadata
section. If you define pods indirectly with replication controllers, replica sets, or deployments, add pod annotations under .spec.template.metadata
.
Note: As a best practice in containerized environments, Datadog recommends using unified service tagging when assigning tags. Unified service tagging ties Datadog telemetry together through the use of three standard tags: env
, service
, and version
. To learn how to configure your environment with unified tagging, refer to the dedicated unified service tagging documentation.
Storing templates as local files and mounting them inside the containerized Agent doesn’t require an external service or a specific orchestration platform. The downside is that you need to restart your Agent containers each time you change, add, or remove templates. The Agent looks for Autodiscovery templates in the mounted /conf.d
directory.
Since Agent v6.2.0 (and v5.24.0), the default templates use the default port for the monitored software, instead of auto-detecting it. If you need to use a different port, provide a custom Autodiscovery template in the Kubernetes pod annotations.
These integration templates are meant for basic cases. If you need a custom Datadog integration configuration to enable extra options, use different container identifiers—or use template variables indexing and write your own auto-configuration file:
- Create a
conf.d/<INTEGRATION_NAME>.d/conf.yaml
file on your host and add your custom auto-configuration. - Mount your host
conf.d/
folder to the containerized Agent’s conf.d
folder.
Example auto-configuration file:
ad_identifiers:
<INTEGRATION_AUTODISCOVERY_IDENTIFIER>
init_config:
<INIT_CONFIG>
instances:
<INSTANCES_CONFIG>
See the Autodiscovery Container Identifiers documentation for information on the <INTEGRATION_AUTODISCOVERY_IDENTIFIER>
.
Note: You don’t need to set up the <INTEGRATIONS_NAME>
since the Agent infers it from the file name directly.
On Kubernetes, you can use ConfigMaps to externally define configurations and subsequently mount them using the manifest. Reference the template below and the Kubernetes Custom Integrations documentation.
kind: ConfigMap
apiVersion: v1
metadata:
name: "<NAME>-config-map"
namespace: default
data:
<INTEGRATION_NAME>-config: |-
ad_identifiers:
<INTEGRATION_AUTODISCOVERY_IDENTIFIER>
init_config:
<INIT_CONFIG>
instances:
<INSTANCES_CONFIG>
See the Autodiscovery Container Identifiers documentation for information on the <INTEGRATION_AUTODISCOVERY_IDENTIFIER>
.
Autodiscovery can use Consul, Etcd, and Zookeeper as integration template sources. To use a key-value store, configure it in the Agent datadog.yaml
configuration file and mount this file inside the containerized Agent. Alternatively, pass your key-value store as environment variables to the containerized Agent.
Configure in datadog.yaml:
In the datadog.yaml
file, set the <KEY_VALUE_STORE_IP>
address and <KEY_VALUE_STORE_PORT>
of your key-value store:
config_providers:
- name: etcd
polling: true
template_dir: /datadog/check_configs
template_url: '<KV_STORE_IP>:<KV_STORE_PORT>'
username:
password:
- name: consul
polling: true
template_dir: datadog/check_configs
template_url: '<KV_STORE_IP>:<KV_STORE_PORT>'
ca_file:
ca_path:
cert_file:
key_file:
username:
password:
token:
- name: zookeeper
polling: true
template_dir: /datadog/check_configs
template_url: '<KV_STORE_IP>:<KV_STORE_PORT>'
username:
password:
Then restart the Agent to apply the configuration change.
Configure in environment variables:
Note: As a best practice in containerized environments, Datadog recommends using unified service tagging when configuring tags and environment variables. Unified service tagging ties Datadog telemetry together through the use of three standard tags: env
, service
, and version
. To learn how to configure your environment with unified tagging, refer to the dedicated [unified service tagging][9] documentation.
With the key-value store enabled as a template source, the Agent looks for templates under the key /datadog/check_configs
. Autodiscovery expects a key-value hierarchy like this:
/datadog/
check_configs/
<CONTAINER_IDENTIFIER>/
- check_names: ["<INTEGRATION_NAME>"]
- init_configs: ["<INIT_CONFIG>"]
- instances: ["<INSTANCE_CONFIG>"]
...
Note: To apply a specific configuration to a given container, Autodiscovery identifies containers by image when using the key-value stores by trying to match <CONTAINER_IDENTIFIER>
to .spec.containers[0].image
.
The values.yaml
file contains a confd
section to define both static and Autodiscovery integration checks. You can find inline examples in the sample values.yaml. Each key becomes a file in the Agent’s conf.d
directory.
confd:
<INTEGRATION_NAME>.yaml: |-
ad_identifiers:
- <INTEGRATION_AUTODISCOVERY_IDENTIFIER>
init_config:
- <INIT_CONFIG>
instances:
- <INSTANCES_CONFIG>
See Autodiscovery Container Identifiers for information on the <INTEGRATION_AUTODISCOVERY_IDENTIFIER>
.
Note: The Helm chart has two confd
sections: one for Agent checks, and a second for cluster checks. If you are using the Cluster Agent and looking to configure Autodiscovery for a cluster check, follow the cluster check configuration example and make sure to include cluster_check: true
. See Cluster Check for more context.