Skip to content

Commit caf28b3

Browse files
modular-magicianc2thorn
modular-magician
and
c2thorn
committed
Edit pass on upgrade guide for 5.0.0 (#9142) (#6420)
Signed-off-by: Modular Magician <[email protected]> Co-authored-by: Cameron Thornton <[email protected]>
1 parent 7ce4dca commit caf28b3

File tree

2 files changed

+192
-26
lines changed

2 files changed

+192
-26
lines changed

‎.changelog/9142.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
```release-note:none
2+
```

‎website/docs/guides/version_5_upgrade.html.markdown‎

Lines changed: 190 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -90,34 +90,134 @@ terraform {
9090

9191
### Provider-level Labels Rework
9292

93-
Label and annotation fields across the provider have had a major rework. Labels and annotations are key-value pairs attached on Google cloud resources. Cloud labels are used for organizing resources, filtering resources, breaking down billing, and so on. Annotations are used to attach metadata to Kubernetes resources.
94-
95-
Not all of Google cloud resources support labels and annotations. Please check the Terraform Google provider resource documentation to figure out if the resource supports the `labels` and `annotations` fields.
93+
Label and annotation fields across the provider have been reworked with impact
94+
across numerous resources. Two notable cases from this upgrade are covered
95+
immediately, with more details in dedicated headers below:
96+
97+
!> For resources with **any** `labels` values previously defined, running
98+
`terraform plan` or `terraform apply` on Google provider `5.0.0` or later with
99+
an existing pre-`5.0.0` resource before an `apply`, the plan will show an
100+
update adding your current `labels` values to `terraform_labels`. This change
101+
may result in a no-op update call to the API depending on the resource
102+
implementation, but can otherwise be safely applied.
103+
104+
!> This change introduced a regression we were unable to resolve, and labels
105+
with an empty value (`""`) should be avoided, as they will be ignored and not
106+
included in requests to the API. Replacing those labels' values with `_` or
107+
`true` are recommended.
108+
109+
Not all of Google Cloud resources support labels and annotations. Please check
110+
the Terraform Google provider resource documentation to figure out if a given
111+
resource supports `labels` or `annotations` fields.
96112

97113
#### Provider default labels
98114

99-
Default labels configured on the provider through the new `default_labels` field are now supported. The default labels configured on the provider will be applied to all of the resources with the top level `labels` field or the nested `labels` field inside the top level `metadata` field. This change introduced a regression we were unable to resolve, and labels with an empty value (`""`) should be avoided, as they will be ignored and not included in `terraform_labels`, `effective_labels` and then API requests. Instead, labels with the value `_` or `true` are recommended.
115+
Default labels configured on the provider through a new `default_labels` field
116+
are now supported. The default labels configured on the provider will be applied
117+
to all resources with a top level `labels` field or a `labels` field nested
118+
inside a top level `metadata` field.
100119

101-
Provider-level default annotations are not supported.
120+
Setting the same key as a default label at the resource level will override the
121+
default value for that label.
102122

103-
#### Resource labels
123+
These values will be recorded in individual resource plans through the
124+
`terraform_labels` and `effective_labels` fields.
125+
126+
```
127+
provider "google" {
128+
default_labels = {
129+
my_global_key = "one"
130+
my_default_key = "two"
131+
}
132+
}
133+
134+
resource "google_compute_address" "my_address" {
135+
name = "my-address"
104136
105-
Labels and annotations fields on Terraform Google provider were authoritative and Terraform thought it was the only owner of the fields. This model worked well initially, but with the introduction of system labels and other client managed labels, Terraform would conflict with their labels and show a diff. We've reworked the `labels` field to resolve this class of problem.
137+
labels = {
138+
my_key = "three"
139+
# overrides provider-wide setting
140+
my_default_key = "four"
141+
}
142+
}
143+
```
106144

107-
The new labels model will be applied to all of the resources with the top level `labels` field or the nested `labels` field inside the top level `metadata` field. Some labels fields are for child resources, so the new model will not be applied to labels fields for child resources.
145+
```
146+
# google_compute_address.my_address will be created
147+
+ resource "google_compute_address" "my_address" {
148+
+ address = (known after apply)
149+
+ address_type = "EXTERNAL"
150+
+ creation_timestamp = (known after apply)
151+
+ effective_labels = {
152+
+ "my_default_key" = "four"
153+
+ "my_global_key" = "one"
154+
+ "my_key" = "three"
155+
}
156+
+ id = (known after apply)
157+
+ label_fingerprint = (known after apply)
158+
+ labels = {
159+
+ "my_default_key" = "four"
160+
+ "my_key" = "three"
161+
}
162+
+ name = "my-address"
163+
+ network_tier = (known after apply)
164+
+ prefix_length = (known after apply)
165+
+ project = "my-project"
166+
+ purpose = (known after apply)
167+
+ region = (known after apply)
168+
+ self_link = (known after apply)
169+
+ subnetwork = (known after apply)
170+
+ terraform_labels = {
171+
+ "my_default_key" = "four"
172+
+ "my_global_key" = "one"
173+
+ "my_key" = "three"
174+
}
175+
+ users = (known after apply)
176+
}
177+
178+
Plan: 1 to add, 0 to change, 0 to destroy.
179+
```
108180

109-
There are now three label-related fields with the new model:
181+
Provider-level default annotations are not supported at this time.
110182

111-
* The `labels` field will be non-authoritative and only manage the labels defined by the users on the resource through Terraform. If a label was added outside of Terraform, it will not be managed by Terraform, unless it is added to the `labels` field in the configuration. The out of band labels will be listed in the `effective_labels` field. The new model introduced a regression we were unable to resolve, and the labels with an empty value (`""`) should be avoided, as they will be ignored and not included in `terraform_labels`, `effective_labels` and then API requests. Instead, labels with the value `_` or `true` are recommended.
112-
* The output-only `terraform_labels` will merge the labels defined by the users on the resource through Terraform and the default labels configured on the provider. If the same label exists on both the resource labels and provider default labels, the label on the resource will override the provider label.
113-
* The output-only `effective_labels` will list all of labels present on the resource in GCP, including the labels configured through Terraform, the system, and other clients.
183+
#### Resource labels
114184

115-
**Note:** `ignore_changes` can be applied to `labels` field to ignore the changes of the user defined labels. It is not recommended to apply `ignore_changes` to `terraform_labels` or `effective_labels`, as it may unintuitively affect the final API call.
185+
Previously, `labels` and `annotations` fields in the Terraform Google provider
186+
were authoritative and Terraform thought it was the only owner of the fields.
187+
This model worked well initially, but with the introduction of system labels and
188+
other client-managed labels, Terraform would conflict with their labels and show
189+
a diff. We've reworked the `labels` field to resolve this class of problem.
190+
191+
This reworked labels model has been applied to all resources with a top level
192+
`labels` field or a nested `labels` field inside a top level `metadata` field.
193+
Non-standard labels fields are unaffected, for example the `node_labels` GKE
194+
field that affects child resources.
195+
196+
Resources that previously contained a single `labels` field will now contain
197+
three fields:
198+
199+
* The `labels` field is now non-authoritative and only manages the label keys
200+
defined in your configuration for the resource. If a label was added outside of
201+
Terraform, it will not be managed by Terraform, unless it is added to the
202+
`labels` field in the configuration.
203+
* The `terraform_labels` cannot be specified directly by the user. It merges the
204+
labels defined in the resource's configuration and the default labels configured
205+
in the provider block. If the same label key exists on both the resource level
206+
and provider level, the value on the resource will override the
207+
provider-level default.
208+
* The output-only `effective_labels` will list all the labels present on the
209+
resource in GCP, including the labels configured through Terraform, the system,
210+
and other clients.
211+
212+
~> **Note:** `ignore_changes` can be applied to `labels` field to ignore the
213+
changes of the user defined labels. It is not recommended to apply
214+
`ignore_changes` to `terraform_labels` or `effective_labels`, as it may
215+
unintuitively affect the final API call.
116216

117217
The following changes will be observed in applicable resources after upgrading to `5.0.0`:
118-
* Running `terraform refresh` on Google provider `5.0.0` or later with an existing pre-`5.0.0` resource before an `apply`, these three fields will show in the state file. `labels` field will have your current labels, `terraform_labels` will be empty, and `effective_labels` will have all of labels present on the resource in GCP.
119-
* Running `terraform plan` or `terraform apply` on Google provider `5.0.0` or later with an existing pre-`5.0.0` resource before an `apply`, the plan will show an updated adding your current labels to `terraform_labels`. After running `terraform apply`, these three fields will show in the state file. `labels` will have your current labels, `terraform_labels` will have the combination of `labels` and your provider-default labels, and `effective_labels` will have all of labels present on the resource in GCP.
120-
* Running `terraform import` on Google provider `5.0.0` or later, these three fields will show in the state file with an empty `labels` and `terraform_labels` value. `effective_labels` will have all of labels present on the resource in GCP. You can update the resource to bring labels defined in your configuration under management by Terraform.
218+
* Running `terraform refresh` on Google provider `5.0.0` or later with an existing pre-`5.0.0` resource before an `apply`, these three fields will show in the state file. `labels` field will have your current labels, `terraform_labels` will be empty, and `effective_labels` will have all of labels present on the resource in GCP.
219+
* For resources with **any** `labels` values previously defined, running `terraform plan` or `terraform apply` on Google provider `5.0.0` or later with an existing pre-`5.0.0` resource before an `apply`, the plan will show an updated adding your current labels to `terraform_labels`. After running `terraform apply`, these three fields will show in the state file. `labels` will have your current labels, `terraform_labels` will have the combination of `labels` and your provider-default labels, and `effective_labels` will have all of labels present on the resource in GCP.
220+
* Running `terraform import` on Google provider `5.0.0` or later, these three fields will show in the state file with an empty `labels` and `terraform_labels` value. `effective_labels` will have all the labels present on the resource in GCP. You can update the resource to bring labels defined in your configuration under management by Terraform.
121221

122222
The following are resource-specific label changes:
123223
* In the resource `google_cloud_run_domain_mapping`, the system labels `cloud.googleapis.com/location` and `run.googleapis.com/overrideAt` will be removed from `labels` inside `metadata` field in the state file as part of a one-time resource schema upgrade. If any of these label keys are in the configuration, after upgrading to `5.0.0`, the plan will show that these keys will be added. You can safely accept this change, and Terraform will begin to manage them again.
@@ -130,15 +230,33 @@ The following are resource-specific label changes:
130230

131231
#### Data source labels
132232

133-
For most resource-based datasources, all three of `labels`, `effective_labels` and `terraform_labels` will now be present. All of these three fields will have all of labels present on the resource in GCP including the labels configured through Terraform, the system, and other clients, equivalent to `effective_labels` on the resource.
233+
For most resource-based datasources, all three of `labels`, `effective_labels`
234+
and `terraform_labels` will now be present. All of these three fields include
235+
all of the labels present on the resource in GCP including the labels configured
236+
through Terraform, the system, and other clients, equivalent to
237+
`effective_labels` on the resource.
134238

135239
#### Resource annotations
136240

137-
The new annotations model is similar to the new labels model and will be applied to all of the resources with the top level `annotations` field or the nested `annotations` field inside the top level `metadata` field.
241+
Annotations have been reworked similarly to `labels`, and `annotations` fields
242+
will now manage only the keys included in configuration. This model has been
243+
applied to top level `annotations` fields and those nested in `metadata` blocks.
138244

139-
There are now two annotation-related fields with the new model, `annotations` and the output-only `effective_annotations`.
245+
Resources that previously contained a single `annotations` field will now contain
246+
two fields:
140247

141-
**Note:** `ignore_changes` can be applied to `annotations` field to ignore the changes of the user defined annotations. It is not recommended to apply `ignore_changes` to `effective_annotations`, as it may unintuitively affect the final API call.
248+
* The `annotations` field is now non-authoritative and only manage the keys
249+
defined in your configuration for the resource. If an annotations entry was
250+
added outside of Terraform, it will not be managed by Terraform, unless it is
251+
added to the `annotations` field in the configuration.
252+
* The output-only `effective_annotations` will list all the annotations present
253+
on the resource in GCP, including the entries configured through Terraform, the
254+
system, and other clients.
255+
256+
**Note:** `ignore_changes` can be applied to `annotations` field to ignore the
257+
changes of the user defined annotations. It is not recommended to apply
258+
`ignore_changes` to `effective_annotations`, as it may unintuitively affect the
259+
final API call.
142260

143261
The following changes will be observed after upgrading to `5.0.0`.
144262
* Running `terraform import` on Google provider `5.0.0` or later, these two fields will show in the state file with an empty `annotations` value. `effective_annotations` will have all of annotations present on the resource in GCP. You can update the resource to bring annotations defined in your configuration under management by Terraform.
@@ -149,10 +267,16 @@ The following changes will be observed after upgrading to `5.0.0`.
149267

150268
#### Data source annotations
151269

152-
For most resource-based datasources, both `annotations` and `effective_annotations` will now be present. Both fields will have all of annotations present on the resource in GCP including the annotations configured through Terraform, the system, and other clients, equivalent to `effective_annotations` on the resource.
270+
For most resource-based datasources, both `annotations` and
271+
`effective_annotations` will now be present. Both fields will have all the
272+
annotations present on the resource in GCP including the annotations configured
273+
through Terraform, the system, and other clients, equivalent to
274+
`effective_annotations` on the resource.
153275

154276
#### Example
155-
##### Config
277+
278+
##### Mixing resource, provider, and system labels
279+
156280
```hcl
157281
provider "google" {
158282
default_labels = {
@@ -170,9 +294,14 @@ resource "google_dataproc_cluster" "with_labels" {
170294
}
171295
}
172296
```
173-
After the configuration is applied, Terraform is managing `key1` and `key2` in the `labels` field. `terraform_labels` field has label `default_key`, `key1` and `key2`. `effective_labels` has label `default_key`, `key1`, `key2` and system labels.
174297

175-
##### Config
298+
After the configuration is applied, Terraform is managing `key1` and `key2` in
299+
the `labels` field. `terraform_labels` field has the keys `default_key`, `key1`
300+
and `key2`. `effective_labels` has the keys `default_key`, `key1`, `key2` and
301+
any system labels added by GCP.
302+
303+
##### Removing a key
304+
176305
```hcl
177306
provider "google" {
178307
default_labels = {
@@ -189,7 +318,24 @@ resource "google_dataproc_cluster" "with_labels" {
189318
}
190319
}
191320
```
192-
After the configuration is applied, Terraform stops managing `key2` and is managing `key1` in the `labels` field. `terraform_labels` field has label `default_key` and `key1`. `effective_labels` has label `default_key`, `key1` and system labels.
321+
322+
Applying this configuration **after** the previous example, Terraform will clear
323+
the value of `key2`. Other values are unaffected.
324+
325+
```
326+
~ effective_labels = {
327+
- "key2" = "value2" -> null
328+
# (5 unchanged elements hidden)
329+
}
330+
~ labels = {
331+
- "key2" = "value2" -> null
332+
# (1 unchanged element hidden)
333+
}
334+
~ terraform_labels = {
335+
- "key2" = "value2" -> null
336+
# (2 unchanged elements hidden)
337+
}
338+
```
193339

194340
### Updates to how empty strings are handled in the `provider` block
195341

@@ -229,7 +375,25 @@ This will only affect users whose configuration contains resource blocks that ha
229375

230376
### Provider default values shown at plan-time
231377

232-
`project`, `region`, and `zone` fields will now display their values during plan-time instead of the placeholder `(known after apply)` value normally displayed for fields without fixed Terraform default values. These values will be taken from either the Terraform resource config file, provider config, or local environment variables, depending on which variables are supplied by the user, matching the existing per-resource functionality for what default values are used in execution of a Terraform plan.
378+
The `project`, `region`, and `zone` fields will now display their values during
379+
plan-time instead of the placeholder `(known after apply)` value normally
380+
displayed for fields without fixed Terraform default values. These values will
381+
be taken from either the Terraform resource config file, provider config, or
382+
local environment variables, depending on which variables are supplied by the
383+
user, matching the existing per-resource functionality for what default values
384+
are used in execution of a Terraform plan.
385+
386+
Before `5.0.0`:
387+
388+
```
389+
project = (known after apply)
390+
```
391+
392+
After `5.0.0` (when possible):
393+
394+
```
395+
project = "my-project"
396+
```
233397

234398
### Resource import formats have improved validation
235399

0 commit comments

Comments
 (0)