Index of every page on this site: llms.txt
All skills
datadog-labs avatar

/dd-agent-install-kubernetes

@618fae3 official
Run it yourself

Install the Datadog Agent on a Kubernetes cluster - Amazon EKS (standard or Fargate profiles), Azure AKS, Google GKE (standard or Autopilot), OpenShift, Oracle OKE, VMware Tanzu (TKG), Rancher (RKE2/K3s), or self-managed - through the Datadog Operator (kubectl/Helm), the Datadog Helm chart, or Terraform, with metrics, logs, and APM trace intake on by default, Single Step Instrumentation off unless the user asks, and optional products; for an SSI-first install use `dd-apm/k8s-ssi` `agent-install`. Use when the user is running a Kubernetes cluster on GKE, EKS, AKS, OpenShift, OKE, or TKG, asks to install or set up the Datadog Agent on Kubernetes, wants to install the Agent with Terraform, or wants to monitor their Kubernetes pods. Does not connect a cloud provider integration or install the Agent on standalone hosts or plain Docker. Requires a Datadog account with a valid API key and application key; run `dd-account-setup` first if they are missing.

Use this Skill: https://skilld.dev/gh/datadog-labs/agent-skills/dd-agent-install-kubernetes

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesterraform.md

≈2.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Terraform Install (IaC path)

Use this when the user manages the cluster (or their infra) with Terraform. Installing imperatively with helm/kubectl into a Terraform-managed setup leaves the Datadog install as drift that the next terraform plan won't know about; put it in their IaC instead. Add these resources to the user's existing Terraform project rather than creating a standalone one.

The API key never goes into Terraform. sensitive = true only redacts CLI output - the value still lands plaintext in terraform.tfstate. Create the Secret out-of-band with the same kubectl heredoc from SKILL.md Phase 3 and reference it by name from the CR.

Providers

The helm and kubernetes providers authenticate from the kubeconfig you connected in Phase 1. The example below is for new configurations using Helm provider v3 syntax. In an existing project, respect its lock file and provider major version; do not silently upgrade a v2 configuration while adding the Datadog resources. A module can have only one required_providers block: if the project already declares one (often in versions.tf), add the helm and kubernetes entries to it instead of writing a second terraform block.

terraform {
  required_providers {
    helm = {
      source  = "hashicorp/helm"
      version = "~> 3.0"
    }
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 3.0"
    }
  }
}

provider "helm" {
  kubernetes = {
    config_path    = "~/.kube/config"
    config_context = "<KUBE_CONTEXT>"
  }
}

provider "kubernetes" {
  config_path    = "~/.kube/config"
  config_context = "<KUBE_CONTEXT>"
}

If the cluster itself is Terraform-managed, wire the providers to the cluster resource/data source (aws_eks_cluster + aws_eks_cluster_auth, google_container_cluster + google_client_config, azurerm_kubernetes_cluster.kube_config) instead of a static kubeconfig.

Operator (datadog.tf)

resource "helm_release" "datadog_operator" {
  name             = "datadog-operator"
  repository       = "https://helm.datadoghq.com"
  chart            = "datadog-operator"
  version          = "<OPERATOR_CHART_VERSION>"
  namespace        = "datadog"
  create_namespace = true
}

Pin version (resolve via helm search repo datadog/datadog-operator --versions) for the same reproducibility reason as the imperative install.

For a private mirror, add values = [file("${path.module}/datadog-operator-values.yaml")] to the release and use the Operator image and pull-secret values from Private registries in references/advanced.md. Create the datadog namespace and its pull secret through the user's approved secret-management workflow before terraform apply; otherwise the Operator pod cannot pull its own image. Do not put registry credentials in Terraform state.

For GKE Autopilot, the Operator helm_release above works on Operator 1.27+ - apply the CR with the experimental.agent.datadoghq.com/autopilot annotation and the Autopilot resource requests from the Operator path in references/distributions.md.

Use this resource only when SKILL.md Phase 2 selected the Operator. When it selected the Helm chart (the user asked for Helm, cannot install CRDs, or runs GKE Autopilot on an older Operator), the Operator chart would try to install CRDs; replace this resource with a helm_release for chart datadog and follow Direct chart release at the end of this file instead of the CR and sequenced apply below.

DatadogAgent CR

The DatadogAgent is a CRD the Operator installs, so kubernetes_manifest can't plan it until that CRD exists (it validates against the API server at plan time). Two reliable options:

  • Recommended: keep the CR as datadog-agent.yaml (the SKILL.md Phase 3 baseline plus whatever distribution / product blocks apply) and kubectl apply it after terraform apply. This mirrors the Phase 3 flow and sidesteps the plan-time CRD dependency.
  • All-Terraform: manage the CR with kubernetes_manifest, but split the apply (terraform apply -target=helm_release.datadog_operator first, then a full terraform apply) so the CRD is registered before the manifest is planned.

Sequenced apply

terraform init
terraform plan -out=tfplan

Show the plan to the user; apply that saved file after they've reviewed it, since a bare terraform apply re-plans and could differ from what they approved. Stop if the plan fails. Apply the Operator first, then seed the Secret (kept out of state), then the CR. When the CR includes the EKS Fargate distribution block it references spec.global.clusterAgentTokenSecret, so the Secret must also carry a token key. Set EKS_FARGATE='true' in the block below in that case; the block then resolves the token in the same shell as in references/distributions.md (from .env.local / .env, else the existing datadog-secret, else openssl rand -hex 16), writes the Secret to datadog and to every namespace in WORKLOAD_NAMESPACES (injected sidecars read it from their own namespace), and stops before terraform apply if no usable token is available or the existing Secret cannot be read. It also stops before the CR if the Secret apply fails. Leave it 'false' for non-Fargate installs.

For a private Operator image, create the namespace and registry pull secret before the terraform apply shown below. The API-key Secret remains after the Operator apply so it cannot be captured in Terraform state.

for f in .env.local .env; do [ -f "$f" ] || continue; for k in DD_SITE DD_API_KEY DD_APP_KEY DD_CLUSTER_AGENT_TOKEN; do eval "[ -n \"\${$k:-}\" ]" && continue; v=$(grep -E "^$k=" "$f" | head -1 | cut -d= -f2- | tr -d '\r' | sed 's/^["'\'']//;s/["'\'']$//'); [ -n "$v" ] && export "$k=$v"; done; done
: "${DD_API_KEY:?not set - run dd-account-setup (commercial sites) or supply it directly (government sites)}"
EKS_FARGATE='false'   # <- 'true' when datadog-agent.yaml includes the EKS Fargate block.
WORKLOAD_NAMESPACES=''   # <- with EKS_FARGATE='true', the space-separated Fargate workload namespaces.
TOKEN_LINE=''
if [ "$EKS_FARGATE" = true ]; then
  [ -n "$WORKLOAD_NAMESPACES" ] || { echo "Set WORKLOAD_NAMESPACES to the Fargate workload namespaces - stop"; exit 1; }
  if [ -z "${DD_CLUSTER_AGENT_TOKEN:-}" ]; then
    EXISTING_TOKEN=$(kubectl get secret datadog-secret -n datadog --ignore-not-found -o jsonpath='{.data.token}') || { echo "Could not read datadog-secret - fix cluster access and re-run"; exit 1; }
    if [ -n "$EXISTING_TOKEN" ]; then
      DD_CLUSTER_AGENT_TOKEN=$(printf '%s' "$EXISTING_TOKEN" | base64 --decode) || { echo "Could not decode the token in datadog-secret"; exit 1; }
    else
      DD_CLUSTER_AGENT_TOKEN=$(openssl rand -hex 16 2>/dev/null)
    fi
  fi
  case "${DD_CLUSTER_AGENT_TOKEN:-}" in ''|*[!A-Za-z0-9]*) echo "No usable cluster agent token - add DD_CLUSTER_AGENT_TOKEN to .env.local and re-run"; exit 1;; esac
  [ "${#DD_CLUSTER_AGENT_TOKEN}" -ge 32 ] || { echo "DD_CLUSTER_AGENT_TOKEN must be at least 32 characters"; exit 1; }
  TOKEN_LINE="  token: \"${DD_CLUSTER_AGENT_TOKEN}\""
fi
trap 'rm -f tfplan' EXIT HUP INT TERM
if ! terraform apply tfplan; then
  echo "terraform apply FAILED - do NOT create the Secret or the CR"
  exit 1
fi
for ns in datadog $WORKLOAD_NAMESPACES; do
  if ! kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: datadog-secret
  namespace: ${ns}
type: Opaque
stringData:
  api-key: "${DD_API_KEY}"
${TOKEN_LINE}
EOF
  then
    echo "Secret creation FAILED in $ns - do NOT apply datadog-agent.yaml"
    exit 1
  fi
done
kubectl apply -f datadog-agent.yaml

Direct chart release (Helm method)

This path installs the Agent from the datadog chart directly, so there is no Operator, no CRD and no DatadogAgent CR. Do not build or apply datadog-agent.yaml here; applying it would fail without the CRD or create a second Agent installation through an Operator that is already present.

  1. Build datadog-values.yaml with the complete SKILL.md Phase 4 values (baseline, products, options) plus the distribution values from Helm chart path in references/distributions.md (for example GKE Autopilot).

  2. The chart reads the key via apiKeyExistingSecret, so the Secret must exist before the release's pods start, and it stays out of Terraform state. Create it only after the user approves the plan in step 4: run the namespace and Secret lines of the SKILL.md Phase 4 install block (or the Fargate Secret block on EKS Fargate) without its helm install, then apply the saved plan.

  3. Use this release in place of helm_release.datadog_operator:

    resource "helm_release" "datadog_agent" {
      name             = "datadog-agent"
      repository       = "https://helm.datadoghq.com"
      chart            = "datadog"
      version          = "<AGENT_CHART_VERSION>"
      namespace        = "datadog"
      create_namespace = true
      values           = [file("${path.module}/datadog-values.yaml")]
    }
  4. Run the plan block from Sequenced apply, show the plan to the user, and after they approve it apply the saved plan:

    trap 'rm -f tfplan' EXIT HUP INT TERM
    if ! terraform apply tfplan; then
      echo "terraform apply FAILED"
      exit 1
    fi
  5. Continue to SKILL.md Phase 5 to verify the installation.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning8d3 checks · Risk SAFE
  • Gen Agent Trust Hub8d

    This skill provides a robust and secure method for installing the Datadog Agent across various Kubernetes distributions. It adheres to security best practices for credential management, utilizes trusted sources for configuration data, and incorporates mandatory user-confirmation steps before executing any modifications to the target environment.

  • Socket8d

    No alerts

  • Snyk8d

    Risk: MEDIUM · 1 issue

Signed by skilld at 618fae3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated last week
Other metadata
metadata
{
  "version": "1.0.3",
  "author": "datadog-labs",
  "repository": "https://github.com/datadog-labs/agent-skills",
  "tags": "datadog,agent,kubernetes,k8s,eks,aks,gke,openshift,oke,tkg,rancher,terraform",
  "alwaysApply": "false",
  "tools": "kubectl,oc,helm,terraform,aws,az,gcloud,oci,openssl"
}

README badge

README badge for datadog-labs/agent-skills/dd-agent-install-kubernetes