Module: utils
Terraform provider for various utilities (deep merging, Atmos stack configuration management), and to add additional missing functionality to Terraform
Usage
Here is how to use this provider in your own Terraform code:
terraform {
required_providers {
utils = {
source = "cloudposse/utils"
version = ">= 1.17.0"
}
}
}
See the Docs for additional information.
Important: Pin both the
cloudposse/utilsprovider and the Atmos CLI to compatible versions. See docs/versions.md for the full compatibility matrix.
Examples
Here is an example of using this provider:
terraform {
required_providers {
utils = {
source = "cloudposse/utils"
}
}
}
locals {
yaml_data_1 = file("${path.module}/data1.yaml")
yaml_data_2 = file("${path.module}/data2.yaml")
}
data "utils_deep_merge_yaml" "example" {
input = [
local.yaml_data_1,
local.yaml_data_2
]
}
output "deep_merge_output" {
value = data.utils_deep_merge_yaml.example.output
}
Here are some additional examples:
Variables
Required Variables
Context Variables
The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.
context.tf file of this module and part of the terraform-null-label pattern.Dependencies
Version Compatibility: Atmos ↔ cloudposse/utils Provider
The cloudposse/utils Terraform provider embeds the Atmos Go library to perform
deep-merge operations on YAML and JSON.
Because deep-merge semantics can change between Atmos releases, the Atmos library version compiled into the
provider must match the Atmos CLI version you are running. A mismatch can cause the provider and Atmos to
produce different merge results for the same inputs, breaking deterministic infrastructure configuration.
Use the table below to pin both tools to compatible versions.
Note: The
2.xline is the actively developed release line. The1.xline receives parallel backport releases for users who cannot yet migrate. Where multiple provider releases share an Atmos version, only the latest release in each line is shown.
Version Compatibility: terraform-yaml-stack-config ↔ cloudposse/utils Provider
The cloudposse/terraform-yaml-stack-config module
uses the cloudposse/utils provider internally. Its modules/remote-state child module declares explicit provider
version constraints — if you source that child module in a root module, both the child's constraint and any
constraint declared by the root module must be satisfiable simultaneously.
Use the table below to pick a terraform-yaml-stack-config release that is compatible with your chosen
cloudposse/utils provider version.
terraform-yaml-stack-config | Required cloudposse/utils (root module) | Required cloudposse/utils (modules/remote-state) |
|---|---|---|
| v2.0.0 | >= 2.0.0, < 3.0.0 | >= 2.0.0, < 3.0.0 |
| v1.5.0–v1.8.0 | >= 1.7.1 | >= 1.7.1, < 2.0.0 |
| v1.1.1–v1.4.3 | >= 1.5.0 | = 1.5.0 |
| v1.0.0 | >= 1.2.0 | >= 1.2.0 |
Developing the Provider
If you wish to work on the provider, you'll first need Go installed on your machine (see Requirements above).
Install atmos
To compile the provider, run go install. This will build the provider and put the provider binary in the $GOPATH/bin directory.
To generate or update documentation, run go generate.
In order to run the full suite of Acceptance tests, run atmos testacc.
Note: Acceptance tests create real resources, and often cost money to run.
$ atmos testacc
Testing Locally
You can test the provider locally by using the provider_installation functionality.
For testing this provider, you can edit your ~/.terraformrc file with the following:
provider_installation {
dev_overrides {
"cloudposse/utils" = "/path/to/your/code/github.com/cloudposse/terraform-provider-utils/"
}
# For all other providers, install them directly from their origin provider
# registries as normal. If you omit this, Terraform will _only_ use
# the dev_overrides block, and so no other providers will be available.
direct {}
}
With that in place, you can build the provider (see above) and add a provider block:
required_providers {
utils = {
source = "cloudposse/utils"
}
}
Then run terraform init, terraform plan and terraform apply as normal.
$ terraform init
Initializing the backend...
Initializing provider plugins...
- Finding latest version of cloudposse/utils...
Warning: Provider development overrides are in effect
The following provider development overrides are set in the CLI configuration:
- cloudposse/utils in /path/to/your/code/github.com/cloudposse/terraform-provider-utils
The behavior may therefore not match any released version of the provider and
applying changes may cause the state to become incompatible with published
releases.
terraform apply
Warning: Provider development overrides are in effect
The following provider development overrides are set in the CLI configuration:
- cloudposse/utils in /Users/matt/code/src/github.com/cloudposse/terraform-provider-utils
The behavior may therefore not match any released version of the provider and
applying changes may cause the state to become incompatible with published
releases.
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
Terraform will perform the following actions:
Plan: 0 to add, 0 to change, 0 to destroy.
Changes to Outputs:
+ deep_merge_output = <<-EOT
Statement:
- Action:
- s3:*
Effect: Allow
Resource:
- '*'
Sid: FullAccess
- Action:
- s3:*
Complex:
ExtraComplex:
ExtraExtraComplex:
Foo: bazzz
SomeArray:
- one
- two
- three
Effect: Deny
Resource:
- arn:aws:s3:::customer
- arn:aws:s3:::customer/*
- foo
Sid: DenyCustomerBucket
Version: "2012-10-17"
EOT