Private Network Integration Agent

Private Network Integrations lets you use Gremlin's Health Checks and Webhooks features without exposing your internal network endpoints to the public Internet. This lets you integrate Gremlin with your observability solutions, testing tools, and other internal platforms, all while keeping them fully contained within your private network.

Here's how it works:

1. Deploy the Integration Agent into your environment. This agent is separate from our Gremlin agent.
2. When creating a Health Check, set "Is this observability tool behind a firewall or on-prem' to Yes. When creating a Webhook, check "Private Network Endpoint".
3. When the Health Check or Webhook runs, Gremlin runs it from the Integration Agent instead of from our backend systems.

‍

Installation

Gremlin's Integration Agent can be deployed into bare-metal Linux environments, container-based environments running Linux, and into virtual machines.

‍

Choosing team or company scoping

The Integration Agent can be deployed for your entire Gremlin company, or on a per-team basis.

• Company-wide scoping means that every team in your Gremlin company will use the same agent instance. This is useful if all teams in your organization test within the same environment.
• Per-team scoping means that each team uses its own agent independently of other teams. This is useful if your organization's teams use different environments or tools.

By default, the Integration Agent enables team scoping for newly created Gremlin companies. Companies created before this feature will continue using company scoping.

To change your scoping, open the Company Settings page, select the Preferences tab, and enable the Private Network Integrations (PNI) are unique per team checkbox.

‍

Gathering credentials

Just like the regular agent, the Integration Agent requires authentication details to connect to your Gremlin team. Make sure to create and download a certificate pair before continuing. You'll also need your Gremlin team ID, which you can retrieve from the Gremlin web app.

Kubernetes

The Kubernetes version of the Integration Agent is available as a Helm chart.

First, add the Gremlin Helm repository:

helm repo add gremlin https://helm.gremlin.com/

‍

Before running the chart, unzip the ZIP file containing your Gremlin certificates. You'll need to reference the files in here when running the Helm command. In the command below, replace <span class="code-class-custom">/path/to/gremlin.cert</span> and <span class="code-class-custom">/path/to/gremlin.key</span> with the full paths to your certificate and private key files, respectively. You'll also need to replace <span class="code-class-custom">$GREMLIN_TEAM_ID</span> with your actual team ID:

helm install gremlin-integrations gremlin/gremlin-integrations \
  --namespace gremlin \
  --set       gremlin.secret.managed=true \
  --set       gremlin.secret.type=certificate \
  --set       gremlin.secret.teamID=$GREMLIN_TEAM_ID \
  --set-file  gremlin.secret.certificate=/path/to/gremlin.cert \
  --set-file  gremlin.secret.key=/path/to/gremlin.key \
  --set       'tolerations[0].effect=NoSchedule' \
  --set       'tolerations[0].key=node-role.kubernetes.io/master' \
  --set       'tolerations[0].operator=Exists'

‍

For more info on the Helm chart, including additional options, features, and update instructions, see the chart's Github repo.

Ubuntu, Debian, etc.

For DEB-based Linux distributions (DEB packages), use the following commands to install the agent:

# Add packages needed to install and verify gremlin (already on many systems)
sudo apt update && sudo apt install -y apt-transport-https dirmngr

# Add the Gremlin repo
echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list

# Import the GPG key
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6

# Install Gremlin client and daemon
sudo apt update && sudo apt install -y gremlin-integrations

‍

‍

Next, download the configuration file and copy it to <span class="code-class-custom">/etc/gremlin/integrations-config.yaml</span>. Then restart the service:

sudo systemctl restart gremlin-integrations

‍

Amazon Linux, RHEL, CentOS, etc.

For RPM-based Linux distributions (RPM packages)

# Add the Gremlin repo
sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo

# Install Gremlin client and daemon
sudo yum install -y gremlin-integrations

‍

‍

Next, download the configuration file and copy it to <span class="code-class-custom">/etc/gremlin/integrations-config.yaml</span>. Then restart the service:

sudo systemctl restart gremlin-integrations

‍

Docker

While we recommend against using standalone Docker to deploy the Integration Agent (use Kubernetes or install using a package manager), it is possible.

When using Docker, the easiest way to pass configuration is using a client configuration file. A client configuration file is a file generated by Gremlin containing everything needed to connect an agent to your Gremlin account, including your team ID, public key, and private key. Download the configuration file and run the following command:

docker run -it \
  -v /path/to/my/integrations-config.yaml:/etc/gremlin/integrations-config.yaml \
  gremlin/gremlin-integrations:latest

‍

Managing Allowlists

By default, the Integration Agent can send requests to any URL provided by a Gremlin user when setting up a Health Check or Webhook. If you want to restrict which URLs the agent can communicate with, you can use Allowlists. This prevents the agent from accessing any endpoints not included in the list.

You can set up an allow list by adding an <span class="code-class-custom">integration_agent_allow_list</span> array to the agent's configuration file. Each item in the array is a URL pattern. For example, the following allow list will only communicate with port 8080 on <span class="code-class-custom">localhost</span> and port 8080 on <span class="code-class-custom">host.docker.internal</span>:

integration_agent_allow_list:
  - ^http://localhost:8080
  - ^http://host.docker.internal:8080

‍

Items in the list will be evaluated as regex expressions. If you want to allow the agent to communicate with any URL, just remove or comment out the allow list from the configuration file.