Migrate VPC firewall rules that use network tags and service accounts

Your Virtual Private Cloud (VPC) firewall rules can contain network tags and source service accounts. Perform the following tasks to migrate your VPC firewall rules that contain network tags and source service accounts to a global network firewall policy:

Assess your environment.
List existing network tags and service accounts.
Create Tags for each network tag and source service account.
Map the network tags and service accounts to the Tags that you create.
Bind Tags to virtual machine (VM) instances.
Migrate VPC firewall rules to a global network firewall policy.
Review the new network firewall policy.
Complete the postmigration tasks.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine API.

Enable the API

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running

gcloud components
      update

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine API.

Enable the API

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running

gcloud components
      update

Make sure that you have the Compute Security Admin role (roles/compute.securityAdmin).

Assess your environment

Before you migrate your VPC firewall rules to a global network firewall policy, assess your existing environment and Identity and Access Management (IAM) roles and permissions:

Identify the number of VPC firewall rules in your VPC network.
Make a note of the priorities associated with each VPC firewall rule.
Make sure that you have the required IAM roles and permissions to create, associate, modify, and view global network firewall policies.

Make sure that you have the required IAM roles and permissions to create, update, and delete secure Tag definitions.

The following table provides a summary of the various roles that are required to create and manage Tags:

Role name	Tasks performed
Tag Administrator role (`roles/resourcemanager.tagAdmin`)	Create, update, and delete tag definitions. For more information, see Administer tags.
Tag Viewer role (`roles/resourcemanager.tagViewer`)	View tag definitions and tags that are attached to resources.
Tag User role (`roles/resourcemanager.tagUser`)	Add and remove tags that are attached to resources.

List existing network tags and service accounts

Determine whether your VPC firewall rules use any network tags or service accounts, and create a JSON file to save the details of the existing network tags and service accounts.

To export the network tags and service accounts in your network to a mapping JSON file, use the compute firewall-rules migrate command with the --export-tag-mapping flag.

gcloud beta compute firewall-rules migrate \
    --source-network=NETWORK_NAME \
    --export-tag-mapping \
    --tag-mapping-file=TAG_MAPPING_FILE

Replace the following:

NETWORK_NAME: the name of your VPC network containing the VPC firewall rules that you want to migrate.
TAG_MAPPING_FILE: the name of the mapping JSON file.

If your VPC firewall rules contain only service accounts, the generated JSON file contains only service accounts. Similarly, if your VPC firewall rules contain only network tags, the generated JSON file contains only network tags. The service accounts are prefixed with sa, and network tags don't have any prefix.

For example, the following generated JSON file contains a network tag sql-server and a service account example@example.com.

{"sql-server": null, "sa:example@example.com": null}

Create Tags

Based on the network tags and source service accounts listed in the mapping file, you must create the corresponding secure Tags in your network.

The new secure Tags serve as a replacement to the network tags and service accounts and preserve the original network configuration after migration.

As a principal with the Tag Administrator role, for each network tag and service account, create the corresponding secure Tag key-value pair.

gcloud resource-manager tags keys create TAG_KEY \
    --parent organizations/ORGANIZATION_ID \
    --purpose GCE_FIREWALL \
    --purpose-data network=PROJECT_ID/NETWORK_NAME

gcloud resource-manager tags values create TAG_VALUE \
    --parent ORGANIZATION_ID/TAG_KEY

Replace the following:

TAG_KEY: the name of the Tag key.
ORGANIZATION_ID: the ID of your organization.
PROJECT_ID: the ID of your project.
NETWORK_NAME: the name of your VPC network.
TAG_VALUE: the value to assign to the Tag key.

For example, if you have a VPC firewall rule with a network tag called sql-server, create a corresponding secure Tag key-value pair of sql-server:production.

gcloud resource-manager tags keys create sql-server \
    --parent organizations/123456 \
    --purpose GCE_FIREWALL \
    --purpose-data network=test-project/test-network

gcloud resource-manager tags values create production \
   --parent 123456/sql-server

Map network tags and service accounts to Tags

After creating IAM-governed secure Tags for each network tag and service account used by your VPC firewall rules, you must map the Tags to the corresponding network tags and service accounts in the mapping JSON file.

Edit the JSON file to map the network tags and the service accounts to the corresponding secure Tags.

{"sql-server": "tagValues/yyyyy", "sa:example@example.com": "tagValues/zzzzz"}

For example, the following JSON file maps the network tag sql-server to the Tag value of the key sql-server and the service account example@example.com to the Tag value of the key example@example.com:

{"sql-server": "tagValues/production", "sa:example@example.com": "tagValues/example"}

Bind Tags to VMs

Based on the tag mapping JSON file, bind the newly created secure Tags to the VMs to which the existing network tags are attached:

As a principal with the Tag Administrator role, do the following:
1. Review the permissions required to attach secure Tags to Google Cloud resources.
2. Assign the Tag User role to the principal that uses the secure Tags and binds the Tags to VMs.
As a principal with the Tag User role, use the compute firewall-rules migrate command with the --bind-tags-to-instances flag:
```
gcloud beta compute firewall-rules migrate \
   --source-network=NETWORK_NAME \
   --bind-tags-to-instances \
   --tag-mapping-file=TAG_MAPPING_FILE
```
Replace the following:
- NETWORK_NAME: the name of your VPC network.
- TAG_MAPPING_FILE: the name of the mapping JSON file.

Migrate VPC firewall rules to a global network firewall policy

Migrate your VPC firewall rules to a global network firewall policy. Use the compute-firewall-rules migrate command.

gcloud beta compute firewall-rules migrate \
    --source-network=NETWORK_NAME \
    --target-firewall-policy=POLICY_NAME \
    --tag-mapping-file=TAG_MAPPING_FILE

Replace the following:

NETWORK_NAME: the name of your VPC network containing the VPC firewall rules that you want to migrate.
POLICY_NAME: the name of the global network firewall policy to create during migration.

Exclude firewall rules from migration

To exclude specific firewall rules from migration, use the gcloud beta compute firewall-rules migrate command with the --exclusion-patterns-file flag:

gcloud beta compute firewall-rules migrate \
    --source-network=NETWORK_NAME \
    --target-firewall-policy=POLICY_NAME \
    --exclusion-patterns-file=EXCLUSION_PATTERNS_FILE

Replace the following:

NETWORK_NAME: the name of your VPC network that contains the VPC firewall rules that you want to migrate.
POLICY_NAME: the name of the global network firewall policy to create during migration.
EXCLUSION_PATTERNS_FILE: the name of the file that contains regular expressions that define VPC firewall naming patterns to exclude from migration. Make sure to specify the full path of the file. Firewall rules that match the specified patterns are skipped.

When defining the exclusion patterns, consider the following:
- Each regular expression must be on its own line and represent a single firewall naming pattern.
- The regular expressions don't contain any leading or trailing whitespaces.

View excluded firewall rules

Based on the excluded firewall rule naming patterns, the migration tool doesn't migrate some firewall rules, such as Google Kubernetes Engine (GKE) firewall rules. To export the list of excluded firewall rule naming patterns, use thegcloud beta compute firewall-rules migrate command with the --export-exclusion-patterns and the --exclusion-patterns-file flags.

gcloud beta compute firewall-rules migrate \
    --source-network=NETWORK_NAME \
    --target-firewall-policy=POLICY_NAME \
    --exclusion-patterns-file=EXCLUSION_PATTERNS_FILE \
    --export-exclusion-patterns

Replace the following:

NETWORK_NAME: the name of your VPC network that contains the VPC firewall rules that you want to migrate.
POLICY_NAME: the name of the global network firewall policy to create during migration.

EXCLUSION_PATTERNS_FILE: the path of the file where the following excluded firewall rule naming patterns are exported.

gke-(.+)-ipv6-all
gke-(.+)-(.+)-((master)|(vms)|(all)|(inkubelet)|(exkubelet)|(mcsd))
k8s-fw-(l7-)?(.+)
k8s-(.+)-((node)|(http)|(node-http))-hc
(.+)-hc
k8s2-(.+)-(.+)-(.+)-(.+)(-fw)?
k8s2-(.+)-l4-shared-hc-fw
gke((gw)|(mcg))1-l7-(.+)-(.+)

To migrate excluded firewall rules that match a specific pattern, remove the pattern from the exported list and run the gcloud beta compute firewall-rules migrate command with the --exclusion-patterns-file flag.

Force migration while preserving evaluation order

During migration, if an excluded firewall rule's evaluation order falls between the evaluation orders of user-specified firewall rules, the migration fails.This happens because the excluded firewall rules are not migrated, and the migration tool cannot preserve the original evaluation order of user-defined rules in the new network firewall policy.

For example, if your firewall rules have the following priorities, the migration fails.

A user-specified rule with priority 100
An excluded rule with priority 200
A user-specified rule with priority 300

To force the migration tool migrate the user-specified rules while preserving their original evaluation order and ignoring excluded firewall rules, use the gcloud beta compute firewall-rules migrate command with the --force flag.

gcloud beta compute firewall-rules migrate \
    --source-network=NETWORK_NAME \
    --target-firewall-policy=POLICY_NAME \
    --force

Replace the following:

NETWORK_NAME: the name of your VPC network that contains the VPC firewall rules that you want to migrate.
POLICY_NAME: the name of the global network firewall policy to create during migration.

Review the new global network firewall policy

Before you associate the newly created policy to a VPC network, Google recommends that you review the policy to ensure that the migration process has completed accurately.

Verify the following:

The firewall policy rules configuration is correct, and the following rule components are properly migrated for each rule:
- Relative priority
- Direction of traffic
- Action on match
- Log settings
- Target parameters
- Source parameters (for ingress rules)
- Destination parameters (for egress rules)
- Protocol and port constraints
Verify whether the secure Tags are attached to the correct VM. Use the resource-manager tags bindings list command.
```
gcloud resource-manager tags bindings list \
    --location=ZONE_ID \
    --parent //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE_ID/instances/INSTANCE_NAME \
    --effective
```
Replace the following:
- ZONE_ID: the zone of your VM.
- PROJECT_ID: the ID of your project.
- INSTANCE_NAME: the name of your VM.

Postmigration tasks

To activate and use the new global network firewall policy, complete the postmigration tasks. For more information, see Postmigration tasks.

What's next

Learn more about migrating VPC firewall rules.
Migrate VPC firewall rules without any dependencies.