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.
Because the CPM operates as a container instead of a virtual machine, it delivers many features:
- Easy to install, start, and update
- Runs on:
- Enhanced security and support for non-root user execution
- Ability to leverage a Docker container as a sandbox environment
- Customizable monitor check timeout
- Custom provided modules for scripted monitor types
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
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.
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:
- Go to one.newrelic.com > Synthetics > Private locations.
- In the Private locations index, locate the private location you want your CPM to be assigned to.
- Note the key associated with the private location with the key icon.
Sandboxing and Docker dependencies are applicable to the CPM in a Docker container system environment.
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.
Unless hosting the images in a local image repository, connections to either
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.
To start the CPM, follow the applicable Docker or Kubernetes instructions.
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.
Use these options as applicable:
To get a list of the most commonly used run options directly in the command line interface, run the
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
showcommands can be used to view the
helm show chart YOUR_REPO_NAME/synthetics-minion
helm show values YOUR_REPO_NAME/synthetics-minion
To show the licensing information for the open source software that we use in the CPM, run the
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.
You can configure the containerized private minion with custom npm 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
--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.
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:
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.
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
Communicate with Synthetics via a proxy
To set up communication with New Relic by proxy, use the environment variables named
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.