Backport of Complete upgrade guide for v1.7 into v1.7 (#34519)

* backport of commit d57df01

* backport of commit d646454

* backport of commit 9025fa2

* backport of commit 13a762e

---------

Co-authored-by: Liam Cervante <[email protected]>

Author: The Terraform Team

website/docs/language/upgrade-guides/index.mdx

@@ -1,138 +1,45 @@
 ---
-page_title: Upgrading to Terraform v1.6
-description: Upgrading to Terraform v1.6
+page_title: Upgrading to Terraform v1.7
+description: Upgrading to Terraform v1.7
 ---
 
-# Upgrading to Terraform v1.6
+# Upgrading to Terraform v1.7
 
 -> **Tip:** Use the version selector to view the upgrade guides for older Terraform versions.
 
-Terraform v1.6 is a minor release in the stable Terraform v1.0 series.
+Terraform v1.7 is a minor release in the stable Terraform v1.0 series.
 
-Terraform v1.6 honors the
+Terraform v1.7 honors the
 [Terraform v1.0 Compatibility Promises](https://developer.hashicorp.com/terraform/language/v1-compatibility-promises),
 but there are some behavior changes outside of those promises that may affect a
 small number of users. Specifically, the following updates may require
 additional upgrade steps:
-* [End of experimental period for `terraform test`](#terraform-test)
-* [Deprecated parameters for the  S3 backend](#s3-backend)
+* [Validations and checks in the state file](#validations-and-checks)
+* [Deprecated parameters for the S3 backend](#s3-backend)
 
 See [the full changelog](https://github.com/hashicorp/terraform/blob/v1.6/CHANGELOG.md)
 for more details. If you encounter any problems during upgrading which are not
 covered this guide, please start a new topic in
 [the Terraform community forum](https://discuss.hashicorp.com/c/terraform-core)
 to discuss it.
 
-## Terraform Test
+## Validations and Checks
 
-The previous experimental `terraform test` command has been deprecated and replaced with a fully supported and finalized `terraform test` command.
+Due to a state interoperability issue ([#33770](https://github.com/hashicorp/terraform/issues/33770), [#34014](https://github.com/hashicorp/terraform/issues/34014)) in earlier versions of Terraform, state files created by the Terraform v1.7.x series may not be compatible with the following Terraform versions:
 
-There are substantial differences between the previous experimental approach and the finalized approach:
+* Terraform v1.3.0 through v1.3.9
+* Terraform v1.4.0 through v1.4.6
+* Terraform v1.5.0 through v1.5.6
 
-- The builtin test provider, `terraform.io/builtin/test`, has been removed and a dedicated syntax introduced for testing files.
-- A new `.tftest.hcl` file extension has been introduced for testing files, allowing a change into the directory structure and test file layout.
-- Test assertions and conditions execute with extended scope and access to the configuration under test.
+If your v1.7.x state file contains `check` blocks or input validations, it will not be compatible with the above versions. Attempting to load a state file created by Terraform v1.7.x in one of the above versions will result in an error similar to `Error refreshing state: unsupported checkable object "var"`. This will particularly affect configurations using the `terraform_remote_state` data source to load state files created by the `v1.7.x` series.
 
-The major differences are discussed here, for more information consult the [CLI](/terraform/cli/test) and [Language](/terraform/language/tests) documentation.
+To prevent this issue, users should upgrade any usage of the affected versions to the following patch releases in the relevant minor release series before attempting to process state files created by Terraform v1.7.x:
 
-### Directory structure
+* Terraform v1.3.x series users should upgrade to v1.3.10
+* Terraform v1.4.x series users should upgrade to v1.4.7
+* Terraform v1.5.x series users should upgrade to v1.5.7
 
-Previously, test files would be placed within their own subdirectories underneath the `tests` directory from the configuration directory. The following example contains three test files using the experimental framework:
-
-```
-main.tf
-outputs.tf
-providers.tf
-variables.tf
-tests/
-  defaults/
-    test_defaults.tf
-  maximums/
-    test_maximums.tf
-  minimums/
-    test_minimums.tf
-```
-
-With the new directory structure, tests are defined using the new `.tftest.hcl` file extension and do not need to be embedded within subdirectories. To help with organization, test files can, optionally, be embedded within a test directory. The name for this test directory defaults to `tests`, but can be overridden with the `-test-directory` flag.
-
-The following examples are both valid directory structures for test files in the updated framework:
-
-```
-main.tf
-outputs.tf
-providers.tf
-variables.tf
-defaults.tftest.hcl
-maximums.tftest.hcl
-minimums.tftest.hcl
-```
-
-```
-main.tf
-outputs.tf
-providers.tf
-variables.tf
-tests/
-  defaults.tftest.hcl
-  maximums.tftest.hcl
-  minimums.tftest.hcl
-```
-
-### Test structure and assertions
-
-Previously, a test file would contain a module call and a collection of resources from the builtin `test` provider:
-
-```hcl
-# tests/defaults/test_defaults.tf
-
-terraform{
-  required_providers {
-    test = {
-      source = "terraform.io/builtin/test"
-    }
-  }
-}
-
-module "main" {
-  source = "../.."
-}
-
-resource "test_assertions" "api_url" {
-  component = "api_url"
-
-  equal "scheme" {
-    description = "default scheme is https"
-    got         = module.main.scheme
-    want        = "https"
-  }
-  check "port_number" {
-    description = "default port number is 8080"
-    condition   = can(regex(":8080$", module.main.authority))
-  }
-}
-```
-
-With the new framework each test file is made up of a series of `run` blocks. Each `run` block represents a single `terraform plan` or a `terraform apply` operation executed against the main configuration. Assertions from within these `run` blocks can access outputs, variables, resources, and local values from the main configuration directly.
-
-```hcl
-# tests/defaults.tftest.hcl
-
-run "test_defaults" {
-  assert {
-    condition     = output.scheme == "https"
-    error_message = "default scheme should be https"
-  }
-
-  assert {
-    condition     = can(regex(":8080", output.authority))
-    error_message = "default port number should be 8080"
-  }
-}
-```
-
-The above examples demonstrates the differences in layout, scope and access between the two approaches. In the experimental framework, access is granted as if the configuration was being called like a normal module call. In the released framework, assertions execute as if they are custom conditions defined within the main configuration directly.
-
-The `run` block also applies or plans the main configuration by default, there is no need for the specific module call seen in the experimental framework.
+Terraform versions prior to v1.3.0 and equal to or after v1.6.0 are not affected by this issue.
 
 ## S3 Backend