Cluster Agent Setup
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

Cluster Agent Setup

To set up the Datadog Cluster Agent on your Kubernetes cluster, follow these steps:

  1. Set up the Datadog Cluster Agent.
  2. Configure your Agent to communicate with the Datadog Cluster Agent

Configure the Datadog Cluster Agent

Step 1 - Configure RBAC permissions

The Datadog Cluster Agent needs a proper RBAC to be up and running:

  1. Review the manifests in the Datadog Cluster Agent RBAC folder. Note that when using the Cluster Agent, your node Agents are not able to interact with the Kubernetes API server—only the Cluster Agent is able to do so.

  2. To configure Cluster Agent RBAC permissions, apply the following manifests. (You may have done this already when setting up the node Agent daemonset.)

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

This creates the appropriate ServiceAccount, ClusterRole, and ClusterRoleBinding for the Cluster Agent and updates the ClusterRole for the node Agent.

If you are using Azure Kubernetes Service (AKS), you may require extra permissions. See the RBAC for DCA on AKS FAQ.

Step 2 - Secure Cluster-Agent-to-Agent Communication

Use one of the following options to secure communication between the Datadog Agent and the Datadog Cluster Agent.

  • Create a secret and access it with an environment variable.
  • Set a token in an environment variable.
  • Use a ConfigMap to manage your secrets.

Setting the value without a secret results in the token being readable in the PodSpec.

  1. Run the following command to create a secret token:

    echo -n '<ThirtyX2XcharactersXlongXtoken>' | base64
    
  2. Run this one line command:

    kubectl create secret generic datadog-cluster-agent --from-literal=token='<ThirtyX2XcharactersXlongXtoken>'
    

    Alternatively, modify the value of the secret in the agent-secret.yaml file located in the manifest/cluster-agent directory or create it with:

    kubectl create -f Dockerfiles/manifests/cluster-agent/agent-secret.yaml

  3. Refer to this secret with the environment variable DD_CLUSTER_AGENT_AUTH_TOKEN in the manifests of the Cluster Agent. See Step 3 - Create the Cluster Agent and its service) and Step 2 - Enable the Datadog Cluster Agent.

  1. Run the following command to create a secret token:

    echo -n '<ThirtyX2XcharactersXlongXtoken>' | base64
    
  2. Refer to this secret with the environment variable DD_CLUSTER_AGENT_AUTH_TOKEN in the manifests of the Cluster Agent and the node-based Agent.

              - name: DD_CLUSTER_AGENT_AUTH_TOKEN
                value: "<ThirtyX2XcharactersXlongXtoken>"
    
  1. Run the following command to create a secret token:

    echo -n '<ThirtyX2XcharactersXlongXtoken>' | base64
    
  2. Create your datadog-cluster.yaml with the variables of your choice within the datadog.yaml file and create the ConfigMap accordingly:

    kubectl create configmap dca-yaml --from-file datadog-cluster.yaml
    

Note: This needs to be set in the manifest of the Cluster Agent and the node agent.

Step 3 - Create the Cluster Agent and its service

  1. Download the following manifests:
  1. In the secrets.yaml manifest, replace PUT_YOUR_BASE64_ENCODED_API_KEY_HERE with your Datadog API key encoded in base64:

    echo -n '<Your API key>' | base64
    
  2. In the cluster-agent-deployment.yaml manifest, set the token from Step 2 - Secure Cluster-Agent-to-Agent Communication. The format depends on how you set up your secret; instructions can be found in the manifest directly.

  3. Run: kubectl apply -f agent-services.yaml

  4. Run: kubectl apply -f secrets.yaml

  5. Run: kubectl apply -f install_info-configmap.yaml

  6. Finally, deploy the Datadog Cluster Agent: kubectl apply -f cluster-agent-deployment.yaml

Step 4 - Verification

At this point, you should see:

-> kubectl get deploy

NAME                    DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
datadog-cluster-agent   1         1         1            1           1d

-> kubectl get secret

NAME                         TYPE                                  DATA      AGE
datadog-agent-cluster-agent  Opaque                                1         1d

-> kubectl get pods -l app=datadog-cluster-agent

datadog-cluster-agent-8568545574-x9tc9   1/1       Running   0          2h

-> kubectl get service -l app=datadog-cluster-agent

NAME                    TYPE           CLUSTER-IP       EXTERNAL-IP        PORT(S)          AGE
datadog-cluster-agent   ClusterIP      10.100.202.234   none               5005/TCP         1d

Note: If you already have the Datadog Agent running, you may need to apply the agent-rbac.yaml manifest before the Cluster Agent can start running.

Configure the Datadog Agent

After having set up the Datadog Cluster Agent, configure your Datadog Agent to communicate with the Datadog Cluster Agent.

Setup

Step 1 - Set Configure RBAC permissions for node-based Agents

  1. Download the the agent-rbac.yaml manifest. Note: When using the Cluster Agent, your node Agents are not able to interact with the Kubernetes API server—only the Cluster Agent is able to do so.

  2. Run: kubectl apply -f agent-rbac.yaml

Step 2 - Enable the Datadog Agent

  1. Download the daemonset.yaml manifest.

  2. In the daemonset.yaml manifest, replace <DD_SITE> with the Datadog site you are using, i.e. datadoghq.com or datadoghq.eu. This value defaults to datadoghq.com.

  3. In the daemonset.yaml manifest, set the token from Step 2 - Secure Cluster-Agent-to-Agent Communication. The format depends on how you set up your secret; instructions can be found in the manifest directly.

  4. In the daemonset.yaml manifest, check that the environment variable DD_CLUSTER_AGENT_ENABLED is set to true.

  5. (Optional) If your cluster encompasses a single environment, you can also set <DD_ENV> in the agent.yaml.

  6. Create the DaemonSet with this command: kubectl apply -f daemonset.yaml

Verification

Run:

kubectl get pods | grep agent

You should see:

datadog-agent-4k9cd                      1/1       Running   0          2h
datadog-agent-4v884                      1/1       Running   0          2h
datadog-agent-9d5bl                      1/1       Running   0          2h
datadog-agent-dtlkg                      1/1       Running   0          2h
datadog-agent-jllww                      1/1       Running   0          2h
datadog-agent-rdgwz                      1/1       Running   0          2h
datadog-agent-x5wk5                      1/1       Running   0          2h
[...]
datadog-cluster-agent-8568545574-x9tc9   1/1       Running   0          2h

Kubernetes events are beginning to flow into your Datadog account, and relevant metrics collected by your Agents are tagged with their corresponding cluster level metadata.

Further Reading