Private actions allow your Datadog workflows and apps to interact with services hosted on your private network without exposing them to the public internet. To use private actions, you must install a private action runner on a host in your network using Docker or Kubernetes and pair the runner with a connection.

When you first start the runner, it generates a private key for authentication with Datadog’s servers. This private key is never accessible by Datadog and ensures you exclusive access. Datadog uses a public key derived from the private key as the means to authenticate specific runners.

Modes

A private action runner can be used with App Builder, Workflow Automation, or both.

The following is a general overview diagram for private actions:

Mode differences

The following table explains some distinctions between App Builder and Workflows modes, including their triggering mechanisms and operational models.

The difference in models can result in varying latencies. App Builder mode’s push model might lead to more immediate responses, whereas the pull model in Workflows mode might introduce delays based on polling frequency.

App Builder mode

When your private action runner is in App Builder mode, queries that call your private services are sent directly from the user’s browser to the private action runner, which proxies requests to your services. At no point does your data enter Datadog when the runner is in App Builder mode; it communicates with Datadog only for enrollment and authentication purposes.

In the following diagram, App Management refers to backend App Builder actions that are unrelated to the Private Action runner, such as deleting an app.

Authentication

To ensure secure communication, the Datadog frontend sends a single-use scoped token with each request, which the runner validates using a private key. This mechanism ensures that your data remains within your network and does not enter Datadog while maintaining the integrity and security of your private actions.

Runner hostname

In App Builder mode, the user’s browser talks directly to your private action runner. As a result, you must specify a custom domain name that points to your runner. To set up your domain, point an A or CNAME record to your network’s ingress. Your ingress must be capable of terminating HTTPS requests and forwarding them to the runner container on port 9016. The domain and ingress do not have to be accessible to the public internet; the A or CNAME record can point, for example, to a load balancer that is only accessible through your company’s VPN.

Workflow Automation mode

If your private action runner runs in Workflows-only mode, you do not need to perform any setup beyond the initial enrollment. The private action runner continuously polls for tasks from your Datadog account, executes them by interacting with your internal service, and reports the result back to Datadog.

Both

When you select the option to use both modes, the runner dynamically adjusts the mode it uses based on the type of request it receives. This ensures smooth operation whether the runner is handling app requests, Workflow Automation executions, or a combination of both.

Further reading

Additional helpful documentation, links, and articles:

App Builder ConnectionsDOCUMENTATION Workflow ConnectionsDOCUMENTATION Use Private Actions in WorkflowsDOCUMENTATION Use Private Actions in App BuilderDOCUMENTATION Handling Private Action Credentials for Workflow AutomationDOCUMENTATION Handling Private Action Credentials for App BuilderDOCUMENTATION