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.

Use the following example gcloud beta 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 beta 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 beta 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 gcloud beta network-security address-groups add-items command. You provide a comma-separated list of items with the --item flag. 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:

gcloud beta 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 gcloud beta network-security address-groups remove-items command. 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 beta 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 security policy.

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

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

You can't delete an address group if it is referenced by a resource, including a security policy.

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

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