Create and manage IP allowlists

IP allowlists, also called CIDR range lists, let you restrict access to HCP Terraform resources based on source IP addresses. Use IP allowlists to enhance security by ensuring that only requests from approved IP addresses can access your infrastructure.

Overview

IP allowlists define sets of IP address ranges in CIDR notation that are permitted to access specific HCP Terraform resources. When you configure an IP allowlist, HCP Terraform checks the source IP address of incoming requests and only allows access if the IP address matches one of the ranges in the allowlist.

Create an IP allowlist

To create an IP allowlist:

1. Open your organization's settings, then click IP allowlists in the Security section.

2. Click Create IP allowlist.

3. Specify a name for the allowlist and add an optional description.

4. Click Add IP addresses. IP addresses must be in CIDR notation.

5. Add an optional description for each address.

6. Toggle the Enable option for each IP address to enable or disable the address in the list. When an address is enabled, it is part of the allowlist and can access HCP Terraform resources. IP addresses added to the list are enabled by default.

7. Enable one of the following scope options. Refer to Enforcement scopes for more information:

   • Entire organization: This allowlist applies to an entire organization, excluding agent pools.
   • Apply to all agent pools: The allowlist applies to all agent pools in the organization. This is the default.
   • Apply to specific agent pools: This allowlist applies to specific agent pools. Refer to Assign agent pools for additional instructions.

8. Click Save IP allowlist to finish.

Assign agent pools

For IP allowlists with Apply to selected agent pools scope, you can explicitly assign agent pools to the allowlist. Only requests to the assigned agent pools are subject to the IP restrictions.

To assign agent pools:

1. Create an IP allowlist with Apply to selected agent pools scope
2. Search for an agent pool from the Agent Pools drop-down menu in the Enforce on section.
3. Verify that the agent pools are correctly associated, then click Save IP allowlist.

Manage CIDR ranges

CIDR (classless inter-domain routing) ranges define blocks of IP addresses using a base IP address and a prefix length.

1. Open your organization's settings, then click IP allowlists in the Security section.
2. Click on an allowlist containing the ranges you want to manage. You can use the search bar to find a specific list.
3. Click Edit, then open the ellipses menu for an address you want to manage.
4. You can enable, disable, or delete the address. When enabled, the range is actively enforced. When disabled, the range is temporarily inactive but not deleted.
5. Click Save IP allowlist to save your changes.

This allows you to quickly enable or disable specific IP ranges without removing them from the allowlist.

Enforcement scopes

IP allowlists support the following enforcement scopes that determine where the allowlist applies.

Organization scope

Enable the Entire organization scope to apply the IP allowlist to all workspaces in your organization. This provides centralized control over IP-based access restrictions.

Organization-scoped IP allowlists have the following key characteristics:

• Only one organization-scoped IP allowlist is allowed per organization
• Applies to all resources, except agent pools, within the organization
• Provides the broadest level of IP restriction

Use organization-scoped allowlists when you want to enforce a single set of IP restrictions across your entire HCP Terraform organization. However, an organization scope does not apply to agent pool resources. You must also apply an allowlist scoped to the agent pool.

All agent pools scope

Enable the Apply to all agent pools scope to apply an IP allowlist to all agent pools in your organization. This is the default scope.

This scope has the following key characteristics:

• You can create multiple IP allowlists scoped to all agent pools in the organization
• Applies to all agent pools in the organization

Specific agent pools scope

Enable the Apply to specific agent pools scope to apply IP allowlists to specific agent pools.

IP allowlists scoped to specific agent pools have the following key characteristics:

• You can create multiple IP allowlists
• You explicitly assign agent pools to each allowlist

Use this scope when you need granular control over which agent pools should have IP restrictions.

Update IP allowlists

1. Open your organization's settings, then click IP allowlists in the Security section.
2. Click on an allowlist you want to manage. You can use the search bar to find a specific list.
3. Click Edit. You can perform the following actions:
   • Rename the allowlist
   • Update the description
   • Manage a CIDR range
   • Click Add IP address to add more CIDR ranges to the allowlist
   • Change the enforcement scope. When you change the enforcement scope to Entire organization or Apply to all agent pools, HCP Terraform automatically removes any existing agent pool assignments.
4. Click Save IP allowlist to save your changes.

Delete IP allowlists

Deleting an IP allowlist removes all IP restrictions associated with it. Before deleting an IP allowlist, ensure that removing the restrictions won't inadvertently grant access to unauthorized IP addresses.

To delete an IP allowlist:

1. Open your organization's settings, then click IP allowlists in the Security section.
2. Click the name of the IP allowlist that you want to delete.
3. Click Delete IP allowlist.
4. Confirm deletion in the confirmation modal.

Limitations

• Only one organization-scoped IP allowlist is allowed per organization
• Changing an IP allowlist's enforcement scope to Entire organization or Apply to all agent pools removes all agent pool assignments
• The Entire organization enforcement scope does not apply to the organization's agent pools.