DEPRECATED This repository has moved

With upcoming deprecation of helm/charts repository, the Datadog Helm Charts repository has moved to: https://github.com/DataDog/helm-charts

You can use this new repository by doing:

helm repo add datadog https://helm.datadoghq.com
helm repo update

You can now use datadog/datadog instead of stable/datadog in all your Helm commands, e.g.:

# New installation
helm install --name <RELEASE_NAME> --set datadog.apiKey=<DATADOG_API_KEY> datadog/datadog
# Upgrade existing installation
helm upgrade --name <RELEASE_NAME> --set datadog.apiKey=<DATADOG_API_KEY> datadog/datadog

Datadog

Datadog is a hosted infrastructure monitoring platform. This chart adds the Datadog Agent to all nodes in your cluster via a DaemonSet. It also optionally depends on the kube-state-metrics chart. For more information about monitoring Kubernetes with Datadog, please refer to the Datadog documentation website.

Datadog offers two variants, switch to a -jmx tag if you need to run JMX/java integrations. The chart also supports running the standalone dogstatsd image.

See the Datadog JMX integration to learn more.

Prerequisites

Kubernetes 1.4+ or OpenShift 3.4+, note that:

• the Datadog Agent supports Kubernetes 1.4+
• The Datadog chart's defaults are tailored to Kubernetes 1.7.6+, see Datadog Agent legacy Kubernetes versions documentation for adjustments you might need to make for older versions

Quick start

By default, the Datadog Agent runs in a DaemonSet. It can alternatively run inside a Deployment for special use cases.

Note: simultaneous DaemonSet + Deployment installation within a single release will be deprecated in a future version, requiring two releases to achieve this.

Installing the Datadog Chart

To install the chart with the release name <RELEASE_NAME>, retrieve your Datadog API key from your Agent Installation Instructions and run:

helm install --name <RELEASE_NAME> \
  --set datadog.apiKey=<DATADOG_API_KEY> stable/datadog

By default, this Chart creates a Secret and puts an API key in that Secret. However, you can use manually created secret by setting the datadog.apiKeyExistingSecret value. After a few minutes, you should see hosts and metrics being reported in Datadog.

Create and provide a secret that contains your Datadog API Key

To create a secret that contains your Datadog API key, replace the <DATADOG_API_KEY> below with the API key for your organization. This secret is used in the manifest to deploy the Datadog Agent.

DATADOG_SECRET_NAME=datadog-secret
kubectl create secret generic $DATADOG_SECRET_NAME --from-literal api-key="<DATADOG_API_KEY>" --namespace="default"

Note: This creates a secret in the default namespace. If you are in a custom namespace, update the namespace parameter of the command before running it.

Now, the installation command contains the reference to the secret.

helm install --name <RELEASE_NAME> \
  --set datadog.apiKeyExistingSecret=$DATADOG_SECRET_NAME stable/datadog

Note: Provide a secret for the application key (AppKey) using the datadog.appKeyExistingSecret chart variable.

Enabling the Datadog Cluster Agent

Read about the Datadog Cluster Agent in the official documentation.

Run the following if you want to deploy the chart with the Datadog Cluster Agent:

helm install --name datadog-monitoring \
    --set datadog.apiKey=<DATADOG_API_KEY> \
    --set datadog.appKey=<DATADOG_APP_KEY> \
    --set clusterAgent.enabled=true \
    --set clusterAgent.metricsProvider.enabled=true \
    stable/datadog

Note: Specifying clusterAgent.metricsProvider.enabled=true enables the External Metrics Server. If you want to learn to use this feature, you can check out this Datadog Cluster Agent walkthrough.

The Leader Election is enabled by default in the chart for the Cluster Agent. Only the Cluster Agent(s) participate in the election, in case you have several replicas configured (using clusterAgent.replicas.

Cluster Agent Token

You can specify the Datadog Cluster Agent token used to secure the communication between the Cluster Agent(s) and the Agents with clusterAgent.token.

If you don't specify a token, a random one is generated at each deployment so you must use --recreate-pods to ensure all pod use the same token. seeDatadog Chart notes to learn more.

Upgrading

From 1.x to 2.x

⚠️ Migrating from 1.x to 2.x requires a manual action.

The datadog chart has been refactored to regroup the values.yaml parameters in a more logical way. Please follow the migration guide to update you values.yaml file.

From 1.19.0 onwards

Version 1.19.0 introduces the use of release name as full name if it contains the chart name(datadog in this case). E.g. with a release name of datadog, this renames the DaemonSet from datadog-datadog to datadog. The suggested approach is to delete the release and reinstall it.

From 1.0.0 onwards

Starting with version 1.0.0, this chart does not support deploying Agent 5.x anymore. If you cannot upgrade to Agent 6.x or later, you can use a previous version of the chart by calling helm install with --version 0.18.0.

See 0.18.1's README to see which options were supported at the time.

Uninstalling the Chart

To uninstall/delete the <RELEASE_NAME> deployment:

helm delete <RELEASE_NAME> --purge

The command removes all the Kubernetes components associated with the chart and deletes the release.

Configuration

As a best practice, a YAML file that specifies the values for the chart parameters should be provided to configure the chart:

1. Copy the default datadog-values.yaml value file.
2. Set the apiKey parameter with your Datadog API key.
3. Upgrade the Datadog Helm chart with the new datadog-values.yaml file:

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

See the All configuration options section to discover all possibilities offered by the Datadog chart.

Enabling Log Collection

Update your datadog-values.yaml file with the following log collection configuration:

datadog:
  # (...)
  logs:
    enabled: true
    containerCollectAll: true

then upgrade your Datadog Helm chart:

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

Enabling Process Collection

Update your datadog-values.yaml file with the process collection configuration:

datadog:
  # (...)
  processAgent:
    enabled: true
    processCollection: true

then upgrade your Datadog Helm chart:

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

Enabling System Probe Collection

The system-probe agent only runs in dedicated container environment. Update your datadog-values.yaml file with the system-probe collection configuration:

datadog:
  # (...)
  systemProbe:
    # (...)
    enabled: true

# (...)

then upgrade your Datadog Helm chart:

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

Kubernetes event collection

Use the Datadog Cluster Agent to collect Kubernetes events. Please read the official documentation for more context.

Alternatively set the datadog.leaderElection, datadog.collectEvents and rbac.create options to true in order to enable Kubernetes event collection.

conf.d and checks.d

The Datadog entrypoint copies files with a .yaml extension found in /conf.d and files with .py extension in /checks.d to /etc/datadog-agent/conf.d and /etc/datadog-agent/checks.d respectively.

The keys for datadog.confd and datadog.checksd should mirror the content found in their respective ConfigMaps. Update your datadog-values.yaml file with the check configurations:

datadog:
  confd:
    redisdb.yaml: |-
      ad_identifiers:
        - redis
        - bitnami/redis
      init_config:
      instances:
        - host: "%%host%%"
          port: "%%port%%"
    jmx.yaml: |-
      ad_identifiers:
        - openjdk
      instance_config:
      instances:
        - host: "%%host%%"
          port: "%%port_0%%"
    redisdb.yaml: |-
      init_config:
      instances:
        - host: "outside-k8s.example.com"
          port: 6379

then upgrade your Datadog Helm chart:

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

For more details, please refer to the documentation.

Kubernetes Labels and Annotations

To map Kubernetes node labels and pod labels and annotations to Datadog tags, provide a dictionary with kubernetes labels/annotations as keys and Datadog tags key as values in your datadog-values.yaml file:

nodeLabelsAsTags:
  beta.kubernetes.io/instance-type: aws_instance_type
  kubernetes.io/role: kube_role

podAnnotationsAsTags:
  iam.amazonaws.com/role: kube_iamrole

podLabelsAsTags:
  app: kube_app
  release: helm_release

then upgrade your Datadog Helm chart:

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

CRI integration

As of the version 6.6.0, the Datadog Agent supports collecting metrics from any container runtime interface used in your cluster. Configure the location path of the socket with datadog.criSocketPath; default is the Docker container runtime socket. To deactivate this support, you just need to unset the datadog.criSocketPath setting. Standard paths are:

• Docker socket: /var/run/docker.sock
• Containerd socket: /var/run/containerd/containerd.sock
• Cri-o socket: /var/run/crio/crio.sock

All configuration options

The following table lists the configurable parameters of the Datadog chart and their default values. Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

helm install --name <RELEASE_NAME> \
  --set datadog.apiKey=<DATADOG_API_KEY>,datadog.logLevel=DEBUG \
  stable/datadog

Configuration options for Windows deployments

Some options above are not working/not available on Windows, here is the list of unsupported options: