Install the Datadog Agent on Kubernetes

Overview

This page provides instructions on installing the Datadog Agent in a Kubernetes environment. By default, the Datadog Agent runs in a DaemonSet.

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 Kubernetes and Datadog Agent versions

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

Kubernetes versionAgent versionReason
1.16.0+7.19.0+Kubelet metrics deprecation
1.21.0+7.36.0+Kubernetes resource deprecation
1.22.0+7.37.0+Support dynamic service account token

See also: Minimum Kubernetes and Cluster Agent versions.

Installation

You have the following options for installing the Datadog Agent on Kubernetes:

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 v1.20.0+; should be supported in 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

  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, datadog-agent.yaml, 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
    

Prerequisites

  • Helm
  • If this is a fresh install, add the Helm Datadog repo:
    helm repo add datadog https://helm.datadoghq.com
    helm repo update
    

Install the chart

  1. Create an empty datadog-values.yaml file. Any parameters not specified in this file default to those set in values.yaml.

  2. Create a Kubernetes Secret to store your Datadog API key and app key:

    kubectl create secret generic datadog-secret --from-literal api-key=$DD_API_KEY --from-literal app-key=$DD_APP_KEY
    
  3. Set the following parameters in your datadog-values.yaml to reference the secret:

    datadog:
     apiKeyExistingSecret: datadog-secret
     appKeyExistingSecret: datadog-secret
     site: <DATADOG_SITE>
    

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

  4. Run the following command:

    helm install <RELEASE_NAME> \
     -f datadog-values.yaml \
     --set targetSystem=<TARGET_SYSTEM> \
     datadog/datadog
    
  • <RELEASE_NAME>: Your release name. For example, datadog-agent.

  • <TARGET_SYSTEM>: The name of your OS. For example, linux or windows.

Note: If you are using Helm 2.x, run the following:

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

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 Datadog Operator, including information about using tolerations, refer to the Datadog Operator advanced setup guide.

To uninstall/delete the <RELEASE_NAME> deployment:

helm uninstall <RELEASE_NAME>

Unprivileged

(Optional) To run an unprivileged installation:

Add the following to the Datadog custom resource (CR) in your datadog-agent.yaml:

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

Add the following in your datadog-values.yaml file:

datadog:
  securityContext:
      runAsUser: <USER_ID>
      supplementalGroups:
        - <DOCKER_GROUP_ID>
  • <USER_ID> is the UID to run the Agent.
  • <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.

Docker Hub is subject to image pull rate limits. If you are not a Docker Hub customer, Datadog recommends that you update your Datadog Agent and Cluster Agent configuration to pull from GCR or ECR. 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 Amazon 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 Amazon ECR registry (public.ecr.aws/datadog) when the Datadog chart is deployed in an AWS environment.

Next steps

Further Reading