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.


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

You only need to deploy a single Integration Agent for your entire Gremlin company. While the agent must be authenticated using a team ID and credentials, every team within your company will be able to use the same agent instance.

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.

Accessing your team settings in the Gremlin web app
Viewing your team settings page in the Gremlin web app


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 \
  --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

List older versions of the gremlin integrations agent via: apt list -a gremlin-integrations and install them via apt install gremlin-integrations=x.x.x-x

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

List older versions of the gremlin integrations agent via: yum list available gremlin-integrations --showduplicates and install them via yum install gremlin-integrations-x.x.x-x

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


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 \

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


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

No items found.
This is some text inside of a div block.
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
User Management
Health Checks
Command Line Interface
Updating Gremlin
Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Container security
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Configuring Role Based Access Control (RBAC)
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Managing Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Managing Users
Integration Agent for Linux
Test Suites
Restricting Testing Times
Process Exhaustion Experiment
Enabling DNS collection
Authenticating Users with Microsoft Entra ID (Azure Active Directory) via SAML