- `init`: Provider installation will utilise credentials configured in a `.netrc` file for the download and shasum URLs returned by provider registries. ([https://github.com/hashicorp/terraform/pull/35843](35843))
EXPERIMENTS:
Experiments are only enabled in alpha releases of Terraform CLI. The following features are not yet available in stable releases.
After you initialize, Terraform creates a `.terraform/` directory locally. This directory contains the most recent backend configuration, including any authentication parameters you provided to the Terraform CLI. Do not check this directory into Git, as it may contain sensitive credentials for your remote backend.
The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](/terraform/language/state) about your real-world infrastruture. Terraform stores the `terraform.tfstate` file in your remote backend.
The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](/terraform/language/state) about your real-world infrastructure. Terraform stores the `terraform.tfstate` file in your remote backend.
When you change backends, Terraform gives you the option to migrate
your state to the new backend. This lets you adopt backends without losing
providers, and Terraform itself. Learn version constraint syntax and behavior.
---
# Version Constraints
# 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:
This topic provides reference information about the version constraints syntax in Terraform configuration language.
## Introduction
Terraform lets you specify a range of acceptable versions for
components you define in the configuration. Terraform expects a specially-formatted string to constrain the versions of the component. You can specify version constraints when configuring the following components:
- [The `required_version` setting](/terraform/language/terraform#terraform-required_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"
```
## Version constraint syntax
A version constraint is a [string literal](/terraform/language/expressions/strings)
containing one or more conditions, which are separated by commas.
containing one or more conditions 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.
Version numbers are a series of numbers separated by periods, for example `1.2.0`. It is optional, but you can include a suffix to indicate a beta release. Refer to [Specify a pre-release version](#specify-a-pre-release-version) for additional information.
The following operators are valid:
Use the following syntax to specify version constraints:
- `=` (or no operator): Allows only one exact version number. Cannot be combined
with other conditions.
```hcl
version = "<operator> <version>"
```
- `!=`: Excludes an exact version number.
In the following example, Terraform installs a versions `1.2.0` and newer, as well as version older than `2.0.0`:
- `>`, `>=`, `<`, `<=`: Comparisons against a specified version, allowing
versions for which the comparison is true. "Greater-than" requests newer
versions, and "less-than" requests older versions.
```hcl
version = ">= 1.2.0, < 2.0.0"
```
## Operators
- `~>`: Allows only the _rightmost_ version component to increment. This format is referred to as the _pessimistic constraint_ operator. For example,
to allow new patch releases within a specific minor release, use the full
version number:
- `~> 1.0.4`: Allows Terraform to install `1.0.5` and `1.0.10` but not `1.1.0`.
- `~> 1.1`: Allows Terraform to install `1.2` and `1.10` but not `2.0`.
The following table describes the operators you can use to configure version constraints:
## Version Constraint Behavior
| Operator | Description |
| --- | --- |
| `=`, <br/>no operator | Allows only one exact version number. Cannot be combined with other conditions. |
| `!=` | Excludes an exact version number. |
| `>`,<br/> `>=`,<br/> `<`,<br/> `<=` | Compares to a specified version. Terraform allows versions that resolve to `true`. The `>` and `>=` operators request newer versions. The `<` and `<=` operators request older versions. |
| `~>` | Allows only the right-most version component to increment. Examples: <ul><li>`~> 1.0.4`: Allows Terraform to install `1.0.5` and `1.0.10` but not `1.1.0`.</li><li>`1.1`: Allows Terraform to install `1.2` and `1.10` but not `2.0`. </li></ul>|
A version number that meets every applicable constraint is considered acceptable.
## Version constraint behavior
Terraform uses versions that meet all applicable constraints.
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
plugins and modules, Terraform uses 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
When Terraform does not have an acceptable version of a required plugin or module,
it attempts 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.
When Terraform is unable to obtain acceptable versions of external dependencies
or if it does not have an acceptable version of itself, then it does not proceed with any
`terraform plan`, `terraform apply`, or `terraform state` operations.
The root module and any child modules can constrain the Terraform version and any provider versions the modules use. Terraform considers these constraints
equal, and only proceeds if all are met.
### Specify a pre-release version
A pre-release version is a version number that contains a suffix introduced by
a dash, for example `1.2.0-beta`. To configure Terraform to select a pre-release version, set the exact version number using the `=` operator. You can also omit the operator and specify the exact pre-release version. Terraform does not match pre-release versions on `>`, `>=`, `<`, `<=`, or `~>` operators.
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.
## Best practices
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.
We recommend implementing the following best practices when configuration version constraints.
## Best Practices
### Module versions
### Module Versions
- Require specific versions to ensure that updates only happen when convenient to you when your infrastructure depencds on third-party modules.
- When depending on third-party modules, require specific versions to ensure
that updates only happen when convenient to you.
- Specify version ranges when your organization consistently uses semantic versioning for modules it maintains.
- 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.
- Specify version ranges when your organization follows a well-defined release process that avoids unwanted updates.
### Terraform Core and Provider Versions
### 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
@ -94,4 +95,4 @@ versions do not match inexact operators such as `>=`, `~>`, etc.
upgrade to newer versions of Terraform without altering the module.
- Root modules should use a `~>` constraint to set both a lower and upper bound
`trimprefix` removes the specified prefix from the start of the given string. If the string does not start with the prefix, the string is returned unchanged.
`trimprefix` removes the specified prefix from the start of the given string, but only once. If the string does not begin with the prefix, the original string is returned unchanged.
## Examples
@ -21,6 +21,11 @@ world
helloworld
```
```
> trimprefix("--hello", "-")
-hello
```
## Related Functions
* [`trim`](/terraform/language/functions/trim) removes characters at the start and end of a string.
`trimsuffix` removes the specified suffix from the end of the given string.
`trimsuffix` removes the specified suffix from the end of the given string, but only once, even if the suffix appears multiple times. If the suffix does not appear at the very end of the string, the original string is returned unchanged.
## Examples
@ -16,6 +16,16 @@ description: |-
hello
```
```
> trimsuffix("helloworld", "cat")
helloworld
```
```
> trimsuffix("hello--", "-")
hello-
```
## Related Functions
* [`trim`](/terraform/language/functions/trim) removes characters at the start and end of a string.
> **Hands-on:** Try the [Lock and Upgrade Provider Versions](/terraform/tutorials/configuration-language/provider-versioning?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
### Private Providers
If you are using a provider that is not in a Hashicorp-hosted registry, you may
need to attach additional credentials to your requests to external registries.
You do not need these credentials if your provider is in the Terraform public
registry or the HCP Terraform private registry.
By default, Terraform only authenticates the opening request from a provider to
-> **Note**: Test mocking is available in Terraform v1.7.0 and later. This feature is in beta.
-> **Note**: Test mocking is available in Terraform v1.7.0 and later.
Terraform lets you mock providers, resources, and data sources for your tests. This allows you to test parts of your module without creating infrastructure or requiring credentials. In a Terraform test, a mocked provider or resource will generate fake data for all computed attributes that would normally be provided by the underlying provider APIs.
Moved blocks now respect reserved keywords such as `local`, `each`, `self` etc. when parsing resource addresses.
Configurations that reference resources with type names that match top level blocks and
keywords from moved blocks will need to prepend the reference identifier with `resource.`.
## S3 Backend
### S3 Native State Locking
The S3 backend now supports S3 native state locking as an opt-in, experimental feature.
An S3 lock can be used alongside a DynamoDB lock, or independently.
When both locking mechanisms are configured, a lock must be successfully acquired from both locations before subsequent operations will proceed.
To opt-in to S3 native state locking, set `use_lockfile` to `true`.
```terraform
terraform {
backend "s3" {
# additional configuration omitted for brevity
use_lockfile = true
}
}
```
With S3 locking enabled, a lock file will be placed in the same location as the state file.
The lock file will be named identically to the state file, but with a `.tflock` extension.
**S3 bucket policies and IAM policies attached to the calling principal may need to be adjusted to include permissions for the new lock file.**
In a future minor version of Terraform the experimental label will be removed from the `use_lockfile` attribute and attributes related to DynamoDB based locking will be deprecated.
### Root Assume Role Attribute Removal
Several root level attributes related to IAM role assumption which were previously deprecated have been removed.
Each removed field has an analogous field inside the [`assume_role` block](https://developer.hashicorp.com/terraform/language/backend/s3#assume-role-configuration) which should be used instead.
trujillo-adam
1 year ago
committed by
GitHub