Announcement: Upcoming Changes in Version 3.0 of the AWS Provider

[breathingdust]

In the time since the last major provider release in February of 2019, we have been listening closely to the community's feedback. Areas of particular interest are where users are finding friction in the day to day use of the provider. In some cases, we are able to resolve these issues in the course of our weekly releases, but in some cases, the changes necessitate a breaking change. The bulk of the v3.0 release is made up of small quality of life changes and improving consistency by removing atypical behaviors in existing resources in favor of ones well understood by practitioners.

Summary

A major release is our opportunity to make breaking changes in a scheduled and publicized manner in an attempt to avoid unnecessary churn for our users. We attempt to limit major releases to a once-yearly schedule. Version v2.0 of the AWS provider was released in February of 2019.

Along with larger changes in behavior detailed below this release will also remove attributes that have been marked as deprecated. Typically these have been marked as such due to changes in the upstream API, or in some cases that the use of the attribute causes confusion.

This release also adopts the Terraform SDK v2.0. This upgrade allows for future enhancements to the provider that can only be supported by Terraform CLI 0.12 and later.

Drop Native Support for Terraform 0.11 and Earlier

In order for the provider to keep in step with Terraform Core development and to take advantage of Terraform 0.12 and later native features (such as the ability to surface warning messages in resources), we need to drop support for earlier versions of Terraform. As of this release, practitioners who wish to remain on 0.11 will be limited to v2.* releases of the provider. This move will also consolidate all example code to use Terraform 0.12 syntax. Examples using the older syntax style can still be viewed by browsing older versions of the provider in the Terraform Registry.

Remove Hashing from State Storage

Hashing schema attribute values in Terraform state storage was implemented as a workaround for attribute-level encryption of some sensitive values. Terraform is designed to work with wholly known values during resource operations and when performing diffs. For example, if a resource only saves a hashed value in the state, during update operations the resource will incorrectly send the hashed value in API calls.

This change is expected to be transparent to users, and expanded reasoning as to the change can be found on the Terraform Website.

Authentication Ordering and Improvements

Unlike the AWS CLI, the AWS Go SDK does not enable support for the shared AWS configuration file (e.g. ~/.aws/config) by default. In version 2 of the provider and earlier, this required setting the AWS_SDK_LOAD_CONFIG environment variable to enable this support. Newer practitioners to Terraform are confused by different behavior between the AWS CLI and Terraform AWS Provider. This release also ensures the shared configuration file, if used, is referenced before using EC2 Instance Metadata credentials. In version 2 of the provider and earlier, this required disabling the EC2 Instance Metadata handling via the skip_metadata_api_check provider configuration or AWS_EC2_METADATA_DISABLED environment variable. With version 3 of the provider, the authentication behavior of the provider should generally be more inline with the AWS CLI behaviors and ensure that shared configuration settings, such as credential process, are honored as expected without extra workarounds. These authentication changes were separately applied to the Terraform S3 Backend as part of the Terraform CLI 0.13.0-beta2 release.

Remove Multiple Resource Imports

Terraform historically has supported importing multiple resources at once, however this support was not implemented in many resources. In the few cases where it was, these additional resources imported cannot have their state references controlled by the user, risking API deletion in the next Terraform run unless the Terraform configuration is carefully updated to match the secondary resource import structure. This is a tedious and error-prone process. Terraform may also not have access to these secondary resources during import, returning unexpected and unavoidable errors. Given all this, practitioners have come to expect that Terraform resource imports only do the resource given. This version removes the multiple resource import support from the aws_s3_bucket and aws_security_group resources.

Remove Non-Inclusive Terminology

We are also taking this opportunity to remove non-inclusive terminology in the provider codebase, documentation, and examples. We will be removing words whose meanings, origin, or associations are contrary to our Principles.

Follow our Progress

The full contents of the major release and progress towards it can be viewed in the v3.0.0 milestone

Upgrading

As a major version contains breaking changes, it is considered best practice to pin a provider version to avoid bringing in potentially breaking changes automatically. To remain on v2.* versions of the provider until such time that you are able to accommodate those changes, either pin to any v2.* version:

terraform {
 required_providers {
   aws = "~> 2.x"
 }
}

Or a specific version:

terraform {
 required_providers {
   aws = "=2.66.0"
 }
}

Full documentation on how to pin a version of a provider can be found on the Terraform Website.

Your usage patterns will dictate how much effort upgrading to v3.0 will take. We document each breaking change in our upgrade guide which will describe what changes are necessary to existing resources to preserve behavior. The upgrade guide can be found here on the Terraform Website.

[bflad]

Version 3.0.0 of the Terraform AWS Provider was just released. 👍 Please see the Version 3 Upgrade Guide for additional provider-level and resource-level changes.

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you feel this issue should be reopened, we encourage creating a new issue linking back to this one for added context. Thanks!