Install the Datadog Agent on Kubernetes

Docs > Container Monitoring > Kubernetes > Install the Datadog Agent on Kubernetes

Overview

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

Installation

Use the Installing on Kubernetes page in Datadog to guide you through the installation process.

Select installation method
Choose one of the following installation methods:
- Datadog Operator (recommended): a Kubernetes operator that you can use 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.
- Helm
- Manual installation. See Manually install and configure the Datadog Agent with a DaemonSet

Requires Helm and the kubectl CLI.

Install the Datadog Operator

To install the Datadog Operator in your current namespace, run:

helm repo add datadog https://helm.datadoghq.com
helm install datadog-operator datadog/datadog-operator
kubectl create secret generic datadog-secret --from-literal api-key=<DATADOG_API_KEY>

Replace <DATADOG_API_KEY> with your Datadog API key.

Configure datadog-agent.yaml

Create a file, datadog-agent.yaml, that contains:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    clusterName: <CLUSTER_NAME>
    site: <DATADOG_SITE>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key

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

Deploy Agent with the above configuration file
Run:
```
kubectl apply -f datadog-agent.yaml
```

Requires Helm.

Add the Datadog Helm repository

Run:

helm repo add datadog https://helm.datadoghq.com
helm repo update
kubectl create secret generic datadog-secret --from-literal api-key=<DATADOG_API_KEY>

Replace <DATADOG_API_KEY> with your Datadog API key.

Configure datadog-values.yaml
Create a file, datadog-values.yaml, that contains:
```
datadog:
 apiKeyExistingSecret: datadog-secret
 clusterName: <CLUSTER_NAME>
 site: <DATADOG_SITE>
```
- Replace <CLUSTER_NAME> with a name for your cluster.
- Replace <DATADOG_SITE> with your Datadog site. Your site is . (Ensure the correct SITE is selected on the right).
Deploy Agent with the above configuration file
Run:
```
helm install datadog-agent -f datadog-values.yaml datadog/datadog
```
For Windows, append --set targetSystem=windows to the helm install command.

Confirm Agent installation
Verify that Agent pods (tagged with app.kubernetes.io/component:agent) appear on the Containers page in Datadog. Agent pods are detected within a few minutes of deployment.

<CLUSTER_NAME> allows you to scope hosts and Cluster Checks. This unique name must be dot-separated tokens and abide by the following restrictions:

Must only contain lowercase letters, numbers, and hyphens
Must start with a letter
Must end with a number or a letter
Must be less than or equal to 80 characters

Unprivileged installation

To run an unprivileged installation, add the following to datadog-agent.yaml:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    clusterName: <CLUSTER_NAME>
    site: <DATADOG_SITE>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key
agent:
  config:
    securityContext:
      runAsUser: <USER_ID>
      supplementalGroups:
        - <GROUP_ID>

Replace <USER_ID> with the UID to run the Datadog Agent. Datadog recommends setting this value to 100 since Datadog Agent v7.48+.
Replace <GROUP_ID> with the group ID that owns the Docker or containerd socket.

Then, deploy the Agent:

kubectl apply -f datadog-agent.yaml

To run an unprivileged installation, add the following to your datadog-values.yaml file:

datadog:
  apiKeyExistingSecret: datadog-secret
  site: <DATADOG_SITE>
  securityContext:
      runAsUser: <USER_ID>
      supplementalGroups:
        - <GROUP_ID>

Replace <USER_ID> with the UID to run the Datadog Agent.
Replace <GROUP_ID> with the group ID that owns the Docker or containerd socket.

Then, deploy the Agent:

helm install datadog-agent -f datadog-values.yaml datadog/datadog

Container registries

Datadog publishes container images to Google Artifact Registry, Amazon ECR, Azure ACR, and Docker Hub:

Google Artifact Registry	Amazon ECR	Azure ACR	Docker Hub
gcr.io/datadoghq	public.ecr.aws/datadog	datadoghq.azurecr.io	docker.io/datadog

By default, the Agent image is pulled from Google Artifact Registry (gcr.io/datadoghq). If Artifact Registry is not accessible in your deployment region, use another registry.

If you are deploying the Agent in an AWS environment, Datadog recommend that you use Amazon ECR.

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 Google Artifact Registry or Amazon ECR. For instructions, see Changing your container registry.

To use a different container registry, modify global.registry in datadog-agent.yaml.

For example, to use Amazon ECR:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    clusterName: <CLUSTER_NAME>
    registry: public.ecr.aws/datadog
    site: <DATADOG_SITE>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key

To use a different container registry, modify registry in datadog-values.yaml.

For example, to use Amazon ECR:

registry: public.ecr.aws/datadog
datadog:
  apiKeyExistingSecret: datadog-secret
  site: <DATADOG_SITE>

For more information, see Changing your container registry.

Uninstall

kubectl delete datadogagent datadog
helm delete datadog-operator

This command deletes all Kubernetes resources created by installing Datadog Operator and deploying the Datadog Agent.

helm uninstall datadog-agent

Next steps

Monitor your infrastructure in Datadog

Use the Containers page for visibility into your container infrastructure, with resource metrics and faceted search. For information on how to use the Containers page, see Containers View.

Use the Container Images page for insights into every image used in your environment. This page also displays vulnerabilities found in your container images from Cloud Security. For information on how to use the Container Images page, see the Containers Images View.

The Kubernetes section features an overview of all your Kubernetes resources. Orchestrator Explorer allows you to monitor the state of pods, deployments, and other Kubernetes concepts in a specific namespace or availability zone, view resource specifications for failed pods within a deployment, correlate node activity with related logs, and more. The Resource Utilization page provides insights into how your Kubernetes workloads are using your computing resources across your infrastructure. For information on how to use these pages, see Orchestrator Explorer and Kubernetes Resource Utilization.