|
| 1 | +# Upgrading to v2.x |
| 2 | + |
| 3 | +The v2.x release of _google-network_ is a backwards incompatible |
| 4 | +release. |
| 5 | + |
| 6 | +Because v2.x changed how the subnet resource is iterated on, resources in Terraform state need to be migrated in order to avoid the resources from getting destroyed and recreated. |
| 7 | + |
| 8 | +## Migration Instructions |
| 9 | + |
| 10 | +First, upgrade to the new version of this module. |
| 11 | + |
| 12 | +```diff |
| 13 | + module "kubernetes_engine_private_cluster" { |
| 14 | + source = "terraform-google-modules/network/google" |
| 15 | +- version = "~> 1.5" |
| 16 | ++ version = "~> 2.0" |
| 17 | + |
| 18 | + # ... |
| 19 | + } |
| 20 | +``` |
| 21 | + |
| 22 | +If you run `terraform plan` at this point, Terraform will inform you that it will attempt to delete and recreate your existing subnets. This is almost certainly not the behavior you want. |
| 23 | + |
| 24 | +You will need to migrate your state, either [manually](#manual-migration-steps) or [automatically](#migration-script). |
| 25 | + |
| 26 | +### Migration Script |
| 27 | + |
| 28 | +1. Download the script: |
| 29 | + |
| 30 | + ```sh |
| 31 | + curl -O https://raw.githubusercontent.com/terraform-google-modules/terraform-google-network/master/helpers/migrate.py |
| 32 | + chmod +x migrate.py |
| 33 | + ``` |
| 34 | + |
| 35 | +2. Back up your Terraform state: |
| 36 | + |
| 37 | + ```sh |
| 38 | + terraform state pull >> state.bak |
| 39 | + ``` |
| 40 | + |
| 41 | +2. Run the script to output the migration commands: |
| 42 | + |
| 43 | + ```sh |
| 44 | + $ ./migrate.py --dryrun |
| 45 | + terraform state mv 'module.example.module.test-vpc-module-02.google_compute_network.network[0]' 'module.example.module.test-vpc-module-02.module.vpc.google_compute_network.network' |
| 46 | + terraform state mv 'module.example.module.test-vpc-module-02.google_compute_subnetwork.subnetwork' 'module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork' |
| 47 | + terraform state mv 'module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork[0]' 'module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork["us-west1/multi-vpc-a1-02-subnet-01"]' |
| 48 | + terraform state mv 'module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork[1]' 'module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork["us-west1/multi-vpc-a1-02-subnet-02"]' |
| 49 | + terraform state mv 'module.example.module.test-vpc-module-02.google_compute_route.route' 'module.example.module.test-vpc-module-02.module.routes.google_compute_route.route' |
| 50 | + terraform state mv 'module.example.module.test-vpc-module-02.module.routes.google_compute_route.route[0]' 'module.example.module.test-vpc-module-02.module.routes.google_compute_route.route["multi-vpc-a1-02-egress-inet"]' |
| 51 | + terraform state mv 'module.example.module.test-vpc-module-02.module.routes.google_compute_route.route[1]' 'module.example.module.test-vpc-module-02.module.routes.google_compute_route.route["multi-vpc-a1-02-testapp-proxy"]' |
| 52 | +
|
| 53 | + ``` |
| 54 | + |
| 55 | +3. Execute the migration script: |
| 56 | + |
| 57 | + ```sh |
| 58 | + $ ./migrate.py |
| 59 | + ---- Migrating the following modules: |
| 60 | + -- module.example.module.test-vpc-module-02 |
| 61 | + ---- Commands to run: |
| 62 | + Move "module.example.module.test-vpc-module-02.google_compute_network.network[0]" to "module.example.module.test-vpc-module-02.module.vpc.google_compute_network.network" |
| 63 | + Successfully moved 1 object(s). |
| 64 | + Move "module.example.module.test-vpc-module-02.google_compute_subnetwork.subnetwork" to "module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork" |
| 65 | + Successfully moved 1 object(s). |
| 66 | + Move "module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork[0]" to "module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork[\"us-west1/multi-vpc-a1-02-subnet-01\"]" |
| 67 | + Successfully moved 1 object(s). |
| 68 | + Move "module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork[1]" to "module.example.module.test-vpc-module-02.module.subnets.google_compute_subnetwork.subnetwork[\"us-west1/multi-vpc-a1-02-subnet-02\"]" |
| 69 | + Successfully moved 1 object(s). |
| 70 | + Move "module.example.module.test-vpc-module-02.google_compute_route.route" to "module.example.module.test-vpc-module-02.module.routes.google_compute_route.route" |
| 71 | + Successfully moved 1 object(s). |
| 72 | + Move "module.example.module.test-vpc-module-02.module.routes.google_compute_route.route[0]" to "module.example.module.test-vpc-module-02.module.routes.google_compute_route.route[\"multi-vpc-a1-02-egress-inet\"]" |
| 73 | + Successfully moved 1 object(s). |
| 74 | + Move "module.example.module.test-vpc-module-02.module.routes.google_compute_route.route[1]" to "module.example.module.test-vpc-module-02.module.routes.google_compute_route.route[\"multi-vpc-a1-02-testapp-proxy\"]" |
| 75 | + Successfully moved 1 object(s). |
| 76 | +
|
| 77 | + ``` |
| 78 | + |
| 79 | +4. Run `terraform plan` to confirm no changes are expected. |
| 80 | + |
| 81 | +### Manual Migration Steps |
| 82 | + |
| 83 | +In this example here are the commands used migrate the vpc and subnets created by the `simple_project` in the examples directory. _please note the need to escape the quotes on the new resource_. You may also use the migration script. |
| 84 | + |
| 85 | +- `terraform state mv module.example.module.test-vpc-module.google_compute_network.network module.example.module.test-vpc-module.module.vpc.google_compute_subnetwork.network` |
| 86 | + |
| 87 | +- `terraform state mv module.example.module.test-vpc-module.google_compute_subnetwork.subnetwork module.example.module.test-vpc-module.module.subnets.google_compute_subnetwork.subnetwork` |
| 88 | + |
| 89 | +- `terraform state mv module.example.module.test-vpc-module.module.subnets.google_compute_subnetwork.subnetwork[0] module.example.module.test-vpc-module.module.subnets.google_compute_subnetwork.subnetwork[\"us-west1/simple-project-timh-subnet-01\"]` |
| 90 | + |
| 91 | +- `terraform state mv module.example.module.test-vpc-module.module.subnets.google_compute_subnetwork.subnetwork[1] module.example.module.test-vpc-module.module.subnets.google_compute_subnetwork.subnetwork[\"us-west1/simple-project-timh-subnet-02\"]` |
| 92 | + |
| 93 | +*You'll notice that because of a terraform [issue](https://github.com/hashicorp/terraform/issues/22301), we need to move the whole resource collection first before renaming to the `for_each` keys* |
| 94 | +
|
| 95 | +`terraform plan` should now return a no-op and show no new changes. |
| 96 | +
|
| 97 | +```Shell |
| 98 | +$ terraform plan |
| 99 | +Refreshing Terraform state in-memory prior to plan... |
| 100 | +The refreshed state will be used to calculate this plan, but will not be |
| 101 | +persisted to local or remote state storage. |
| 102 | +
|
| 103 | +module.example.module.test-vpc-module.google_compute_network.network: Refreshing state... [id=simple-project-timh] |
| 104 | +module.example.module.test-vpc-module.google_compute_subnetwork.subnetwork["us-west1/simple-project-timh-subnet-02"]: Refreshing state... [id=us-west1/simple-project-timh-subnet-02] |
| 105 | +module.example.module.test-vpc-module.google_compute_subnetwork.subnetwork["us-west1/simple-project-timh-subnet-01"]: Refreshing state... [id=us-west1/simple-project-timh-subnet-01] |
| 106 | +
|
| 107 | +------------------------------------------------------------------------ |
| 108 | +
|
| 109 | +No changes. Infrastructure is up-to-date. |
| 110 | +
|
| 111 | +This means that Terraform did not detect any differences between your |
| 112 | +configuration and real physical resources that exist. As a result, no |
| 113 | +actions need to be performed. |
| 114 | +``` |
| 115 | +
|
| 116 | +### Known Issues |
| 117 | +
|
| 118 | +If your previous state only contains a **single** subnet or route then `terraform mv` will throw an error similar to the following during migration: |
| 119 | +
|
| 120 | +``` |
| 121 | +Error: Invalid target address |
| 122 | +
|
| 123 | +Cannot move to |
| 124 | +module.example.module.test-vpc-module-01.module.routes.google_compute_route.route["multi-vpc-a1-01-egress-inet"]: |
| 125 | +module.example.module.test-vpc-module-01.module.routes.google_compute_route.route |
| 126 | +does not exist in the current state. |
| 127 | +``` |
| 128 | +
|
| 129 | +This is due to a terraform mv [issue](https://github.com/hashicorp/terraform/issues/22301) |
| 130 | +
|
| 131 | +The workaround is to either |
| 132 | +
|
| 133 | +1. Create a temporary subnet or route prior to migration |
| 134 | +2. Manually updating the state file. Update the `index_key` of the appropriate user and push the to the remote state if necessary. |
0 commit comments