Manage firewall endpoints and endpoint associations

This page explains how to manage a firewall endpoint and its associations with a Virtual Private Cloud (VPC) network by using the Google Cloud console and Google Cloud CLI.

For more information about firewall endpoints, see Firewall endpoint overview. To create a firewall endpoint, see Create firewall endpoints.

Before you begin

Before you manage firewall endpoints and associations, complete the following:

1. Ensure that you have a VPC network and a subnet.
2. Enable the required APIs:
   • Compute Engine API (Compute Engine API) in your Google Cloud project.
   • Network Security API in the Google Cloud project that you want to use for billing.
   • Certificate Authority Service API in your Google Cloud project.
3. Install the gcloud CLI if you want to run gcloud command-line examples.

Roles and permissions

To get the permissions that you need to view, update, or delete firewall endpoints and associations, ask your administrator to grant you the necessary Identity and Access Management (IAM) roles on your organization or project. For more information, see Manage access.

To check the progress of the operations listed on this page, ensure that your user account has the Compute Network User (roles/compute.networkUser) role, which includes the following permissions:

• networksecurity.operations.get
• networksecurity.operations.list

Quotas

To view quotas for firewall endpoints and associations, see Quotas and limits.

Manage organization-level endpoints

In this section, learn to manage the firewall endpoints that are defined at organization-level.

View organization-level endpoints

To view the details of an organization-level firewall endpoint, use the Google Cloud console or the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.get

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the organization level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your organization where the endpoint was activated.

   The Firewall endpoints page lists all the configured firewall endpoints in the organization.

3. Click the name of the firewall endpoint to view its details.

gcloud

To view details of a firewall endpoint, use the gcloud network-security firewall-endpoints describe command:

gcloud network-security firewall-endpoints \
    describe NAME \
    --organization ORGANIZATION_ID \
    --zone ZONE

Replace the following:

• NAME: the name of the firewall endpoint.

• ORGANIZATION_ID: the organization where the endpoint is activated.

• ZONE: the zone where the endpoint is activated.

List organization-level endpoints

To list all organization-level firewall endpoints, use the Google Cloud console or the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.list

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the organization level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your organization where the endpoint was activated.

3. The Firewall endpoints page lists all the configured firewall endpoints.

gcloud

To list all firewall endpoints, use the gcloud network-security firewall-endpoints list command:

gcloud network-security firewall-endpoints list \
    --organization ORGANIZATION_ID \
    --zone ZONE \
    --billing-project BILLING_PROJECT_ID

Replace the following:

• ORGANIZATION_ID: the organization where the endpoint is activated.

• ZONE: the zone where the endpoint is activated. To list endpoints in all zones, use -.

• BILLING_PROJECT_ID: an optional Google Cloud project ID that will be charged quota for the operation. This is required only for organization-level firewall endpoints.

Update organization-level endpoint

To update an organization-level firewall endpoint, use the Google Cloud console or the gcloud CLI. You can also update the billing project of a firewall endpoint in an organization.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.get

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the organization level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your organization where the endpoint was activated.

   The Firewall endpoints page lists all the configured firewall endpoints.

3. Click the name of the firewall endpoint to view its details.

4. Click Edit.

5. In the Billing project list, select the Google Cloud project that you want to use for billing the firewall endpoint.

6. Click Save.

gcloud

To update a firewall endpoint, use the gcloud network-security firewall-endpoints update command:

gcloud network-security firewall-endpoints \
    update NAME \
    --organization ORGANIZATION_ID \
    --zone ZONE \
    --billing-project BILLING_PROJECT_ID

Replace the following:

• NAME: the name of the firewall endpoint.

• ORGANIZATION_ID: the organization where the endpoint is activated.

• ZONE: the zone where the endpoint is activated.

• BILLING_PROJECT_ID: the Google Cloud project ID that you want to associate with this firewall endpoint for billing. This is required only for organization-level firewall endpoints.

Note: You can't reconfigure an existing endpoint to add or remove support for jumbo frames. To add or remove jumbo frame support, delete the endpoint and recreate it. For more information, see Delete a firewall endpoint and Create a firewall endpoint.

For information about the packet sizes supported by firewall endpoints, see Supported packet size.

Delete organization-level endpoints

You can delete a firewall endpoint by specifying its name, zone, and organization or project.

Note: You can delete a firewall endpoint only if it is not associated with any VPC network.

To delete an organization-level firewall endpoint, use the Google Cloud console or the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.delete

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the organization level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your organization where the endpoint was activated.

3. Select the firewall endpoint, and then click Delete.

4. Click Delete again to confirm.

gcloud

To delete a firewall endpoint, use the gcloud network-security firewall-endpoints delete command:

gcloud network-security firewall-endpoints delete NAME
    --organization ORGANIZATION_ID \
    --zone ZONE

Replace the following:

• NAME: the name of the firewall endpoint.

• ORGANIZATION_ID: the organization where the endpoint is activated.

• ZONE: the zone where the endpoint is activated.

Manage project-level endpoints

In this section, learn to manage the firewall endpoints that are defined at project-level.

View project-level endpoints

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To view the details of a project-level firewall endpoint, use the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.get

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the project level or the organization level

gcloud

To view details of a firewall endpoint, use the gcloud beta network-security firewall-endpoints describe command:

gcloud beta network-security firewall-endpoints \
    describe NAME \
    --project PROJECT_ID \
    --zone ZONE

Replace the following:

• NAME: the name of the firewall endpoint.

• PROJECT_ID: the project where the endpoint is activated.

• ZONE: the zone where the endpoint is activated.

List project-level endpoints

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To list all project-level firewall endpoints, use the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.list

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the project level or the organization level

gcloud

To list all firewall endpoints, use the gcloud beta network-security firewall-endpoints list command:

gcloud beta network-security firewall-endpoints list \
    --project PROJECT_ID \
    --zone ZONE

Replace the following:

• PROJECT_ID: the project where the endpoint is activated.

• ZONE: the zone where the endpoint is activated. To list endpoints in all zones, use -.

Update project-level endpoint

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To update a project-level firewall endpoint, use the gcloud CLI. You can manage labels or update the description for a firewall endpoint.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.get

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at project level or the organization level

gcloud

To update a firewall endpoint, use the gcloud beta network-security firewall-endpoints update command:

gcloud beta network-security firewall-endpoints \
    update NAME \
    --project PROJECT_ID \
    --zone ZONE

Replace the following:

• NAME: the name of the firewall endpoint.

• PROJECT_ID: the project where the endpoint is activated.

• ZONE: the zone where the endpoint is activated.

Note: You can't reconfigure an existing endpoint to add or remove support for jumbo frames. To add or remove jumbo frame support, delete the endpoint and recreate it. For more information, see Delete a firewall endpoint and Create a firewall endpoint.

For information about the packet sizes supported by firewall endpoints, see Supported packet size.

Delete project-level endpoints

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To delete a project-level firewall endpoint, use the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your organization.

Permissions

• networksecurity.firewallEndpoints.delete

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) granted at the project level or the organization level

gcloud

To delete a firewall endpoint, use the gcloud network-security firewall-endpoints delete command:

gcloud beta network-security firewall-endpoints delete NAME
    --project PROJECT_ID \
    --zone ZONE

Replace the following:

• NAME: the name of the firewall endpoint.

• PROJECT_ID: the project where the endpoint is activated.

• ZONE: the zone where the endpoint is activated.

Manage firewall endpoint associations

A firewall endpoint association connects a firewall endpoint to a VPC network in a specific zone.

Ensure that you have a firewall endpoint before you manage its associations. To create an association, see Create firewall endpoints and associations.

Association requirements

When you configure endpoint associations, follow these requirements:

• Zone constraints: You must create the association in the same zone as the firewall endpoint. For effective traffic inspection, create associations in zones where your compute instances are deployed.
• One endpoint per zone: In a single zone, you can associate a VPC network with only one firewall endpoint (either project-level (Preview) or organization-level). However, you can associate a single VPC network with different firewall endpoints across multiple, different zones.
• Cross-project associations: You can associate a VPC network with a firewall endpoint in a separate project.
  • If you use a project-level endpoint (Preview), the endpoint's project must reside in the same organization as the VPC network.
• Resource mapping: An association is a project-level resource. You create the association within the specific project where your compute instances are deployed, even if the association points to an organization-level firewall endpoint.

A firewall endpoint with jumbo frame support can accept packets only up to 8,500 bytes. Alternatively, a firewall endpoint without jumbo frame support can accept packets only up to 1,460 bytes. If you need URL filtering service or intrusion detection and prevention service, we recommend that you configure the associated VPC networks to use the maximum transmission unit (MTU) limits of 8,500 bytes and 1,460 bytes. For more information, see Supported packet size.

Caution: A firewall endpoint doesn't perform URL filtering service or intrusion detection and prevention service for a VPC network if the network is configured with an MTU that's greater than the firewall endpoint's limit.

View a firewall endpoint association

To view details of an organization-level firewall endpoint association or a project-level firewall endpoint association, use the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your project.

Permissions

• networksecurity.firewallEndpointAssociations.get

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) at the organization level or the project level

gcloud

To view a firewall endpoint association, use the gcloud network-security firewall-endpoint-associations describe command.

Organization-level firewall endpoint

gcloud network-security firewall-endpoint-associations \
    describe NAME \
    --zone ZONE \
    [ --project PROJECT_ID ]

Project-level firewall endpoint

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

gcloud beta network-security firewall-endpoint-associations \
    describe NAME \
    --zone ZONE \
    [ --project PROJECT_ID ]

Replace the following:

• NAME: the name of the firewall endpoint association.

• ZONE: the zone of the firewall endpoint association.

• PROJECT_ID: the Google Cloud project ID where the association is created.

List all firewall endpoint associations

To list all organization-level firewall endpoint associations, use Google Cloud console or the gcloud CLI. To list all project-level firewall endpoint association, use the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your project.

Permissions

• networksecurity.firewallEndpointAssociations.list

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Compute Network User (roles/compute.networkUser)
• Compute Network Viewer (roles/compute.networkViewer)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) at the organization level or the project level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your Google Cloud project.

   In the Firewall endpoint associations section, the table lists all the configured firewall endpoint associations for this project.

gcloud

To list firewall endpoint associations for a specific network, use the gcloud network-security firewall-endpoint-associations list command with the --filter flag.

Organization-level firewall endpoint

gcloud network-security firewall-endpoint-associations list \
    --filter network:NETWORK_NAME \
    [ --project PROJECT_ID ]

Project-level firewall endpoint

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

gcloud beta network-security firewall-endpoint-associations list \
    --filter network:NETWORK_NAME \
    [ --project PROJECT_ID ]

Replace the following:

• NETWORK_NAME: the name of the VPC network.
• PROJECT_ID: the Google Cloud project ID where the firewall endpoint association is created.

Edit a firewall endpoint association

To edit an organization-level firewall endpoint association, use Google Cloud console or the gcloud CLI. To edit a project-level firewall endpoint association, use the gcloud CLI.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your project.

Permissions

• networksecurity.firewallEndpointAssociations.update

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) at the organization level or the project level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your Google Cloud project.

   In the Firewall endpoint associations section, the table lists all the configured firewall endpoint associations for this project.

3. Next to the firewall endpoint association that you want to update, click Edit.

4. To disable the firewall endpoint association, clear the Enable association checkbox.

5. To update the TLS inspection policy, select a new policy from the TLS inspection policy list.

6. Click Save.

gcloud

To update a firewall endpoint association, use the gcloud network-security firewall-endpoint-associations update command.

Organization-level firewall endpoint

gcloud network-security firewall-endpoint-associations
    update NAME \
    --zone ZONE \
    --project PROJECT_ID \
    [ --disabled ] \
    [ --tls-inspection-policy projects/TLS_PROJECT_NAME/locations/REGION_NAME/tlsInspectionPolicies/TLS_POLICY_NAME ]

Project-level firewall endpoint

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

gcloud beta network-security firewall-endpoint-associations
    update NAME \
    --zone ZONE \
    --project PROJECT_ID \
    [ --disabled ] \
    [ --tls-inspection-policy projects/TLS_PROJECT_NAME/locations/REGION_NAME/tlsInspectionPolicies/TLS_POLICY_NAME ]

Replace the following:

• NAME: the name of the firewall endpoint association.

• ZONE: the zone of the firewall endpoint association.

• PROJECT_ID: the Google Cloud project ID where the association is created.

• TLS_PROJECT_NAME: the Google Cloud project name of the TLS inspection policy.

• REGION_NAME: the region name of the TLS inspection policy.

• TLS_POLICY_NAME: the name of the TLS inspection policy.

Delete a firewall endpoint association

To delete an organization-level firewall endpoint association, use Google Cloud console or the gcloud CLI. To delete a project-level firewall endpoint association, use the gcloud CLI.

When a Google Cloud project is deleted, its associated firewall endpoint associations are automatically removed. This deletion is irreversible, even if the project is later restored.

However, the deletion process for these associations might sometimes fail. If this happens and the project is restored, the associated firewall endpoints appear in ORPHAN state within the restored project. This indicates the broken link between the project and its resources due to the unsuccessful deletion.

You can view these orphaned associations on the Google Cloud console, however, you can't edit these associations. Cloud Next Generation Firewall periodically runs a background process that deletes these orphaned resources.

Permissions required for this task

To perform this task, you must have been granted the following permissions or one of the following IAM roles on your project.

Permissions

• networksecurity.firewallEndpointAssociations.delete

Roles

• Compute Network Admin (roles/compute.networkAdmin)
• Firewall Endpoint Admin (roles/networksecurity.firewallEndpointAdmin) at the organization level or the project level

Console

1. In the Google Cloud console, go to the Firewall endpoints page.

   Go to Firewall endpoints

2. In the project selector menu, select your Google Cloud project.

   In the Firewall endpoint associations section, the table lists all the configured firewall endpoint associations for this project.

3. Select the firewall endpoint association, and then click Delete.

4. Click Delete again to confirm.

gcloud

To delete a firewall endpoint association, use the gcloud network-security firewall-endpoint-associations delete command.

Organization-level firewall endpoint

gcloud network-security firewall-endpoint-associations \
    delete NAME \
    --zone ZONE \
    --project PROJECT_ID

Project-level firewall endpoint

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

gcloud beta network-security firewall-endpoint-associations \
    delete NAME \
    --zone ZONE \
    --project PROJECT_ID

Replace the following:

• NAME: the name of the firewall endpoint association.

• ZONE: the zone of the firewall endpoint association.

• PROJECT_ID: the Google Cloud project ID where the association is created.

What's next

• Create firewall endpoints and associations
• Use hierarchical firewall policies and rules
• Use global network firewall policies and rules