Install containerized private minions (CPMs)

Private minions and locations are an add-on feature for paid Synthetics accounts. For more information, contact your account representative or a New Relic technical sales rep.

This document describes the New Relic containerized private minion (CPM), a Docker based private minion that accepts and runs the jobs you assign to your private locations.

Like the VM private minion (legacy), this is designed to execute Synthetics monitors against your private locations. But while existing private minions are virtual machines (.ovf format), a CPM is a Docker container.

Private minion enhancements

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

  • Easier to install, start, and update
  • Runs on Linux, Mac OS and Windows
  • Improved security and support for non-root user execution
  • Ability to leverage a Docker container as a sandbox environment
  • Multi-locations support: Run multiple CPMs against different private locations on a single host
  • Customizable monitor check timeout
  • Custom provided modules for scripted monitor types

System requirements and compatibility

To host CPMs, your system must meet these minimal requirements:

Compatibility for Requirements
Operating system

Linux kernel: 3.10 or higher

MacOS: 10.11 or higher

Windows: Windows 10 64-bit or higher. See additional recommendations for Windows.

Processor A modern, multi-core CPU
Memory 2.5 GB of RAM per CPU core
Disk Space A minimum of 10 GB per host
Docker version Docker 17.03 or higher
Private location key You must have a private location key

If running on Windows: CPMs can run on Windows, if configured to run Linux containers. Linux containers on Windows (LCOW) is an experimental feature under active development, and New Relic does not recommend running a CPM on Windows. New Relic Support will be unable to help with any issues you encounter when running the CPM on Windows.

If running on Windows is a constraint for your environment, ensure you read Docker's official documentation on Docker for Windows: What to know before you install, Shared drives, and Shared drives on demand.

Private location key (required)

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

If you currently have no private locations, see Create a private location

To find the key for existing private location:

  1. Go to https://synthetics.newrelic.com > 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 key icon.

Sandboxing and Docker dependencies

The CPM runs in Docker and is able to leverage Docker as a sandboxing technology. This ensures complete isolation of the monitor execution, which improves security, reliability, and repeatability. Every time a monitor is executed, the CPM creates a brand new Docker container to run in.

The minion container needs to be configured to communicate with the Docker engine in order to spawn additional containers. Each spawned container is then dedicated to run a check associated with the Synthetics monitor running on the private location the minion container is associated with.

There are two crucial dependencies required to be provided at launch. To enable sandboxing, ensure your:

  1. Writable directory is mounted at /tmp. The writable directory can be any directory you want the CPM to write into, but New Relic recommends the system's own /tmp to make things easy.

  2. Writable Docker UNIX socket is mounted at /var/run/docker.sock or DOCKER_HOST environment variable. For more information, see Docker's Daemon socket option.

For additional information on sandboxing and running as a root or non-root user, see Security, sandboxing, and running as non-root.

Install and update CPM versions

Both installing and updating the CPM are done by pulling the latest Docker image from the Quay.io repository that the CPM Docker image is hosted on. The command for installing and updating is the same for both cases. Go to quay.io/repository/newrelic/synthetics-minion for a list of all the releases.

To install a new CPM version or update CPM versions:

  1. Ensure you meet the system requirements.
  2. Stop your container and ensure a CPM instance is not already running.
  3. To override and update any existing CPM versions already on your system, pull the image and run:
      docker pull quay.io/newrelic/synthetics-minion:latest
    
  4. If installing, enable the CPM with the copy/paste method.

Be sure to periodically check your docker disk usage to preserve space. See docker's documentation on how to manage docker and how to remove images.

Enable CPM with copy/paste method

To enable with the copy/paste method, Docker service needs to be installed and running. After you've installed the new CPM version, run the following:

  docker run \
    -e "MINION_PRIVATE_LOCATION_KEY=YOUR_PRIVATE_LOCATION_KEY" \
    -v /tmp:/tmp:rw \
    -v /var/run/docker.sock:/var/run/docker.sock:rw \
    quay.io/newrelic/synthetics-minion:latest

Start the CPM

To start the CPM:

  1. Locate your private location key.
  2. Ensure you've enabled Docker dependencies for sandboxing and installed CPM on your system.
  3. Run the appropriate script for your system. Tailor the common defaults for /tmp and /var/run/docker.sock in the following examples to match your system.

    Linux/MacOS
      docker run \
        --name YOUR_CONTAINER_NAME \
        -e "MINION_PRIVATE_LOCATION_KEY=YOUR_PRIVATE_LOCATION_KEY" \
        -v /tmp:/tmp:rw \
        -v /var/run/docker.sock:/var/run/docker.sock:rw \
        -p 8080:8080 -p 8180:8180 \
        quay.io/newrelic/synthetics-minion:latest
    
    Windows
      docker run ^
        --name YOUR_CONTAINER_NAME ^
        -e "MINION_PRIVATE_LOCATION_KEY=YOUR_PRIVATE_LOCATION_KEY" ^
        -v /tmp:/tmp:rw ^
        -v /var/run/docker.sock:/var/run/docker.sock:rw ^
        -p 8080:8080 -p 8180:8180 ^
        quay.io/newrelic/synthetics-minion:latest
    
  4. Once a message similar to Synthetics Minion is ready and servicing location YOUR_PRIVATE_LOCATION_LABEL appears, your CPM is up and ready to run monitors assigned to that location.

Stop the CPM

You can stop a Docker container either by the container name, or the container ID:

Container name stop

For Linux, MacOS, and Windows:

  docker stop YOUR_CONTAINER_NAME
  docker rm YOUR_CONTAINER_NAME
Container ID stop for Linux/MacOS

In the examples the container is stopped and removed. To only stop the container, omit docker rm $CONTAINER_ID.

  CONTAINER_ID=$(docker ps -aqf name=YOUR_CONTAINER_NAME)
  docker stop $CONTAINER_ID
  docker rm $CONTAINER_ID
Container ID stop for Windows

In the examples the container is stopped and removed. To only stop the container, omit docker rm $CONTAINER_ID.

  FOR /F "tokens=*" %%CID IN ('docker ps -aqf name=YOUR_CONTAINER_NAME') do (SET CONTAINER_ID=%%CID)
  docker stop %CONTAINER_ID%
  docker rm %CONTAINER_ID%

Show help and examples

Running the show help command provides a list of the most commonly used run options directly in the command line interface. Run the following command to show CPM usage examples as well as the list of all the available run options:

  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.

Configure CPM

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.

Security, sandboxing, and running as non-root

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

For more information, see Docker's official documentation about security and AppArmor security profiles.

To change the default AppArmor profile used by containers that CPM spawns to run monitors, see the environment variable MINION_DOCKER_RUNNER_APPARMOR.

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

Run as non-root user

If your environment requires you to run the CPM as a non-root user, this can be achieved if a couple of conditions are fulfilled.

In the following scenario, the non-root user is my_user.

  1. my_user must be able to use the Docker engine on the host. This can be done by ensuring my_user belongs to the "docker" system group (see related doc) OR by enabling the Docker TCP socket option and passing the DOCKER_HOST environment variable to CPM
  2. my_user must have read/write permission to all the directory/volumes passed to CPM. chmod is the command to tweak these permissions.

Once the conditions are met, use the option "[-u | --user] <name|uid>[:<group|gid>]" when launching CPM:

  docker run ... -u my_user ...

OR

  docker run ... -u my_user -e DOCKER_HOST=http://localhost:2375 ...

Docker image repository

The CPM 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

Connection Description
CPMs without Internet access A CPM can operate without access to the internet, but with some exceptions. 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 Synthetics 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 Synthetics by proxy, use the environment variables named MINION_API_PROXY*
Arguments passed at launch 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.

For more help

Recommendations for learning more: