Containerized private minion (CPM) configuration

Important

As of August 26, 2024, you can no longer create new monitors using legacy runtimes on public or private locations.

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.

This doc guides you through configuring your containerized private minion (CPM).

You can do the following to customize your CPMs:

Use environment-variables to configure your containerized private minion.
Set up custom modules for scripted API or scripted browser monitors.
Preserve launch data with permanent data storage.

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

Configuration using 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 table shows all the environment variables that CPM supports. MINION_PRIVATE_LOCATION_KEY is required, and all other variables are optional.

Name	Description
`MINION_PRIVATE_LOCATION_KEY`	REQUIRED. UUID of the Private Location, as found on the Private Location Web page.
`DOCKER_API_VERSION`	Format: `"vX.Y"` API version to be used with the given Docker service. Default: `v1.35.`
`DOCKER_HOST`	Points the minion to a given `DOCKER_HOST`. If absent, the default value is `/var/run/docker.sock.`
`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 to serve your monitor.
`MINION_DOCKER_RUNNER_REGISTRY_ENDPOINT`	The Docker Registry and Organization where the Minion Runner image is hosted. Use this to override `quay.io/newrelic` as the default (for example, `docker.io/newrelic`).
`MINION_API_PROXY`	Format: `"host:port"`.
`MINION_API_PROXY_AUTH`	Format: `"username:password"` - Support HTTP Basic Auth + additional authentication protocols supported by Chrome.
`MINION_API_PROXY_SELF_SIGNED_CERT`	Acceptable values: `true`, `1`, or `yes` (any case).
`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)` (for example, from 1 second to 15 minutes). Default: `65 seconds` for ping monitors, `180 seconds` for the other monitor types.
`MINION_DOCKER_API_VERSION`	Synonym of `DOCKER_API_VERSION`.
`MINION_DOCKER_HOST`	Synonym of `DOCKER_HOST.`
`MINION_RUNNER_APPARMOR (CPM version > 3.0.2)` `OR` `MINION_DOCKER_RUNNER_APPARMOR (CPM version <= 3.0.2)`	The AppArmor profile name, if it has been applied to Docker containers running monitor scripts (for example, Docker Runner). The AppArmor profile name must exist and be set up on the machine to work.
`MINION_JVM_MB`	Default: `"2560"` (2.5GB).
`MINION_JVM_OPTS`	Passes command line options to the internal JVM. See Oracle's Java documentation for more information. Default: `-server.`
`MINION_LOG_LEVEL`	When contacting New Relic Support, they may ask you to increase this to `"DEBUG"` or `"TRACE"`. Default: `INFO.`
`MINION_NETWORK_HEALTHCHECK_DISABLED (CPM version >= 3.0.11)`	The Minion Network Healthcheck disabled state, to manage the CPM check for public internet access. The default is 'false', when set as 'true' the CPM will bypass this healthcheck.
`MINION_USER_DEFINED_ENV_VARIABLES`	Format: Example. A locally hosted set of user-defined key-value pairs.
`MINION_HEAVY_WORKERS`	The number of workers the minion will use to run heavy jobs (`BROWSER`, `SCRIPT_BROWSER`, `SCRIPT_API`). If undefined, the minion will use `NUM_CPUS` where `NUM_CPUS` is the number of CPUs available to the minion. The maximum allowed value for this variable is `50`. For more information on monitor types, see Types of synthetic monitors.
`MINION_LIGHTWEIGHT_WORKERS`	The number of workers the minion will use to run lightweight jobs (`SIMPLE` ping jobs). If undefined, the minion will use `25 * NUM_CPUS` where `NUM_CPUS` is the number of CPUs available to the minion. The maximum allowed value for this variable is `1250`. For more information on monitor types, see Types of synthetic monitors.
`MINION_VSE_PASSPHRASE`	If set, enables verified script execution and uses this value as a passphrase.

The variables are provided at startup using the --set argument.

The following list shows all the environment variables that CPM supports. synthetics.privateLocationKey is required, and all other variables are optional.

Name	Description
`synthetics.privateLocationKey`	REQUIRED if `synthetics.privateLocationKeySecretName` is not set. UUID/Private location key of the private location, as found on the private location web page.
`synthetics.privateLocationKeySecretName`	REQUIRED if `synthetics.privateLocationKey` is not set. Name of the Kubernetes secret that contains the key `privateLocationKey`, which contains the authentication key associated with your synthetics private location.
`replicaCount`	Number of replicas to maintain with your StatefulSet installation Default: `1.`
`imagePullSecrets`	The name of the secret object used to pull an image from a specified container registry.
`fullnameOverride`	Name override used for your `StatefulSet` installation, replacing the default.
`appVersionOverride`	Release version of CPM to use instead of the version specified in chart.yml.
`synthetics.minionLogLevel`	If contacting New Relic Support, they may ask you to increase this to `"DEBUG"` or `"TRACE"`. Default: `INFO.`
`synthetics.heavyWorkers`	The number of concurrent workers the minion will use to run heavy jobs (`BROWSER`, `SCRIPT_BROWSER`, `SCRIPT_API`). If undefined, the minion will use the value `2`. The maximum allowed value for this variable is `50`. For more information on monitor types, see Types of synthetic monitors.
`synthetics.lightweightWorkers`	The number of workers the minion will use to run lightweight jobs (`SIMPLE` ping jobs). If undefined, the minion will use `25 * synthetics.heavyWorkers`, where `synthetics.heavyWorkers` is number defined in the previous environment variable. The maximum allowed value for this variable is `1,250`. For more information on monitor types, see Types of synthetic monitors.
`synthetics.minionApiEndpoint`	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 to serve your monitor.
`synthetics.minionDockerRunnerRegistryEndpoint`	The Docker Registry and Organization where the Minion Runner image is hosted. Use this to override `quay.io/newrelic` as the default (for example, `docker.io/newrelic`)
`synthetics.minionVsePassphrase`	If set, it enables verified script execution, and uses this value as a passphrase.
`synthetics.minionVsePassphraseSecretName`	If set, enables verified script execution and uses this value to retrieve the passphrase from a Kubernetes secret with a key called minionVsePassphrase.
`synthetics.minionApiProxy`	Format: `"host:port"`.
`synthetics.minionApiProxySelfSignedCert`	Acceptable values: `true`, `1`, or `yes` (any case).
`synthetics.minionApiProxyAuth`	Format: `"username:password"` - Support HTTP Basic Auth + additional authentication protocols supported by Chrome.
`synthetics.minionCheckTimeout`	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)` (for example, from 1 second to 15 minutes). Default: `65 seconds` for ping monitors, `180 seconds` for the other monitor types.
`synthetics.minionUserDefinedEnvVariable`	Format: Example. A locally hosted set of user-defined key value pairs.
`synthetics.minionJVMOpts`	Passes command line options to the internal JVM. Default: `-server -XX:-UsePerfData`
`synthetics.minionNetworkHealthCheckDisabled (CPM version >= 3.0.11)`	The Minion Network Healthcheck disabled state, to manage the CPM check for public internet access. The default is 'false', when set as 'true' the CPM will bypass this healthcheck.
`image.repository`	The container to pull. Default: `quay.io/newrelic/synthetics-minion`
`image.pullPolicy`	The pull policy. Default: `IfNotPresent`
`persistence.claimName`	The name of the PVC to use. If undefined or not set, `Statefulset` will dynamically create a PVC for each replica.
`persistence.storageClass`	Overrides `StorageClass` for `VolumeClaimTemplates`, relevant only if `claimName` is undefined or empty. For more details see persistent volumes.
`persistence.accessMode`	Access mode to be defined for the PVC, relevant only if `claimName` is undefined or empty. Default: `ReadWriteOnce`.
`persistence.annotations`	Annotations to add to the PVC, relevant only if `claimName` is undefined or empty.
`persistence.size`	Size to be defined for the PVC, relevant only if `claimName` is undefined or empty. Default: `10Gi`.
`persistence.permanentData`	Path on the volume to the permanent data storage directory. For more details, see permanent data storage.
`persistence.customModules`	Path on the volume to the custom modules directory. For more details, see custom modules.
`persistence.userDefinedVariables`	Path on the volume to the `user-defined-variable.json` file. For more details, see user-defined variables.
`serviceAccount.create`	If true, a service account is created and assigned to the deployment. Default: `false`.
`serviceAccount.name`	The service account to assign to the deployment. If `serviceAccount.create` is true, then this name is used when creating the service account.
`serviceAccount.annotations`	The annotations to add to the service account if `serviceAccount.create` is set to `true`.
`removeJobsLog`	Default Kubernetes doesn't include a jobs/log resource. Set this to `true` to remove it from the role if needed. Default: `false`.
`headlessService.serviceName`	The name of the headless service to associate to the `StatefulSet`. If not set a name is generated using the fullname template.
`appArmorProfileName`	The `AppArmor` profile name that will be applied to the Minion and Runner pods. If set, then the AppArmor profile must exist on the Kubernetes node(s) for this to work.
`podSecurityContextRunAsUser`	A UID that can be set to either `0 (root)` or between `[2000, 4000]`, inclusive. If set, runs the CPM as the given UID. Default: `2379`.

Guidelines for mounting volumes

All directories and files must be assigned group ownership as 3729 with read/write permissions. This ensures that the Runner, which uses uid: 1000 and gid: 3729, has access to all the mounted volumes. However, the Minion can run as root (uid: 0) or with any uid between the range of [2000, 4000], inclusive. For more information, see running as non-root in Kubernetes or Docker.

Docker

Directories are mounted onto a container as volumes by specifying a -v argument within docker run
For example, docker run ... -v /path/to/src:/path/to/dest:rw

Kubernetes

It is possible to add a directory onto a persistent volume (PV) by using kubectl cp. However, alternative approaches are supported as long as the file permissions are set appropriately.
For example, kubectl cp /path/to/src <POD_NAME>:/path/to/dest will add a directory onto each PV in the specified pod
Each PV must have a separate copy of the directories. For example, a cluster with n Minion replicas must have n PVs, each with their own copy of directories
The directories and files must be added before the Minion boot-up, otherwise, the Minion must be restarted to detect the updates

Custom node modules

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

To set up the modules:

Create a directory containing a package.json, following the npm official guidelines, in the directory's root. 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.js version-specific directory. This allows a script to be updated per monitor runtime if a Node.js version of a runtime is no longer compatible with your dependencies. See an example of this below.
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 (for example, counter) and any hosted modules (for example, async version ^2.6.1):
{ "name": "custom-modules", "version": "1.0.0", ⇦ optional "description": "example custom modules directory", ⇦ optional "dependencies": { "async": "^2.6.1", ⇦ hosted module "counter": "file:./counter" ⇦ local module } }
You can declare a package.json per Node.js 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.js 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.js 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.js specific directory │ └── package.json └── 10.15.0 ⇦ optional Node.js specific directory │ └── package.json ├── counter │ ├── index.js │ └── package.json └── package.json ⇦ the only mandatory file
Once you create the custom modules directory and the package.json you can apply it to your CPM for Docker and Kubernetes.
For Docker, launch CPM mounting the directory at /var/lib/newrelic/synthetics/modules. For example:
bash
$docker run ... -v /example-custom-modules-dir:/var/lib/newrelic/synthetics/modules:rw ...
Complete the following:
Launch the CPM, setting a value for the persistence.customModules configuration value either in the command line or in a YAML file during installation. The value should specify the subpath on your Minion's Persistent Volume where your custom modules files exist. For example:
bash
$helm install ... --set persistence.customModules=CUSTOM_MODULES_SUBPATH ...
Make sure your custom modules directory is available on the Minion Pod. You can use kubectl cp as one method to copy the directory from your host to the Minion. For example:
bash
$kubectl cp /example-custom-modules-dir NAMESPACE/POD_NAME:/var/lib/newrelic/synthetics/modules
Look at the CPM 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

You can also use Node.js modules along with local and hosted 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.

Caution

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 (for example, Minion_ID), and use it to associate that data with the exact minion that produced it.

To set permanent data storage on Docker:

Create a directory.
Launch the CPM, mounting the directory at /var/lib/newrelic/synthetics.
Example:
bash
```
$docker run ... -v /example-permanent-dir:/var/lib/newrelic/synthetics:rw ...
```

To set permanent data storage on Kubernetes:

Launch the CPM, setting a value for the persistence.permanentData configuration value either in the command line or in a YAML file during installation. The value should specify the subpath on your Minion's Persistent Volume where you want the data to be saved.
Example:
bash
```
$helm install ... --set persistence.permanentData=PERMANENT_DATA_SUBPATH ...
```

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 via $env.USER_DEFINED_VARIABLES. 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 the environment only.

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/",
  "ETC": "ETC"
}

The file must be available or mounted to the path in your container:

/var/lib/newrelic/synthetics/variables/user_defined_variables.json

Docker example:

bash

$docker run ... -v /example-user-defined-variables.json:/var/lib/newrelic/synthetics/variables/user_defined_variables.json:rw ...

Kubernetes example:

When mounting a JSON file to your Minion Pod in Kubernetes, you can either copy the file directly to the Minion Pod or to a Pod that has access to the same Persistent Volume and Persistent Volume Claim that the Minion will use. After successfully loading the file, you may need to restart your Minion Pod for the change to take effect.

bash

$kubectl cp path/to/user_defined_variables.json NAMESPACE/POD_NAME:/var/lib/newrelic/synthetics/variables/user_defined_variables.json

Use 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.

bash

$docker run ... -e MINION_USER_DEFINED_ENV_VARIABLES='{"KEY":"VALUE","NAME":"MINION","ETC":"ETC"}' ...

Tip

The CPM on Kubernetes does not currently support loading user-defined environment variables via environment variable. You will have to configure your Kubernetes CPM by mounting a JSON file.

Accessing user-defined environment variables from scripts

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

For example, $env.USER_DEFINED_VARIABLES.MY_VARIABLE

Caution

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

Containerized private minion (CPM) configuration

Important

Configuration using environment variables

Docker environment configuration

Kubernetes environment configuration

Guidelines for mounting volumes

Custom node modules

Custom module directory

Node.js version-specific overrides

Docker

Kubernetes

Change `package.json` for custom modules

Caution

Permanent data storage

User-defined environment variables for scripted monitors

Mounting JSON file

Passing as an environment variable

Tip

Accessing user-defined environment variables from scripts

Caution

Containerized private minion (CPM) configuration

Important

Configuration using environment variables .css-21sua1{background:none;border:none;width:0;padding:0;}

Kubernetes environment configuration

Guidelines for mounting volumes

Custom node modules

Custom module directory

Node.js version-specific overrides

Docker

Kubernetes

Change package.json for custom modules

Caution

Permanent data storage

User-defined environment variables for scripted monitors

Mounting JSON file

Passing as an environment variable

Accessing user-defined environment variables from scripts

Caution

Configuration using environment variables

Change `package.json` for custom modules