Configure address groups

Address groups let you combine multiple IP addresses and IP address ranges into a single named logical unit, which you can use across multiple products. This document shows you how to use address groups with Google Cloud Armor security policies. You need an active Google Cloud Armor Enterprise subscription to use address groups.

IAM roles

To create and manage an address group, you need the Network Administrator role (compute.networkAdmin) or the Security Administrator role (compute.securityAdmin). You can also define a custom role with an equivalent set of permissions.

The following table provides a list of Identity and Access Management (IAM) permissions required to perform a set of tasks on address groups.

Task	IAM role name	IAM permissions
Create and manage address groups	compute.networkAdmin compute.securityAdmin	networksecurity.addressGroups.*
Discover and view address groups	compute.networkUser	networksecurity.addressGroups.list networksecurity.addressGroups.get networksecurity.addressGroups.use

For more information about which roles include specific IAM permissions, see the IAM permissions reference.

Create or modify address groups

The following sections explain how to create address groups, how to add and remove addresses from address groups, and how to delete address groups.

Create an address group

When you create an address group, you must specify its capacity and IP address version using the --capacity and --type flags respectively. You cannot change these values after you create the address group.

In addition, the maximum capacity for Google Cloud Armor might be higher than the maximum capacity for other products, like Cloud Next Generation Firewall. Therefore, if you want to use the same address group across more than one product, you must set the capacity to be less than or equal to the lowest maximum capacity among those products.

Console

1. In the Google Cloud console, go to the Address groups page.

   Go to Address groups

2. In the project selector menu, if available, select your project.

3. Click Create Address Group.

4. In the Name field, enter a name.

5. (Optional): In the Description field, add a description.

6. For Scope, choose Global.

7. For Type, choose IPv4 or IPv6.

8. For Purpose, choose Cloud Armor; alternatively, choose Firewall and Cloud Armor if you also plan to use the address group with Cloud Next Generation Firewall policies.

   For more information about choosing a purpose, see address group specification.

9. In the Capacity field, enter the capacity of the address group.

   Note: After the address group capacity is set, it cannot be changed. Make sure that you set the capacity to an appropriate value based on your use case.

10. In the IP Addresses field, list the IP addresses or IP ranges that you want to include in the address group separated by commas. For example, 1.1.1.0/24,1.2.0.0.

    Note: The number of IP addresses or IP ranges cannot exceed the configured capacity.

11. Click Create.

gcloud

Use the following example gcloud network-security address-groups create command to create an address group called GROUP_NAME with a capacity of 1,000 IPv4 addresses, which can be used with both Google Cloud Armor or Cloud NGFW:

gcloud network-security address-groups create GROUP_NAME \
  --location global \
  --description  "address group description" \
  --capacity 1000 \
  --type IPv4 \
  --purpose DEFAULT,CLOUD_ARMOR

Alternatively, you can create an address group with a larger capacity by setting the purpose exclusively to CLOUD_ARMOR. In the following example, you create an address group with a capacity of 10,000 IPv6 IP address ranges:

gcloud network-security address-groups create GROUP_NAME \
  --location global \
  --description  "address group description" \
  --capacity 10000 \
  --type IPv6 \
  --purpose CLOUD_ARMOR

Add items to an address group

After you create an address group, you can add items using the Google Cloud console or the gcloud network-security address-groups add-items command.

Console

1. In the Google Cloud console, go to the Address groups page.

   Go to Address groups

2. In the project selector menu, if available, select your project.

3. To edit an address group, click the name of your address group.

4. Click Edit.

5. In the IP Addresses field, add the new items to the comma-separated list of IP addresses. Alternatively, you can click Import addresses to upload a CSV file with a list of IP addresses.

6. Click Save.

gcloud

In the following example, you add the IP addresses 192.168.1.2, 192.168.1.8, and 192.168.1.9 to the address group GROUP_NAME. You provide a comma-separated list of items with the --item flag:

gcloud network-security address-groups add-items GROUP_NAME \
  --location global \
  --items 192.168.1.2,192.168.1.8,192.168.1.9

Remove items from an address group

You can remove items from an address group using the Google Cloud console or the gcloud network-security address-groups remove-items command.

Console

1. In the Google Cloud console, go to the Address groups page.

   Go to Address groups

2. In the project selector menu, if available, select your project.

3. To edit an address group, click the name of your address group.

4. Click Edit.

5. In the IP Addresses field, delete the items that you want to remove from the comma-separated list of IP addresses.

6. Click Save.

gcloud

The following command removes the IP addresses 192.168.1.2, 192.168.1.8, and 192.168.1.9 that you added in the previous command:

gcloud network-security address-groups remove-items GROUP_NAME \
  --location global \
  --items 192.168.1.2,192.168.1.8,192.168.1.9

Delete an address group

You can't delete an address group if it is referenced by a resource, including a firewall policy or security policy. Use the following steps to delete an address group:

Console

1. In the Google Cloud console, go to the Address groups page.

   Go to Address groups

2. In the project selector menu, if available, select your project.

3. Select the checkbox next to the address group that you want to delete. Make sure that the selected address group is not referenced by any firewall or security policy.

4. Click Delete, and then click Delete again to confirm.

gcloud

The following example uses the gcloud network-security address-groups delete command to delete an address group called GROUP_NAME.

gcloud network-security address-groups delete GROUP_NAME \
  --location global

Use address groups with security policies

After you have created an address group and added IP addresses to it, you can use it with any existing Google Cloud Armor backend security policy. The following examples show you a two different ways to use address groups.

Deny a group of IP addresses

For this example, imagine that you have an IP address group called BAD_IPS with 10,000 IP addresses that you know are malicious. You can deny all of these IP addresses using a single security policy deny rule with the following match condition:

evaluateAddressGroup('BAD_IPS', origin.ip)

Reuse a group of IP address ranges in multiple security policies

For this example, imagine that you have the same list of 10,000 IP addresses as in the previous example, but that some of the IP addresses are known to be web crawlers. You want to block all these IP addresses from some backend services, but allow the web crawlers to access other backend services to improve search engine optimization (SEO). Use the following steps to deny all of the addresses access to BACKEND_SERVICE_1, while allowing IP address ranges 66.249.77.32/27 and 66.249.77.64/27 to access BACKEND_SERVICE_2:

1. Create a backend security policy called POLICY_1, and attach it to BACKEND_SERVICE_1.

2. In POLICY_1, create a deny rule with the following match condition:

   evaluateAddressGroup('BAD_IPS', origin.ip)
   

3. Create a second backend security policy called POLICY_2, and attach it to BACKEND_SERVICE_2.

4. In POLICY_2, create a deny rule with the following match condition, which excludes 66.249.77.32/27 and 66.249.77.64/27:

   evaluateAddressGroup('BAD_IPS', origin.ip, [66.249.77.32/27, 66.249.77.64/27])
   

Use an address group to match against user IP addresses

Caution: When you use origin.user_ip as the second argument in evaluateAddressGroup, you must configure userIpRequestHeaders[] in the security policy. The value of origin.user_ip defaults to the value of origin.ip when you meet any of the following conditions:

• You don't configure the userIpRequestHeaders[] option.
• The configured header contains invalid IP address values.
• The configured header is not present.

For this example, imagine that you have an IP address group called BAD_IPS with 10,000 IP addresses that you know are malicious. In addition, you use an upstream proxy, which includes information about the originating clients in the header. You can deny all of these IP addresses using a single security policy deny rule with the following match condition:

evaluateAddressGroup('BAD_IPS', origin.user_ip)

For more information about user IP addresses, see rules language attributes.

What's next

• Configure custom rules language attributes