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.

Before you begin

Before you configure address groups, you must first enable the Network Security API networksecurity.googleapis.com.

IAM roles

To create and manage an address group, you need the Compute Network Admin role (roles/compute.networkAdmin). 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.

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

Use project-scoped address groups

The following sections explain how to create and modify project-scoped address groups, and how to use project-scoped address groups with your security policies.

Create or modify project-scoped address groups

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

Create a project-scoped 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.

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

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

Add items to a project-scoped 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.

 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 a project-scoped 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.

 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 a project-scoped 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:

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

Use project-scoped 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 MALICIOUS_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('MALICIOUS_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('MALICIOUS_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('MALICIOUS_IPS', origin.ip, [66.249.77.32/27, 66.249.77.64/27])
   

Use an address group to match against user IP addresses

To use an address group to match against originating client ("user") IP addresses, you must configure userIpRequestHeaders[] in the security policy.

It's important to note that in the following conditions, you receive the source IP address of the request and not the IP address of the originating client because the value of origin.user_ip defaults to the value of origin.ip:

• You don't configure the userIpRequestHeaders[] option.
• The configured headers aren't present.
• The configured headers contain invalid IP address values.

For this example, imagine that you have an IP address group called MALICIOUS_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('MALICIOUS_IPS', origin.user_ip)

For more information about user IP addresses, see Attributes.

Use organization-scoped address groups

The following sections explain how to create and modify organization-scoped address groups, and how to use organization-scoped address groups with your security policies.

Create or modify organization-scoped address groups

Organization-scoped address groups can be used with both service-level security policies and hierarchical security policies.

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

Create an organization-scoped 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.

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

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

Add items to an organization-scoped address group

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

 gcloud network-security org-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 organization-scoped address group

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

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

Delete an organization-scoped address group

You can't delete an organization-scoped 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:

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

Use organization-scoped 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 two different ways to use address groups.

Deny a group of IP addresses for all backend services in an organization

For this example, imagine that you have an organization-scoped IP address group called MALICIOUS_IPS with 10,000 IP addresses that you know are malicious. You can deny all of these IP addresses for all of the backend services in your organization by using a single hierarchical security policy. Create a hierarchical security policy, then add a deny rule with the following match condition:

evaluateOrganizationAddressGroup('MALICIOUS_IPS', origin.ip)

Finally, associate the hierarchical security policy to all of the backend services in your organization, replacing POLICY_NAME with the name of your hierarchical security policy and ORGANIZATION_ID with the ID of your organization:

  gcloud beta compute org-security-policies associations create \
      --security-policy=POLICY_NAME \
      --organization=ORGANIZATION_ID

Reuse a group of IP address ranges for all backend services within an organization

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 the non-web crawler IP addresses from accessing all of the backend services in your organization, but you want to allow project-scoped security policies to determine whether the web crawlers can access your 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 BACKEND_POLICY_1.

2. Add a deny rule to BACKEND_POLICY_1 with the following match condition, which blocks all of the IP addresses in MALICIOUS_IPS:

   evaluateOrganizationAddressGroup('MALICIOUS_IPS', origin.ip)
   

3. Use the following command to associate BACKEND_POLICY_1 with BACKEND_SERVICE_1:

    gcloud compute backend-services update BACKEND_SERVICE_1 \
        --security-policy BACKEND_POLICY_1
   

4. Create a second backend security policy called BACKEND_POLICY_2.

5. Add a deny rule to BACKEND_POLICY_2 with the following match condition, which blocks all of the IP addresses in MALICIOUS_IPS except for 66.249.77.32/27 and 66.249.77.64/27:

   evaluateOrganizationAddressGroup('MALICIOUS_IPS', origin.ip, [`66.249.77.32/27`, `66.249.77.64/27`])
   

6. Use the following command to associate BACKEND_POLICY_2 with BACKEND_SERVICE_2. Replace ORG_ID with the ID of your organization:

    gcloud compute backend-services update BACKEND_SERVICE_2 \
        --security-policy BACKEND_POLICY_2
   

Use an address group to match against user IP addresses for all backend services in an organization

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

evaluateOrganizationAddressGroup('MALICIOUS_IPS', origin.user_ip)

For more information about user IP addresses, see Attributes.

What's next

• Configure custom rules language attributes