• EnglishEspañol日本語한국어Português
  • Log inStart now

Install containerized private minions (CPMs)


On October 22, 2024, we will end of life the containerized private minion (CPM) and the legacy synthetics runtime versions it supports. Please review our recommended migration steps to avoid degradation of your private location monitors.

You can use New Relic's containerized private minions (CPM). These are Docker container-based private minions that accept and execute synthetic monitors against your private locations.

The CPM can operate in a Docker container system environment or a Kubernetes container orchestration system environment. The CPM will auto-detect its environment to select the appropriate operating mode.

General private minion features

Because the CPM operates as a container instead of a virtual machine, it delivers many features:

Kubernetes-specific features

Also, the CPM delivers the following features in a Kubernetes environment:

  • Integrates with the Kubernetes API to delegate runtime lifecycle management to Kubernetes
  • Does not require privileged access to the Docker socket
  • Supports hosted and on-premise Kubernetes clusters
  • Supports various container engines such as Docker and Containerd
  • Deployable via Helm charts as well as configuration YAMLs
  • Allows job (ping vs. non-ping checks) based resource allocation for optimum resource management
  • Observability offered via the New Relic Kubernetes cluster explorer

System requirements and compatibility

To host CPMs, your system must meet the minimum requirements for the chosen system environment.


Do not modify any CPM files. New Relic is not liable for any modifications you make. For more information, contact your account representative or a New Relic technical sales rep.

Private location key

Before launching CPMs, you must have a private location key. Your CPM uses the key to authenticate against New Relic and run monitors associated with that private location.

To find the key for existing private location:

  1. Go to one.newrelic.com > Synthetic monitoring > Private locations.
  2. In the Private locations index, locate the private location you want your CPM to be assigned to.
  3. Note the key associated with the private location with the key icon.

Sandboxing and Docker dependencies

Sandboxing and Docker dependencies are applicable to the CPM in a Docker container system environment.

Install and update CPM versions

Both installing and updating the CPM use the same command to pull the latest Docker image from the Quay.io repository where the CPM Docker image is hosted. Go to quay.io/repository/newrelic/synthetics-minion for a list of all the releases.

CPM images are also hosted on Docker Hub. Go to hub.docker.com/r/newrelic/synthetics-minion/tags for a list of all the releases.

Unless hosting the images in a local image repository, connections to either quay.io or docker.io will need to be allowed through your firewall in order for Docker to pull the synthetics-minion and synthetics-minion-runner images. The "runner" image is pulled automatically on startup of the synthetics-minion container. See Docker environment configuration and Kubernetes environment configuration for details on how to set a local repository and the runner registry endpoint.

Start the CPM

To start the CPM, follow the applicable Docker or Kubernetes instructions.

Stop or delete the CPM

On a Docker container system environment, use the Docker stop procedure to stop the CPM from running. On a Kubernetes container orchestration system environment, use the Kubernetes delete procedure to stop the CPM from running.

Show help and examples

Use these options as applicable:

  • To get a list of the most commonly used run options directly in the command line interface, run the show help command.

  • To show CPM usage examples as well as the list of all the available run options, run this command:

    docker run quay.io/newrelic/synthetics-minion:latest help
  • To keep track of Docker logs and verify the health of your monitors, see Containerized private minion (CPM) maintenance and monitoring.

  • For a CPM in the Kubernetes container orchestration system environment, the following Helm show commands can be used to view the chart.yaml and the values.yaml, respectively:

    helm show chart YOUR_REPO_NAME/synthetics-minion
    helm show values YOUR_REPO_NAME/synthetics-minion

Show license information

To show the licensing information for the open source software that we use in the CPM, run the LICENSE command.

Run this command to view license information for CPM versions 2.2.27 or higher:

docker run quay.io/newrelic/synthetics-minion:latest LICENSE

Some of our open-source software is listed under multiple software licenses, and in that case we have listed the license we've chosen to use. Our license information is also available in the our licenses documentation.

Configure CPM

You can configure the containerized private minion with custom node modules, preserve data between launches, use environment variables, and more. For more information, see CPM configuration.


For both Docker and Kubernetes, the CPM and its runner containers will inherit network settings from the host. For an example of this on a Docker container system environment, see the Docker site.

A new bridge network is created for each runner container. This means networking command options like --network and --dns passed to the CPM container at launch (such as through Docker run commands on a Docker container system environment) are not inherited or used by the runner containers.

When these networks are created, they pull from the default IP address pool configured for daemon. For an example of this on a Docker container system environment, see the Docker site.

Typically, the runner network is removed after the check is completed. However, if a CPM exits while a check is still running, or exits in another unexpected circumstance, these networks may get orphaned. This can potentially use up IP address space that is available to the Docker daemon.

If this happens, you may see INTERNAL ENGINE ERROR code: 31 entries in your CPM logging when trying to create a new runner container. To clean these up in Docker container system environments only, run docker network prune.

Security, sandboxing, and running as non-root

By default, the software running inside a CPM is executed with root user privileges. This is suitable for most scenarios, as the execution is sandboxed.

In a Docker container system environment: To change the default AppArmor profile used by containers that CPM spawns to run monitors, see the environment variable MINION_RUNNER_APPARMOR (CPM version 3.0.3 or higher) or MINION_DOCKER_RUNNER_APPARMOR (CPM version up to v3.0.2).

To run the CPM as a non-root user, additional steps are required:

Docker image repository

A single CPM Docker image serves both the Docker container system environment and Kubernetes container orchestration system environment. The Docker image is hosted on quay.io. To make sure your Docker image is up-to-date, see the quay.io newrelic/synthetics-minion repository.

Additional considerations for CPM connection



CPMs without Internet access

A CPM can operate without access to the internet, but with some exceptions. The public internet health check can be disabled using the environment variables named MINION_NETWORK_HEALTHCHECK_DISABLED for a Docker container system environment or synthetics.minionNetworkHealthCheckDisabled for a Kubernetes container orchestration system environment. The CPM needs to be able to contact the "synthetics-horde.nr-data.net" domain. This is necessary for it to report data to New Relic and to receive monitors to execute. Ask your network administration if this is a problem and how to set up exceptions.

Communicate with synthetics via a proxy

To set up communication with New Relic by proxy, use the environment variables named MINION_API_PROXY*.

Arguments passed at launch

This applies to a Docker container environment only. Arguments passed to the CPM container at launch do not get passed on to the containers spawned by the CPM. Docker has no concept of "inheritance" or a "hierarchy" of containers, and we don't copy the configuration that is passed from CPM to the monitor-running containers. The only shared configuration between them is the one set at the Docker daemon level.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.