To use address groups, you must first identify the scope of the address group relevant to your requirement. The scope identifies the level at which the address group is applicable in the resource hierarchy.
If you want to use an address group in a firewall policy rule that applies to an individual project, use a project-scoped address group.
If you want to use an address group in a firewall policy rule that is applicable throughout the hierarchy on all resources in an organization or network, use an organization-scoped address group.
Project-scoped address groups
This section provides detailed information about how to manage project-scoped address groups.
Project-scoped address groups are defined at the project level, and only apply to the project where they are created. To use an address group, you must associate it to a firewall rule in a global network firewall policy or regional network firewall policy. The location of the address group must be the same as the location of the firewall policy where it is used.
Create an address group
The container type
of the project-scoped address group is always set to projects
.
When you create an address group, you can specify the name of the address group as a string or as a unique URL identifier. The unique URL for a project-scoped address group can be constructed in the following format:
projects/PROJECT_ID/locations/location/addressGroups/ADDRESS_GROUP_NAME
If you use a unique URL identifier for the address group name, the location of the address group is already included in the URL identifier. However, if you use only the address group name, you must specify the location separately. For more information about unique URL identifiers, see Address group specifications.
An address group can have IPv4 or IPv6 item types, but not both. You must also specify the maximum item capacity for an address group. After the address group is created, you cannot change the name, item type, or item capacity of the address group.
gcloud
gcloud network-security address-groups create NAME \ --type TYPE \ --capacity CAPACITY \ --location LOCATION \ --description DESCRIPTION
Replace the following:
NAME
: the name of the address group; you can specify the name as a string or as a unique URL identifierTYPE
: the type of address group—IPv4 or IPv6CAPACITY
: the capacity of the address groupLOCATION
: the location of the address groupThis can be set to
global
or a region code (such aseurope-west
). If you use a unique URL identifier for thename
parameter, you can omit thelocation
parameter.DESCRIPTION
: an optional description for the address group
Describe an address group
To view the details of an address group, you must specify the name and location of the address group.
gcloud
gcloud network-security address-groups describe NAME \ --location LOCATION
Update an address group description
You cannot update the name, type, or capacity of the address group. You can only update the address group description.
gcloud
gcloud network-security address-groups update NAME \ --description DESCRIPTION \ --location LOCATION
List address groups
You can list all the address groups in a location.
gcloud
gcloud network-security address-groups list \ --location LOCATION
Delete an address group
You can delete an address group by specifying its name and location. However, if the address group is referenced by a firewall policy, that address group cannot be deleted.
gcloud
gcloud network-security address-groups delete NAME \ --location LOCATION
Find address group references
An address group is used by firewall policies. You can find the list of all the firewall policies that use a specific address group.
gcloud
gcloud network-security address-groups list-references NAME \ --location LOCATION
Add items to an address group
You can add multiple items such as IP addresses or IP ranges to an address group. If the request contains items that are already part of the address groups, those items are ignored. If the request contains invalid items, the entire request fails.
gcloud
gcloud network-security address-groups add-items NAME \ --items ITEMS \ --location LOCATION
Replace the following:
NAME
: the name of the address group; you can specify the name as a string or as a unique URL identifierITEMS
: a comma-separated list of IP addresses or IP ranges in CIDR formatLOCATION
: the location of the address groupThis can be set to
global
or a region code (such aseurope-west
). If you use a unique URL identifier for thename
parameter, you can omit thelocation
parameter.
Remove item from an address group
You can remove existing items from an address group. If any of the items in the request are invalid, the request fails. If the request contains items that are not part of the address group, those items are ignored.
gcloud
gcloud network-security address-groups remove-items NAME \ --items ITEMS \ --location LOCATION
Clone items from another address group
You can clone items from one address group to another. To clone an address group, follow these guidelines:
- Both address groups must be of the same type.
- Both address groups must be in the same region.
- Make sure that the new address group has sufficient capacity to fit the items of the source address group that are being cloned.
To specify the source address group, use the following unique URL identifier format:
projects/PROJECT_ID/locations/location/addressGroups/ADDRESS_GROUP_NAME
For more information about unique URL identifiers for address groups, see Address group specifications.
gcloud
gcloud network-security address-groups clone-items NAME \ --source SOURCE_NAMED_LIST \ --location LOCATION
Replace the following:
NAME
: the name of the address group; you can specify the name as a string or as a unique URL identifierSOURCE_NAMED_LIST
: a unique URL identifier of the source address group from where the items are clonedLOCATION
: the location of the destination address groupThis can be set to
global
or a region code (such aseurope-west
). If you use a unique URL identifier for thename
parameter, you can omit thelocation
parameter.
Organization-scoped address groups
This section provides detailed information about how to manage organization-scoped address groups.
Organization-scoped address groups are defined at the organization level and apply to all the resources in the organization as specified in the resource hierarchy. To use an address group, you must associate it to a firewall rule in a hierarchical firewall policy, a global network firewall policy, or a regional network firewall policy.
Create an address group
The container type
of the organization-scoped address group is always set to organization
.
When you create an address group, you can specify the name of the address group as a string or as a unique URL identifier. The unique URL for an organization-scoped address group can be constructed in the following format:
organization/ORGANIZATION_ID/locations/LOCATION/addressGroups/ADDRESS_GROUP_NAME
If you use a unique URL identifier for the address group name, the organization ID or location for the address group is already included in the URL identifier. However, if you use only the address group name, you must specify the ID of the organization and the location where you are defining the address group. For more information about unique URL identifiers, see Address group specifications.
An address group can have IPv4 or IPv6 item types, but not both. You must also specify the maximum item capacity for an address group. After the address group is created, you cannot change the name, item type, or item capacity of the address group.
gcloud
gcloud network-security org-address-groups create NAME \ --organization ORGANIZATION \ --type TYPE \ --capacity CAPACITY \ --location LOCATION \ --description DESCRIPTION
Replace the following:
NAME
: the name of the address group; you can specify the name as a string or as a unique URL identifierORGANIZATION
: the organization ID where the address group is createdIf you use a unique URL identifier for the
name
parameter, you can omit theorganization
parameter.TYPE
: the type of address group—IPv4 or IPv6CAPACITY
: the capacity of the address groupLOCATION
: the location of the address groupThis can be set to
global
or a region code (such aseurope-west
). If you use a unique URL identifier for thename
parameter, you can omit thelocation
parameter.DESCRIPTION
: an optional description for the address group
Describe an address group
You can view the details of a specific address group.
gcloud
gcloud network-security org-address-groups describe NAME \ --organization ORGANIZATION \ --location LOCATION
Update an address group description
You cannot update the name, type, or capacity of the address group. You can only update the address group description.
gcloud
gcloud network-security org-address-groups update NAME \ --organization ORGANIZATION \ --description DESCRIPTION \ --location LOCATION
List address groups
You can list all the address groups in a location.
gcloud
gcloud network-security org-address-groups list \ --organization ORGANIZATION \ --location LOCATION
Delete an address group
You can delete an address group by specifying its name, organization, and location. If the address group is referenced by a firewall policy, that address group cannot be deleted.
gcloud
gcloud network-security org-address-groups delete NAME \ --organization ORGANIZATION \ --location LOCATION
Find address group references
An address group is used by the firewall policies. You can find the list of all the firewall policies that use a specific address group.
gcloud
gcloud network-security org-address-groups list-references NAME \ --organization ORGANIZATION \ --location LOCATION
Add items to an address group
You can add multiple items such as IP addresses or IP ranges to an address group. If the request contains items that are already part of the address group, such items are ignored. If the request contains invalid items, the entire request fails.
gcloud
gcloud network-security org-address-groups add-items NAME \ --organization ORGANIZATION \ --items ITEMS \ --location LOCATION
Replace the following:
NAME
: the name of the address group; you can specify the name as a string or as a unique URL identifierORGANIZATION
: the organization ID where the address group is createdIf you use a unique URL identifier for the
name
parameter, you can omit theorganization
parameter.ITEMS
: a comma-separated list of IP addresses or IP ranges in CIDR formatLOCATION
: the location of the address groupThis can be set to
global
or a region code (such aseurope-west
). If you use a unique URL identifier for thename
parameter, you can omit thelocation
parameter.
Remove item from an address group
You can remove existing items from an address group. If any of the items in the request are invalid, the request fails. If the request contains items that are not part of the address group, those items are ignored.
gcloud
gcloud network-security org-address-groups remove-items NAME \ --organization ORGANIZATION \ --items ITEMS \ --location LOCATION
Clone items from another address group
You can clone items from one address group to another. To clone an address group, follow these guidelines:
- Both address groups must be of the same type.
- Both address groups must be in the same location.
- Make sure that the new address group has sufficient capacity to fit the items of the source address group that are being cloned.
To specify the source address group, you must use the following unique URL identifier:
organization/ORGANIZATION_ID/locations/LOCATION/addressGroups/ADDRESS_GROUP_NAME
For more information about unique URL identifiers for address groups, see Address group specifications.
gcloud
gcloud network-security org-address-groups clone-items NAME \ --organization ORGANIZATION \ --source SOURCE_NAMED_LIST \ --location LOCATION
Replace the following:
NAME
: the name of the address group; you can specify the name as a string or as a unique URL identifierORGANIZATION
: the organization ID where the address group is createdIf you use a unique URL identifier for the
name
parameter, you can omit theorganization
parameter.SOURCE_NAMED_LIST
: a unique URL identifier of the source address group from where the items are clonedLOCATION
: the location of the destination address groupThis can be set to
global
or a region code (such aseurope-west
). If you use a unique URL identifier for thename
parameter, you can omit thelocation
parameter.
What's next
- Use hierarchical firewall policies
- Use global network firewall policies
- Use regional network firewall policies