97 lines
4.0 KiB
Plaintext
97 lines
4.0 KiB
Plaintext
---
|
|
page_title: Version Constraints - Configuration Language
|
|
description: >-
|
|
Version constraint strings specify a range of acceptable versions for modules,
|
|
providers, and Terraform itself. Learn version constraint syntax and behavior.
|
|
---
|
|
|
|
# Version Constraints
|
|
|
|
Anywhere that Terraform lets you specify a range of acceptable versions for
|
|
something, it expects a specially formatted string known as a version
|
|
constraint. Version constraints are used when configuring:
|
|
|
|
- [Modules](/language/modules)
|
|
- [Provider requirements](/language/providers/requirements)
|
|
- [The `required_version` setting](/language/settings#specifying-a-required-terraform-version) in the `terraform` block.
|
|
|
|
## Version Constraint Syntax
|
|
|
|
Terraform's syntax for version constraints is very similar to the syntax used by
|
|
other dependency management systems like Bundler and NPM.
|
|
|
|
```hcl
|
|
version = ">= 1.2.0, < 2.0.0"
|
|
```
|
|
|
|
A version constraint is a [string literal](/language/expressions/strings)
|
|
containing one or more conditions, which are separated by commas.
|
|
|
|
Each condition consists of an operator and a version number.
|
|
|
|
Version numbers should be a series of numbers separated by periods (like
|
|
`1.2.0`), optionally with a suffix to indicate a beta release.
|
|
|
|
The following operators are valid:
|
|
|
|
- `=` (or no operator): Allows only one exact version number. Cannot be combined
|
|
with other conditions.
|
|
|
|
- `!=`: Excludes an exact version number.
|
|
|
|
- `>`, `>=`, `<`, `<=`: Comparisons against a specified version, allowing
|
|
versions for which the comparison is true. "Greater-than" requests newer
|
|
versions, and "less-than" requests older versions.
|
|
|
|
- `~>`: Allows only the _rightmost_ version component to increment. For example,
|
|
to allow new patch releases within a specific minor release, use the full
|
|
version number: `~> 1.0.4` will allow installation of `1.0.5` and `1.0.10`
|
|
but not `1.1.0`. This is usually called the pessimistic constraint operator.
|
|
|
|
## Version Constraint Behavior
|
|
|
|
A version number that meets every applicable constraint is considered acceptable.
|
|
|
|
Terraform consults version constraints to determine whether it has acceptable
|
|
versions of itself, any required provider plugins, and any required modules. For
|
|
plugins and modules, it will use the newest installed version that meets the
|
|
applicable constraints.
|
|
|
|
If Terraform doesn't have an acceptable version of a required plugin or module,
|
|
it will attempt to download the newest version that meets the applicable
|
|
constraints.
|
|
|
|
If Terraform isn't able to obtain acceptable versions of external dependencies,
|
|
or if it doesn't have an acceptable version of itself, it won't proceed with any
|
|
plans, applies, or state manipulation actions.
|
|
|
|
Both the root module and any child module can constrain the acceptable versions
|
|
of Terraform and any providers they use. Terraform considers these constraints
|
|
equal, and will only proceed if all of them can be met.
|
|
|
|
A prerelease version is a version number that contains a suffix introduced by
|
|
a dash, like `1.2.0-beta`. A prerelease version can be selected only by an
|
|
_exact_ version constraint (the `=` operator or no operator). Prerelease
|
|
versions do not match inexact operators such as `>=`, `~>`, etc.
|
|
|
|
## Best Practices
|
|
|
|
### Module Versions
|
|
|
|
- When depending on third-party modules, require specific versions to ensure
|
|
that updates only happen when convenient to you.
|
|
|
|
- For modules maintained within your organization, specifying version ranges
|
|
may be appropriate if semantic versioning is used consistently or if there is
|
|
a well-defined release process that avoids unwanted updates.
|
|
|
|
### Terraform Core and Provider Versions
|
|
|
|
- Reusable modules should constrain only their minimum allowed versions of
|
|
Terraform and providers, such as `>= 0.12.0`. This helps avoid known
|
|
incompatibilities, while allowing the user of the module flexibility to
|
|
upgrade to newer versions of Terraform without altering the module.
|
|
|
|
- Root modules should use a `~>` constraint to set both a lower and upper bound
|
|
on versions for each provider they depend on.
|