diff --git a/hugo/config/_default/menus/main.en.yaml b/hugo/config/_default/menus/main.en.yaml index 38cf9934406..b3f90c59d07 100644 --- a/hugo/config/_default/menus/main.en.yaml +++ b/hugo/config/_default/menus/main.en.yaml @@ -3121,16 +3121,16 @@ menu: parent: private_actions identifier: set_up_agent_based weight: 2 + - name: Set Up a Standalone Runner + url: actions/private_actions/set_up_standalone/ + parent: private_actions + identifier: set_up_standalone + weight: 3 - name: Run a Script url: actions/private_actions/run_script/ parent: private_actions identifier: run_script weight: 202 - - name: Update the Private Action Runner - url: actions/private_actions/update_private_action_runner/ - parent: private_actions - identifier: update_private_action_runner - weight: 203 - name: Cloudcraft url: datadog_cloudcraft/ pre: cloudcraft diff --git a/hugo/content/en/actions/private_actions/set_up_agent_based.md b/hugo/content/en/actions/private_actions/set_up_agent_based.md index 6fe33a47783..eb5f33b0e5e 100644 --- a/hugo/content/en/actions/private_actions/set_up_agent_based.md +++ b/hugo/content/en/actions/private_actions/set_up_agent_based.md @@ -6,6 +6,7 @@ aliases: - service_management/workflows/private_actions/use_private_actions - service_management/app_builder/private_actions/use_private_actions - actions/private_actions/use_private_actions/ +- actions/private_actions/update_private_action_runner/ further_reading: - link: "actions/private_actions/" tag: "Documentation" diff --git a/hugo/content/en/actions/private_actions/set_up_standalone.md b/hugo/content/en/actions/private_actions/set_up_standalone.md new file mode 100644 index 00000000000..cb2c44c9739 --- /dev/null +++ b/hugo/content/en/actions/private_actions/set_up_standalone.md @@ -0,0 +1,289 @@ +--- +title: Set up a standalone private action runner +description: Install, connect, manage, and update a standalone private action runner that you deploy and manage yourself with Docker or Helm. +disable_toc: false +further_reading: +- link: "actions/private_actions/" + tag: "Documentation" + text: "Private Actions Overview" +- link: "actions/private_actions/set_up_agent_based" + tag: "Documentation" + text: "Set up a private action runner in the Datadog Agent" +- link: "actions/connections" + tag: "Documentation" + text: "Connections" +--- + +The standalone private action runner is a dedicated container you can install and manage independently of the Datadog Agent with Docker or Helm. +It is supported and in maintenance mode: it continues to receive security and +stability updates, and no new features are planned. For new deployments, and to use Execution +Policies, run the runner in the Datadog Agent instead. See +[Set up a private action runner in the Datadog Agent][2]. + +Setting up the runner takes three steps: + +1. **Install** the runner with Docker, Docker Compose, or Kubernetes. +1. **Connect** the runner to Datadog with a connection. +1. **Update** the runner as new versions are released. + +A standalone runner is always **owned**: creating one, through either method below, always +registers it under the creating user, authorized with [Connections][3]. + +## Prerequisites + +- Docker, or a Kubernetes cluster. +- Network access to Datadog at `https://{{< region-param key=dd_site >}}` and + `https://config.{{< region-param key=dd_site >}}`. + +## Install the runner + +1. Go to **Actions Catalog > Private Action Runners**, and click **New Private Action Runner**. +1. Enter a name for your runner and select the allowed actions. +1. Create a directory on your host where the runner can store its configuration, such as `./config`. +1. Deploy your runner by following the steps for your container platform: + +{{< tabs >}} +{{% tab "Docker" %}} + +1. Click **Docker**. +1. 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`. + +{{% /tab %}} +{{% tab "Docker Compose" %}} + +1. Click **Docker Compose**. +1. Create a `docker-compose.yaml` file and add the provided YAML, or add the `runner` stanza to an + existing Docker Compose file. +1. Replace `./config` with the path to the directory you created for the runner configuration. +1. Run `docker compose up -d`. + +You can safely ignore the error `DATADOG TRACER DIAGNOSTIC - Agent Error: connect ECONNREFUSED`. + +{{% /tab %}} +{{% tab "Kubernetes (Helm)" %}} + +1. Click **Kubernetes**. +1. Confirm that `kubectl` and `helm` are installed, and that you have sufficient permissions to + create Kubernetes resources in your cluster. +1. Follow the instructions provided in the app to enroll the runner, generate the config, add the + Private Action Runner Helm repository, and install the chart. +1. Run `kubectl get pods -w` and verify the private action runner pod's status becomes **Ready**. + +{{% /tab %}} +{{< /tabs >}} + +## Alternative: programmatic installation + +As an alternative to the UI-based setup above, you can enroll and configure a standalone runner +programmatically using your API key and application key. This approach is suited to automated +deployments, CI/CD pipelines, and infrastructure-as-code workflows. Like the UI-based setup, this +always creates an owned runner. + +To set up the runner programmatically: + +1. Provide your Datadog API and application keys through the `DD_API_KEY` and `DD_APP_KEY` + environment variables. +1. Pass the `--with-api-key` flag to the runner container. Despite the flag's name, this path still + requires an application key: the runner uses both credentials together to register itself and + assign the application key's owner as the runner's editor. + +{{< tabs >}} +{{% tab "Docker" %}} + +```bash +export DD_API_KEY="" +export DD_APP_KEY="" + +docker run -d \ + -e DD_BASE_URL=https://{{< region-param key=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= \ + -v ./config:/etc/dd-action-runner/config \ + gcr.io/datadoghq/private-action-runner:v{{< private-action-runner-version "private-action-runner" >}} \ + --with-api-key +``` + +{{% /tab %}} +{{% tab "Docker Compose" %}} + +```yaml +services: + private-runner: + image: gcr.io/datadoghq/private-action-runner:v{{< private-action-runner-version "private-action-runner" >}} + command: ["--with-api-key"] + environment: + DD_API_KEY: ${DD_API_KEY} + DD_APP_KEY: ${DD_APP_KEY} + DD_BASE_URL: https://{{< region-param key=dd_site >}} + DD_PRIVATE_RUNNER_CONFIG_DIR: /etc/dd-action-runner/config + RUNNER_NAME: my-compose-runner + volumes: + - "./config:/etc/dd-action-runner/config" +``` + +Run with: + +```bash +export DD_API_KEY="" +export DD_APP_KEY="" +docker compose up -d +``` + +{{% /tab %}} +{{% tab "Kubernetes" %}} + +Generate the runner configuration: + +```bash +export DD_API_KEY="" +export DD_APP_KEY="" + +docker run \ + -e DD_BASE_URL=https://{{< region-param key=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" \ + -v ./config:/etc/dd-action-runner/config \ + gcr.io/datadoghq/private-action-runner:v{{< private-action-runner-version "private-action-runner" >}} \ + --with-api-key --enroll -f helm-values > values.yaml +``` + +Deploy the Helm chart: + +```bash +helm upgrade --install datadog-par datadog/private-action-runner -f values.yaml +``` + +{{% /tab %}} +{{< /tabs >}} + +When the runner shows **Ready to use**, create a connection for it, or view it on the **Private +Action Runners** page. + +## Connect the runner + +A standalone runner is always owned and uses the Connections authorization model. A connection +stores the credentials for a service and pairs them with the runner. To create a connection and +pair it with your runner, see [Connections][3]. For how permissions on the runner itself work, see +[Manage access to owned runners][5]. + +## Manage the runner + +### Edit connections or delete a runner + +From the **Private Action Runner** page in Actions Catalog, you can view all your private runners +together with the workflows or apps that use each one. To edit the connections for a runner, click +**View Details**. Click the trash can icon to delete a runner. + +### Change the allowlist + +To edit the allowlist for a standalone runner, edit the `actionsAllowlist` section of the +`config.yaml` file in your runner's environment, then restart the runner by restarting your +container or deployment. + +## Update the runner + +Choose the tab that matches how you installed the runner. Use the current +`v{{< private-action-runner-version "private-action-runner" >}}` version rather than a hardcoded +tag. + +{{< tabs >}} +{{% tab "Docker" %}} + +Find the current ID of your container: + +```bash +docker ps +``` + +Stop the container: + +```bash +docker stop +``` + +Start a new container with [the latest image][101]. Environment variables are not needed: +everything is configured in the `config/config.yaml` file. + +```bash +docker run -d \ + -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \ + -v ./config:/etc/dd-action-runner/config \ + gcr.io/datadoghq/private-action-runner:v{{< private-action-runner-version "private-action-runner" >}} +``` + +After confirming the new version is working, remove the old container: + +```bash +docker rm +``` + +[101]: https://api.datadoghq.com/api/v2/on-prem-management-service/runner/latest-image + +{{% /tab %}} +{{% tab "Docker Compose" %}} + +Navigate to the directory containing your `docker-compose.yaml` file and update the image version: + +```yaml +services: + private-actions-runner: + image: gcr.io/datadoghq/private-action-runner:v{{< private-action-runner-version "private-action-runner" >}} +``` + +Start the container again: + +```bash +docker compose up -d +``` + +{{% /tab %}} +{{% tab "Helm" %}} + +There are two options for upgrading with Helm: + +1. **(Recommended)** Upgrade the chart, which uses the latest version of the runner. There may be + changes to the chart; review [the changelog][101]. +1. Upgrade the runner only, without upgrading the chart. + +**Upgrading the chart (recommended):** + +```bash +helm repo update +helm upgrade datadog/private-action-runner -f ./values.yaml +``` + +**Upgrading the runner only:** specify the runner version in `values.yaml` under the +`common.image.tag` key with a value from [the chart's values file][102]: + +```yaml +common: + image: + tag: v{{< private-action-runner-version "private-action-runner" >}} +``` + +Then run: + +```bash +helm upgrade datadog/private-action-runner -f ./values.yaml +``` + +[101]: https://github.com/DataDog/helm-charts/blob/main/charts/private-action-runner/CHANGELOG.md +[102]: https://github.com/DataDog/helm-charts/blob/main/charts/private-action-runner/values.yaml + +{{% /tab %}} +{{< /tabs >}} + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[2]: /actions/private_actions/set_up_agent_based/ +[3]: /actions/connections/ +[5]: /actions/private_actions/enroll_runner/#manage-access-to-owned-runners diff --git a/hugo/content/en/actions/private_actions/update_private_action_runner.md b/hugo/content/en/actions/private_actions/update_private_action_runner.md deleted file mode 100644 index a60bf349a6f..00000000000 --- a/hugo/content/en/actions/private_actions/update_private_action_runner.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -title: Update the Private Action Runner -description: Learn how to update the Private Action Runner to the latest version for both agent-based and standalone installations. ---- - -## Overview - -This page explains how to update the private action runner (PAR). The update process depends on your installation method. - -## Agent-based runner - -If you installed the PAR through the Datadog Agent, updating the PAR is part of the standard Agent upgrade process. - -{{< tabs >}} -{{% tab "Linux" %}} - -Upgrade the Datadog Agent to the latest version. The PAR is bundled with Agent version 7.77.0 and later. - -```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][101]. - -[101]: /agent/versions/upgrade_to_agent_v7/ - -{{% /tab %}} - -{{% tab "Windows" %}} - -Download the latest Agent MSI installer from the [Datadog Agent download page][101] and run the installer. - -Alternatively, 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 -``` - -[101]: https://app.datadoghq.com/account/settings#agent/windows - -{{% /tab %}} - -{{% tab "Kubernetes (Datadog 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][102]. - -2. 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: - ``` - -3. Apply the updated manifest: - - ```bash - kubectl apply -f datadog-agent.yaml - ``` - -4. Verify the update: - - ```bash - kubectl get pods - kubectl logs -l app.kubernetes.io/component=cluster-agent --tail=100 | grep private - ``` - -[102]: https://hub.docker.com/r/datadog/operator/tags - -{{% /tab %}} - -{{% tab "Kubernetes (Helm)" %}} - -Updating the PAR 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][101]. - -[101]: https://github.com/DataDog/helm-charts/blob/main/charts/datadog/README.md#upgrading - -{{% /tab %}} - -{{% tab "Terraform (Datadog 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 %}} -{{< /tabs >}} - -## Standalone runner - -If you installed the PAR as a standalone container, use one of the following methods to update. - -Currently, the PAR is on v{{< private-action-runner-version "private-action-runner" >}}. - -{{< tabs >}} -{{% tab "Docker" %}} - -Navigate to the directory where you started the PAR. Next, navigate to the `config` directory, then the `config.yaml` file. - -Find the current ID of your container: -```bash -docker ps -``` - -Stop the container: -```bash -docker stop -``` - -Start a new container with [the latest image][101]. Environment variables are not needed. Everything is configured in the `config/config.yaml` file. - -Run: -```bash -docker run -d \ - --cpus="0.25" \ - --memory="1g" \ - -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \ - -v ./config:/etc/dd-action-runner/config \ - --health-cmd "curl http://localhost:9016/liveness" \ - --health-interval 10s \ - --health-timeout 10s \ - --health-retries 3 gcr.io/datadoghq/private-action-runner:v{{< private-action-runner-version "private-action-runner" >}} -``` - -After confirming the new PAR version is working as expected, remove the old version: -```bash -docker rm -``` - -To check the PAR logs: -```bash -docker logs -``` - -[101]: https://api.datadoghq.com/api/v2/on-prem-management-service/runner/latest-image - -{{% /tab %}} - -{{% tab "Docker Compose" %}} - -Navigate to the directory containing your `docker-compose.yaml` file and update the image version: - -```yaml -services: - private-actions-runner: - image: gcr.io/datadoghq/private-action-runner:{{< private-action-runner-version "private-action-runner" >}} - cpus: 0.25 - mem_limit: 1g - deploy: - replicas: 1 - environment: - - DD_BASE_URL=https://app.datadoghq.com - - DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config - - STATSD_ENABLED=true - volumes: - - "./config:/etc/dd-action-runner/config" -``` - -Start the container again: -```bash -docker compose up -d -``` - -To check the logs: -```bash -docker compose logs runner -``` - -{{% /tab %}} - -{{% tab "Helm" %}} - -When using Helm, there are two options for upgrading the PAR: -1. **(Recommended)** Upgrade the chart, which uses the latest version of the PAR. There may be changes to the chart; review [the changelog][101]. -1. Upgrade the runner without upgrading the chart. - -**Upgrading the chart (recommended)** - -Navigate to the directory containing your `values.yaml` file and run: - -```bash -helm repo update -helm upgrade datadog/private-action-runner -f ./values.yaml -``` - -**Upgrading the PAR only** - -Specify the PAR version in your `values.yaml` under the `common.image.tag` key with the values found [here][102]: - -```yaml -common: - image: - repository: gcr.io/datadoghq/private-action-runner # optional - # latest image https://api.datadoghq.com/api/v2/on-prem-management-service/runner/latest-image - tag: v1.0.0 -``` - -Then run: -```bash -helm upgrade datadog/private-action-runner -f ./values.yaml -``` - -To check the logs: -```bash -kubectl get pods -kubectl logs -``` - -[101]: https://github.com/DataDog/helm-charts/blob/main/charts/private-action-runner/CHANGELOG.md -[102]: https://github.com/DataDog/helm-charts/blob/main/charts/private-action-runner/values.yaml - -{{% /tab %}} -{{< /tabs >}}