Install the Datadog Agent on Kubernetes
Installation
This page provides instructions on installing the Datadog Agent in a Kubernetes environment through three different methods. The following methods are supported:
- Datadog Operator
- Helm chart
- 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 Agent and Cluster Agent versions
Some features related to later Kubernetes versions require a minimum Datadog Agent version.
Kubernetes version | Agent version | Cluster Agent version | Reason |
---|
1.16.0+ | 7.19.0+ | 1.9.0+ | Kubelet metrics deprecation |
1.21.0+ | 7.36.0+ | 1.20.0+ | Kubernetes resource deprecation |
The Datadog Operator is in public beta. If you have any feedback or questions, contact
Datadog support.
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:
Install the Datadog Operator:
helm repo add datadog https://helm.datadoghq.com
helm install my-datadog-operator datadog/datadog-operator
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
Create a file with the spec of your Datadog Agent deployment configuration. The simplest configuration is as follows:
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"
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
):
- Install Helm.
- 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. - If this is a fresh install, add the Helm Datadog repo:
helm repo add datadog https://helm.datadoghq.com
helm repo update
- Retrieve your Datadog API key from your Agent installation instructions and run:
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
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.
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:
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. If you are in a custom namespace, update the namespace
parameter before applying them.
Create the Datadog Agent manifest. Create the datadog-agent.yaml
manifest out of one of the following templates:
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, and Security documentation pages to learn how to enable each feature individually.
Note: Those manifests are set for the default
namespace. If you are in a custom namespace, update the metadata.namespace
parameter before applying them.
In the secret-api-key.yaml
manifest, replace PUT_YOUR_BASE64_ENCODED_API_KEY_HERE
with your Datadog API key encoded in base64. To get the base64 version of your API key, you can run:
echo -n '<Your API key>' | base64
In the secret-cluster-agent-token.yaml
manifest, replace PUT_A_BASE64_ENCODED_RANDOM_STRING_HERE
with a random string encoded in base64. To get the base64 version of it, you can run:
echo -n 'Random string' | base64
Note: The random string must contain at least 32 alphanumeric characters to secure Cluster Agent to Agent communication.
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 datadoghq.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.
Deploy the DaemonSet with the command:
kubectl apply -f datadog-agent.yaml
Verification: To verify the Datadog Agent is running in your environment as a DaemonSet, execute:
If the Agent is deployed, output similar to the text below appears, 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
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.
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.