Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README and framework #16

Merged
merged 3 commits into from
May 19, 2022
Merged

Update README and framework #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
59fb231
Update Makefile and tests
Nuru May 19, 2022
40c2ef3
Update README to cover new features
Nuru May 19, 2022
a41caa5
Add missing provider to tests
Nuru May 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
43 changes: 33 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down Expand Up @@ -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/)

Expand Down Expand Up @@ -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.


Expand Down Expand Up @@ -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]
Expand Down
43 changes: 34 additions & 9 deletions README.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down Expand Up @@ -123,3 +146,5 @@ include:
contributors:
- name: "Erik Osterman"
github: "osterman"
- name: "Nuru"
github: "Nuru"
4 changes: 4 additions & 0 deletions examples/complete/main.tf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
provider "aws" {
region = var.region
}

module "example" {
source = "../.."

Expand Down
4 changes: 2 additions & 2 deletions test/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, ../$@)
5 changes: 2 additions & 3 deletions test/src/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand 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:
Expand Down
61 changes: 54 additions & 7 deletions test/src/go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
)
Loading