Containerized private minion (CPM) configuration

This document describes how to configure your containerized private minion (CPM).

You can do the following to customize your CPMs:

Custom npm modules

Custom npm modules are exclusive to CPM. They allow you to provide an arbitrary set of npm modules, and make them available for scripted monitors in Synthetics.

To set up the modules:

  1. Mount a directory to CPM on the Docker host. The directory must have read/write permissions, and contain a single file package.json created following the npm official guidelines.

    Anything contained in the "dependencies" field will be installed by the CPM at start, and made available when running monitors on that private minion.

    Example custom module directory

    In this example, a custom module directory is used with the following structure:

        /example-custom-modules-dir/
          ├── counter
          │   ├── index.js
          │   └── package.json
          └── package.json            ⇦ the only mandatory file
      

    The package.json defines "dependencies" as both a local module (i.e. "counter") and an npm hosted modules (i.e. "async" version ^2.6.1):

        {
          "name": "custom-modules",
          "version": "1.0.0",                                 ⇦ optional
          "description": "example custom modules directory",  ⇦ optional
          "dependencies": {
            "async": "^2.6.1",                                ⇦ npm hosted module
            "counter": "file:./counter"                       ⇦ Local module
          }
        }
    
  2. Once you have created the custom module directory and the package.json on the Docker host, launch CPM mounting the directory at /var/lib/newrelic/synthetics/modules:

      docker run ... -v /example-custom-modules-dir:/var/lib/newrelic/synthetics/modules:rw ...
    
  3. Look into the docker logs for "... Initialization of Custom Modules ..." to see if the modules were installed properly, or if there were any errors. The npm installation logs will be shown.

    Now you can add "require('async');" into the script of monitors you send to this private location.

Change package.json for custom modules

Along with npm modules, you can also use Node.js modules. To change the custom modules used by your CPM, modify package.json and reboot the CPM. It will detect the change in configuration during the reboot, and then clean up and re-install.

Local modules: While your package.json can include any local module, these modules must reside inside the tree under your custom module directory. If stored outside the tree, the initialization process will fail and you will see an error message in the docker logs after launching CPM.

Permanent data storage

CPM is a stateless application and does not preserve information from prior requests or sessions by default. However, you can preserve data between launches by enabling permanent data storage. For example, you can permanently set how the minion identifies itself (e.g. Minion_ID), and use it to associate the data visible in Synthetics and Insights events with the exact minion that produced it.

To set permanent data storage:

  1. Create a directory.
  2. Launch CPM, mounting the directory at /var/lib/newrelic/synthetics.

    For example:

      docker run ... -v /example-permanent-dir:/var/lib/newrelic/synthetics:rw ...
    

Environment variables

Environmental variables allow you to fine-tune the CPM configuration to meet your specific environmental and functional needs. The variables are provided at startup using the -e, --env argument.

The list below shows all the environment variables that CPM supports. MINION_PRIVATE_LOCATION_KEY is required, and all other variables are optional.

Name Description Since
MINION_PRIVATE_LOCATION_KEY REQUIRED. UUID of the Private Location, as found on the Private Location Web page. 2.0.0
DOCKER_API_VERSION Format: "vX.Y" API version to be used with the given Docker service.

Default: v1.35.

2.0.0
DOCKER_HOST Points the minion to a given DOCKER_HOST. If absent, the default value is /var/run/docker.sock. 2.0.0
MINION_API_ENDPOINT Default: https://synthetics-horde.nr-data.net. 2.0.0
MINION_DOCKER_RUNNER_REGISTRY_ENDPOINT The Docker Registry where the Minion Runner image is hosted. Use this to override quay.io as the default. (ex. docker.io) 2.1.0
MINION_API_PROXY Format: "host:port". 2.0.0
MINION_API_PROXY_AUTH Format: "username:password" - Support HTTP Basic Auth + additional authentication protocols supported by Chrome. 2.0.0
MINION_API_PROXY_SELF_SIGNED_CERT Acceptable values: true, 1, or yes (any case). 2.0.0
MINION_CHECK_TIMEOUT

The maximum amount of seconds that your monitor checks are allowed to run. This value must be an integer between 0 seconds (excluded) and 900 seconds (included) (i.e. from 1 second to 15 minutes).

Default: 65 seconds for ping monitors, 180 seconds for the other monitor types.

2.0.0
MINION_DOCKER_API_VERSION Synonym of DOCKER_API_VERSION. 2.0.0
MINION_DOCKER_HOST Synonym of DOCKER_HOST. 2.0.0
MINION_DOCKER_RUNNER_APPARMOR

The AppArmor profile name, if it has been applied to Docker containers running monitor scripts (i.e. Docker Runner). The AppArmor profile name must exist and be set up on the machine to work.

2.0.0
MINION_JVM_MB Default: "2560" (2.5GB). 2.0.0
MINION_JVM_OPTS Passes command line options to the internal JVM. See Oracle's Java documentation for more information.

Default: -server.

2.0.0
MINION_LOG_LEVEL When contacting New Relic Support, they may ask you to increase this to "DEBUG" or "TRACE".

Default: INFO.

2.0.0
MINION_VSE_PASSPHRASE​ If set, enables verified script execution and uses this value as a passphrase. 2.0.4

For more help

Recommendations for learning more: