Use Private Actions

Using Fleet Automation (recommended)

1. Go to the Fleet Automation install page for Linux.
2. In Customize your Agent coverage, go to the Optimization & Remediation section and enable the toggle Enable Agent to take action. This creates an Application key with the on_prem_runner_write scope and Actions API Access enabled.
3. In Install the Agent, add an API key and follow the instructions to run the installation command.
4. After installation, go to the Private Action Runners page to verify your runner appears on the list.

Manual installation

Create an Application key

1. Go to Application Keys.
2. Click New Key and enter a name.
3. Under Scopes, select on_prem_runner_write.
4. Enable Actions API Access.
5. Click Create Key and copy the key value.

Install or upgrade the Datadog Agent

Run the following command to install or upgrade the Agent and enable the private action runner. Replace the placeholder values:

• <API_KEY>: Your Datadog API key
• <APP_KEY>: The Application key you created
• DD_SITE: Your Datadog site (for example, datadoghq.com)
• DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLIST: Comma-separated list of actions to allow. See Available actions for the full list.

DD_API_KEY=<API_KEY> \
DD_APP_KEY=<APP_KEY> \
DD_SITE="datadoghq.com" \
DD_PRIVATE_ACTION_RUNNER_ENABLED=true \
DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLIST=com.datadoghq.script.runPredefinedScript,com.datadoghq.kubernetes.core.listPod \
bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

Verify the installation

Go to the Private Action Runners page. You should see a new runner on the list. You can create new connections or start using existing ones.

Install or upgrade the Datadog Agent

If you already have the Datadog Agent installed, upgrade to version 7.77.0 or later. See Upgrade to Agent v7 for instructions.

For new installations, download and run the MSI installer. Replace <API_KEY> with your Datadog API key and update DD_SITE if you’re not using the “datadoghq.com”.

# Download the installer
Invoke-WebRequest -Uri "https://windows-agent.datadoghq.com/datadog-agent-7-latest.amd64.msi" -OutFile datadog-agent-7-latest.amd64.msi
# Install the Agent
Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /l*v install.log /i datadog-agent-7-latest.amd64.msi APIKEY="<API_KEY>" DD_SITE="datadoghq.com"'

Create an Application key

1. Go to Application Keys.
2. Click New Key and enter a name.
3. Under Scopes, select on_prem_runner_write.
4. Enable Actions API Access.
5. Click Create Key and copy the key value.

Configure the Agent

Edit the C:\ProgramData\Datadog\datadog.yaml file and add the following configuration:

app_key:<YOUR_APP_KEY>private_action_runner:enabled:trueself_enroll:trueactions_allowlist:- "com.datadoghq.script.runPredefinedPowershellScript"- "com.datadoghq.http.request"

See Available actions for the full list of actions you can add to the allowlist. Not all actions are supported on Windows yet. Safe choices for Windows include HTTP and runPredefinedPowershellScript.

Restart the Agent

Restart the Agent to apply the configuration and enroll the runner:

Restart-Service -Force datadogagent

Verify the installation

Go to the Private Action Runners page. You should see a new runner on the list. You can create new connections or start using existing ones.

Follow these steps to install the Private Action Runner on your Datadog Node Agents and Datadog Cluster Agent.

Using Fleet Automation (recommended)

1. Go to the Fleet Automation install page.
2. In Select Agent install method, choose Datadog Operator.
3. In Select your Kubernetes distribution, choose the distribution that matches your environment.
4. In Customize your Agent coverage, go to the Optimization & Remediation section and enable the toggle Enable Agent to take action. This creates an Application key with the on_prem_runner_write scope and Actions API Access enabled.
5. In Add the Datadog Helm repository, add an API key.
6. Follow the remaining Fleet instructions to complete the installation.

Manual installation

Install the Datadog Operator

Install the Datadog Operator version 1.25.0:

helm repo add datadog https://helm.datadoghq.com
helm repo update
helm install datadog-operator datadog/datadog-operator \
 --set image.repository=registry.datadoghq.com/operator \
 --set image.tag=1.25.0

Create an API key and Application key

1. Create or choose an API key.
2. Go to Application Keys and create a new key:
   • Under Scopes, select on_prem_runner_write. This scope is required to register the runner and automatically create connections.
   • Enable Actions API Access.

Create Kubernetes secrets

kubectl create secret generic datadog-secret \
 --from-literal api-key=<YOUR_API_KEY> \
 --from-literal app-key=<YOUR_APP_KEY>

Configure and deploy the Datadog Agent

Create a datadog-agent.yaml file with the following content:

• Set clusterName to a meaningful name for your cluster.
• Update site to your Datadog site if you’re not using datadoghq.com.
• The app-key in the secret is required for the Private Action Runner.
• Adjust actions_allowlist based on your needs. See Available actions for the full list.

apiVersion:datadoghq.com/v2alpha1kind:DatadogAgentmetadata:name:datadogannotations:agent.datadoghq.com/private-action-runner-enabled:"true"agent.datadoghq.com/private-action-runner-configdata:| private_action_runner:
 enabled: true
 actions_allowlist:
 - "com.datadoghq.script.runPredefinedScript"cluster-agent.datadoghq.com/private-action-runner-enabled:"true"cluster-agent.datadoghq.com/private-action-runner-configdata:| private_action_runner:
 enabled: true
 actions_allowlist:
 - "com.datadoghq.script.runPredefinedScript"
 - "com.datadoghq.kubernetes.core.listPod"spec:global:clusterName:<YOUR_CLUSTER_NAME>site:datadoghq.comcredentials:apiSecret:secretName:datadog-secretkeyName:api-keyappSecret:secretName:datadog-secretkeyName:app-keykubelet:tlsVerify:falseoverride:clusterAgent:replicas:2containers:cluster-agent:command:- /entrypoint.shargs:- datadog-cluster-agent- start- -E=/etc/datadog-agent/privateactionrunner.yamlfeatures:logCollection:enabled:truecontainerCollectAll:trueliveContainerCollection:enabled:true

Deploy the Agent:

kubectl apply -f datadog-agent.yaml

Verify the deployment

Check that the cluster agent pods are running:

kubectl get pods

Check the Private Action Runner logs:

kubectl logs -l app.kubernetes.io/component=cluster-agent --tail=1000 | grep private

You should see logs indicating PAR identity secret creation, self-enrollment success, and the runner starting with its URN.

Go to the Private Action Runners page. You should see a new runner on the list.

Follow these steps to install the Private Action Runner on your Datadog Node Agents and Datadog Cluster Agent using Terraform.

Create an API key and Application key

1. Create or choose an API key.
2. Go to Application Keys and create a new key:
   • Under Scopes, select on_prem_runner_write. This scope is required to register the runner and automatically create connections.
   • Enable Actions API Access.

Create the Terraform configuration

Note: You must first deploy without the kubernetes_manifest.datadog_agent resource for the CRDs to be created, then add it back.

Create a Terraform file with the following content. Update eks_cluster and other values as needed:

locals {
 helm_chart_version = "2.19.0"
 operator_version = "1.25.0"
 agent_version = "7.77.0"
 eks_cluster = "<YOUR_CLUSTER_NAME>"
}
variable "datadog_api_key" {
 type = string
}
variable "datadog_app_key" {
 type = string
}
terraform {
 required_providers {
 aws = {
 source = "hashicorp/aws"
 version = "~> 5.56.0"
 }
 kubernetes = {
 source = "hashicorp/kubernetes"
 version = "~> 3.0.1"
 }
 helm = {
 source = "hashicorp/helm"
 version = "~> 3.1.1"
 }
 }
}
provider "aws" {
 region = "us-east-1"
}
provider "kubernetes" {
 host = data.aws_eks_cluster.target.endpoint
 token = data.aws_eks_cluster_auth.target.token
 cluster_ca_certificate = base64decode(data.aws_eks_cluster.target.certificate_authority[0].data)
}
provider "helm" {
 helm_driver = "configmap"
 kubernetes = {
 host = data.aws_eks_cluster.target.endpoint
 token = data.aws_eks_cluster_auth.target.token
 cluster_ca_certificate = base64decode(data.aws_eks_cluster.target.certificate_authority[0].data)
 }
}
data "aws_eks_cluster" "target" {
 name = local.eks_cluster
}
data "aws_eks_cluster_auth" "target" {
 name = local.eks_cluster
}
resource "kubernetes_namespace_v1" "namespace" {
 metadata {
 name = "datadog"
 }
}
resource "kubernetes_secret_v1" "datadog" {
 metadata {
 name = "datadog-secret"
 namespace = "datadog"
 }
 data = {
 "api-key" = var.datadog_api_key
 "app-key" = var.datadog_app_key
 }
 depends_on = [kubernetes_namespace_v1.namespace]
}
resource "helm_release" "datadog_operator" {
 name = "datadog-operator"
 repository = "https://helm.datadoghq.com"
 chart = "datadog-operator"
 version = local.helm_chart_version
 namespace = "datadog"
 create_namespace = false
 set {
 name = "image.tag"
 value = local.operator_version
 }
 depends_on = [kubernetes_namespace_v1.namespace]
}
resource "kubernetes_manifest" "datadog_agent" {
 manifest = {
 apiVersion = "datadoghq.com/v2alpha1"
 kind = "DatadogAgent"
 metadata = {
 name = "datadog"
 namespace = "datadog"
 annotations = {
 "agent.datadoghq.com/private-action-runner-enabled" = true
 "agent.datadoghq.com/private-action-runner-configdata" = <<EOF
private_action_runner:
 enabled: true
 actions_allowlist:
 - com.datadoghq.script.runPredefinedScript
EOF
 "cluster-agent.datadoghq.com/private-action-runner-enabled" = true
 "cluster-agent.datadoghq.com/private-action-runner-configdata" = <<EOF
private_action_runner:
 enabled: true
 actions_allowlist:
 - com.datadoghq.script.runPredefinedScript
 - com.datadoghq.kubernetes.core.listPod
EOF
 }
 }
 spec = {
 global = {
 clusterName = local.eks_cluster
 site = "datadoghq.com"
 credentials = {
 apiSecret = {
 secretName = "datadog-secret"
 keyName = "api-key"
 }
 appSecret = {
 secretName = "datadog-secret"
 keyName = "app-key"
 }
 }
 }
 features = {
 apm = {
 enabled = true
 }
 liveProcessCollection = {
 enabled = true
 }
 logCollection = {
 enabled = true
 containerCollectAll = true
 }
 processDiscovery = {
 enabled = true
 }
 }
 override = {
 clusterAgent = {
 image = {
 tag = local.agent_version
 }
 containers = {
 "cluster-agent" = {
 command = ["/entrypoint.sh"]
 args = [
 "datadog-cluster-agent",
 "start",
 "-E=/etc/datadog-agent/privateactionrunner.yaml",
 ]
 }
 }
 }
 nodeAgent = {
 image = {
 tag = local.agent_version
 }
 }
 }
 }
 }
 depends_on = [helm_release.datadog_operator]
}

Deploy

terraform init
terraform apply -var="datadog_api_key=<YOUR_API_KEY>" -var="datadog_app_key=<YOUR_APP_KEY>"

Verify the deployment

Check that the cluster agent pods are running:

kubectl get pods -n datadog

Check the Private Action Runner logs:

kubectl logs -l app.kubernetes.io/component=cluster-agent -n datadog --tail=1000 | grep private

Go to the Private Action Runners page. You should see a new runner on the list.

Using Fleet Automation (recommended)

1. Go to the Fleet Automation install page.
2. In Select Agent install method, choose Helm Chart.
3. In Select your Kubernetes distribution, choose the distribution that matches your environment.
4. In Customize your Agent coverage, go to the Optimization & Remediation section and enable the toggle Enable Agent to take action. This creates an Application key with the on_prem_runner_write scope and Actions API Access enabled.
5. In Add the Datadog Helm repository, add an API key.
6. Follow the remaining Fleet instructions to complete the installation.

Manual installation

Prerequisites

• Helm 3+
• Kubernetes cluster with access to kubectl

Create a Kubernetes secret

Create a secret containing your API key and Application key. The Application key must have the on_prem_runner_write scope and Actions API Access enabled.

kubectl create secret generic datadog-secret \
 --from-literal=api-key=<API_KEY> \
 --from-literal=app-key=<APP_KEY>

Configure and install the Helm chart

1. Add the Datadog Helm repository:

   helm repo add datadog https://helm.datadoghq.com
   helm repo update
   

2. Create a values.yaml file with the following content:

   Note: To customize the actions allowlist, use datadog.privateActionRunner.actionsAllowlist for the node agent and clusterAgent.privateActionRunner.actionsAllowlist for the cluster agent. For all available configuration options, see datadog.privateActionRunner and clusterAgent.privateActionRunner in the Helm chart.

   datadog:apiKeyExistingSecret:datadog-secretappKeyExistingSecret:datadog-secretsite:datadoghq.comclusterName:<YOUR_CLUSTER_NAME>remoteConfiguration:enabled:trueprivateActionRunner:enabled:trueclusterAgent:enabled:trueenv:- name:DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLISTvalue:"com.datadoghq.http.request,com.datadoghq.kubernetes.core.listPod"agents:enabled:truecontainers:agent:env:- name:DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLISTvalue:"com.datadoghq.http.request,com.datadoghq.kubernetes.core.listPod"

3. Install the Datadog Agent with Helm:

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

Verify the installation

Go to the Private Action Runners page. You should see a new runner on the list.

1. Click Docker.

2. Run the provided docker run command on your host, replacing ./config with the path to the directory you created for the runner configuration.

   You can safely ignore the error DATADOG TRACER DIAGNOSTIC - Agent Error: connect ECONNREFUSED.

1. Click Docker Compose.

2. Create a docker-compose.yaml file and add the provided YAML, or add the runner stanza to an existing Docker Compose file. For information on creating a Docker Compose file, see the official Compose documentation.

3. Replace ./config with the path to the directory you created for the runner configuration.

4. Run docker compose up -d.

   You can safely ignore the error DATADOG TRACER DIAGNOSTIC - Agent Error: connect ECONNREFUSED.

1. Click Kubernetes.
2. Confirm that you have installed kubectl on your machine: run kubectl version and verify that there is output.
3. Confirm that you have installed helm on your machine: run helm version and verify that there is output.
4. Confirm that you have sufficient permissions to create Kubernetes resources in your cluster.
5. Follow the instructions provided in the app to:
   1. Enroll the runner and generate the config.
   2. Add the Private Action Runner to your Helm repositories.
   3. Install the Helm chart.
6. Run kubectl get pods -w and verify that the status of the Private Action Runner pod becomes Ready.

Create a docker-compose.yaml file with the following content. For more information, see the official Compose documentation.

# docker-compose.yamlversion:'3.8'services:private-runner:image:gcr.io/datadoghq/private-action-runner:v1.17.1command:["--with-api-key"]environment:DD_API_KEY:${DD_API_KEY}DD_APP_KEY:${DD_APP_KEY}DD_BASE_URL:<YOUR_DD_SITE>DD_PRIVATE_RUNNER_CONFIG_DIR:/etc/dd-action-runner/configRUNNER_NAME:my-compose-runnerRUNNER_MODES:pullACTIONS_ALLOWLIST:"com.datadoghq.http.request"volumes:- "./config:/etc/dd-action-runner/config"

Run with:

export DD_API_KEY="<YOUR_API_KEY>"
export DD_APP_KEY="<YOUR_APP_KEY>"
DD_API_KEY=$DD_API_KEY DD_APP_KEY=$DD_APP_KEY docker compose up -d

1. Generate the runner configuration:

export DD_API_KEY="<YOUR_API_KEY>"
export DD_APP_KEY="<YOUR_APP_KEY>"
docker run \
 -e DD_BASE_URL=<YOUR_DD_SITE> \
 -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \
 -e DD_API_KEY="$DD_API_KEY" \
 -e DD_APP_KEY="$DD_APP_KEY" \
 -e RUNNER_NAME="my-runner" \
 -e 'ACTIONS_ALLOWLIST=com.datadoghq.http.request' \
 -v ./config:/etc/dd-action-runner/config \
 gcr.io/datadoghq/private-action-runner:v1.17.1 \
 --with-api-key --enroll -f helm-values > values.yaml

2. Deploy the Helm chart:

helm upgrade --install datadog-par datadog/private-action-runner -f values.yaml

To edit the allowlist for an agent-based private action runner:

Linux:

1. Edit the private_action_runner.actions_allowlist section in /etc/datadog-agent/datadog.yaml.
2. Restart the Agent: sudo systemctl restart datadog-agent

Windows:

1. Edit the private_action_runner.actions_allowlist section in C:\ProgramData\Datadog\datadog.yaml.
2. Restart the Agent: Restart-Service -Force datadogagent

Kubernetes (Operator):

1. Update the actions_allowlist in both DatadogAgent manifest annotations:
   • agent.datadoghq.com/private-action-runner-configdata
   • cluster-agent.datadoghq.com/private-action-runner-configdata
2. Apply the updated manifest: kubectl apply -f datadog-agent.yaml

To edit the allowlist for a standalone private action runner:

1. Edit the actionsAllowlist section of the config.yaml file in your runner’s environment and add or remove the relevant actions.
2. Restart the runner by restarting your container or deployment.