Skip to content

Commit a172ad3

Browse files
morgantemorgante
authored
Merge pull request #127 from terraform-google-modules/bugfix/2.0-releasefix
2.0 release upgrade guide
2 parents ecdfe25 + f4a98d1 commit a172ad3

File tree

2 files changed

+57
-118
lines changed

2 files changed

+57
-118
lines changed

‎docs/upgrading_to_v2.0.md‎

Lines changed: 54 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -7,138 +7,41 @@ Because v2.x changed how the subnet resource is iterated on, resources in Terraf
77

88
## Migration Instructions
99

10-
- Upgrade to the new version of this module.
10+
First, upgrade to the new version of this module.
1111

12-
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. For example:
12+
```diff
13+
module "kubernetes_engine_private_cluster" {
14+
source = "terraform-google-modules/network/google"
15+
- version = "~> 1.5"
16+
+ version = "~> 2.0"
1317

14-
```Shell
15-
Terraform will perform the following actions:
16-
17-
# module.example.module.test-vpc-module.google_compute_subnetwork.subnetwork will be destroyed
18-
- resource "google_compute_subnetwork" "subnetwork" {
19-
- creation_timestamp = "2019-10-02T08:40:26.282-07:00" -> null
20-
- enable_flow_logs = false -> null
21-
- fingerprint = "f8LZx006zY4=" -> null
22-
- gateway_address = "10.10.10.1" -> null
23-
- id = "us-west1/simple-project-timh-subnet-01" -> null
24-
- ip_cidr_range = "10.10.10.0/24" -> null
25-
- name = "simple-project-timh-subnet-01" -> null
26-
- network = "https://www.googleapis.com/compute/v1/projects/dev-xpn-networking/global/networks/simple-project-timh" -> null
27-
- private_ip_google_access = false -> null
28-
- project = "dev-xpn-networking" -> null
29-
- region = "us-west1" -> null
30-
- secondary_ip_range = [] -> null
31-
- self_link = "https://www.googleapis.com/compute/v1/projects/dev-xpn-networking/regions/us-west1/subnetworks/simple-project-timh-subnet-01" -> null
32-
}
33-
34-
# module.example.module.test-vpc-module.google_compute_subnetwork.subnetwork[1] will be destroyed
35-
- resource "google_compute_subnetwork" "subnetwork" {
36-
- creation_timestamp = "2019-10-02T08:40:26.292-07:00" -> null
37-
- enable_flow_logs = true -> null
38-
- fingerprint = "wOwStN9lK-Q=" -> null
39-
- gateway_address = "10.10.20.1" -> null
40-
- id = "us-west1/simple-project-timh-subnet-02" -> null
41-
- ip_cidr_range = "10.10.20.0/24" -> null
42-
- name = "simple-project-timh-subnet-02" -> null
43-
- network = "https://www.googleapis.com/compute/v1/projects/dev-xpn-networking/global/networks/simple-project-timh" -> null
44-
- private_ip_google_access = true -> null
45-
- project = "dev-xpn-networking" -> null
46-
- region = "us-west1" -> null
47-
- secondary_ip_range = [] -> null
48-
- self_link = "https://www.googleapis.com/compute/v1/projects/dev-xpn-networking/regions/us-west1/subnetworks/simple-project-timh-subnet-02" -> null
49-
}
50-
51-
# module.example.module.test-vpc-module.google_compute_subnetwork.module.subnets.subnetwork["us-west1/simple-project-timh-subnet-01"] will be created
52-
+ resource "google_compute_subnetwork" "subnetwork" {
53-
+ creation_timestamp = (known after apply)
54-
+ enable_flow_logs = false
55-
+ fingerprint = (known after apply)
56-
+ gateway_address = (known after apply)
57-
+ id = (known after apply)
58-
+ ip_cidr_range = "10.10.10.0/24"
59-
+ name = "simple-project-timh-subnet-01"
60-
+ network = "simple-project-timh"
61-
+ private_ip_google_access = false
62-
+ project = "dev-xpn-networking"
63-
+ region = "us-west1"
64-
+ secondary_ip_range = []
65-
+ self_link = (known after apply)
66-
}
67-
68-
# module.example.module.test-vpc-module.module.subnets.google_compute_subnetwork.subnetwork["us-west1/simple-project-timh-subnet-02"] will be created
69-
+ resource "google_compute_subnetwork" "subnetwork" {
70-
+ creation_timestamp = (known after apply)
71-
+ enable_flow_logs = true
72-
+ fingerprint = (known after apply)
73-
+ gateway_address = (known after apply)
74-
+ id = (known after apply)
75-
+ ip_cidr_range = "10.10.20.0/24"
76-
+ name = "simple-project-timh-subnet-02"
77-
+ network = "simple-project-timh"
78-
+ private_ip_google_access = true
79-
+ project = "dev-xpn-networking"
80-
+ region = "us-west1"
81-
+ secondary_ip_range = []
82-
+ self_link = (known after apply)
83-
}
84-
85-
Plan: 2 to add, 0 to change, 2 to destroy.
86-
87-
------------------------------------------------------------------------
88-
89-
Note: You didn't specify an "-out" parameter to save this plan, so Terraform
90-
can't guarantee that exactly these actions will be performed if
91-
"terraform apply" is subsequently run.
18+
# ...
19+
}
9220
```
9321

94-
### Manual Migration Steps
95-
96-
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.
97-
98-
- `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`
99-
100-
- `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`
101-
102-
- `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\"]`
103-
104-
- `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\"]`
105-
106-
*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*
107-
108-
`terraform plan` should now return a no-op and show no new changes.
109-
110-
```Shell
111-
$ terraform plan
112-
Refreshing Terraform state in-memory prior to plan...
113-
The refreshed state will be used to calculate this plan, but will not be
114-
persisted to local or remote state storage.
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.
11523

116-
module.example.module.test-vpc-module.google_compute_network.network: Refreshing state... [id=simple-project-timh]
117-
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]
118-
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]
119-
120-
------------------------------------------------------------------------
121-
122-
No changes. Infrastructure is up-to-date.
123-
124-
This means that Terraform did not detect any differences between your
125-
configuration and real physical resources that exist. As a result, no
126-
actions need to be performed.
127-
```
24+
You will need to migrate your state, either [manually](#manual-migration-steps) or [automatically](#migration-script).
12825

12926
### Migration Script
13027

131-
1. Download the script
28+
1. Download the script:
13229

13330
```sh
13431
curl -O https://raw.githubusercontent.com/terraform-google-modules/terraform-google-network/master/helpers/migrate.py
13532
chmod +x migrate.py
13633
```
13734

35+
2. Back up your Terraform state:
36+
37+
```sh
38+
terraform state pull >> state.bak
39+
```
40+
13841
2. Run the script to output the migration commands:
13942

14043
```sh
141-
$ ./migrate.py --dry-run
44+
$ ./migrate.py --dryrun
14245
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'
14346
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'
14447
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"]'
@@ -149,7 +52,7 @@ actions need to be performed.
14952
15053
```
15154

152-
3. Execute the migration command
55+
3. Execute the migration script:
15356

15457
```sh
15558
$ ./migrate.py
@@ -175,6 +78,41 @@ actions need to be performed.
17578

17679
4. Run `terraform plan` to confirm no changes are expected.
17780

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+
178116
### Known Issues
179117
180118
If your previous state only contains a **single** subnet or route then `terraform mv` will throw an error similar to the following during migration:

‎helpers/migrate.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,8 @@
3131
{
3232
"resource_type": "google_compute_shared_vpc_host_project",
3333
"name": "shared_vpc_host",
34-
"module": ".module.vpc"
34+
"module": ".module.vpc",
35+
"new_plural": False
3536
},
3637
{
3738
"resource_type": "google_compute_subnetwork",
@@ -280,7 +281,7 @@ def read_state(self):
280281
def resource_value(self, resource, key):
281282
# Find the resource in the state
282283
state_resource_list = [r for r in self.state["resources"] if
283-
r["module"] == resource.module and
284+
r.get("module", "none") == resource.module and
284285
r["type"] == resource.resource_type and
285286
r["name"] == resource.name]
286287

0 commit comments

Comments
 (0)