From 6960ada6db1f9456430d78a6f9db5582d26cbfeb Mon Sep 17 00:00:00 2001 From: Riley Karson Date: Tue, 1 Oct 2019 20:05:41 +0000 Subject: [PATCH] Add a `3.0.0` upgrade guide including google_project_services deprecation Signed-off-by: Modular Magician --- website/docs/version_3_upgrade.html.markdown | 159 +++++++++++++++++++ website/google.erb | 3 + 2 files changed, 162 insertions(+) create mode 100644 website/docs/version_3_upgrade.html.markdown diff --git a/website/docs/version_3_upgrade.html.markdown b/website/docs/version_3_upgrade.html.markdown new file mode 100644 index 00000000000..b4794acb005 --- /dev/null +++ b/website/docs/version_3_upgrade.html.markdown @@ -0,0 +1,159 @@ +--- +layout: "google" +page_title: "Terraform Google Provider 3.0.0 Upgrade Guide" +sidebar_current: "docs-google-provider-version-3-upgrade" +description: |- + Terraform Google Provider 3.0.0 Upgrade Guide +--- + +# Terraform Google Provider 3.0.0 Upgrade Guide + +The `3.0.0` release of the Google provider for Terraform is a major version and +includes some changes that you will need to consider when upgrading. This guide +is intended to help with that process and focuses only on the changes necessary +to upgrade from the final `2.X` series release to `3.0.0`. + +Most of the changes outlined in this guide have been previously marked as +deprecated in the Terraform `plan`/`apply` output throughout previous provider +releases, up to and including the final `2.X` series release. These changes, +such as deprecation notices, can always be found in the CHANGELOG of the +affected providers. [google](https://github.com/terraform-providers/terraform-provider-google/blob/master/CHANGELOG.md) +[google-beta](https://github.com/terraform-providers/terraform-provider-google-beta/blob/master/CHANGELOG.md) + +## I accidentally upgraded to 3.0.0, how do I downgrade to `2.X`? + +If you've inadvertently upgraded to `3.0.0`, first see the +[Provider Version Configuration Guide](#provider-version-configuration) to lock +your provider version; if you've constrained the provider to a lower version +such as shown in the previous version example in that guide, Terraform will pull +in a `2.X` series release on `terraform init`. + +If you've only ran `terraform init` or `terraform plan`, your state will not +have been modified and downgrading your provider is sufficient. + +If you've ran `terraform refresh` or `terraform apply`, Terraform may have made +state changes in the meantime. + +* If you're using a local state, or a remote state backend that does not support +versioning, `terraform refresh` with a downgraded provider is likely sufficient +to revert your state. The Google provider generally refreshes most state +information from the API, and the properties necessary to do so have been left +unchanged. + +* If you're using a remote state backend that supports versioning such as +[Google Cloud Storage](https://www.terraform.io/docs/backends/types/gcs.html), +you can revert the Terraform state file to a previous version. If you do +so and Terraform had created resources as part of a `terraform apply` in the +meantime, you'll need to either delete them by hand or `terraform import` them +so Terraform knows to manage them. + +## Upgrade Topics + + +- [Resource: `google_project_services`](#resource-google_project_services) + + + +## Provider Version Configuration + +-> Before upgrading to version 3.0.0, it is recommended to upgrade to the most +recent `2.X` series release of the provider and ensure that your environment +successfully runs [`terraform plan`](https://www.terraform.io/docs/commands/plan.html) +without unexpected changes or deprecation notices. + +It is recommended to use [version constraints](https://www.terraform.io/docs/configuration/providers.html#provider-versions) +when configuring Terraform providers. If you are following that recommendation, +update the version constraints in your Terraform configuration and run +[`terraform init`](https://www.terraform.io/docs/commands/init.html) to download +the new version. + +If you aren't using version constraints, you can use `terraform init -upgrade` +in order to upgrade your provider to the latest released version. + +For example, given this previous configuration: + +```hcl +provider "google" { + # ... other configuration ... + + version = "~> 2.17.0" +} +``` + +An updated configuration: + +```hcl +provider "google" { + # ... other configuration ... + + version = "~> 3.0.0" +} +``` + +## Resource: `google_project_services` + +### `google_project_services` has been removed from the provider + +The `google_project_services` resource was authoritative over the list of GCP +services enabled on a project, so that services not explicitly set would be +removed by Terraform. + +However, this was dangerous to use in practice. Services have dependencies that +are automatically enabled alongside them and GCP will add dependencies to +services out of band, enabling them. If a user ran Terraform after this, +Terraform would disable the service- and implicitly disable any service that +relied on it. + +The `google_project_service` resource is a much better match for most users' +intent, managing a single service at a time. Setting several +`google_project_service` resources is an assertion that "these services are set +on this project", while `google_project_services` was an assertion that "**only** +these services are set on this project". + +Users should migrate to using `google_project_service` resources, or using the +[`"terraform-google-modules/project-factory/google//modules/project_services"`](https://registry.terraform.io/modules/terraform-google-modules/project-factory/google/3.3.0/submodules/project_services) +module for a similar interface to `google_project_services`. + +#### Old Config + +```hcl +resource "google_project_services" "project" { + project = "your-project-id" + services = ["iam.googleapis.com", "cloudresourcemanager.googleapis.com"] + disable_on_destroy = false +} +``` + +#### New Config (module) + +```hcl +module "project_services" { + source = "terraform-google-modules/project-factory/google//modules/project_services" + version = "3.3.0" + + project_id = "your-project-id" + activate_apis = [ + "iam.googleapis.com", + "cloudresourcemanager.googleapis.com", + ] + + disable_services_on_destroy = false + disable_dependent_services = false +} +``` + +#### New Config (google_project_service) + +```hcl +resource "google_project_service" "project_iam" { + project = "your-project-id" + service = "iam.googleapis.com" + disable_on_destroy = false +} + +resource "google_project_service" "project_cloudresourcemanager" { + project = "your-project-id" + service = "cloudresourcemanager.googleapis.com" + disable_on_destroy = false +} +``` diff --git a/website/google.erb b/website/google.erb index 7d91181e34a..4978b08bacc 100644 --- a/website/google.erb +++ b/website/google.erb @@ -24,6 +24,9 @@ > 2.0.0 Upgrade Guide + > + 3.0.0 Upgrade Guide +