diff --git a/website/docs/guides/version_6_upgrade.html.markdown b/website/docs/guides/version_6_upgrade.html.markdown index 8b9dfcbcdb..5739f98c35 100644 --- a/website/docs/guides/version_6_upgrade.html.markdown +++ b/website/docs/guides/version_6_upgrade.html.markdown @@ -86,23 +86,12 @@ terraform { } ``` -## Provider +## Provider: Terraform provider attribution label is added to new resources by default -### Compute: `name_prefix` max length has been extended from 37 to 54 characters - -Affected resources: `google_compute_instance_template`, `google_compute_region_instance_template`, `google_compute_ssl_certificate`, -and `google_compute_region_ssl_certificate` - -Previously, the max length of `name_prefix` was 37 characters since the autogenerated UUID suffix was 26 characters which combined to -the total max length for names of 63 characters. -In 6.0, providing a `name_prefix` larger than 37 characters will prompt the provider to use a shortened suffix of only 9 characters, leading to a new max of 54 characters for `name_prefix`. This shortened suffix is inevitably more prone to collisions, so use the longer max `name_prefix` length with caution. - -### Provider attribution label is enabled by default - -Version 5.0.0 introduced the `goog-terraform-provisioned = true` label that could +Version 5.16.0 introduced the `goog-terraform-provisioned = true` label that could be automatically added to resources, making it easy to identify resources created by the provider when using other tools such as `gcloud` or the GCP web console. In -5.0.0 the label needed to be enabled explicitly; in 6.0.0 the default is to add the +5.16.0 the label needed to be enabled explicitly; in 6.0.0 the default is to add the label to all newly created resources. This behavior can be disabled in the provider configuration. For example: @@ -112,25 +101,27 @@ provider "google" { } ``` -## Datasources - -## Datasource: `google_product_datasource` +## Provider: `name_prefix` max length has been extended from 37 to 54 characters for multiple resources -### Datasource-level change example header +Affected resources: `google_compute_instance_template`, `google_compute_region_instance_template`, `google_compute_ssl_certificate`, +and `google_compute_region_ssl_certificate` -Description of the change and how users should adjust their configuration (if needed). +Previously, the max length of `name_prefix` was 37 characters since the autogenerated UUID suffix was 26 characters which combined to +the total max length for names of 63 characters. +In 6.0.0, providing a `name_prefix` larger than 37 characters will prompt the provider to use a shortened suffix of only 9 characters, leading to a new max of 54 characters for `name_prefix`. This shortened suffix is inevitably more prone to collisions, so use the longer max `name_prefix` length with caution. -## Resources +## Provider: Opt-out deletion protection is added to several resources, including google_project -## Resource: `google_bigquery_table` +Affected resources: `google_cloud_run_v2_job`, `google_cloud_run_v2_service`, `google_domain`, `google_folder`, +`google_project` -### View creation now validates `schema` +Protection against Terraform deleting these resources has been added via a new field in each resource which is enabled by default. See the individual resource entries for the field names and other resource-specific details. -A `view` can no longer be created when `schema` contains required fields +## Resource: `google_alloydb_cluster` -### `allow_resource_tags_on_deletion` is now removed +### `network` is now removed -Resource tags are now always allowed on table deletion. +`network` has been removed in favor of `network_config.network` ## Resource: `google_bigquery_reservation` @@ -138,44 +129,15 @@ Resource tags are now always allowed on table deletion. This field is no longer supported by the BigQuery Reservation API. -## Resource: `google_sql_database_instance` - -### `settings.ip_configuration.require_ssl` is now removed - -Removed in favor of field `settings.ip_configuration.ssl_mode`. - -## Resource: `google_pubsub_topic` - -### `schema_settings` no longer has a default value - -An empty value means the setting should be cleared. - -## Resources: `google_container_cluster`, `google_container_node_pool`, and `google_compute_instance` - -### `guest_accelerator = []` is no longer valid configuration - -To explicitly set an empty list of objects, set `guest_accelerator.count = 0`. - -Previously, to explicitly set `guest_accelerator` as an empty list of objects, the specific configuration `guest_accelerator = []` was necessary. -This was to maintain compatability in behavior between Terraform versions 0.11 and 0.12 using a special setting ["attributes as blocks"](https://developer.hashicorp.com/terraform/language/attr-as-blocks). -This special setting causes other breakages so it is now removed, with setting `guest_accelerator.count = 0` available as an alternative form of empty `guest_accelerator` object. - -### `guest_accelerator.gpu_driver_installation_config = []` and `guest_accelerator.gpu_sharing_config = []` are no longer valid configuration - -These were never intended to be set this way. Removing the fields from configuration should not produce a diff. - -## Resource: `google_domain` +## Resource: `google_bigquery_table` -### Domain deletion now prevented by default with `deletion_protection` +### View creation now validates `schema` -The field `deletion_protection` has been added with a default value of `true`. This field prevents -Terraform from destroying or recreating the Domain. In 6.0.0, existing domains will have -`deletion_protection` set to `true` during the next refresh unless otherwise set in configuration. +A `view` can no longer be created when `schema` contains required fields -**`deletion_protection` does NOT prevent deletion outside of Terraform.** +### `allow_resource_tags_on_deletion` is now removed -To disable deletion protection, explicitly set this field to `false` in configuration -and then run `terraform apply` to apply the change. +Resource tags are now always allowed on table deletion. ## Resource: `google_cloud_run_v2_job` @@ -226,25 +188,7 @@ If you were relying on accessing an individual environment variable by index (fo There was no functional difference between setting `ip_allocation_policy = []` and not setting `ip_allocation_policy` at all. Removing the field from configuration should not produce a diff. -## Resources: `google_compute_instance_from_template` and `google_compute_instance_from_machine_image` - -### `network_interface.alias_ip_range, network_interface.access_config, attached_disk, guest_accelerator, service_account, scratch_disk` can no longer be set to an empty block `[]` - -`field = []` is no longer valid configuration for these fields. Removing the fields from configuration should not produce a diff. - -## Resource: `google_compute_subnetwork` - -### `secondary_ip_range = []` is no longer valid configuration - -To explicitly set an empty list of objects, use `send_secondary_ip_range_if_empty = true` and completely remove `secondary_ip_range` from config. - -Previously, to explicitly set `secondary_ip_range` as an empty list of objects, the specific configuration `secondary_ip_range = []` was necessary. -This was to maintain compatability in behavior between Terraform versions 0.11 and 0.12 using a special setting ["attributes as blocks"](https://developer.hashicorp.com/terraform/language/attr-as-blocks). -This special setting causes other breakages so it is now removed, with `send_secondary_ip_range_if_empty` available instead. - -## Resource: `google_compute_backend_service` - -## Resource: `google_compute_region_backend_service` +## Resources: `google_compute_backend_service` and `google_compute_region_backend_service` ### `iap.enabled` is now required in the `iap` block @@ -262,59 +206,35 @@ An empty value now means 300. An empty value now means UTILIZATION. -## Resource: `google_redis_cluster` - -### `deletion_protection_enabled` field with default value added +## Resources: `google_compute_instance`, `google_container_cluster`, and `google_container_node_pool` -Support for the deletionProtectionEnabled field has been added. Redis clusters will now be created with a `deletion_protection_enabled = true` value by default. - -## Resource: `google_vpc_access_connector` - -### Fields `min_throughput` and `max_throughput` no longer have default values - -The fields `min_throughput` and `max_throughput` no longer have default values -set by the provider. This was necessary to add conflicting field validation, also -described in this guide. - -No configuration changes are needed for existing resources as these fields' values -will default to values present in data returned from the API. - -### Conflicting field validation added for `min_throughput` and `min_instances`, and `max_throughput` and `max_instances` +### `guest_accelerator = []` is no longer valid configuration -The provider will now enforce that `google_vpc_access_connector` resources can only -include one of `min_throughput` and `min_instances` and one of `max_throughput` and -`max_instances`. Previously if a user included all four fields in a resource block -they would experience a permadiff. This is a result of how `min_instances` and -`max_instances` fields' values take precedence in the API, and how the API calculates -values for `min_throughput` and `max_throughput` that match the number of instances. +To explicitly set an empty list of objects, set `guest_accelerator.count = 0`. -Users will need to check their configuration for any `google_vpc_access_connector` -resource blocks that contain both fields in a conflicting pair, and remove one of those fields. -The fields that are removed from the configuration will still have Computed values, -that are derived from the API. +Previously, to explicitly set `guest_accelerator` as an empty list of objects, the specific configuration `guest_accelerator = []` was necessary. +This was to maintain compatability in behavior between Terraform versions 0.11 and 0.12 using a special setting ["attributes as blocks"](https://developer.hashicorp.com/terraform/language/attr-as-blocks). +This special setting causes other breakages so it is now removed, with setting `guest_accelerator.count = 0` available as an alternative form of empty `guest_accelerator` object. -## Resource: `google_folder` +### `guest_accelerator.gpu_driver_installation_config = []` and `guest_accelerator.gpu_sharing_config = []` are no longer valid configuration -### Folder deletion now prevented by default with `deletion_protection` +These were never intended to be set this way. Removing the fields from configuration should not produce a diff. -The field `deletion_protection` has been added with a default value of `true`. This field prevents -Terraform from destroying or recreating the Folder. In 6.0.0, existing folders will have -`deletion_protection` set to `true` during the next refresh unless otherwise set in configuration. +## Resources: `google_compute_instance_from_template` and `google_compute_instance_from_machine_image` -**`deletion_protection` does NOT prevent deletion outside of Terraform.** +### `network_interface.alias_ip_range, network_interface.access_config, attached_disk, guest_accelerator, service_account, scratch_disk` can no longer be set to an empty block `[]` -To disable deletion protection, explicitly set this field to `false` in configuration -and then run `terraform apply` to apply the change. +`field = []` is no longer valid configuration for these fields. Removing the fields from configuration should not produce a diff. -## Resource: `google_storage_bucket` +## Resource: `google_compute_subnetwork` -### `lifecycle_rule.condition.no_age` is now removed +### `secondary_ip_range = []` is no longer valid configuration -Previously `lifecycle_rule.condition.age` attribute was being set zero value by default and `lifecycle_rule.condition.no_age` was introduced to prevent that. -Now `lifecycle_rule.condition.no_age` is no longer supported and `lifecycle_rule.condition.age` won't set a zero value by default. -Removed in favor of the field `lifecycle_rule.condition.send_age_if_zero` which can be used to set zero value for `lifecycle_rule.condition.age` attribute. +To explicitly set an empty list of objects, use `send_secondary_ip_range_if_empty = true` and completely remove `secondary_ip_range` from config. -For a seamless update, if your state today uses `no_age=true`, update it to remove `no_age` and set `send_age_if_zero=false`. If you do not use `no_age=true`, you will need to add `send_age_if_zero=true` to your state to avoid any changes after updating to 6.0.0. +Previously, to explicitly set `secondary_ip_range` as an empty list of objects, the specific configuration `secondary_ip_range = []` was necessary. +This was to maintain compatability in behavior between Terraform versions 0.11 and 0.12 using a special setting ["attributes as blocks"](https://developer.hashicorp.com/terraform/language/attr-as-blocks). +This special setting causes other breakages so it is now removed, with `send_secondary_ip_range_if_empty` available instead. ## Resource: `google_container_cluster` @@ -342,8 +262,6 @@ See exported endpoints for Dataplane V2 Observability feature to learn what target you might wish to expose with load balancers: https://cloud.google.com/kubernetes-engine/docs/concepts/about-dpv2-observability#gke-dataplane-v2-observability-endpoints -## Resource: `google_container_cluster` - ### Three label-related fields are now present * `resource_labels` field is non-authoritative and only manages the labels defined by @@ -362,6 +280,23 @@ All of these three fields include all of the labels present on the resource in G the labels configured through Terraform, the system, and other clients, equivalent to `effective_labels` on the resource. +## Resource: `google_datastore_index` is now removed + +`google_datastore_index` is removed in favor of `google_firestore_index` + +## Resource: `google_domain` + +### Domain deletion now prevented by default with `deletion_protection` + +The field `deletion_protection` has been added with a default value of `true`. This field prevents +Terraform from destroying or recreating the Domain. In 6.0.0, existing domains will have +`deletion_protection` set to `true` during the next refresh unless otherwise set in configuration. + +**`deletion_protection` does NOT prevent deletion outside of Terraform.** + +To disable deletion protection, explicitly set this field to `false` in configuration +and then run `terraform apply` to apply the change. + ## Resource: `google_edgenetwork_network` ### Three label-related fields are now present @@ -384,46 +319,59 @@ on the resource through Terraform and the default labels configured on the provi * The new output-only `effective_labels` field lists all of labels present on the resource in GCP, including the labels configured through Terraform, the system, and other clients. -## Resource: `google_workstations_workstation_config` - -### `host.gce_instance.disable_ssh` now defaults to true - -* `disable_ssh` field now defaults to true. To enable SSH, please set `disable_ssh` to false. +## Resource: `google_folder` -## Removals +### Folder deletion now prevented by default with `deletion_protection` -### Resource: `google_alloydb_cluster` +The field `deletion_protection` has been added with a default value of `true`. This field prevents +Terraform from destroying or recreating the Folder. In 6.0.0, existing folders will have +`deletion_protection` set to `true` during the next refresh unless otherwise set in configuration. -## `network` is now removed +**`deletion_protection` does NOT prevent deletion outside of Terraform.** -`network` has been removed in favor of `network_config.network` +To disable deletion protection, explicitly set this field to `false` in configuration +and then run `terraform apply` to apply the change. -### Resource: `google_identity_platform_project_default_config` is now removed +## Resource: `google_identity_platform_project_default_config` is now removed `google_identity_platform_project_default_config` is removed in favor of `google_identity_platform_project_config` ## Resource: `google_integrations_client` -### `create_sample_worklfows` and `provision_gmek` is now removed +### `create_sample_workflows` and `provision_gmek` is now removed -`create_sample_worklfows` and `provision_gmek` is now removed in favor of `create_sample_integrations` +`create_sample_workflows` and `provision_gmek` is now removed in favor of `create_sample_integrations` ## Resource: `google_project` ### Project deletion now prevented by default with `deletion_policy` -The field `skip_delete` is removed and the default value for `deletion_policy` is now -`PREVENT` instead of `DELETE`. The `PREVENT` value for `deletion_policy` stops Terraform -from deleting or recreating your project. Setting this field to `ABANDON` allows the -resource to be abandoned instead of deleted. To remove deletion protection entirely, -explicitly set this field to `DELETE` in your configuration and run `terraform apply`. A -`skip_delete` value of `false` can be changed to a `deletion_policy` value of `DELETE` and -a `skip_delete` value of `true` to a `deletion_policy` value of `ABANDON` for equivalent -behavior. +The default value for `deletion_policy` is now `PREVENT` instead of `DELETE`. The `PREVENT` value for `deletion_policy` stops Terraform +from deleting or recreating your project. To remove deletion protection entirely, +explicitly set this field to `DELETE` in your configuration and run `terraform apply`. +Alternatively, setting this field to `ABANDON` allows Terraform to remove your project from state without destroying it. -### Resource: `google_datastore_index` is now removed +### `skip_delete` is now removed -`google_datastore_index` is removed in favor of `google_firestore_index` +`skip_delete` has been removed in favor of `deletion_policy`. In order to get the same behavior as `skip_delete = true`, set `deletion_policy = ABANDON`. Be aware that `deletion_policy = ABANDON` will override the error-on-delete behaviour that the `PREVENT` policy applies. + +## Resource: `google_pubsub_topic` + +### `schema_settings` no longer has a default value + +An empty value means the setting should be cleared. + +## Resource: `google_redis_cluster` + +### `deletion_protection_enabled` field with default value added + +Support for the deletionProtectionEnabled field has been added. Redis clusters will now be created with a `deletion_protection_enabled = true` value by default. + +## Resource: `google_sql_database_instance` + +### `settings.ip_configuration.require_ssl` is now removed + +Removed in favor of field `settings.ip_configuration.ssl_mode`. ## Resource: `google_storage_bucket` @@ -436,3 +384,34 @@ Removed in favor of the field `lifecycle_rule.condition.send_age_if_zero` which For a seamless update, if your state today uses `no_age=true`, update it to remove `no_age` and set `send_age_if_zero=false`. If you do not use `no_age=true` and desire to continue creating rules with an `age=0` condition, you will need to add `send_age_if_zero=true` to your state to avoid any changes after updating to 6.0.0. With the 6.0.0 update, `send_age_if_zero` will be set to `false` by default unless declared explicitly `true`, and `age=0` conditions will be removed from existing buckets next time your `lifecycle_rule.condition` configuration is updated. + +## Resource: `google_vpc_access_connector` + +### Fields `min_throughput` and `max_throughput` no longer have default values + +The fields `min_throughput` and `max_throughput` no longer have default values +set by the provider. This was necessary to add conflicting field validation, also +described in this guide. + +No configuration changes are needed for existing resources as these fields' values +will default to values present in data returned from the API. + +### Conflicting field validation added for `min_throughput` and `min_instances`, and `max_throughput` and `max_instances` + +The provider will now enforce that `google_vpc_access_connector` resources can only +include one of `min_throughput` and `min_instances` and one of `max_throughput` and +`max_instances`. Previously if a user included all four fields in a resource block +they would experience a permadiff. This is a result of how `min_instances` and +`max_instances` fields' values take precedence in the API, and how the API calculates +values for `min_throughput` and `max_throughput` that match the number of instances. + +Users will need to check their configuration for any `google_vpc_access_connector` +resource blocks that contain both fields in a conflicting pair, and remove one of those fields. +The fields that are removed from the configuration will still have Computed values, +that are derived from the API. + +## Resource: `google_workstations_workstation_config` + +### `host.gce_instance.disable_ssh` now defaults to true + +`disable_ssh` field now defaults to true. To enable SSH, please set `disable_ssh` to false.