Google recommends using thefirewallPolicies methods for configuringCloud Next Generation Firewall policies. This document guides you through migrating yourTerraform configurations to usefirewallPolicies methodsinstead oforganizationSecurityPoliciesmethods.

Firewall policies let you group several firewall rules that can explicitly denyor allow connections. For more information about firewall policies, seeFirewall policies.

Before you begin the migration process, you need to complete the followingsteps, which are described in theBefore you begin section:

• Ensure that you are using version 4.0.0 or later of the Terraform providerfor Google Cloud.
• Ensure that the Terraform state matches the current configuration.
• Identify resources that are in the scope of migration, includingpolicies, rules, and associations.
• Prepare commands to import the newfirewallPolicies resources to theTerraform state either manually or by using an automated script.
• Review the recommended backup and recovery procedures for your version ofTerraform, and create a backup of your current Terraform state.

The process of reconfiguring Terraform to migrate theorganizationSecurityPolicies resources includes these steps:

1. Remove existing resources from the Terraform state.Remove existingorganizationSecurityPolicies resources from the Terraform state.

2. Update the Terraform configuration.Edit the Terraform configuration files to replace the existing resource type,names, and attributes with the new resource type, names, and attributes.

3. Import new resources to the Terraform state.Import the newfirewallPolicies resources to the Terraform state.

Before you begin

This section explains the prerequisites for the migration process.

Ensure that the Terraform provider is supported

Ensure that you are using version 4.0.0 or later of the Terraform provider forGoogle Cloud, which includes the following resources from the Terraformregistry:

• google_compute_firewall_policy
• google_compute_firewall_policy_association
• google_compute_firewall_policy_rule

Ensure that the Terraform state is up-to-date

Run the following Terraform command to check that the Terraform state matchesthe current configuration.

terraform plan

To avoid any inconsistencies, we recommend that you apply any pending changesor actions before proceeding with the migration process.

Identify the resources to migrate

Run the following Terraform command to generate a list of resources that are inthe scope of migration, including policies, rules, and associations.

terraform state list | grep ^google_compute_organization_security_policy

The output is similar to the following:

google_compute_organization_security_policy.policygoogle_compute_organization_security_policy_association.association["folders/45678"]google_compute_organization_security_policy_rule.rule["allow-inbound-ssh"]google_compute_organization_security_policy_rule.rule["deny-all-egress"]

You need these resources to migrate to thefirewallPolicies methods. Save themfor later.

Prepare import commands using an automated script

To avoid errors or missed configurations during your migration, we recommend usingan automated script to generate the commands that are required for importingthefirewallPolicies resources to the Terraform state.

Run the following Terraform script to perform these tasks:

• Generate new resource addresses from the existing resource addresses.
• Get resource identifiers (or resource IDs) from the existing resource addresses.
• Generate import identifiers (or import IDs) from the resource IDs.
• Display the import commands for all the newfirewallPolicies resources.

terraform state list | grep ^google_compute_organization_security_policy | while read -r resource_address; do# Generate the new resource address for google_compute_firewall_policynew_address=$(echo "$resource_address" | sed 's/google_compute_organization_security_policy/google_compute_firewall_policy/')# Get the full resource ID from terraform state and remove quotesresource_id=$(echo "$resource_address.id" | terraform console | tr -d '"')# Use awk to parse the resource_id and generate the correct import identifierimport_id=$(echo "$resource_id" | awk -F'/' '  /association/ {    split($0, a, "/association/");    assoc_name = a[2];    gsub(/\//, "%2F", assoc_name);    print $4 "/" assoc_name;    next  }  /priority/ {    print $4 "/" $6;    next  }  {    print $4  }')# Print the final import commandecho "terraform import '$new_address' '$import_id'"done

You need the output from this script toimport the resources. Savethe output for later.

Prepare import commands manually

If the automated approach isn't feasible, you can generate the commands forimporting thefirewallPolicies resources manually. You can use theterraform console command to get the identifiers (IDs) of the resources.

The following Terraform command displays the resource ID of thegoogle_compute_organization_security_policy.policy resource:

echo google_compute_organization_security_policy.policy.id | terraform console

The output is similar to the following:

"locations/global/securityPolicies/12345"

Similarly, obtain the resource IDs for the other resources you identified in theIdentify resources to migrate section.

Alternatively, you can use the following Terraform command to obtain the resource IDs ofall the identified resources together:

terraform state list | grep ^google_compute_organization_security_policy | while read -r line; do echo "$line".id | terraform console; done

The output is similar to the following:

"locations/global/securityPolicies/12345""locations/global/securityPolicies/12345/association/locations/global/securityPolicies/23456-folders/56789""locations/global/securityPolicies/12345/priority/1000""locations/global/securityPolicies/12345/priority/65535"

To import thefirewallPolicies resources, you need their import IDs. ImportIDs are made up of a numeric identifier called a policy number, an associationname, and a rule priority number, as described in this section.

• The numeric identifier after the third forward slash character (/) is thepolicy number, which represents the import ID for policies. The followingtable shows an example of a resource ID and an import ID for a policy.

  Resource ID	Import ID
  "locations/global/securityPolicies/12345"	12345

• The policy number along with the association name represents the import ID forassociations. An association name is the part of the resource ID shown afterthe element/association/.

  Replace any forward slash character (/) in the association name with%2F to enabletheterraform import command to interpret the association name as a singleentity. The following table shows examples of resource ID and import ID forassociations.

  Resource ID	Import ID
  "locations/global/securityPolicies/12345/association/assoc-name"	12345/assoc-name
  "locations/global/securityPolicies/12345/association/locations/global/securityPolicies/23456-folders/56789"	12345/locations%2Fglobal%2FsecurityPolicies%2F23456-folders%2F56789

• The policy number along with the rule priority number represents the import ID forrules. The following table shows an example of a resource ID and an import ID for arule.

  Resource ID	Import ID
  "locations/global/securityPolicies/12345/priority/1000"	12345/1000

To import thefirewallPolicies resources, you need their updated resourceinstance names. Generate the resource instance names by replacing the prefixgoogle_compute_organization_security_policy withgoogle_compute_firewall_policyfor all the resources that you identified in theIdentify resources to migratesection. The following list shows an example of the updated resource instancenames:

google_compute_firewall_policy.policygoogle_compute_firewall_policy_association.association["folders/45678"]google_compute_firewall_policy_rule.rule["allow-inbound-ssh"]google_compute_firewall_policy_rule.rule["deny-all-egress"]

Combine the resource instance names with the associated import IDs to obtaintheterraform import commands. The following list shows an example of theterraform import commands:

terraform import 'google_compute_firewall_policy.policy' '12345'terraform import 'google_compute_firewall_policy_association.association["folders/23456"]' '12345/locations%2Fglobal%2FsecurityPolicies%2F23456-folders%2F56789'terraform import 'google_compute_firewall_policy_rule.rule["allow-inbound-ssh"]' '12345/1000'terraform import 'google_compute_firewall_policy_rule.rule["deny-all-egress"]' '12345/65535'

Save these import commands for later reference.

Back up the Terraform state

Before proceeding with the migration process, we recommend that you create abackup of the Terraform state. Use the following Terraform command to createa backup in the fileterraform.tfstate.backup.

terraform state pull > terraform.tfstate.backup

If you change the Terraform state in unintended ways, you can use the backupfileterraform.tfstate.backup to restore the original Terraform state byusing the following command:

terraform state push terraform.tfstate.backup

To remove theorganizationSecurityPolicies resources found in theIdentify resources to migrate section fromthe Terraform state, run the following Terraform command.

terraform state list | grep ^google_compute_organization_security_policy | while read -r resource; do  terraform state rm "$resource"done

Update the Terraform configuration

To update your Terraform configuration file, find the definitionsof the resources that you found in theIdentify resources to migratesection. Use the following command to find the definitions.

grep -r google_compute_organization_security_policy .

For example, the Terraform configuration file defines the policygoogle_compute_organization_security_policy.policy in the following manner:

resource "google_compute_organization_security_policy" "policy" {  …  }

Use the following table to edit the definition of an organization securitypolicy resource to create a new hierarchical firewall policy resource.

Use the following table to edit the definition of an organization securitypolicy association resource to create a new hierarchical firewall policyassociation resource.

Use the following table to edit the definition of an organization securitypolicy rule resource to create a new hierarchical firewall policyrule resource.

match {  config {    src_ip_ranges = SRC_IP_RANGES    dest_ip_ranges = DEST_IP_RANGES    layer4_config {      ip_protocol = IP_PROTOCOL      ports = [PORT1, PORT2]    }    layer4_config {      ip_protocol = IP_PROTOCOL    }  }}

match {  src_ip_ranges = SRC_IP_RANGES  dest_ip_ranges = DEST_IP_RANGES  layer4_configs {    ip_protocol = IP_PROTOCOL    ports = [PORT1, PORT2]  }  layer4_configs {    ip_protocol = IP_PROTOCOL  }}

You can use the following Terraform command to verify whether the modified Terraformconfiguration is valid:

terraform validate

Import resources to the Terraform state

To importfirewallPolicies resources to your Terraform configuration file,run the Terraform import commands that you generated in thePrepare import commands using an automated scriptorPrepare import commands manually section.

After you import thefirewallPolicies resources, Terraform accesses them usingthefirewallPolicies methods.

Verify your Terraform configuration and fix discrepancies

Run the following Terraform command to check for any actions.

terraform plan

Because the migration doesn't change any underlying Google Cloud resources,the plan that Terraform creates must not contain any actions.

For example, in the following output obtained by running theterraform plancommand, the Terraform actions indicate that thename in the resourcegoogle_compute_firewall_policy_association must beupdated.

Terraform will perform the following actions: # google_compute_firewall_policy_association.association["folders/23456"] must be replaced-/+ resource "google_compute_firewall_policy_association" "association" {    ~ firewall_policy   = "12345" -> "locations/global/firewallPolicies/12345"    ~ id                = "locations/global/firewallPolicies/12345/associations/locations%2Fglobal%2FsecurityPolicies%2F12345-folders%2F23456" -> (known after apply)    ~ name              = "locations/global/securityPolicies/12345-folders/23456" -> "locations/global/firewallPolicies/12345-folders/23456" # forces replacement    + short_name        = (known after apply)      # (1 unchanged attribute hidden)  }

In this case, you must verify and update the Terraform configuration file suchthat thename attribute is consistent with the name that is already installed.

You can configure Terraform to change the expectedname in the resourcegoogle_compute_firewall_policy_association to itsoriginal valuelocations/global/securityPolicies/12345-folders/23456by replacing thename field in the configuration as follows:

name = "${replace(local.policy_id, "firewallPolicies", "securityPolicies")}-${each.value}"

The preceding change uses the replace function to update the value oflocal.policy_id tosecurityPolicies instead offirewallPolicies. BecauseTerraform now expectslocations/global/securityPolicies/12345-folders/23456for thename attribute, runningterraform plan no longer shows Terraformaction related to thename attribute.

• Learn more aboutfirewallPolicies methods.