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 version | Agent version | Reason |
---|
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
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, 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).
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
Create an empty datadog-values.yaml
file. Any parameters not specified in this file default to those set in values.yaml
.
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
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).
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
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
Additional helpful documentation, links, and articles: