Upgrading to Terraform v1.6
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.6 honors the Terraform v1.0 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:
See the full changelog 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 to discuss it.
Terraform Test
The previous experimental terraform test
command has been deprecated and replaced with a fully supported and finalized terraform test
command.
There are substantial differences between the previous experimental approach and the finalized approach:
- 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.
The major differences are discussed here, for more information consult the CLI and Language documentation.
Directory structure
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:
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:
Test structure and assertions
Previously, a test file would contain a module call and a collection of resources from the builtin test
provider:
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.
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.
S3 Backend
In Terraform 1.7.0 the S3 backend will begin phasing out the legacy credential chain evaluation order by defaulting use_legacy_workflow
to false
and deprecating the argument.
This will bring the default behavior of the backend into alignment with the AWS SDKs and CLI.
The legacy behavior can be preserved by setting this argument to true
.
In Terraform 1.8.0 this argument will be removed, and the S3 backend will always use the default AWS SDK for Go credential chain evaluation order.