Overview

Follow this guide to deploy a private action runner inside the Datadog Agent with the Datadog Operator, then run a read-only action that Datadog authorizes for you automatically.

This is the recommended path to get started. It uses the following configuration:

• Run the runner in the Datadog Agent, rather than as a standalone host process.
• Install with the Datadog Operator on Kubernetes.
• Enroll with an API key, so the runner is authorized with Execution Policies.
• Rely on Datadog’s default Execution Policies, which Datadog provisions for you, to authorize read-only Kubernetes and Remote Action actions across your runners with no setup.

At the end of this guide, you have an enrolled runner and a working read-only action.

Prerequisites

• A Kubernetes cluster managed by the Datadog Operator v1.28.0 or later, running Datadog Agent 7.81.0 or later.
• Remote Configuration enabled for your organization.
• Permission to create API keys in Organization Settings.
• Network access to Datadog at https://.

Step 1: Create an API key with the Private Action Runner capability

An ownerless runner enrolls with an API key that has the Private Action Runner capability. It does not need an application key.

1. In Datadog, go to Organization Settings > API Keys and create or select an API key.
2. On the key, next to PAR (the Private Action Runner capability), click Enable.

3. Store the key value in a Kubernetes secret that the Agent reads:

   kubectl create secret generic datadog-secret \
     --from-literal api-key=<DD_API_KEY>
   

Step 2: Deploy the runner with the Datadog Operator

Enable the runner on your DatadogAgent resource through Operator annotations. The following example enables the runner in both the node Agent and the Cluster Agent, enrolls it as ownerless with your API key, and allows a small set of read-only actions.

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
  annotations:
    agent.datadoghq.com/private-action-runner-enabled: "true"
    agent.datadoghq.com/private-action-runner-configdata: |
      private_action_runner:
        enabled: true
        api_key_only_enrollment: true
        actions_allowlist:
          - "com.datadoghq.remoteaction.*"
          - "com.datadoghq.script.*"
    cluster-agent.datadoghq.com/private-action-runner-enabled: "true"
    cluster-agent.datadoghq.com/private-action-runner-configdata: |
      private_action_runner:
        enabled: true
        api_key_only_enrollment: true
        actions_allowlist:
          - "com.datadoghq.kubernetes.*"
          - "com.datadoghq.script.*"
spec:
  global:
    clusterName: <YOUR_CLUSTER_NAME>
    site: 
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key

Apply the manifest:

kubectl apply -f datadog-agent.yaml

Because api_key_only_enrollment is set and you provide only an API key, each runner self-enrolls as ownerless on startup, which means it is authorized with Execution Policies. This manifest is the minimal Operator setup for this guide; for the full runner configuration, other install methods (Host, Windows, Helm), and the complete field reference, see Set up a private action runner in the Datadog Agent. To learn more about enrollment, see Enrollment and ownership.

The actions_allowlist entries in the example use bundle wildcards to allow the actions this guide uses. To use the runner’s built-in read-only actions instead, leave actions_allowlist empty. The runner then enables its default action set, which includes read-only Remote Action network and shell actions, plus a set of read-only Kubernetes actions on the Cluster Agent.

Step 3: Confirm the runner is enrolled

In Datadog, go to Private Action Runners. Verify your new runner appears in the list.

You can also check the Cluster Agent logs to confirm the runner started:

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

For node Agent logs and other platforms, see Debugging with logs.

Datadog provisions default Execution Policies in your organization. These policies use a target selector of *, so they automatically cover every Agent that runs a private action runner, including the one you deployed. This is what authorizes read-only actions with no Execution Policy setup of your own. See Datadog Default Execution Policies.

Step 4: Run your first action

Run a read-only Kubernetes action against your new runner from the Action Catalog. The Action Catalog runs an action the same way a workflow step does; you choose a target Agent, provide inputs, and run the action.

1. In the Datadog Action Catalog, open List Pods (com.datadoghq.kubernetes.core.listPod).
2. Under Configure connection, select the Target tab (instead of Connection).
3. Set Orch Cluster ID to the orchestration cluster ID of the cluster running your runner. You can find the orchestration cluster ID among the tags of your cluster in Fleet Automation’s Fleet View.
4. Under Configure inputs, enter the Namespace to list pods from. You can also set Field selector, Label selector, or Limit.
5. Click Run. The results appear in the panel.

The action runs on your runner and returns its result. To run the same action from a workflow instead, add a private action step in Workflow Automation and choose Target in its connection picker. See Use an Execution Policy in a workflow.

Next steps

This guide uses Datadog’s default Execution Policies, which authorize read-only actions only. To run write-capable actions, or to scope access to specific teams or environments, create your own Execution Policy. See Execution Policies.

Further reading

Additional helpful documentation, links, and articles:

Private Actions OverviewDOCUMENTATION Private Action Runner ReferenceDOCUMENTATION