Kubernetes

To install the chart with a custom release name, <RELEASE_NAME> (e.g. 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 via 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:

• For a full list of the Datadog chart’s configurable parameters and their default values, refer to the Datadog Helm repository README.

• If Google Container Registry (gcr.io/datadoghq) is not accessible in your deployment region, use the Docker Hub registry with the images datadog/agent and datadog/cluster-agent with the following configuration in the values.yaml file:

  agents:
    image:
      repository: datadog/agent
  
  clusterAgent:
    image:
      repository: datadog/cluster-agent
  
  clusterChecksRunner:
    image:
      repository: datadog/agent
  

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.

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.

Take advantage of DaemonSets to deploy the Datadog Agent on all your nodes (or on specific nodes by using nodeSelectors).

To install the Datadog Agent on your Kubernetes cluster:

1. Configure Agent permissions: If your Kubernetes has role-based access control (RBAC) enabled, configure RBAC permissions for your Datadog Agent service account. From Kubernetes 1.6 onwards, RBAC is enabled by default. Create the appropriate ClusterRole, ServiceAccount, and ClusterRoleBinding with the following command:

   kubectl apply -f "https://raw.githubusercontent.com/DataDog/datadog-agent/master/Dockerfiles/manifests/rbac/clusterrole.yaml"
   
   kubectl apply -f "https://raw.githubusercontent.com/DataDog/datadog-agent/master/Dockerfiles/manifests/rbac/serviceaccount.yaml"
   
   kubectl apply -f "https://raw.githubusercontent.com/DataDog/datadog-agent/master/Dockerfiles/manifests/rbac/clusterrolebinding.yaml"
   

   Note: Those RBAC configurations are set for the default namespace by default. If you are in a custom namespace, update the namespace parameter before applying them.

2. 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.

   kubectl create secret generic datadog-agent --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.

3. Create the Datadog Agent manifest. Create the datadog-agent.yaml manifest out of one of the following templates:

   Metrics	Logs	APM	Process	NPM	Linux	Windows
   					Manifest template	Manifest template
   					Manifest template	Manifest template
   					Manifest template	Manifest template
   					Manifest template	Manifest template
   					Manifest template	no template
   					Manifest template	Manifest template

   To enable trace collection completely, extra steps are required on your application Pod configuration. Refer also to the logs, APM, processes, and Network Performance Monitoring documentation pages to learn how to enable each feature individually.

   Note: Those manifests are set for the default namespace by default. If you are in a custom namespace, update the metadata.namespace parameter before applying them.

4. Set your Datadog site to using the DD_SITE environment variable in the datadog-agent.yaml manifest.

   Note: If the DD_SITE environment variable is not explicitly set, it defaults to the US site datadog.com. If you are using one of the other sites (EU, US3, or US1-FED) this will result in an invalid API key message. Use the documentation site selector to see documentation appropriate for the site you’re using.

5. Deploy the DaemonSet with the command:

   kubectl apply -f datadog-agent.yaml
   

6. Verification: To verify the Datadog Agent is running in your environment as a DaemonSet, execute:

   kubectl get daemonset
   

   If the Agent is deployed, you will see output similar to the text below, where DESIRED and CURRENT are equal to the number of nodes running in your cluster.

   NAME            DESIRED   CURRENT   READY     UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
   datadog-agent   2         2         2         2            2           <none>          10s
   

7. Optional - Setup Kubernetes State metrics: Download the Kube-State manifests folder and apply them to your Kubernetes cluster to automatically collects kube-state metrics:

   kubectl apply -f <NAME_OF_THE_KUBE_STATE_MANIFESTS_FOLDER>
   

Unprivileged

(Optional) To run an unprivileged installation, add the following to your pod template:

  spec:
    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.

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.14.X: Tests were done on versions >= 1.14.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:

   apiVersion: datadoghq.com/v1alpha1
   kind: DatadogAgent
   metadata:
     name: datadog
   spec:
     credentials:
       apiSecret:
         secretName: datadog-secret
         keyName: api-key
       appSecret:
         secretName: datadog-secret
         keyName: app-key
     agent:
       image:
         name: "gcr.io/datadoghq/agent:latest"
     clusterAgent:
       image:
         name: "gcr.io/datadoghq/cluster-agent:latest"
   

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.

Set the datadog.leaderElection, datadog.collectEvents and agents.rbac.create options to true in your value.yaml file in order to enable Kubernetes event collection.

If you want to collect events from your Kubernetes cluster set the environment variables DD_COLLECT_KUBERNETES_EVENTS and DD_LEADER_ELECTION to true in your Agent manifest. Alternatively, use the Datadog Cluster Agent Event collection

Set agent.config.collectEvents to true in your datadog-agent.yaml manifest.

For example:

agent:
  config:
    collectEvents: true