--- title: Set Up a Private Action Runner in the Datadog Agent description: >- Install, enroll, manage, and update a private action runner that runs inside the Datadog Agent. breadcrumbs: >- Docs > Actions > Private Actions > Set Up a Private Action Runner in the Datadog Agent --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Set Up a Private Action Runner in the Datadog Agent {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} ## Overview{% #overview %} Running the private action runner in the Datadog Agent is the recommended path for new deployments. If you already run the Datadog Agent, you enable the runner with a single configuration flag and manage it through the Agent life cycle. Setting up the runner takes three steps: 1. **Install** the runner, using the deployment option that fits your environment. 1. **Enroll** the runner, which sets its ownership and the authorization model it uses. 1. **Update** the runner as part of your Agent upgrades. To deploy the runner as a separate binary instead, see [Set up a standalone private action runner](https://docs.datadoghq.com/actions/private_actions/set_up_standalone.md). ## Prerequisites{% #prerequisites %} - A Linux or Windows host with **Datadog Agent 7.81.0 or later**, or a Kubernetes cluster with **Datadog Operator v1.28.0 or later** or the **Datadog Helm chart 3.231.6 or later**. - [Remote Configuration](https://docs.datadoghq.com/remote_configuration.md) enabled for your organization. - Network access to Datadog at `https://`. ## Install the runner{% #install-the-runner %} The runner in the Datadog Agent has three deployment options, based on where the runner needs to act: | Deployment option | How it runs | Deploy with | Best for | | ---------------------------- | -------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------- | | **Host** | A separate process next to the Datadog Agent on a Linux or Windows host. | Host install | Actions that target a specific host. | | **Kubernetes node Agent** | A container in the node Agent, using the same runner binary as the host process. | Helm, Operator | Node-local actions in a Kubernetes cluster. | | **Kubernetes Cluster Agent** | In-process inside the Cluster Agent, with no separate binary. One runner serves the whole cluster. | Helm, Operator | Cluster-wide Kubernetes actions. | You have the option to install with **Fleet Automation**, a UI-driven flow that enrolls the runner as owned, or **Manual installation**, where you choose the enrollment type yourself. ### Using Fleet Automation (recommended){% #using-fleet-automation-recommended %} The Fleet Automation install flow is the same across platforms. 1. Go to the [Fleet Automation install page](https://app.datadoghq.com/fleet/install-agent/latest) and select your platform. For Kubernetes, also select **Helm Chart** or **Datadog Operator** as the install method, to match the Manual installation tab you plan to follow. 1. In **Customize your Agent coverage**, go to the **Optimization & Remediation** section and turn on **Enable Agent to take action**. This creates an application key with the `on_prem_runner_write` scope and enrolls the runner as **owned**, authorized with [Connections](https://docs.datadoghq.com/actions/connections.md). To enroll an ownerless runner instead, authorized with [Execution Policies](https://docs.datadoghq.com/actions/private_actions/execution_policies.md), use Manual installation. 1. Follow the remaining instructions in the install panel to add an API key and complete the installation. 1. After installation, go to [Private Action Runners](https://app.datadoghq.com/actions/action-catalog) to verify your runner appears on the list. ### Manual installation{% #manual-installation %} {% tab title="Linux" %} Set the following environment variables when you install or run the Agent. On the host, private action runner settings use the `DD_PRIVATE_ACTION_RUNNER_*` prefix: ```bash DD_API_KEY= \ DD_APP_KEY= \ DD_SITE="" \ DD_PRIVATE_ACTION_RUNNER_ENABLED=true \ DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLIST=com.datadoghq.kubernetes.*,com.datadoghq.remoteaction.* \ bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)" ``` `DD_APP_KEY` enrolls the runner as owned, the same as Fleet Automation. The application key needs the `on_prem_runner_write` scope. `DD_PRIVATE_ACTION_RUNNER_ACTIONS_ALLOWLIST` takes a comma-separated list. Use bundle wildcards to allow the actions a runner in the Datadog Agent can run: `com.datadoghq.kubernetes.*` and `com.datadoghq.remoteaction.*`. To rely on the runner's built-in default actions instead (read-only Remote Action actions, plus a set of read-only Kubernetes actions on the Cluster Agent), leave the allowlist unset. After installation, go to [Private Action Runners](https://app.datadoghq.com/actions/action-catalog) to verify your runner appears on the list. {% /tab %} {% tab title="Windows" %} Install or upgrade to Datadog Agent 7.81.0 or later, then edit `C:\ProgramData\Datadog\datadog.yaml`: ```yaml app_key: private_action_runner: enabled: true self_enroll: true actions_allowlist: - "com.datadoghq.kubernetes.*" - "com.datadoghq.remoteaction.*" ``` `app_key` enrolls the runner as owned, the same as Fleet Automation above; the application key needs the `on_prem_runner_write` scope. Restart the Agent to apply the configuration: ```powershell Restart-Service -Force datadogagent ``` After the Agent restarts, go to [Private Action Runners](https://app.datadoghq.com/actions/action-catalog) to verify your runner appears on the list. The host process runs the **node Agent** runner. To run a runner in the Cluster Agent, use the Kubernetes (Helm) or Kubernetes (Operator) tab. {% /tab %} {% tab title="Kubernetes (Helm)" %} The Datadog Helm chart can enable the runner in two places: - The **node Agent** runner, as a sidecar container. The node Agent runner is **Linux-only**. - The **Cluster Agent** runner, in-process. The Cluster Agent runner is available through Helm or the Operator only (there is no standalone binary), and it requires leader election so that identity is coordinated across Cluster Agent replicas. Create an API key with the Private Action Runner capability in [Organization Settings](https://app.datadoghq.com/organization-settings/api-keys), then store it in a Kubernetes secret that the chart reads through `apiKeyExistingSecret`: ```bash kubectl create secret generic datadog-secret \ --from-literal api-key= ``` This example enrolls the runner as **ownerless** (`apiKeyOnlyEnrollment: true`, using the API key only), which authorizes it with Execution Policies. For other enrollment options and how ownership works, see [Enrollment and ownership](https://docs.datadoghq.com/actions/private_actions/enroll_runner.md). Helm settings use the `privateActionRunner.*` key in camelCase. Create a `values.yaml`: ```yaml datadog: apiKeyExistingSecret: datadog-secret site: clusterName: remoteConfiguration: enabled: true privateActionRunner: enabled: true apiKeyOnlyEnrollment: true actionsAllowlist: - "com.datadoghq.remoteaction.*" - "com.datadoghq.script.*" clusterAgent: enabled: true privateActionRunner: enabled: true apiKeyOnlyEnrollment: true actionsAllowlist: - "com.datadoghq.kubernetes.*" - "com.datadoghq.script.*" ``` For all available runner configuration options, see [`datadog.privateActionRunner`](https://github.com/DataDog/helm-charts/blob/main/charts/datadog/values.yaml#L523) and [`clusterAgent.privateActionRunner`](https://github.com/DataDog/helm-charts/blob/main/charts/datadog/values.yaml#L1842) in the Helm chart. Install the chart: ```bash helm repo add datadog https://helm.datadoghq.com helm repo update helm install datadog-agent datadog/datadog -f values.yaml ``` After installation, go to [Private Action Runners](https://app.datadoghq.com/actions/action-catalog) to verify your runner appears on the list. {% /tab %} {% tab title="Kubernetes (Operator)" %} The Datadog Operator enables the runner through annotations on the `DatadogAgent` resource. The runner configuration in the `-configdata` annotation uses the `private_action_runner.*` key in snake_case. The Operator can enable both the node Agent runner and the in-process Cluster Agent runner. Create an API key with the Private Action Runner capability in [Organization Settings](https://app.datadoghq.com/organization-settings/api-keys), then store it in a Kubernetes secret that the `DatadogAgent` resource reads through its `credentials`: ```bash kubectl create secret generic datadog-secret \ --from-literal api-key= ``` This example enrolls the runner as **ownerless** (`api_key_only_enrollment: true`, using the API key only), which authorizes it with Execution Policies. For other enrollment options and how ownership works, see [Enrollment and ownership](https://docs.datadoghq.com/actions/private_actions/enroll_runner.md). ```yaml 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: site: credentials: apiSecret: secretName: datadog-secret keyName: api-key ``` Apply the manifest: ```bash kubectl apply -f datadog-agent.yaml ``` As with Helm, the Cluster Agent runner requires leader election, and the node Agent runner is Linux-only. After you apply the manifest, go to [Private Action Runners](https://app.datadoghq.com/actions/action-catalog) to verify your runner appears on the list. {% /tab %} ### Configuration field names{% #configuration-field-names %} Runner settings follow the standard Datadog Agent configuration conventions for each install method: - Environment variables on a host. - CamelCase keys under `privateActionRunner` in Helm. - Snake_case keys under `private_action_runner` in the Operator. For the field-name crosswalk across all three install methods and the full list of configuration keys and defaults, see the [private action runner reference](https://docs.datadoghq.com/actions/private_actions/reference.md). ## Enroll the runner{% #enroll-the-runner %} Enrollment registers the runner with your Datadog organization and sets its **ownership**, which determines the authorization model. An ownerless runner, enrolled with an API key that has the Private Action Runner capability, uses [Execution Policies](https://docs.datadoghq.com/actions/private_actions/execution_policies.md). An owned runner, enrolled with an application key, uses [Connections](https://docs.datadoghq.com/actions/connections.md). Because the model is fixed at enrollment, decide which one you want before you deploy. For more information on the process, see [Enrollment and ownership](https://docs.datadoghq.com/actions/private_actions/enroll_runner.md). ## Manage the runner{% #manage-the-runner %} ### Change the allowlist{% #change-the-allowlist %} To edit the allowlist for a runner in the Datadog Agent: {% tab title="Linux" %} 1. Edit the `private_action_runner.actions_allowlist` section in `/etc/datadog-agent/datadog.yaml`. 1. Restart the Agent: `sudo systemctl restart datadog-agent`. {% /tab %} {% tab title="Windows" %} 1. Edit the `private_action_runner.actions_allowlist` section in `C:\ProgramData\Datadog\datadog.yaml`. 1. Restart the Agent: `Restart-Service -Force datadogagent`. {% /tab %} {% tab title="Kubernetes (Operator)" %} 1. Update `actions_allowlist` in both `DatadogAgent` manifest annotations: `agent.datadoghq.com/private-action-runner-configdata` and `cluster-agent.datadoghq.com/private-action-runner-configdata`. 1. Apply the updated manifest: `kubectl apply -f datadog-agent.yaml`. {% /tab %} {% tab title="Kubernetes (Helm)" %} 1. Update `privateActionRunner.actionsAllowlist` (node Agent) or `clusterAgent.privateActionRunner.actionsAllowlist` (Cluster Agent) in `values.yaml`. 1. Apply the updated chart: `helm upgrade datadog-agent datadog/datadog -f values.yaml`. {% /tab %} ### Automatic deletion of inactive runners{% #automatic-deletion-of-inactive-runners %} To free up unused resources, Datadog automatically deletes node Agent-based private action runners that use API-key-only (ownerless) configuration after 35 days of inactivity. This automatic cleanup does not apply to owned runners, or to the Cluster Agent runner. If your runner is deleted due to inactivity, restarting it results in an error. You must re-enroll the runner by repeating the installation steps. ## Debugging with logs{% #debugging-with-logs %} {% tab title="Linux" %} ```bash cat /var/log/datadog/private-action-runner.log ``` {% /tab %} {% tab title="Windows" %} ```powershell Get-Content C:\ProgramData\Datadog\logs\private-action-runner.log ``` {% /tab %} {% tab title="Kubernetes" %} ```bash kubectl logs -l app.kubernetes.io/component=cluster-agent --tail=1000 | grep private ``` {% /tab %} ## Update the runner{% #update-the-runner %} Update the runner in the Datadog Agent to stay update to date with any Agent upgrades. {% tab title="Linux" %} Upgrade the Datadog Agent to the latest version. The runner is bundled with the Agent. ```bash sudo apt-get update && sudo apt-get install datadog-agent ``` Or for RHEL/CentOS: ```bash sudo yum update datadog-agent ``` Restart the Agent after the upgrade: ```bash sudo systemctl restart datadog-agent ``` For detailed upgrade instructions, see [Upgrade to Agent v7](https://docs.datadoghq.com/agent/versions/upgrade_to_agent_v7.md). {% /tab %} {% tab title="Windows" %} Download the latest Agent MSI installer from the [Datadog Agent download page](https://app.datadoghq.com/account/settings#agent/windows) and run the installer, or use PowerShell: ```powershell # Download the latest installer Invoke-WebRequest -Uri "https://s3.amazonaws.com/ddagent-windows-stable/ddagent-cli-latest.msi" -OutFile ddagent-cli-latest.msi # Run the installer Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /i ddagent-cli-latest.msi' ``` Restart the Agent after the upgrade: ```powershell Restart-Service -Force datadogagent ``` {% /tab %} {% tab title="Kubernetes (Operator)" %} Update the Datadog Operator and Agent image versions in your `DatadogAgent` manifest. 1. Update the Datadog Operator: ```bash helm repo update helm upgrade datadog-operator datadog/datadog-operator \ --set image.repository=registry.datadoghq.com/operator \ --set image.tag=latest ``` You can pin a specific version. To browse available tags, use [Docker Hub](https://hub.docker.com/r/datadog/operator/tags). 1. Update the Agent image versions in your `datadog-agent.yaml` manifest: ```yaml override: nodeAgent: image: name: registry.datadoghq.com/agent: clusterAgent: image: name: registry.datadoghq.com/cluster-agent: ``` 1. Apply the updated manifest: `kubectl apply -f datadog-agent.yaml`. 1. Verify the update: ```bash kubectl get pods kubectl logs -l app.kubernetes.io/component=cluster-agent --tail=100 | grep private ``` The Cluster Agent runner keeps its identity across the update, since it stores it in a shared Kubernetes secret. The node Agent runner stores its identity in a file: if that path isn't backed by a persistent volume, an update can wipe the identity and force the runner to re-enroll. See [Identity storage on Kubernetes](https://docs.datadoghq.com/actions/private_actions/enroll_runner.md#identity-storage-on-kubernetes). {% /tab %} {% tab title="Kubernetes (Helm)" %} Updating the runner is part of the standard Datadog Agent Helm chart upgrade process. ```bash helm repo update helm upgrade datadog-agent datadog/datadog -f values.yaml ``` For detailed upgrade instructions, see [Upgrading Datadog Helm](https://github.com/DataDog/helm-charts/blob/main/charts/datadog/README.md#upgrading). {% /tab %} {% tab title="Terraform (Operator)" %} Update the version variables in your Terraform configuration: ```hcl locals { helm_operator_version = "" agent_version = "" # ... } ``` Apply the changes: ```bash terraform plan terraform apply -var="datadog_api_key=" -var="datadog_app_key=" ``` {% /tab %} ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Private Actions](https://docs.datadoghq.com/actions/private_actions.md) - [Enrollment and ownership](https://docs.datadoghq.com/actions/private_actions/enroll_runner.md) - [Execution Policies](https://docs.datadoghq.com/actions/private_actions/execution_policies.md) - [Set up a standalone private action runner](https://docs.datadoghq.com/actions/private_actions/set_up_standalone.md)