Cluster Agent

Active contributors: Ahmed Mezghani, Olivier G, Adel Haj Hassan, David Ortiz, Charly Fontaine

Purpose

The Datadog Cluster Agent (DCA) is the Kubernetes-aware companion to the core Agent. It runs once per cluster and provides cluster-level functionality that does not belong on every node:

• External Metrics Provider — exposes Datadog queries as Kubernetes external metrics so HPA can autoscale on them.
• Admission controller — mutates pods and other resources at admission time to inject Agent integration metadata, traces SDKs, and security scanning.
• Cluster checks dispatching — distributes cluster-level checks (e.g., one Kubernetes API check) across node Agents instead of running them everywhere.
• Orchestrator data collection — captures Kubernetes resource manifests and events for the Container Monitoring product.
• Compliance and posture management — drives CSPM checks at the cluster level.

For non-Kubernetes deployments there is also cmd/cluster-agent-cloudfoundry/, the CloudFoundry flavor.

Directory layout

cmd/cluster-agent/
├── main.go
├── command/             # Root cobra command
├── subcommands/         # `run`, `status`, `version`, etc.
├── api/                 # Cluster Agent HTTP/gRPC API
├── admission/           # Admission controller webhook handlers
├── custommetrics/       # External Metrics Provider
└── klog.go              # klog redirection (Kubernetes libraries log via klog)

pkg/clusteragent/        # Most of the actual logic
├── api/
├── autoscaling/
├── clusterchecks/
├── languagedetection/
├── orchestrator/
└── ...

comp/                    # Component bundles consumed by the Cluster Agent
├── core/                # config, log, hostname, IPC
├── api/                 # API server
├── metadata/clusteragent/
├── metadata/clusterchecks/
└── autoscaling/

Subsystems

External Metrics Provider

cmd/cluster-agent/custommetrics/ and pkg/clusteragent/autoscaling/custommetrics/. Implements the external.metrics.k8s.io API, allowing Kubernetes HPA to query Datadog metrics through the cluster.

Admission controller

cmd/cluster-agent/admission/ and pkg/clusteragent/admission/. Registers as a Kubernetes mutating webhook. Mutations include:

• Auto-instrumentation injection (the Datadog tracing libraries get patched into pods that opt in).
• Tag injection.
• Compliance-related volume mounts.
• Trace agent socket injection.

Cluster checks dispatching

pkg/clusteragent/clusterchecks/. The DCA runs the cluster-side check scheduler. It assigns each cluster check to a registered Cluster Checks Runner (CLC), based on load. The CLC, in turn, is a slim core Agent flavor (see cmd/agent/subcommands/run/internal/clcrunnerapi/).

Orchestrator data collection

pkg/orchestrator/. Captures Kubernetes resource manifests (pods, deployments, statefulsets, etc.) on a schedule and ships them to Datadog for the orchestrator product. The corresponding forwarder is comp/forwarder/orchestrator/.

Language detection

pkg/clusteragent/languagedetection/ and comp/languagedetection/. Uses information from the process agent to identify which language a workload is written in, so the admission controller can inject the right tracer.

Subcommands

The Cluster Agent exposes a smaller subcommand set than the core Agent:

Subcommand	What it does
run (default)	Long-running daemon.
status	Status snapshot.
flare	Build a flare archive.
health	Health probe.
config	Read/write runtime config.
compliance	CSPM check helpers.
metamap	Namespace-to-tag mapping.

The full list lives in cmd/cluster-agent/subcommands/.

How it fits in

graph LR
    subgraph cluster[Kubernetes cluster]
        DCA[Cluster Agent]
        CLC[Cluster Checks Runner]
        NODES[Node Agents]
    end
    USERS[User pods] -. webhook .-> DCA
    DCA -. dispatches checks .-> CLC
    DCA -. external metrics API .-> HPA[HPA]
    DCA -- orchestrator payloads --> INTAKE[Datadog intake]
    NODES -- node metrics --> INTAKE
    CLC -- cluster check metrics --> INTAKE

The DCA is also the canonical source of cluster-level metadata for the node Agents to pick up via gRPC.

Key abstractions

Type / package	Location	Purpose
pkg/clusteragent/api	pkg/clusteragent/api/	HTTP API for node Agents to poll cluster state
pkg/clusteragent/clusterchecks	pkg/clusteragent/clusterchecks/	Cluster check dispatcher
pkg/clusteragent/admission	pkg/clusteragent/admission/	Admission webhook implementation
pkg/clusteragent/autoscaling	pkg/clusteragent/autoscaling/	External Metrics Provider plumbing
pkg/clusteragent/orchestrator	pkg/clusteragent/orchestrator/	Resource manifest collection
comp/metadata/clusteragent	comp/metadata/clusteragent/	DCA-specific metadata payloads

CloudFoundry variant

cmd/cluster-agent-cloudfoundry/ reuses the same component framework but with a smaller subset focused on the CloudFoundry BOSH director. It is much smaller in scope than the Kubernetes DCA and has its own subcommands/.

Entry points for modification

• Adding a new admission mutator: implement the mutator interface under pkg/clusteragent/admission/mutate/ and register it in the controller.
• Adding a new External Metrics Provider source: extend pkg/clusteragent/autoscaling/.
• Adding a new orchestrator resource type: extend pkg/orchestrator/ with a new collector and serializer.
• Adding a new subcommand: copy from cmd/cluster-agent/subcommands/ and register in subcommands.go.

Related pages

• Architecture
• Systems: Components framework
• Systems: Autodiscovery
• Features: Network monitoring — the DCA participates in some NPM cluster aggregation.