Repository files navigation

Thisterraform-aws-utils module provides some simple utilities to use when working in AWS.

Tip

👽 Use Atmos with Terraform

Cloud Posse usesatmos to easily orchestrate multiple environments using Terraform.
Works withGithub Actions,Atlantis, orSpacelift.

Watch demo of using Atmos with Terraform

Example of runningatmos to manage infrastructure from ourQuick Start tutorial.

Thisterraform-aws-utils module provides some simple utilities to use when working in AWS.More complex utilities are available through Cloud Posse'sutils Terraform providerterraform-provider-utils.

This module's primary function is to provide compact alternative codes for Regions, Availability Zones,and Local Zones, codes which are guaranteed to use only digits and lower case letters: no hyphens.Conversions to and from official codes and alternative codes are handled via lookup maps.

• Theshort abbreviations for regions are variable length (generally 4-6 characters, but length limits not guaranteed)and strictly algorithmically derived so that people can more easily interpret them. Theshort regioncode abbreviations typically match the prefix of the Availability Zone IDs in that region, but this isnot guaranteed. Theshort abbreviations for local regions are generally of the form AWS uses, withthe region prefix and dashes removed.
• Thefixed abbreviations are always exactly 3 characters for regions and 4 charactersfor availability zones and local zones, but have some exceptional cases (China, Africa, Asia-Pacific South, US GovCloud)that have non-obvious abbreviations. If a future new region causes a conflict with an established local zoneabbreviation, we may change the local zone abbreviation to keep the region mappings consistent. For example,the local zoneus-east-1-mci-1a would have been abbreviatedmc1a had we released it earlier, and that would haveconflicted with the new (in 2022)me-central-1a which would also be abbreviatedmc1a in keeping with the generalpattern of using the first letter of each of the first 2 parts. We might have chosen to change the abbreviationforus-east-1-mci-1 so we could usemc1a forme-central-1a. (As it happens, we added them both at the sametime and avoided this collision.) If we were to make such a change, thiswould be a breaking change for people using the affected local zone, so we recommend using theshortabbreviations if you are using local zones, which are far less likely to have conflicts in the future.
• Theidentity "abbreviations" are not abbreviations but are instead the official codes (output equals input,which is why it is called "identity"). This map is provided to simplify algorithmic choice of region codeabbreviation when you want to include a "no abbreviation" option.

We currently support Local Zones but not Wavelength Zones. If we support Wavelength Zones in the future,it is likely that the fixed-length abbreviations for them will be non-intuitive, or we may only provideshort and notfixed abbreviations for them.

The intention is that existing region mappings will never change, and if new regions or zones are created thatconflict with existing ones, they will be given non-standard mappings so as not to conflict. However, asstated above, we may choose to change a local region abbreviation if it conflicts with the obvious abbreviationfor a newly created region. We have picked abbreviations for local zones with avoiding such futurecollisions in mind, but we cannot predict the future. (Bothbos andden fit the pattern for region abbreviations,but we do not envision a futurebo-south-1 orde-north-1 region.)

This module provides Elastic Load Balancing Account IDs per region to be used inconfiguringS3 Bucket Permissionsto allow access logs to be stored in S3.

However, the account IDs have no other purpose, and as AWS expands, it has become more complicated to createthe correct bucket policy. The policy for regionme-central-1 is different than the policy forus-east-1.So now this module has a new feature: you provide the full AWS region code for the region where loggingis to take place (elb_logging_region), and the S3 bucket ARN for where logs are to be stored (elb_logging_bucket_resource_arn),and this module will output the appropriate S3 bucket policy (in JSON) to attach to your S3 bucket.

NOTE: The region must be known at Terraform "plan" time. Use a configuration input, such as what you usedto configure the Terraform AWS Provider, not an output from some resource or module.

There is no AWS API that reliably returns the human-friendly display name (e.g. "Europe (Stockholm)") giventhe API-friendly region name. So this module providesregion_display_name_map to implement this functionality.

For convenience, this module provides lists of enabled and disabled regions in the current account. Note thatsince these lists are dynamic, they cannot be used in Terraformcount orfor_each resource expressions.

Here's how to invoke this example module in your projects

locals {shorten_regions=truenaming_convention=local.shorten_regions?"to_short":"identity"az_map=module.example.region_az_alt_code_maps[local.naming_convention]}module"utils_example_complete" {source="cloudposse/utils/aws"# Cloud Posse recommends pinning every module to a specific version# version     = "x.x.x"}module"label" {source="cloudposse/label/null"# Cloud Posse recommends pinning every module to a specific version# version     = "x.x.x"attributes=[local.az_map["us-east-2"]]context=module.this.context}

Here is an example of using this module:

• examples/complete - complete example of using this module

{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}

[
  "default"
]

Check out these related projects.

• terraform-provider-utils - The Cloud Posse Terraform Provider for various utilities (e.g. deep merging, stack configuration management).
• terraform-null-label - Terraform module designed to generate consistent names and tags for resources. Use terraform-null-label to implement a strict naming convention.

For additional context, refer to some of these links.

• Terraform Standard Module Structure - HashiCorp's standard module structure is a file and directory layout we recommend for reusable modules distributed in separate repositories.
• Terraform Module Requirements - HashiCorp's guidance on all the requirements for publishing a module. Meeting the requirements for publishing a module is extremely easy.
• Terraform Version Pinning - The required_version setting can be used to constrain which versions of the Terraform CLI can be used with your configuration
• AWS Regions and Zones - AWS documentation on regions and zones

This project is under active development, and we encourage contributions from our community.

Many thanks to our outstanding contributors:

For 🐛 bug reports & feature requests, please use theissue tracker.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

1. Review ourCode of Conduct andContributor Guidelines.
2. Fork the repo on GitHub
3. Clone the project to your own machine
4. Commit changes to your own branch
5. Push your work back up to your fork
6. Submit aPull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

We useAtmos to streamline how Terraform tests are run. It centralizes configuration and wraps common test workflows with easy-to-use commands.

All tests are located in thetest/ folder.

Under the hood, tests are powered by Terratest together with our internalTest Helpers library, providing robust infrastructure validation.

Setup dependencies:

• Install Atmos (installation guide)
• Install Go1.24+ or newer
• Install Terraform or OpenTofu

To run tests:

• Run all tests:

  atmostest run

• Clean up test artifacts:

  atmostest clean

• Explore additional test options:

  atmostest --help

The configuration for test commands is centrally managed. To review what's being imported, see theatmos.yaml file.

Learn more about ourautomated testing in our documentation or implementingcustom commands with atmos.

Join ourOpen Source Community on Slack. It'sFREE for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totallysweet infrastructure.

Sign up forour newsletter and join 3,000+ DevOps engineers, CTOs, and founders who get insider access to the latest DevOps trends, so you can always stay in the know.Dropped straight into your Inbox every week — and usually a 5-minute read.

Join us every Wednesday via Zoom for your weekly dose of insider DevOps trends, AWS news and Terraform insights, all sourced from our SweetOps community, plus alive Q&A that you can’t find anywhere else.It'sFREE for everyone!

Licensed to the Apache Software Foundation (ASF) under oneor more contributor license agreements.  See the NOTICE filedistributed with this work for additional informationregarding copyright ownership.  The ASF licenses this fileto you under the Apache License, Version 2.0 (the"License"); you may not use this file except in compliancewith the License.  You may obtain a copy of the License at  https://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing,software distributed under the License is distributed on an"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANYKIND, either express or implied.  See the License for thespecific language governing permissions and limitationsunder the License.

All other trademarks referenced herein are the property of their respective owners.

Copyright © 2020-2025Cloud Posse, LLC