generated from cloudposse/terraform-example-module
/
README.yaml
173 lines (142 loc) · 9.02 KB
/
README.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#
# Name of this project
name: terraform-aws-utils
# Logo for this project
#logo: docs/logo.png
# License of this project
license: "APACHE2"
# Copyrights
copyrights:
- name: "Cloud Posse, LLC"
url: "https://cloudposse.com"
year: "2020"
# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-utils
# Badges to display
badges:
- name: Latest Release
image: https://img.shields.io/github/release/cloudposse/terraform-aws-utils.svg?style=for-the-badge
url: https://github.com/cloudposse/terraform-aws-utils/releases/latest
- name: Last Updated
image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-utils.svg?style=for-the-badge
url: https://github.com/cloudposse/terraform-aws-utils/commits
- name: Slack Community
image: https://slack.cloudposse.com/for-the-badge.svg
url: https://slack.cloudposse.com
# 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"
# List any resources helpful for someone to get started. For example, link to the hashicorp documentation or AWS documentation.
references:
- name: "Terraform Standard Module Structure"
description: "HashiCorp's standard module structure is a file and directory layout we recommend for reusable modules distributed in separate repositories."
url: "https://www.terraform.io/docs/modules/index.html#standard-module-structure"
- name: "Terraform Module Requirements"
description: "HashiCorp's guidance on all the requirements for publishing a module. Meeting the requirements for publishing a module is extremely easy."
url: "https://www.terraform.io/docs/registry/modules/publish.html#requirements"
- name: "Terraform Version Pinning"
description: "The required_version setting can be used to constrain which versions of the Terraform CLI can be used with your configuration"
url: "https://www.terraform.io/docs/configuration/terraform.html#specifying-a-required-terraform-version"
- name: "AWS Regions and Zones"
description: "AWS documentation on regions and zones"
url: "https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html"
# Short description of this project
description: |-
This `terraform-aws-utils` module provides some simple utilities to use when working in AWS.
# Introduction to the project
introduction: |-
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 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. The `short` region
code abbreviations typically match the prefix of the Availability Zone IDs in that region, but this is
not guaranteed. The `short` abbreviations for local regions are generally of the form AWS uses, with
the region prefix and dashes removed.
- 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. If a future new region causes a conflict with an established local zone
abbreviation, we may change the local zone abbreviation to keep the region mappings consistent. For example,
the local zone `us-east-1-mci-1a` would have been abbreviated `mc1a` had we released it earlier, and that would have
conflicted with the new (in 2022) `me-central-1a` which would also be abbreviated `mc1a` in keeping with the general
pattern of using the first letter of each of the first 2 parts. We might have chosen to change the abbreviation
for `us-east-1-mci-1` so we could use `mc1a` for `me-central-1a`. (As it happens, we added them both at the same
time and avoided this collision.) If we were to make such a change, this
would be a breaking change for people using the affected local zone, so we recommend using the `short`
abbreviations if you are using local zones, which are far less likely to have conflicts in the future.
- 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, or we may only provide
`short` and not `fixed` abbreviations for them.
The intention is that existing region 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. However, as
stated above, we may choose to change a local region abbreviation if it conflicts with the obvious abbreviation
for a newly created region. We have picked abbreviations for local zones with avoiding such future
collisions in mind, but we cannot predict the future. (Both `bos` and `den` fit the pattern for region abbreviations,
but we do not envision a future `bo-south-1` or `de-north-1` region.)
### ELB Logging
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.
However, the account IDs have no other purpose, and as AWS expands, it has become more complicated to create
the correct bucket policy. The policy for region `me-central-1` is different than the policy for `us-east-1`.
So now this module has a new feature: you provide the full AWS region code for the region where logging
is 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 used
to configure the Terraform AWS Provider, not an output from some resource or module.
### Region Display Names
There is no AWS API that reliably returns the human-friendly display name (e.g. "Europe (Stockholm)") given
the API-friendly region name. So this module provides `region_display_name_map` to implement this functionality.
### 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
```hcl
locals {
shorten_regions = true
naming_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
}
```
# Example usage
examples: |-
Here is an example of using this module:
- [`examples/complete`](examples/complete) - complete example of using this module
# How to get started quickly
#quickstart: |-
# Here's how to get started...
# Other files to include in this README from the project folder
include:
- "docs/targets.md"
- "docs/terraform.md"
# Contributors to this project
contributors: []