Install the Datadog Agent on Kubernetes

Installation

This page provides instructions on installing the Datadog Agent in a Kubernetes environment. For dedicated documentation and examples for major Kubernetes distributions including AWS Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), Red Hat OpenShift, Rancher, and Oracle Container Engine for Kubernetes (OKE), see Kubernetes distributions.

For dedicated documentation and examples for monitoring the Kubernetes control plane, see Kubernetes control plane monitoring.

Minimum Agent and Cluster Agent versions

Some features related to later Kubernetes versions require a minimum Datadog Agent version.

Kubernetes versionAgent versionCluster Agent versionReason
1.16.0+7.19.0+1.9.0+Kubelet metrics deprecation
1.21.0+7.36.0+1.20.0+Kubernetes resource deprecation
1.22.0+7.37.0+7.37.0+Support dynamic service account token
The Datadog Operator is Generally Available with the 1.0.0 version, and it reconciles the version v2alpha1 of the DatadogAgent Custom Resource.

The Datadog Operator is a way to deploy the Datadog Agent on Kubernetes and OpenShift. It reports deployment status, health, and errors in its Custom Resource status, and it limits the risk of misconfiguration thanks to higher-level configuration options.

Prerequisites

Using the Datadog Operator requires the following prerequisites:

  • Kubernetes Cluster version >= v1.20.X: Tests were done on versions >= 1.20.0. Still, it should work on versions >= v1.11.0. For earlier versions, because of limited CRD support, the Operator may not work as expected.
  • Helm for deploying the datadog-operator.
  • Kubectl CLI for installing the datadog-agent.

Deploy an Agent with the Operator

To deploy the Datadog Agent with the operator in the minimum number of steps, see the datadog-operator Helm chart. Here are the steps:

  1. Install the Datadog Operator:

    helm repo add datadog https://helm.datadoghq.com
    helm install my-datadog-operator datadog/datadog-operator
    
  2. Create a Kubernetes secret with your API and app keys

    kubectl create secret generic datadog-secret --from-literal api-key=<DATADOG_API_KEY> --from-literal app-key=<DATADOG_APP_KEY>
    

    Replace <DATADOG_API_KEY> and <DATADOG_APP_KEY> with your Datadog API and application keys

  3. Create a file with the spec of your Datadog Agent deployment configuration. The simplest configuration is as follows:

    kind: DatadogAgent
    apiVersion: datadoghq.com/v2alpha1
    metadata:
      name: datadog
    spec:
      global:
        site: <DATADOG_SITE>
        credentials:
          apiSecret:
            secretName: datadog-secret
            keyName: api-key
          appSecret:
            secretName: datadog-secret
            keyName: app-key
      override:
        clusterAgent:
          image:
            name: gcr.io/datadoghq/cluster-agent:latest
        nodeAgent:
          image:
            name: gcr.io/datadoghq/agent:latest
    

    Replace <DATADOG_SITE> with your Datadog site. Your site is . (Ensure the correct SITE is selected on the right).

  4. Deploy the Datadog Agent with the above configuration file:

    kubectl apply -f /path/to/your/datadog-agent.yaml
    

Cleanup

The following command deletes all the Kubernetes resources created by the above instructions:

kubectl delete datadogagent datadog
helm delete my-datadog-operator

For further details on setting up Operator, including information about using tolerations, refer to the Datadog Operator advanced setup guide.

Unprivileged

(Optional) To run an unprivileged installation, add the following to the Datadog custom resource (CR):

agent:
  config:
    securityContext:
      runAsUser: <USER_ID>
      supplementalGroups:
        - <DOCKER_GROUP_ID>

where <USER_ID> is the UID to run the agent and <DOCKER_GROUP_ID> is the group ID owning the Docker or containerd socket.

Container registries

To modify the container image registry, see the Changing Container Registry guide.

To install the chart with a custom release name, <RELEASE_NAME> (for example, datadog-agent):

  1. Install Helm.
  2. Using the Datadog values.yaml configuration file as a reference, create your values.yaml. Datadog recommends that your values.yaml only contain values that need to be overridden, as it allows a smooth experience when upgrading chart versions.
  3. If this is a fresh install, add the Helm Datadog repo:
    helm repo add datadog https://helm.datadoghq.com
    helm repo update
    
  4. Retrieve your Datadog API key from your Agent installation instructions and run:
  • Helm v3+

    helm install <RELEASE_NAME> -f values.yaml  --set datadog.apiKey=<DATADOG_API_KEY> datadog/datadog --set targetSystem=<TARGET_SYSTEM>
    

    Replace <TARGET_SYSTEM> with the name of your OS: linux or windows.

  • Helm v1/v2

    helm install -f values.yaml --name <RELEASE_NAME> --set datadog.apiKey=<DATADOG_API_KEY> datadog/datadog
    

This chart adds the Datadog Agent to all nodes in your cluster with a DaemonSet. It also optionally deploys the kube-state-metrics chart and uses it as an additional source of metrics about the cluster. A few minutes after installation, Datadog begins to report hosts and metrics.

Next, enable the Datadog features that you’d like to use: APM, Logs

Notes:

Container registries

On July 10 2023, Docker Hub will start enforcing download rate limits to Datadog's Docker Hub registries. Image pulls from these registries count against your rate limit quota.

Datadog recommends that you update your Datadog Agent and Cluster Agent configuration to pull from other registries where no rate limits apply. For instructions, see Changing your container registry.

If Google Container Registry (gcr.io/datadoghq) is not accessible in your deployment region, use another registry with the following configuration in the values.yaml file:

  • For the public AWS ECR registry (public.ecr.aws/datadog), use the following:

    registry: public.ecr.aws/datadog
    
  • For the Docker Hub registry (docker.io/datadog), use the following:

    registry: docker.io/datadog
    

Note:

  • It is recommended to use the public AWS ECR registry (public.ecr.aws/datadog) when the Datadog chart is deployed in an AWS environment.

Upgrading from chart v1.x

The Datadog chart has been refactored in v2.0 to regroup the values.yaml parameters in a more logical way.

If your current chart version deployed is earlier than v2.0.0, follow the migration guide to map your previous settings with the new fields.

Kube state metrics core in chart v2.x

In new deployments, Datadog recommends using the newer kube-state-metrics core with the following values:

...
datadog:
...
  kubeStateMetricsCore:
    enabled: true
...

For details about kube-state-metrics core, read the Kubernetes State Metrics Core documentation.

Unprivileged

(Optional) To run an unprivileged installation, add the following in the values.yaml file:

datadog:
  securityContext:
      runAsUser: <USER_ID>
      supplementalGroups:
        - <DOCKER_GROUP_ID>

where <USER_ID> is the UID to run the agent and <DOCKER_GROUP_ID> is the group ID owning the docker or containerd socket.

Next steps

To configure Live Containers, see Live Containers.

To collect events, override proxy settings, send custom metrics with DogStatsD, configure container allowlists and blocklists, or reference the full list of available environment variables, see Configure the Datadog Agent on Kubernetes.

To configure integrations, see Integrations & Autodiscovery.

To set up APM, see Kubernetes Trace Collection.

To set up log collection, see Kubernetes Log Collection.