Update README and framework (#16)

Author: dylanbannon

Makefile

@@ -3,7 +3,7 @@ SHELL := /bin/bash
 # List of targets the `readme` target should call before generating the readme
 export README_DEPS ?= docs/targets.md docs/terraform.md
 
--include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
+-include $(shell curl -sSL -o .build-harness "https://cloudposse.tools/build-harness"; echo .build-harness)
 
 ## Lint terraform code
 lint:

README.md

@@ -28,7 +28,7 @@
 
 -->
 
-This `terraform-aws-utils` project provides some simple utilities to use when working in AWS.
+This `terraform-aws-utils` module provides some simple utilities to use when working in AWS.
 
 ---
 
@@ -61,23 +61,43 @@ We literally have [*hundreds of terraform modules*][terraform_modules] that are
 
 ## Introduction
 
-This `terraform-aws-utils` project provides some simple utilities to use when working in AWS. At the moment, it is
-limited to providing compact alternative codes for Regions, Availability Zones, and Local Zones that 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.
+This `terraform-aws-utils` module provides some simple utilities to use when working in AWS.
+More complex utilities are available through Cloud Posse's `utils` Terraform provider
+[terraform-provider-utils](https://github.com/cloudposse/terraform-provider-utils).
 
-The `short` abbreviations are variable length (generally 4-6 characters, but length limits not guaranteed)
-and strictly algorithmically derived so that people can more easily interpret them.
-The `fixed` abbreviations are always exactly 3 characters for regions and 4 characters
+### Compact Alternative Codes (Abbreviations)
+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.
+
+- The `short` abbreviations are variable length (generally 4-6 characters, but length limits not guaranteed)
+and strictly algorithmically derived so that people can more easily interpret them. The `short` region
+code abbreviations typically match the prefix of the Availability Zone IDs in that region, but this is
+not guaranteed.
+- The `fixed` abbreviations are always exactly 3 characters for regions and 4 characters
 for availability zones and local zones, but have some exceptional cases (China, Africa, Asia-Pacific South, US GovCloud)
 that have non-obvious abbreviations.
+- The `identity` "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 code
+abbreviation 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.
 
 The intention is that existing mappings will never change, and if new regions or zones are created that
 conflict with existing ones, they will be given non-standard mappings so as not to conflict.
 
+### ELB Logging Account IDs
+
+This module provides Elastic Load Balancing Account IDs per region to be used in
+configuring [S3 Bucket Permissions](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-logging-bucket-permissions)
+to allow access logs to be stored in S3.
+
+### Enabled and Disabled Regions
+
+For convenience, this module provides lists of enabled and disabled regions in the current account. Note that
+since these lists are dynamic, they cannot be used in Terraform `count` or `for_each` resource expressions.
+
 
 ## Security & Compliance [<img src="https://cloudposse.com/wp-content/uploads/2020/11/bridgecrew.svg" width="250" align="right" />](https://bridgecrew.io/)
 
@@ -236,6 +256,7 @@ Are you using this project or any of our other projects? Consider [leaving a tes
 
 Check out these related projects.
 
+- [terraform-provider-utils](https://github.com/cloudposse/terraform-provider-utils) - The Cloud Posse Terraform Provider for various utilities (e.g. deep merging, stack configuration management).
 - [terraform-null-label](https://github.com/cloudposse/terraform-null-label) - Terraform module designed to generate consistent names and tags for resources. Use terraform-null-label to implement a strict naming convention.
 
 
@@ -381,12 +402,14 @@ Check out [our other projects][github], [follow us on twitter][twitter], [apply
 ### Contributors
 
 <!-- markdownlint-disable -->
-|  [![Erik Osterman][osterman_avatar]][osterman_homepage]<br/>[Erik Osterman][osterman_homepage] |
-|---|
+|  [![Erik Osterman][osterman_avatar]][osterman_homepage]<br/>[Erik Osterman][osterman_homepage] | [![Nuru][Nuru_avatar]][Nuru_homepage]<br/>[Nuru][Nuru_homepage] |
+|---|---|
 <!-- markdownlint-restore -->
 
   [osterman_homepage]: https://github.com/osterman
   [osterman_avatar]: https://img.cloudposse.com/150x150/https://github.com/osterman.png
+  [Nuru_homepage]: https://github.com/Nuru
+  [Nuru_avatar]: https://img.cloudposse.com/150x150/https://github.com/Nuru.png
 
 [![README Footer][readme_footer_img]][readme_footer_link]
 [![Beacon][beacon]][website]

README.yaml

@@ -36,6 +36,9 @@ badges:
 
 # List any related terraform modules that this module may be used with or that this module depends on.
 related:
+  - name: "terraform-provider-utils"
+    description: "The Cloud Posse Terraform Provider for various utilities (e.g. deep merging, stack configuration management)."
+    url: "https://github.com/cloudposse/terraform-provider-utils"
   - name: "terraform-null-label"
     description: "Terraform module designed to generate consistent names and tags for resources. Use terraform-null-label to implement a strict naming convention."
     url: "https://github.com/cloudposse/terraform-null-label"
@@ -56,27 +59,47 @@ references:
     url: "https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html"
 # Short description of this project
 description: |-
-  This `terraform-aws-utils` project provides some simple utilities to use when working in AWS.
+  This `terraform-aws-utils` module provides some simple utilities to use when working in AWS.
 
 # Introduction to the project
 introduction: |-
-  This `terraform-aws-utils` project provides some simple utilities to use when working in AWS. At the moment, it is
-  limited to providing compact alternative codes for Regions, Availability Zones, and Local Zones that 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.
-
-  The `short` abbreviations are variable length (generally 4-6 characters, but length limits not guaranteed)
-  and strictly algorithmically derived so that people can more easily interpret them.
-  The `fixed` abbreviations are always exactly 3 characters for regions and 4 characters
+  This `terraform-aws-utils` module provides some simple utilities to use when working in AWS.
+  More complex utilities are available through Cloud Posse's `utils` Terraform provider
+  [terraform-provider-utils](https://github.com/cloudposse/terraform-provider-utils).
+
+  ### Compact Alternative Codes (Abbreviations)
+  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.
+
+  - The `short` abbreviations are variable length (generally 4-6 characters, but length limits not guaranteed)
+  and strictly algorithmically derived so that people can more easily interpret them. The `short` region
+  code abbreviations typically match the prefix of the Availability Zone IDs in that region, but this is
+  not guaranteed.
+  - The `fixed` abbreviations are always exactly 3 characters for regions and 4 characters
   for availability zones and local zones, but have some exceptional cases (China, Africa, Asia-Pacific South, US GovCloud)
   that have non-obvious abbreviations.
+  - The `identity` "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 code
+  abbreviation 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.
 
   The intention is that existing mappings will never change, and if new regions or zones are created that
   conflict with existing ones, they will be given non-standard mappings so as not to conflict.
 
+  ### ELB Logging Account IDs
+
+  This module provides Elastic Load Balancing Account IDs per region to be used in
+  configuring [S3 Bucket Permissions](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-logging-bucket-permissions)
+  to allow access logs to be stored in S3.
+
+  ### Enabled and Disabled Regions
+
+  For convenience, this module provides lists of enabled and disabled regions in the current account. Note that
+  since these lists are dynamic, they cannot be used in Terraform `count` or `for_each` resource expressions.
+
 # How to use this module. Should be an easy example to copy and paste.
 usage: |-
   Here's how to invoke this example module in your projects
@@ -123,3 +146,5 @@ include:
 contributors:
   - name: "Erik Osterman"
     github: "osterman"
+  - name: "Nuru"
+    github: "Nuru"

examples/complete/main.tf

@@ -1,3 +1,7 @@
+provider "aws" {
+  region = var.region
+}
+
 module "example" {
   source = "../.."
 

test/Makefile

@@ -33,11 +33,11 @@ clean:
 all: module examples/complete
 
 ## Run basic sanity checks against the module itself
-module: export TESTS ?= installed lint get-modules module-pinning get-plugins provider-pinning validate terraform-docs input-descriptions output-descriptions
+module: export TESTS ?= installed lint module-pinning provider-pinning validate terraform-docs input-descriptions output-descriptions
 module: deps
 	$(call RUN_TESTS, ../)
 
 ## Run tests against example
-examples/complete: export TESTS ?= installed lint get-modules get-plugins validate
+examples/complete: export TESTS ?= installed lint validate
 examples/complete: deps
 	$(call RUN_TESTS, ../$@)

test/src/Makefile

@@ -1,5 +1,4 @@
-export TF_CLI_ARGS_init ?= -get-plugins=true
-export TERRAFORM_VERSION ?= $(shell curl -s https://checkpoint-api.hashicorp.com/v1/check/terraform | jq -r -M '.current_version' | cut -d. -f1-2)
+export TERRAFORM_VERSION ?= $(shell curl -s https://checkpoint-api.hashicorp.com/v1/check/terraform | jq -r -M '.current_version' | cut -d. -f1)
 
 .DEFAULT_GOAL : all
 .PHONY: all
@@ -16,7 +15,7 @@ init:
 ## Run tests
 test: init
 	go mod download
-	go test -v -timeout 60m -run TestExamplesComplete
+	go test -v -timeout 5m
 
 ## Run tests in docker container
 docker/test:

test/src/go.mod

@@ -1,12 +1,59 @@
 module github.com/cloudposse/terraform-aws-utils
 
-go 1.14
+go 1.17
 
 require (
-	github.com/gruntwork-io/terratest v0.31.1
-	github.com/stretchr/testify v1.6.1
-	golang.org/x/crypto v0.0.0-20200820211705-5c72a883971a // indirect
-	golang.org/x/net v0.0.0-20200822124328-c89045814202 // indirect
-	golang.org/x/sys v0.0.0-20200828194041-157a740278f4 // indirect
-	gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776 // indirect
+	github.com/gruntwork-io/terratest v0.39.0
+	github.com/stretchr/testify v1.7.0
+)
+
+require (
+	cloud.google.com/go v0.83.0 // indirect
+	cloud.google.com/go/storage v1.10.0 // indirect
+	github.com/agext/levenshtein v1.2.3 // indirect
+	github.com/apparentlymart/go-textseg/v13 v13.0.0 // indirect
+	github.com/aws/aws-sdk-go v1.40.56 // indirect
+	github.com/bgentry/go-netrc v0.0.0-20140422174119-9fd32a8b3d3d // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/golang/groupcache v0.0.0-20200121045136-8c9f03a8e57e // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/golang/snappy v0.0.3 // indirect
+	github.com/googleapis/gax-go/v2 v2.0.5 // indirect
+	github.com/hashicorp/errwrap v1.0.0 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-getter v1.5.11 // indirect
+	github.com/hashicorp/go-multierror v1.1.0 // indirect
+	github.com/hashicorp/go-safetemp v1.0.0 // indirect
+	github.com/hashicorp/go-version v1.3.0 // indirect
+	github.com/hashicorp/hcl/v2 v2.9.1 // indirect
+	github.com/hashicorp/terraform-json v0.13.0 // indirect
+	github.com/jinzhu/copier v0.0.0-20190924061706-b57f9002281a // indirect
+	github.com/jmespath/go-jmespath v0.4.0 // indirect
+	github.com/jstemmer/go-junit-report v0.9.1 // indirect
+	github.com/klauspost/compress v1.13.0 // indirect
+	github.com/mattn/go-zglob v0.0.2-0.20190814121620-e3c945676326 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
+	github.com/mitchellh/go-testing-interface v1.0.0 // indirect
+	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/tmccombs/hcl2json v0.3.3 // indirect
+	github.com/ulikunitz/xz v0.5.8 // indirect
+	github.com/zclconf/go-cty v1.9.1 // indirect
+	go.opencensus.io v0.23.0 // indirect
+	golang.org/x/crypto v0.0.0-20210513164829-c07d793c2f9a // indirect
+	golang.org/x/lint v0.0.0-20210508222113-6edffad5e616 // indirect
+	golang.org/x/mod v0.4.2 // indirect
+	golang.org/x/net v0.0.0-20210614182718-04defd469f4e // indirect
+	golang.org/x/oauth2 v0.0.0-20210514164344-f6687ab2804c // indirect
+	golang.org/x/sys v0.0.0-20210603125802-9665404d3644 // indirect
+	golang.org/x/text v0.3.6 // indirect
+	golang.org/x/tools v0.1.2 // indirect
+	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
+	google.golang.org/api v0.47.0 // indirect
+	google.golang.org/appengine v1.6.7 // indirect
+	google.golang.org/genproto v0.0.0-20210602131652-f16073e35f0c // indirect
+	google.golang.org/grpc v1.38.0 // indirect
+	google.golang.org/protobuf v1.26.0 // indirect
+	gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 // indirect
+	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b // indirect
 )