Add upgrade guide for v3.0.0 (hashicorp#1201)

- document all removed deprecated fields and their corresponding resources. - fix broken anchor links in v2.0.0 upgrade guide - remove encrypted_token refs for vault_token - document `2.x` maintenance policy Co-authored-by: Theron Voran <[email protected]>
harsimranmaan · Oct 25, 2021 · 2a5ea55 · 2a5ea55
1 parent 52897a5
commit 2a5ea55
Show file tree

Hide file tree

Showing 6 changed files with 336 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -22,8 +22,8 @@ This webinar walks you through how to protect secrets when using Terraform with
 Requirements
 ------------
 
--	[Terraform](https://www.terraform.io/downloads.html) 0.11.x
--	[Go](https://golang.org/doc/install) 1.16 (to build the provider plugin)
+- [Terraform](https://www.terraform.io/downloads.html) 0.12.x and above, we recommend using the latest stable release whenever possible.
+- [Go](https://golang.org/doc/install) 1.17 (to build the provider plugin)
 
 Building The Provider
 ---------------------

diff --git a/website/docs/guides/version_2_upgrade.html.markdown b/website/docs/guides/version_2_upgrade.html.markdown
@@ -7,6 +7,11 @@ description: |-
 
 ---
 
+-> The `2.x` series of the Vault Provider is now in maintenance mode.
+It will only receive critical fixes on a case by case basis.
+All new feature development has been moved to the `3.x` series of the provider.
+Please see the [3.0.0 Upgrade Guide](./version_3_upgrade.html) for more details.
+
 # Terraform Vault Provider 2.0.0 Upgrade Guide
 
 Version `2.0.0` of the Vault provider for Terraform is a major release and
@@ -40,10 +45,10 @@ 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 `1.X` series release on `terraform init`.
 
-If you've only ran `terraform init` or `terraform plan`, your state will not
+If you've only run `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
+If you've run `terraform refresh` or `terraform apply`, Terraform may have made
 state changes in the meantime.
 
 - If you're using a *local* state, `terraform refresh` with a downgraded
@@ -60,17 +65,15 @@ state changes in the meantime.
 <!-- TOC depthFrom:2 depthTo:2 -->
 
 - [Provider Version Configuration](#provider-version-configuration)
-- [Data Sources](#data-sources)
-- [Resource: `vault_auth_backend`](#resource-vault-auth-backend)
-- [Resource: `vault_aws_auth_backend_role`](#resource-vault-aws-auth-backend-role)
-- [Resource: `vault_aws_secret_backend_role`](#resource-vault-aws-secret-backend-role)
-- [Resource: `vault_database_secret_backend_role`](#resource-vault-database-secret-backend-role)
-- [Resource: `vault_gcp_auth_backend_role`](#resource-gcp-auth-backend-role)
-- [Resource: `vault_generic_secret`](#resource-vault-generic-secret)
-- [Resource: `vault_pki_secret_backend_config_urls`](#resource-vault-pki-secret-backend-config-urls)
-- [Resource: `vault_pki_secret_backend_role`](#resource-vault-pki-secret-backend-role)
-- [Resource: `vault_pki_secret_backend_sign`](#resource-vault-pki-secret-backend-sign)
-- [Resource: `vault_rabbitmq_secret_backend_role`](#resource-vault-rabbitmq-secret-backend-role)
+- [Resource: `vault_auth_backend`](#resource-vault_auth_backend)
+- [Resource: `vault_aws_auth_backend_role`](#resource-vault_aws_auth_backend_role)
+- [Resource: `vault_database_secret_backend_role`](#resource-vault_database_secret_backend_role)
+- [Resource: `vault_gcp_auth_backend_role`](#resource-vault_gcp_auth_backend_role)
+- [Resource: `vault_generic_secret`](#resource-vault_generic_secret)
+- [Resource: `vault_pki_secret_backend_config_urls`](#resource-vault_pki_secret_backend_config_urls)
+- [Resource: `vault_pki_secret_backend_role`](#resource-vault_pki_secret_backend_role)
+- [Resource: `vault_pki_secret_backend_sign`](#resource-vault_pki_secret_backend_sign)
+- [Resource: `vault_rabbitmq_secret_backend_role`](#resource-vault_rabbitmq_secret_backend_role)
 
 <!-- /TOC -->
 

diff --git a/website/docs/guides/version_3_upgrade.html.markdown b/website/docs/guides/version_3_upgrade.html.markdown
@@ -0,0 +1,308 @@
+---
+layout: "vault"
+page_title: "Terraform Vault Provider 3.0.0 Upgrade Guide"
+sidebar_current: "docs-vault-provider-version-3-upgrade"
+description: |-
+  Terraform Vault Provider 3.0.0 Upgrade Guide
+
+---
+
+# Terraform Vault Provider 3.0.0 Upgrade Guide
+
+Version `3.0.0` of the Vault provider for Terraform is a major release 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 version `2.24.0` 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 2.24.0. These changes, such as deprecation notices,
+can always be found in the [CHANGELOG](https://github.com/hashicorp/terraform-provider-vault/blob/master/CHANGELOG.md).
+
+-> If you are upgrading from `1.9.x`. Please follow the
+[2.0.0 Upgrade Guide](./version_2_upgrade.html) before proceeding any further.
+
+## Why version 3.0.0?
+
+We introduced version `3.0.0` of the Vault provider in order to upgrade to the
+[Terraform Plugin SDKv2](https://www.terraform.io/docs/extend/sdkv2-intro.html).
+The change was deemed significant enough to warrant the major version bump.
+In addition to the aforementioned SDK upgrade all previously deprecated fields
+have been removed.
+
+While you may see some small changes in your configurations as a result of
+these changes, we don't expect you'll need to make any major refactorings.
+
+## Which Terraform versions are supported?
+
+Terraform versions `0.12.x` and greater are fully supported. Support for `0.11.x` has been removed.
+If you are still on one of the `0.11.x` versions we recommend upgrading to the latest stable release of Terraform.
+
+Please see the [Terraform Upgrade Guide](https://www.terraform.io/upgrade-guides/index.html)
+for more info about upgrading Terraform.
+
+## 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 run `terraform init` or `terraform plan`, your state will not
+have been modified and downgrading your provider is sufficient.
+
+If you've run `terraform refresh` or `terraform apply`, Terraform may have made
+state changes in the meantime.
+
+- If you're using a *local* state, `terraform refresh` with a downgraded
+  provider is likely sufficient to revert your state.
+- If you're using a *remote* state backend
+  - That does not support versioning, see the local state instructions above
+  - That supports *versioning* you can revert the Terraform state file to a previous
+    version by hand. If you do so and Terraform created resources as part of a
+    `terraform apply`, you'll need to either `terraform import` them or delete
+    them by hand.
+
+## Upgrade Topics
+
+<!-- TOC depthFrom:2 depthTo:2 -->
+
+- [Provider Version Configuration](#provider-version-configuration)
+
+- [Data Source: `vault_kubernetes_auth_backend_role`](#data-source-vault_kubernetes_auth_backend_role)
+
+- [Resource: `vault_approle_auth_backend_role`](#resource-vault_approle_auth_backend_role)
+- [Resource: `vault_auth_backend`](#resource-vault_auth_backend)
+- [Resource: `vault_aws_auth_backend_role`](#resource-vault_aws_auth_backend_role)
+- [Resource: `vault_azure_auth_backend_role`](#resource-vault_azure_auth_backend_role)
+- [Resource: `vault_cert_auth_backend_role`](#resource-vault_cert_auth_backend_role)
+- [Resource: `vault_consul_secret_backend_role`](#resource-vault_consul_secret_backend_role)
+- [Resource: `vault_gcp_auth_backend_role`](#resource-vault_gcp_auth_backend_role)
+- [Resource: `vault_generic_secret`](#resource-vault_generic_secret)
+- [Resource: `vault_github_auth_backend`](#resource-vault_github_auth_backend)
+- [Resource: `vault_jwt_auth_backend_role`](#resource-vault_jwt_auth_backend_role)
+- [Resource: `vault_kubernetes_auth_backend_role`](#resource-vault_kubernetes_auth_backend_role)
+- [Resource: `vault_token`](#resource-vault_token)
+- [Resource: `vault_token_auth_backend_role`](#resource-vault_token_auth_backend_role)
+
+<!-- /TOC -->
+
+## Provider Version Configuration
+
+-> Before upgrading to version `3.0.0`, it is recommended to upgrade to the most
+recent version of the provider (`2.24.0`) 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 "vault" {
+  # ... other configuration ...
+
+  version = "~> 2.24.0"
+}
+```
+
+An updated configuration:
+
+```hcl
+provider "vault" {
+  # ... other configuration ...
+
+  version = "~> 3.0.0"
+}
+```
+
+## Data Source: `vault_kubernetes_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `bound_cidrs` - use `token_bound_cidrs` instead.
+
+* `ttl` - use `token_ttl` instead.
+
+* `max_ttl` - use `token_max_ttl` instead.
+
+* `policies` - use `token_policies` instead.
+
+* `period` - use `token_period` instead.
+
+* `num_uses` - use `token_num_uses` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_approle_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `bound_cidr_list` - use `secret_id_bound_cidrs` instead.
+
+* `policies` - use `token_policies` instead.
+
+* `period` - use `token_period` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_auth_backend`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `default_lease_ttl_seconds` - use `tune.default_lease_ttl` instead.
+
+* `max_lease_ttl_seconds` - use `tune.max_lease_ttl` instead.
+
+* `listing_visibility` - use `tune.listing_visibility` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_aws_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `ttl` - use `token_ttl` instead.
+
+* `max_ttl` - use `token_max_ttl` instead.
+
+* `policies` - use `token_policies` instead.
+
+* `period` - use `token_period` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_azure_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `ttl` - use `token_ttl` instead.
+
+* `max_ttl` - use `token_max_ttl` instead.
+
+* `policies` - use `token_policies` instead.
+
+* `period` - use `token_period` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_cert_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `bound_cidrs` - use `token_bound_cidrs` instead.
+
+* `ttl` - use `token_ttl` instead.
+
+* `max_ttl` - use `token_max_ttl` instead.
+
+* `policies` - use `token_policies` instead.
+
+* `period` - use `token_period` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_consul_secret_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `path` - use `backend` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_gcp_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `project_id` - use `bound_projects` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_generic_secret`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `allow_read` - use `disable_read` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_github_auth_backend`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `ttl` - use `token_ttl` instead.
+
+* `max_ttl` - use `token_max_ttl` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_jwt_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `groups_claim_delimiter_pattern` - no alternate exists.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_kubernetes_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `num_uses` - use `token_num_uses` instead.
+
+* `ttl` - use `token_ttl` instead.
+
+* `max_ttl` - use `token_max_ttl` instead.
+
+* `policies` - use `token_policies` instead.
+
+* `period` - use `token_period` instead.
+
+* `bound_cidrs` - use `token_bound_cidrs` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_token`
+
+### Removed fields
+The following fields have been removed as they are no longer supported by the [Terraform Plugin SDK](https://www.terraform.io/docs/extend/guides/v2-upgrade-guide.html#removal-of-helper-encryption-package).
+Please see [Sensitive State Best Practices](https://www.terraform.io/docs/extend/best-practices/sensitive-state.html#don-39-t-encrypt-state) for more info.
+
+* `encrypted_client_token` - removed.
+
+* `pgp_key` - removed
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
+
+## Resource: `vault_token_auth_backend_role`
+
+### Deprecated fields have been removed
+The following deprecated fields have been removed:
+
+* `explicit_max_ttl` use `token_explicit_max_ttl` instead.
+
+* `period` - use `token_period` instead.
+
+* `bound_cidrs` - use `token_bound_cidrs` instead.
+
+_Specifying any of the fields above in your config or trying to interpolate them in your config will raise an error._
diff --git a/website/docs/index.html.markdown b/website/docs/index.html.markdown
@@ -205,12 +205,12 @@ provider "vault" {
 resource "vault_generic_secret" "example" {
   path = "secret/foo"
 
-  data_json = <<EOT
-{
-  "foo":   "bar",
-  "pizza": "cheese"
-}
-EOT
+  data_json = jsonencode(
+    {
+      "foo"   = "bar",
+      "pizza" = "cheese"
+    }
+  )
 }
 ```