Skip to content

Commit

Permalink
Merge pull request #16572 from kondracek-nr/kondracek/user-defined-vars
Browse files Browse the repository at this point in the history 
[synthetics-job-manager] add user-facing docs for user-defined variables feature
  • Loading branch information
@homelessbirds
homelessbirds committed Apr 1, 2024
2 parents a4590b6 + a879aec commit 49c2974
Show file tree
Hide file tree
Showing 2 changed files with 217 additions and 39 deletions.
217 changes: 212 additions & 5 deletions ...synthetics/synthetic-monitoring/private-locations/job-manager-configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,136 @@ redirects:
freshnessValidatedDate: never
---

Learn how to configure your [synthetics job manager](/docs/synthetics/synthetic-monitoring/private-locations/install-job-manager) by using [environment variables](#environment-variables) in your configuration.
This doc will guide you through configuring your [synthetics job manager](/docs/synthetics/synthetic-monitoring/private-locations/install-job-manager) by showing you how to:

* Provide [user-defined variables](#user-defined-vars) in your configuration.
* Update other [environment-variables](#environment-variables) when launching your synthetics job manager.

## User-defined variables for scripted monitors [#user-defined-vars]
Private synthetics job managers let you configure environment variables for scripted monitors. These variables are managed locally on the SJM and can be accessed via `$env.USER_DEFINED_VARIABLES`. You can set user-defined variables in two ways. You can mount a JSON file or you can supply an environment variable to the SJM on launch. If both are provided, the SJM will only use values provided by the environment.

<Callout variant="important">
[Custom modules](/docs/synthetics/synthetic-monitoring/private-locations/containerized-private-minion-cpm-configuration/#custom-modules), [permanent data storage](/docs/synthetics/synthetic-monitoring/private-locations/containerized-private-minion-cpm-configuration/#permanent-data-volume), and [user defined environment variables](/docs/synthetics/synthetic-monitoring/private-locations/containerized-private-minion-cpm-configuration/#vars-scripted-monitors) are not supported for the synthetics job manager at this time.
<CollapserGroup>
<Collapser
id="user-file-example"
title="Mounting JSON file"
>
The user may create a JSON-formatted file and mount the volume where the file is located to a specified target path in the SJM container.

The file must have read permissions and contain a JSON-formatted map. Example user-defined variables file:

```
{
"KEY": "VALUE",
"user_name": "MINION",
"my_password": "PASSW0RD123",
"my_URL": "https://newrelic.com/",
"ETC": "ETC"
}
```

Place the file in the source directory on the host. The SJM is expecting the file name to be user_defined_variables.json

Docker example:

The expected target directory is: `/var/lib/newrelic/synthetics/variables/`

```
docker run ... -v /variables:/var/lib/newrelic/synthetics/variables:rw ...
```

Kubernetes example:

The user has two options when providing a file to the SJM pod in Kubernetes. They may:
1. pass in a local file.
2. provide a PersistentVolume that includes the user_defined_variables.json.

### Pass in a local file
This option creates a ConfigMap Kubernetes resource and mounts that to the SJM pod.

```
helm install newrelic/synthetics-job-manager ... --set-file "synthetics.userDefinedVariables.userDefinedFile=[local-path]/user_defined_variables.json" ...
```

### Mount a PersistentVolume
This option requires the user to provide a PersistentVolume that includes the user_defined_variables.json file or a PersistentVolumeClaim to the same. For more details on helm chart installation using a PersistentVolume, follow the instructions at [permanent data storage](/docs/synthetics/synthetic-monitoring/private-locations/job-manager-configuration#permanent-data-storage).

Once the user has prepared a PersistentVolume as described below, launch the SJM, setting the path where the user_defined_variables.json file is located and setting any other `synthetics.persistence` variables as necessary.

```
helm install newrelic/synthetics-job-manger ... --set synthetics.userDefinedVariables.userDefinedPath="variables"
```
</Collapser>

<Collapser
id="passing-env-var"
title="Passing as an environment variable"
>
The variables may be passed to their respective container system via environment variable.
Docker example:

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

```
docker run ... -e USER_DEFINED_VARIABLES='{"key":"value","name":"sjm"}' ...
```

Kubernetes example:
Use the `--set-literal` flag to pass in the JSON formatted string.
```
helm install newrelic/synthetics-job-manager ... --set-literal synthetics.userDefinedVariables.userDefinedJson='{"key":"value","name":"sjm"}' ...
```
</Collapser>
</CollapserGroup>

### Accessing user-defined environment variables from scripts [#env-vars-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`

<Callout variant="caution">
User-defined environment variables are not sanitized from logs. Consider using the [secure credentials](/docs/synthetics/new-relic-synthetics/using-monitors/secure-credentials-store-credentials-information-scripted-browsers) feature for sensitive information.
</Callout>

As a note, New Relic is not liable for any modifications you make to the synthetics job manager files.
## Permanent data storage [#permanent-data-storage]

Users may want to use permanent data storage to provide the `user_defined_variables.json` file or support custom node modules (not yet available to private Synthetics Job Managers).

### Docker

To set permanent data storage on Docker:

1. Create a directory on the host where you are launching the Job Manager. This is your source directory.
2. Launch the Job Manager, mounting the source directory to the target directory `/var/lib/newrelic/synthetics`.


Example:

```
docker run ... -v /sjm-volume:/var/lib/newrelic/synthetics:rw ...
```

### Kubernetes

To set permanent data storage on Kubernetes, the user has two options:

1. Provide an existing PersistentVolumeClaim (PVC) for an existing PersistentVolume (PV), setting the `synthetics.persistence.existingClaimName` configuration value.

Example:

```
helm install ... --set synthetics.persistence.existingClaimName=sjm-claim ...
```

2. Provide an existing PersistentVolume (PV) name, setting the `synthetics.persistence.existingVolumeName` configuration value. Helm will generate a PVC for the user.

The user may optionally set the following values as well:
- `synthetics.persistence.storageClass`: the storage class of the existing PV. If not provided, Kubernetes will use the default storage class.
- `synthetics.persistence.size`: the size for the claim. If not set, the default is currently 2Gi.

```
helm install ... --set synthetics.persistence.existingVolumeName=sjm-volume --set synthetics.persistence.storageClass=standard ...
```

## Environment variables [#environment-variables]

Expand Down Expand Up @@ -180,7 +303,7 @@ Environmental variables allow you to fine-tune the synthetics job manager config
<td>
Default: `INFO.`

Additional options: `WARN`, `ERROR`
Additional options: `WARN`, `ERROR`, `DEBUG`
</td>
</tr>
<tr>
Expand Down Expand Up @@ -214,6 +337,16 @@ Environmental variables allow you to fine-tune the synthetics job manager config
</td>
</tr>

<tr>
<td>
`USER_DEFINED_VARIABLES`
</td>

<td>
A locally hosted set of user defined key value pairs.
</td>
</tr>

</tbody>
</table>
</Collapser>
Expand Down Expand Up @@ -411,6 +544,76 @@ Environmental variables allow you to fine-tune the synthetics job manager config
</td>
</tr>

<tr>
<td>
`synthetics.userDefinedVariables.userDefinedJson`
</td>

<td>
A JSON string of user-defined variables. The user may access these variables in their script. Format: `'{"key":"value","key2":"value2"}'`.
</td>
</tr>

<tr>
<td>
`synthetics.userDefinedVariables.userDefinedFile`
</td>

<td>
A path local to the user to a JSON file containing user-defined variables. This is passed in via `--set-file` and cannot be set in the Values file.
</td>
</tr>

<tr>
<td>
`synthetics.userDefinedVariables.userDefinedPath`
</td>

<td>
A path on the user's provided PersistentVolume to the user_defined_variables.json file. User must provide a PersistentVolume or PersistentVolumeClaim if this variable is populated.
</td>
</tr>

<tr>
<td>
`synthetics.persistence.existingClaimName`
</td>

<td>
If mounting a volume, the user may provide a name for a PersistentVolumeClaim that already exists in the cluster. Presumes the existence of an corresponding PersistentVolume.
</td>
</tr>

<tr>
<td>
`synthetics.persistence.existingVolumeName`
</td>

<td>
If mounting a volume and not providing a PersistentVolumeClaim, the user must at minimum provide a PersistentVolume name. Helm will generate a PersistentVolumeClaim.
</td>
</tr>

<tr>
<td>
`synthetics.persistence.storageClass`
</td>

<td>
The name of the StorageClass for the generated PersistentVolumeClaim. This should match the StorageClassName on the existing PV. If not providers, Kubernetes will use the default storage class if present.
</td>
</tr>

<tr>
<td>
`synthetics.persistence.size`
</td>

<td>
The size of the volume for the generated PersistentVolumeClaim. Format: `10Gi`. Default 2Gi.
</td>
</tr>

<tr>
<td>
`global.checkTimeout`
Expand Down Expand Up @@ -745,3 +948,7 @@ It's important to note that the `completions` value should not be too large or t
```
8m40s Warning TooManyMissedTimes cronjob/synthetics-node-browser-runtime too many missed start times: 101. Set or decrease .spec.startingDeadlineSeconds or check clock skew
```

<Callout variant="tip">
Please keep in mine that New Relic is not liable for any modifications you make to the synthetics job manager files.
</Callout>
39 changes: 5 additions & 34 deletions ...thetics/synthetic-monitoring/private-locations/job-manager-transition-guide.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,55 +101,26 @@ Some capabilities require a minimum version of job manager and runtime container
Node browser runtime v2.2.22
</td>
</tr>

<tr>
<td>
Broken links monitor
</td>

<td>
release-341
</td>

<td>
Node API runtime v1.2.54
</td>
</tr>

<tr>
<td>
Certifiate check monitor
User-Defined Variables
</td>

<td>
release-341
</td>

<td>
Node API runtime v1.2.54
</td>
</tr>

<tr>
<td>
VSE support
</td>

<td>
release-345
release-347
</td>

<td>
N/A
</td>
</tr>

</tbody>
</table>

## Limitations [#limitations]

A few capabilities available to CPMs aren't supported by synthetics job manager. We'll include these features in the upcoming months and update this page as they become available. They include:
A few capabilities available to CPMs aren't supported by synthetics job manager. We'll include these features in the upcoming months and update this page as they become available. They include:

* User defined environment variables
* Support for SSL certificate expiration and broken link monitors
* Verified script execution (VSE)
* Custom node modules

0 comments on commit 49c2974

Please sign in to comment.