Integrations

Installation

Integration Agent

Gremlin's Integration Agent must be installed in order to use Private Network Integrations. With Private Network Integrations, you can integrate Gremlin with your observability solutions, testing tools, and other internal systems, all while keeping them contained within your private network. This lets you use the Status Checks and Webhooks features without exposing your internal endpoints to the public Internet. Your team can now experiment safely with increased automation, all while maintaining strong internal security controls.

How it works:

Deploy an Integration Agent into your environment. This agent is separate from our Gremlin agent.
When creating a Status Check or Webhook, enable the "Private Network Endpoint" switch to make it internal instead of external.
When the Status 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 environments running Linux, into container-based infrastructure environments running on Linux, and into virtual infrastructure environments.

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. If you want to restrict the URLs that teams can access using the agent, you can create an allowlist.

Kubernetes

The following is an example of a gremlin-integrations Deployment. It creates a single instance of the gremlin-integrations agent, configured via GREMLIN_TEAM_ID, GREMLIN_TEAM_SECRET, and GREMLIN_INTEGRATION_AGENT_ALLOW_LIST.

yaml

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: gremlin-integrations-deployment
5  labels:
6    app: gremlin-integrations
7spec:
8  replicas: 1
9  selector:
10    matchLabels:
11      app: gremlin-integrations
12  template:
13    metadata:
14      labels:
15        app: gremlin-integrations
16    spec:
17      containers:
18      - name: gremlin-integrations
19        image: gremlin/gremlin-integrations:latest
20        env:
21        - name: GREMLIN_TEAM_ID
22          value: 11111111-1111-1111-1111-111111111111
23        - name: GREMLIN_TEAM_SECRET
24          value: 11111111-1111-1111-1111-111111111111
25        - name: GREMLIN_INTEGRATION_AGENT_ALLOW_LIST
26          # A space separated list of values, which can include regular expressions
27          value: "https://my-check.net/health https://my-other-status-check.net/health"

Docker

In addition to the latest tag, gremlin/gremlin-integrations has a tag for each released version (e.g 0.0.1).

When using Docker, the easiest way to pass configuration is through environment variables.

bash

1export GREMLIN_IDENTIFIER="my-integrations-agent"
2export GREMLIN_TEAM_ID="my-team-id"
3export GREMLIN_TEAM_SECRET="my-team-secret"
4export GREMLIN_INTEGRATION_AGENT_ALLOW_LIST="https://my-allowed-endpoint https://my-other-allowed-endpoint"
5docker run -it \
6  -e GREMLIN_IDENTIFIER \
7  -e GREMLIN_TEAM_ID \
8  -e GREMLIN_TEAM_SECRET \
9  -e GREMLIN_INTEGRATION_AGENT_ALLOW_LIST \
10  gremlin/gremlin-integrations:latest

Alternatively, you can configure your agents with a configuration file.

bash

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

Ubuntu, Debian, etc.

For DEB-based Linux distributions (DEB packages)

bash

1# Add packages needed to install and verify gremlin (already on many systems)
2sudo apt update && sudo apt install -y apt-transport-https dirmngr
3
4# Add the Gremlin repo
5echo "deb https://deb.gremlin.com/ release non-free" | sudo tee /etc/apt/sources.list.d/gremlin.list
6
7# Import the GPG key
8sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 9CDB294B29A5B1E2E00C24C022E8EF3461A50EF6
9
10# Install Gremlin client and daemon
11sudo 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

Amazon Linux, RHEL, CentOS, etc.

For RPM-based Linux distributions (RPM packages)

bash

1# Add the Gremlin repo
2sudo curl https://rpm.gremlin.com/gremlin.repo -o /etc/yum.repos.d/gremlin.repo
3
4# Install Gremlin client and daemon
5sudo 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

Managing Allowlists

You can manage what URLs you allow access to by adding them to the allowlist directly in the agent. These are configured in the integrations-config.yaml configuration file. An allowlist would look like this:

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

Items in the list will be evaluated as regex expressions. Not providing an allowlist will allow for invocations to be executed against any URL.