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:

You may not modify any CPM files and New Relic is not liable for any modifications you make.

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 package.json, following the npm official guidelines, in the root of the mounted directory. Anything contained in the dependencies field will be installed by the CPM at start, and made available when running monitors on that private minion.

    Optionally, you can override the root level package.json with a Node version-specific directory. This allows a script to be updated per monitor runtime if a Node version of a runtime is no longer compatible with your dependencies. See an example of this below.

    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
          }
        }
    
    Example: Node version-specific overrides

    You can declare a package.json per Node version that will override the root level package.json. This allows a monitor script to be updated per monitor runtime in the event that the Node version of a runtime is no longer compatible with your dependencies. As shown in the first example, local modules can still be defined within a version specific directory. If a package.json is not defined for a specific Node version, then the root level package.json will be used to install dependencies.

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

        /example-custom-modules-dir/
          ├── 6.11.2            ⇦ optional Node specific directory
          │   └── package.json
          └── 10.15.0           ⇦ optional Node specific directory
          │   └── package.json
          ├── counter
          │   ├── index.js
          │   └── package.json
          └── package.json      ⇦ the only mandatory file
  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 at 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 ...
       

User-defined environment variables for scripted monitors

Containerized private minions let you configure environment variables for use in scripted monitors. These variables are hosted locally on the CPM and can be accessed from scripts via the$env.USER_DEFINED_VARIABLES object. There are two ways to set user-defined variables: by mounting a JSON file or by supplying an environment variable to the CPM on launch. If both are provided, the CPM will use values provided from environment only.

Example: Mounting JSON File

The JSON file must have read permissions and contain a JSON formatted map.

Example user-defined variable file:

{
“KEY” : “VALUE”,
“User_Name”: ”MINION”,
“My_Password”: ”PASSW0RD 1 2 3”,
“my_URL”: ”https://newrelic.com/”,
“ECT” : “ECT ...”
}

The file must be mounted to the docker container at /var/lib/newrelic/synthetics/variables/user_defined_variables.json

docker run ... -v /example-user-defined-variables.json:/var/lib/newrelic/synthetics/variables/user_defined_variables.json:rw ...
Example: Passing as an environment variable

Using the -e flag to set up an environment variable named MINION_USER_DEFINED_VARIABLES and give it a value of a JSON formatted map string.

docker run ... -e MINION_USER_DEFINED_ENV_VARIABLES="{“KEY”:”VALUE”,”NAME”:”MINION”, “ECT”:”ect…” }" ...

Accessing user-defined environment variables from scripts

To reference a configured user-defined environment variable, use the reserved New Relic $env.USER_DEFINED_VARIABLES object followed by the name of a given variable with dot notation.

For example, $env.USER_DEFINED_VARIABLES.MY_VARIABLE

User-defined environment variables are not sanitized from logs. For sensitive information, consider using the secure credentials feature.

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 following list 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

For US-based accounts, the endpoint is: https://synthetics-horde.nr-data.net.

For EU-based accounts, the endpoint is: https://synthetics-horde.eu01.nr-data.net/

Ensure your CPM can connect to the appropriate endpoint in order to serve your monitor.

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_USER_DEFINED_ENV_VARIABLES

Format: Example.

A locally hosted set of user defined key value pairs.

2.2.4
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: