Install synthetics job manager

To view versions, dependencies, default values for how many runtime pods start with each synthetics job manager and more, please see Show help and examples below.

1. Locate your private location key.

2. Ensure you've enabled Docker dependencies for sandboxing and installed synthetics job manager on your system.

3. Run the appropriate script for your system. Tailor the common default /var/run/docker.sock in the following examples to match your system.

   • Linux/macOS:

     bash

     Copy

     $
     docker run \
     >
         --name YOUR_CONTAINER_NAME \
     >
         -e "PRIVATE_LOCATION_KEY=YOUR_PRIVATE_LOCATION_KEY" \
     >
         -v /var/run/docker.sock:/var/run/docker.sock:rw \
     >
         -d \
     >
         --restart unless-stopped \
     >
         newrelic/synthetics-job-manager:latest

   • Windows:

     bash

     Copy

     $
     docker run ^
     $
         --name YOUR_CONTAINER_NAME ^
     $
         -e "PRIVATE_LOCATION_KEY=YOUR_PRIVATE_LOCATION_KEY" ^
     $
         -v /var/run/docker.sock:/var/run/docker.sock:rw ^
     $
         -d ^
     $
         --restart unless-stopped ^
     $
         newrelic/synthetics-job-manager:latest

   View the logs for your minion container:

   bash

   Copy

   $
   docker logs --follow YOUR_CONTAINER_NAME

1. Locate your private location key.

2. Ensure you've enabled Podman dependencies for sandboxing and installed synthetics job manager on your system.

3. Run the below script for your system.

   To create a pod in Linux and add the host machine's IP address:

   podman pod create --network slirp4netns --name YOUR_POD_NAME --add-host=podman.service:IP_ADDRESS

   Copy

   To start tart the Job Manager:

   podman run \
   --name YOUR_CONTAINER_NAME \
   --pod YOUR_POD_NAME \
   -e "PRIVATE_LOCATION_KEY=YOUR_PRIVATE_LOCATION_KEY" \
   -e "CONTAINER_ENGINE=PODMAN" \
   -e "PODMAN_API_SERVICE_PORT=YOUR_PODMAN_API_SERVICE_PORT" \
   -e "PODMAN_POD_NAME=YOUR_POD_NAME" \
   -d \
   --restart unless-stopped \
   newrelic/synthetics-job-manager:latest

   Copy

   To view the logs for your minion container:

   podman logs --follow YOUR_CONTAINER_NAME

   Copy

1. Locate your private location key.

2. Set up the a namespace for the synthetics job manager in your Kubernetes cluster:

   bash

   Copy

   $
   kubectl create namespace YOUR_NAMESPACE

3. Copy the Helm charts from the New Relic Helm repo.

   • If you are copying the charts for the first time:

     bash

     Copy

     $
     helm repo add YOUR_REPO_NAME https://helm-charts.newrelic.com

   • If you previously copied the Helm charts from the New Relic Helm repo, then get the latest:

     bash

     Copy

     $
     helm repo update

4. Install synthetics job manager with the following Helm command:

   • For a fresh installation of the synthetics job manager:

     helm install YOUR_JOB_MANAGER_NAME YOUR_REPO_NAME/synthetics-job-manager -n YOUR_NAMESPACE --set synthetics.privateLocationKey=YOUR_PRIVATE_LOCATION_KEY

     Copy

   • To update an existing synthetics job manager installation:

     bash

     Copy

     $
     helm upgrade YOUR_JOB_MANAGER_NAME YOUR_REPO_NAME/synthetics-job-manager -n YOUR_NAMESPACE --set synthetics.privateLocationKey=YOUR_PRIVATE_LOCATION_KEY

5. Check if the synthetics job manager pod is up and running:

   bash

   Copy

   $
   kubectl get -n YOUR_NAMESPACE pods

   Once the status attribute of each pod is shown as running, your synthetics job manager is up and ready to run monitors assigned to your private location.

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

• Container name stop for Linux, macOS, and Windows:

  bash

  Copy

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

  bash

  Copy

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

  bash

  Copy

  $
  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%

You can stop a Podman container either by the container name, or the container ID.

• Container name stop for Linux:

  podman stop YOUR_CONTAINER_NAME
  podman rm YOUR_CONTAINER_NAME

  Copy

• Container ID stop for Linux:

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

  CONTAINER_ID=$(podman ps -aqf name=YOUR_CONTAINER_NAME)
  podman stop $CONTAINER_ID
  podman rm $CONTAINER_ID

  Copy

1. Get the JOB_MANAGER_POD_INSTALLATION_NAME of the synthetics job manager pod you want to delete:

   bash

   Copy

   $
   helm list -n YOUR_NAMESPACE

2. Delete the minion pod:

   bash

   Copy

   $
   helm uninstall -n YOUR_NAMESPACE JOB_MANAGER_POD_INSTALLATION_NAME

3. Delete the namespace set up for the synthetics job manager in your Kubernetes cluster:

   bash

   Copy

   $
   kubectl delete namespace YOUR_NAMESPACE

The synthetics job manager 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 scripted or browser monitor is executed, the synthetics job manager creates a brand new Docker container to run it in using the matching runtime.

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

There is a crucial dependency at launch. To enable sandboxing, ensure that:

• Your 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.

  Caution

  Core count on the host determines how many runtime containers the synthetics job manager can run concurrently on the host. Since memory requirements are scaled to the expected count of runtime containers, we recommend not running multiple synthetics job managers on the same host to avoid resource contention.

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

The synthetics job manager runs in Podman and is able to leverage Podman as a sandboxing technology. This ensures complete isolation of the monitor execution, which improves security, reliability, and repeatability. Every time a scripted or browser monitor is executed, the synthetics job manager creates a brand new Podman container to run it in using the matching runtime.

The synthetics job manager container needs to be configured to communicate with the Podman engine in order to spawn additional runtime containers. Each spawned container is then dedicated to run a check associated with the synthetic monitor running on the private location the synthetics job manager container is associated with.

There is a crucial dependency at launch. To enable sandboxing, ensure that you have:

1. Installed the Podman 5.0.0-ce or higher.

2. Enabled the Rootless execution:

   • Set up Podman to run containers without requiring root privileges.

     mkdir -p ~/.config/containers
     touch ~/.config/containers/containers.conf
     vi ~/.config/containers/containers.conf

     Copy
   • Edit the containers.conf file to configure Podman to use crun and systemd:

     [engine]
     runtime = "crun"
     cgroup_manager = "systemd"

     Copy

3. Enabled the cgroups v2 (RHEL Only):

   • Edit the GRUB to enable cgroups v2, this ensures compatibility with modern container runtimes in RHEL.

     sudo sed -i 's/GRUB_CMDLINE_LINUX="/&systemd.unified_cgroup_hierarchy=1 /' /etc/default/grub
     sudo grub2-mkconfig -o /boot/grub2/grub.cfg
     sudo reboot

     Copy

4. Enabled the system-wide delegation to allow cgroups delegation for the Podman services.

   sudo mkdir -p /etc/systemd/system/user@.service.d/
   echo -e "[Service]\nDelegate=yes" | sudo tee /etc/systemd/system/user@.service.d/delegate.conf > /dev/null

   Copy

5. Set up the user-level systemd service:

   • Create directories for the user-level systemd services.

     mkdir -p ~/.config/systemd/user/podman.service.d

     Copy
   • Add delegate configuration to the user-level systemd service.

     echo -e "[Service]\nDelegate=yes" > ~/.config/systemd/user/podman.service.d/override.conf

     Copy

6. Enabled and started the Podman socket.

   systemctl --user enable podman.socket
   systemctl --user start podman.socket
   systemctl --user status podman.socket

   Copy

7. Created and configured the Podman API service:

   • Create a Podman API service, sets up Podman to provide HTTP API access.

     mkdir -p ~/.config/systemd/user
     touch ~/.config/systemd/user/podman-api.service
     vi ~/.config/systemd/user/podman-api.service

     Copy

   • Define the service to expose the Podman's API at port 8000.

     [Unit]
     Description=Podman API Service
     After=default.target
     
     [Service]
     Type=simple
     ExecStart=/usr/bin/podman system service -t 0 tcp:0.0.0.0:8000
     Restart=on-failure
     
     [Install]
     WantedBy=default.target

     Copy

8. Enabled and started the Podman API service.

   systemctl --user daemon-reload
   systemctl --user enable podman-api.service
   systemctl --user start podman-api.service
   systemctl --user status podman-api.service

   Copy

   Caution

   Core count on the host determines how many runtime containers the synthetics job manager can run concurrently on the host. Since memory requirements are scaled to the expected count of runtime containers, we recommend not running multiple synthetics job managers on the same host to avoid resource contention.

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

If your environment requires you to run the synthetics job manager as a non-root user, follow this procedure. In the following example, the non-root user is my_user.

1. Ensure that my_user can use the Docker engine on the host:

   Verify that my_user belongs to the "docker" system group. Scoped root access to the docker.sock is still needed to create bridge networks.

   OR

   Enable the Docker TCP socket option, and pass the DOCKER_HOST environment variable to synthetics job manager.

2. Verify that my_user has read/write permissions to all the directories and volumes passed to synthetics job manager. To set these permission, use the chmod command.

3. Get the uid of my_user for use in the run command: id -u my_user.

   Once these conditions are met, use the option "-u <uid>:<gid>" when launching synthetics job manager:

   bash

   Copy

   $
   docker run ... -u 1002 ...

   OR

   bash

   Copy

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

Use these options as applicable:

• To keep track of Docker or Podman logs and verify the health of your monitors, see synthetics job manager maintenance and monitoring.

• For a synthetics job manager in the Kubernetes container orchestration system environment, the following Helm show commands can be used to view the chart.yaml and the values.yaml, respectively:

  bash

  Copy

  $
  helm show chart YOUR_REPO_NAME/synthetics-job-manager

  bash

  Copy

  $
  helm show values YOUR_REPO_NAME/synthetics-job-manager

Some of our open-source software is listed under multiple software licenses, and in that case we have listed the license we've chosen to use. Our license information is also available in the our licenses documentation.

For both Docker and Kubernetes, the synthetics job manager and its runtime containers will inherit network settings from the host. For an example of this on a Docker container system environment, see the Docker site.

A bridge network is created for communication between the synthetics job manager and runtime containers. This means networking command options like --network and --dns passed to the synthetics job manager container at launch (such as through Docker run commands on a Docker container system environment) are not inherited or used by the runtime containers.

When these networks are created, they pull from the default IP address pool configured for daemon. For an example of this on a Docker container system environment, see the Docker site.

In case of Podman, we don't use bridge network for communication between the synthetics job manager and runtime containers instead we use a Podman Pod. All containers in a Podman pod share the same network namespace. This means they share the same IP address within that pod. In this case the although the containers share the same IP, their services are exposed on different ports.

A single synthetics job manager Docker image serves the Docker, Podman, and Kubernetes container orchestration system environment. The Docker image is hosted on the Docker Hub. To make sure your Docker image is up-to-date, see the Docker Hub newrelic/synthetics-job-manager repository.