-
-
Notifications
You must be signed in to change notification settings - Fork 166
/
README.yaml
176 lines (150 loc) · 8.86 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
174
175
176
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#
# Name of this project
name: terraform-aws-dynamic-subnets
# Tags of this project
tags:
- aws
- terraform
- terraform-modules
- networking
- subnet
- vpc
- vpc-resources
# Categories of this project
categories:
- terraform-modules/networking
# Logo for this project
#logo: docs/logo.png
# License of this project
license: "APACHE2"
# Canonical GitHub repo
github_repo: cloudposse/terraform-aws-dynamic-subnets
# Badges to display
badges:
- name: Latest Release
image: https://img.shields.io/github/release/cloudposse/terraform-aws-dynamic-subnets.svg?style=for-the-badge
url: https://github.com/cloudposse/terraform-aws-dynamic-subnets/releases/latest
- name: Last Updated
image: https://img.shields.io/github/last-commit/cloudposse/terraform-aws-dynamic-subnets.svg?style=for-the-badge
url: https://github.com/cloudposse/terraform-aws-dynamic-subnets/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-aws-vpc"
description: "Terraform Module that defines a VPC with public/private subnets across multiple AZs with Internet Gateways"
url: "https://github.com/cloudposse/terraform-aws-vpc"
- name: "terraform-aws-vpc-peering"
description: "Terraform module to create a peering connection between two VPCs"
url: "https://github.com/cloudposse/terraform-aws-vpc-peering"
- name: "terraform-aws-kops-vpc-peering"
description: "Terraform module to create a peering connection between a backing services VPC and a VPC created by Kops"
url: "https://github.com/cloudposse/terraform-aws-kops-vpc-peering"
- name: "terraform-aws-named-subnets"
description: "Terraform module for named subnets provisioning."
url: "https://github.com/cloudposse/terraform-aws-named-subnets"
# Short description of this project
description: |-
Terraform module to provision public and private [`subnets`](https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Subnets.html) in an existing [`VPC`](https://aws.amazon.com/vpc)
__Note:__ This module is intended for use with an existing VPC and existing Internet Gateway.
To create a new VPC, use [terraform-aws-vpc](https://github.com/cloudposse/terraform-aws-vpc) module.
__Note:__ Due to Terraform [limitations](https://github.com/hashicorp/terraform/issues/26755#issuecomment-719103775),
many optional inputs to this module are specified as a `list(string)` that can have zero or one element, rather than
as a `string` that could be empty or `null`. The designation of an input as a `list` type does not necessarily
mean that you can supply more than one value in the list, so check the input's description before supplying more than one value.
The core function of this module is to create 2 sets of subnets, a "public" set with bidirectional access to the
public internet, and a "private" set behind a firewall with egress-only access to the public internet. This
includes dividing up a given CIDR range so that a each subnet gets its own
distinct CIDR range within that range, and then creating those subnets in the appropriate availability zones.
The intention is to keep this module relatively simple and easy to use for the most popular use cases.
In its default configuration, this module creates 1 public subnet and 1 private subnet in each
of the specified availability zones. The public subnets are configured for bi-directional traffic to the
public internet, while the private subnets are configured for egress-only traffic to the public internet.
Rather than provide a wealth of configuration options allowing for numerous special cases, this module
provides some common options and further provides the ability to suppress the creation of resources, allowing
you to create and configure them as you like from outside this module. For example, rather than give you the
option to customize the Network ACL, the module gives you the option to create a completely open one (and control
access via Security Groups and other means) or not create one at all, allowing you to create and configure one yourself.
### Public subnets
This module defines a public subnet as one that has direct access to an internet gateway and can accept incoming connection requests.
In the simplest configuration, the module creates a single route table with a default route targeted to the
VPC's internet gateway, and associates all the public subnets with that single route table.
Likewise it creates a single Network ACL with associated rules allowing all ingress and all egress,
and associates that ACL with all the public subnets.
### Private subnets
A private subnet may be able to initiate traffic to the public internet through a NAT gateway,
a NAT instance, or an egress-only internet gateway, or it might only have direct access to other
private subnets. In the simple configuration, for IPv4 and/or IPv6 with NAT64 enabled via `public_dns64_enabled`
or `private_dns64_enabled`, the module creates 1 NAT Gateway or NAT Instance for each
private subnet (in the public subnet in the same availability zone), creates 1 route table for each private subnet,
and adds to that route table a default route from the subnet to its NAT Gateway or Instance. For IPv6,
the module adds a route to the Egress-Only Internet Gateway configured via input.
As with the Public subnets, the module creates a single Network ACL with associated rules allowing all ingress and
all egress, and associates that ACL with all the private subnets.
### Customization for special use cases
Various features are controlled by `bool` inputs with names ending in `_enabled`. By changing the default
values, you can enable or disable creation of public subnets, private subnets, route tables,
NAT gateways, NAT instances, or Network ACLs. So for example, you could use this module to create only
private subnets and the open Network ACL, and then add your own route table associations to the subnets
and route all non-local traffic to a Transit Gateway or VPN.
### CIDR allocation
For IPv4, you provide a CIDR and the module divides the address space into the largest CIDRs possible that are still
small enough to accommodate `max_subnet_count` subnets of each enabled type (public or private). When `max_subnet_count`
is left at the default `0`, it is set to the total number of availability zones in the region. Private subnets
are allocated out of the first half of the reserved range, and public subnets are allocated out of the second half.
For IPv6, you provide a `/56` CIDR and the module assigns `/64` subnets of that CIDR in consecutive order starting
at zero. (You have the option of specifying a list of CIDRs instead.) As with IPv4, enough CIDRs are allocated to
cover `max_subnet_count` private and public subnets (when both are enabled, which is the default), with the private
subnets being allocated out of the lower half of the reservation and the public subnets allocated out of the upper half.
# How to use this project
usage: |-
```hcl
module "subnets" {
source = "cloudposse/dynamic-subnets/aws"
# Cloud Posse recommends pinning every module to a specific version
# version = "x.x.x"
namespace = "eg"
stage = "prod"
name = "app"
vpc_id = "vpc-XXXXXXXX"
igw_id = ["igw-XXXXXXXX"]
ipv4_cidr_block = ["10.0.0.0/16"]
availability_zones = ["us-east-1a", "us-east-1b"]
}
```
Create only private subnets, route to transit gateway:
```hcl
module "private_tgw_subnets" {
source = "cloudposse/dynamic-subnets/aws"
# Cloud Posse recommends pinning every module to a specific version
# version = "x.x.x"
namespace = "eg"
stage = "prod"
name = "app"
vpc_id = "vpc-XXXXXXXX"
igw_id = ["igw-XXXXXXXX"]
ipv4_cidr_block = ["10.0.0.0/16"]
availability_zones = ["us-east-1a", "us-east-1b"]
nat_gateway_enabled = false
public_subnets_enabled = false
}
resource "aws_route" "private" {
count = length(module.private_tgw_subnets.private_route_table_ids)
route_table_id = module.private_tgw_subnets.private_route_table_ids[count.index]
destination_cidr_block = "0.0.0.0/0"
transit_gateway_id = "tgw-XXXXXXXXX"
}
```
See [examples](examples) for working examples. In particular, see [examples/nacls](examples/nacls)
for an example of how to create custom Network Access Control Lists (NACLs) outside of
but in conjunction with this module.
include:
- "docs/design.md"
- "docs/targets.md"
- "docs/terraform.md"
# Contributors to this project
contributors: []