Search documentation
Dashboard
Getting Started
Installing gremlin

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.

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.

  • For the Prefix list name, enter a name such as "Gremlin API".
  • 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.
  • For Address family, select IPv4.
  • For Prefix list entries, add the following CIDR blocks:
    175.2.112.174
    299.83.220.149
  • Select Create prefix list.
  • 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.

  • Open the VPC console at https://console.aws.amazon.com/vpc/.
  • Select Security groups in the navigation pane, then select Create security group.
  • For the Name and Description, enter a name such as "Gremlin API".
  • From VPC, choose the VPC you want to attach the group to.
  • Add the rule (detailed instructions are available at this link):
    • Under Outbound rules, change All traffic to HTTPS.
    • Using the search box next to Destination, select the managed prefix list you created in the previous section.
    • Optionally, enter a description for this security group (e.g. "Allow outbound HTTPS access to the Gremlin API.")
    • Optionally, add any Tags for this security group.
  • Click Create security group.
  • 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)

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:

  • Open the VPC console at https://console.aws.amazon.com/vpc/.
  • Select Network ACLs in the navigation pane.
  • Select Create Network ACL.
  • Enter a name for the ACL and select the VPC you want to attach it to.
  • 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:

  • Open the ACL you created in the previous step.
  • Under Inbound Rules, select Edit inbound rules.
  • Click Add New Rule to start adding a rule.
  • 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.
  • In the Type dropdown, select Custom TCP.
  • 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.
  • In the Source field, enter one of the IP addresses for the Gremlin API:
    175.2.112.174
    299.83.220.149
  • Make sure the Allow/Deny box is set to Allow.
  • Add another rule and repeat these steps for the second Gremlin IP address.
  • 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:

  • Select Outbound Rules, then select Edit outbound rules.
  • Click Add New Rule to start adding a rule.
  • 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.
  • In the Type dropdown, select HTTPS (443).
  • In the Destination field, enter one of the IP addresses for the Gremlin API:
    175.2.112.174
    299.83.220.149
  • Make sure the Allow/Deny box is set to Allow.
  • Add another rule and repeat these steps for the second Gremlin IP address.
  • Click Save changes.

Associating the network ACL with a subnet

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

  • On the Network ACLs page, click on the ACL you want to edit.
  • Click Subnet associations, then click Edit subnet associations.
  • Check or uncheck the subnet(s) you want this ACL to apply to, then click Save changes.