Dashboard
Getting Started

Installing Gremlin on AWS - Configuring your VPC

Amazon Web Services (AWS) has unique networking requirements that must be implemented for Gremlin to run successfully. This article explains how to configure rules for your AWS Virtual Private Cloud (VPC) security groups and network Access Control Lists (ACLs) to allow outbound and inbound network access to the Gremlin API.

Note
You don't need to follow these instructions if your AWS systems can already connect to api.gremlin.com. This article is meant for environments with restrictive networking policies. You can check whether your systems can successfully connect via the hosts page in the Gremlin web appand verifying that your instance is listed with an Active status.

There are two steps to configure a VPC to allow Gremlin traffic: creating prefix lists, and creating network ACL rules.

Prerequisites

This page assumes that you:

  • Have an existing AWS Lambda or EC2 instance that you want to use with Gremlin.
  • Already created and attached a VPC to the instance.

Step 1: Creating security groups and prefix lists

You'll first need to create a prefix list containing the IP addresses for the Gremlin API, then create a security rule containing the prefix list.

Creating a customer-managed prefix list

Create a customer-managed prefix list. This list will contain the CIDR addresses necessary for identifying Gremlin traffic.

  1. For the Prefix list name, enter a name such as "Gremlin API".
  2. For Max entries, enter 2. The Gremlin API only requires two static IP addresses. However, if you use Webhooks or Health Checks, you'll need to add four additional IP addresses for a total of six.
  3. For Address family, select IPv4.
  4. The Prefix list entries, add the following CIDR blocks:
    75.2.112.174
    99.83.220.149
    
  5. Select Create prefix list.
  6. Optionally enter Tags to help identify this prefix.

Creating a security group

Create a Security Group using the Gremlin API prefix created in the previous section.

  1. Open the VPC console at https://console.aws.amazon.com/vpc/.
  2. Select Security groups in the navigation pane, then select Create security group.
  3. For the Name and Description, enter a name such as "Gremlin API".
  4. From VPC, choose the VPC you want to attach the group to.
  5. Add the rule (detailed instructions are available at this link):
  6. ^Under Outbound rules, change All traffic to HTTPS.
  7. ^Using the search box next to Destination, select the managed prefix list you created in the previous section.
  8. ^Optionally, enter a description for this security group (e.g. "Allow outbound HTTPS access to the Gremlin API.")
  9. ^Optionally, add any Tags for this security group.
  10. Click Create security group.
  11. Assign the security group to your EC2 instance by selecting the security group during the instance launch wizard, or by defining the scurity group in a launch template.

To verify that the Gremlin agent can connect to the Gremlin API, open the hosts page in the Gremlin web app and verify that your instance is listed with an Active status.

Step 2: Creating network Access Control Lists (ACLs)

Note
The default ACLs in AWS allow all traffic. Unless your organization specifically uses ACLs, you may not have to complete this step. Learn more about network ACLs and how to check them in the Amazon VPC user guide.

After creating and assigning security groups, the next step is to create network Access Control List (ACL) rules. There are a few key differences between network ACLs and security groups:

  • Network ACLs are attached at the subnet level, not the VPC level. You'll need to identify the specific subnet(s) that your EC2 or Lambda instance is assigned to.
  • ACLs use individual IP addresses, so you'll need to add each Gremlin API address to the ACL.
  • ACLs are stateless—they don't associate inbound network responses with outbound requests. You'll need to open inbound ports as well as outbound ports.

Creating a network ACL

To create a network ACL for the Gremlin API:

  1. Open the VPC console at https://console.aws.amazon.com/vpc/.
  2. Select Network ACLs in the navigation pane.
  3. Select Create Network ACL.
  4. Enter a name for the ACL and select the VPC you want to attach it to.
  5. Optionally, add any tags you want to use to help identify the ACL.

Adding inbound rules to a network ACL

Next, we'll need to add an inbound rule to the ACL. This allows our instance to receive response traffic from the Gremlin API:

  1. Open the ACL you created in the previous step.
  2. Under Inbound Rules, select Edit inbound rules.
  3. Click Add New Rule to start adding a rule.
  4. Enter a low Rule number. Lower rules are processed before higher numbers. We recommend using a rule number lower than other rules, especially those that block traffic. Note that you can't use the same rule number twice.
  5. In the Type dropdown, select Custom TCP.
  6. In the Port range box, enter the range for all ephemeral ports: 1024-65535. The Gremlin API responds to requests using different ephemeral ports, which is why the ACL must have an inbound rule that allows traffic from these ports.
  7. In the Source field, enter one of the IP addresses for the Gremlin API:
    75.2.112.174
    99.83.220.149
    
  8. Make sure the Allow/Deny box is set to Allow.
  9. Add another rule and repeat these steps for the second Gremlin IP address.
  10. Click Save changes.

Adding outbound rules to a network ACL

Now that we have our inbound rules configured, let's create outbound rules so that our instance can send traffic to the Gremlin API:

  1. Select Outbound Rules, then select Edit outbound rules.
  2. Click Add New Rule to start adding a rule.
  3. Enter a low Rule number. Lower rules are processed before higher numbers. We recommend using a rule number lower than other rules, especially those that block traffic. Note that you can't use the same rule number twice.
  4. In the Type dropdown, select HTTPS (443).
  5. In the Destination field, enter one of the IP addresses for the Gremlin API:
    75.2.112.174
    99.83.220.149
    
  6. Make sure the Allow/Deny box is set to Allow.
  7. Add another rule and repeat these steps for the second Gremlin IP address.
  8. Click Save changes.

Associating the network ACL with a subnet

The final step is to associate the ACL with one or more subnets.

  1. On the Network ACLs page, click on the ACL you want to edit.
  2. Click Subnet associations, then click Edit subnet associations.
  3. Check or uncheck the subnet(s) you want this ACL to apply to, then click Save changes.
No items found.
Previous
This is some text inside of a div block.
Compatibility
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
User Management
Integrations
Health Checks
Notifications
Command Line Interface
Updating Gremlin
Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Targets
Experiments
Scenarios
GameDays
Overview
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Examples
Container security
General
Linux
Windows
Chao
Helm
Glossary
Alfi
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Application Level Fault Injection (ALFI)
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
Jira
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Overview
Overview
Overview
Overview
Overview
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Role Based Access Control
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Slack
Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Users
Webhooks
Integration Agent for Linux
Test Suites
Restricting Testing Times
Reports
Enabling DNS collection