HashiCorp Terraform Provider Versioning

In HashiCorp Terraform 0.10, Terraform was split into two logical components: Terraform Core and Terraform Providers. A major motivation for this change was the acknowledgement that provider development has a different scope and development speed. The various providers are constantly changing, and it's always been frustrating when a major new feature in your chosen platform is delayed in Terraform because of the need to coordinate releases with other providers and with Core.

A more mundane aspect of separate provider releases is separate provider version numbers. Previously Core and all of the providers shared a single version number for each release. Users may have noticed that, with the new separate release schedules, providers have begun their own version numbering scheme at 0.1.0, and have been incrementing from there.

Observing that Terraform providers are in many ways analogous to shared libraries in a programming language, we're adopting a version numbering scheme for providers that follows the guidelines of Semantic Versioning. In summary, this means that with a version number of the form MAJOR.MINOR.PATCH, the following meanings apply:

• Increasing only the patch number suggests that the release includes only bug fixes, and is intended to be functionally equivalent.
• Increasing the minor number suggests that new features have been added but that existing functionality remains broadly compatible.
• Increasing the major number indicates that significant breaking changes have been made, and thus extra care or attention is required during an upgrade.

At the time of writing, most of the providers within the terraform-providers GitHub organization remain on 0.x.x "initial development" numbering, which (per the semantic versioning spec) represents that the above promises do not necessarily yet apply. However, as each provider development team gets ready to work within this scheme it will be indicated by a release numbered 1.0.0, after which the above conventions will be adopted for future releases.

For providers in particular, the move to 1.0.0 will not generally represent any significant change in functionality or any change in development velocity. Most of the providers are already of very high quality and have a stable development process, so this version change is merely an acknowledgement of the existing quality and stability.

»Third-Party Providers

A discussion of provider versioning would not be complete without mentioning third-party providers. We know that many Terraform users maintain their own providers for a variety of additional services, and we are grateful that many of these are maintained as open source projects.

As the suite of providers distributed by HashiCorp has grown, it's become clear that maintaining all of them in-house at the level of quality we expect is impossible to scale. As a result of this, we are grateful to our collaborators in the community and in our partner organizations as we improve the development process. We want to ensure that every provider has a suite of acceptance tests with high coverage, and a responsive team of maintainers who can respond to issues and pull requests. As a consequence, we are being more reserved about adopting new providers into the set HashiCorp distributes.

In Terraform 0.10, the auto-install mechanism in Terraform Core supports only HashiCorp's server and so third-party providers must still be downloaded and copied manually to one of a set of local search directories.

Supporting only the HashiCorp releases service for the first release was a pragmatic compromise to allow this change to happen sooner, by building on distribution infrastructure that was already in place. A more general solution for distribution is planned, with the goal of making third-party-built providers just as easy to obtain and use.

In the meantime, we recommend that third-party provider maintainers begin to adopt a similar semantic versioning scheme for their releases, embedding these version numbers in the plugin binary filenames using the scheme terraform-provider-NAME_vX.Y.Z. Plugin binaries named in this way will be recognized by Terraform as being versioned, and will thus integrate with the explicit provider versioning mechanisms introduced in Terraform 0.10.0.

»Versioning of Terraform Core

Semantic versioning is primarily applicable to libraries, since its promises relate to compatibility with calling software via a well-defined API. Terraform Core, as an application, will therefore not be switching over to semantic versioning conventions and will instead continue in the same vein as other HashiCorp products.

Terraform is already used by many organizations to maintain critical infrastructure, and we take very seriously the tradeoff between improving Terraform's usability and feature set vs. maintaining compatibility with existing configurations and orchestration. Throughout the Terraform 0.x releases, we are listening to feedback and improving Terraform iteratively, making breaking changes only when warranted, and communicating about those changes via the changelog and upgrade guides.

The eventual 1.0 release will represent our intent to adopt an even stronger promise of backward-compatibility, but that entails first finding the right set of configuration language features, a maintainable internal architecture, a more complete module system, and various other aspects of the product so that we can commit to compatibility with the 1.0 feature set for the long haul.

It is our goal to remain as compatible as possible with the wide variety of existing uses of Terraform while continuing to improve it. Thank you to the community for the continued feedback as we continue iterating on the product design!