Skip to content

Commit 8f94997

Browse files
bryantbiggsbryantbiggs
committed
feat: Add upgrade guide documentation
1 parent f8441a2 commit 8f94997

File tree

4 files changed

+366
-26
lines changed

4 files changed

+366
-26
lines changed

‎README.md

Lines changed: 5 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Terraform module which creates AWS Transit Gateway resources.
44

5+
[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
6+
57
## Usage
68

79
```hcl
@@ -54,36 +56,14 @@ module "transit_gateway" {
5456
vpc1 = {
5557
vpc_id = "vpc-1234556abcdef"
5658
security_group_referencing_support = true
57-
subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
59+
subnet_ids = ["sub-abcde012", "sub-bcde012a", "sub-fghi345a"]
5860
ipv6_support = true
5961
}
6062
6163
vpc2 = {
6264
vpc_id = "vpc-98765432d1aad"
6365
security_group_referencing_support = true
64-
subnet_ids = ["subnet-334de012", "subnet-6vfe012a", "subnet-agfi435a"]
65-
}
66-
}
67-
68-
vpc_attachments = {
69-
vpc = {
70-
attachment_type = "vpc"
71-
create_vpc_attachment = true
72-
vpc_id =
73-
subnet_ids =
74-
75-
dns_support = true
76-
ipv6_support = true
77-
78-
tgw_routes = {
79-
vpc = {
80-
destination_cidr_block = "30.0.0.0/16"
81-
},
82-
blackhole = {
83-
blackhole = true
84-
destination_cidr_block = "40.0.0.0/20"
85-
}
86-
}
66+
subnet_ids = ["sub-334de012", "sub-6vfe012a", "sub-agfi435a"]
8767
}
8868
}
8969
@@ -178,7 +158,7 @@ No modules.
178158
| Name | Description | Type | Default | Required |
179159
|------|-------------|------|---------|:--------:|
180160
| <a name="input_amazon_side_asn"></a> [amazon\_side\_asn](#input\_amazon\_side\_asn) | The Autonomous System Number (ASN) for the Amazon side of the gateway. By default the TGW is created with the current default Amazon ASN | `string` | `null` | no |
181-
| <a name="input_auto_accept_shared_attachments"></a> [auto\_accept\_shared\_attachments](#input\_auto\_accept\_shared\_attachments) | Whether resource attachment requests are automatically accepted | `bool` | `false` | no |
161+
| <a name="input_auto_accept_shared_attachments"></a> [auto\_accept\_shared\_attachments](#input\_auto\_accept\_shared\_attachments) | Whether resource attachment requests are automatically accepted | `bool` | `true` | no |
182162
| <a name="input_create"></a> [create](#input\_create) | Controls if resources should be created (it affects almost all resources) | `bool` | `true` | no |
183163
| <a name="input_create_flow_log"></a> [create\_flow\_log](#input\_create\_flow\_log) | Whether to create flow log resource(s) | `bool` | `true` | no |
184164
| <a name="input_default_route_table_association"></a> [default\_route\_table\_association](#input\_default\_route\_table\_association) | Whether resource attachments are automatically associated with the default association route table | `bool` | `false` | no |

‎UPGRADE-3.0.md

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Upgrade from v2.x to v3.x
2+
3+
Please consult the `examples` directory for reference example configurations. If you find a bug, please open an issue with supporting configuration to reproduce.
4+
5+
## List of backwards incompatible changes
6+
7+
- Minimum supported version of Terraform AWS provider updated to v5.78 to support the latest resources utilized
8+
- Minimum supported version of Terraform updated to v1.3
9+
- Route table and routes have been removed from the root module and into a sub-module. This allows for more flexibility in managing routes and route tables (prior implementation was limited to a single route table and routes). Routes are defined via `maps` instead of `lists`, allowing for individual routes to be added/removed anywhere within the configuration without affecting other routes.
10+
- `aws_ram_resource_share_accepter` resource has been removed and should be managed outside of the module as needed.
11+
12+
## Additional changes
13+
14+
### Added
15+
16+
- Added support for security group referencing
17+
- Added support for flow logs on the Transit Gateway itself, as well as any attachments (as specified)
18+
- Added support for Transit Gateway peering attachments
19+
20+
### Modified
21+
22+
- `vpc_attachments` type definition changed from `any` to full object definition
23+
- RAM sharing of gateway is now set to `false` by default; users must opt into sharing by setting `enable_ram_share = true`
24+
- `transit_gateway_default_route_table_association` is now set to `false` by default
25+
- `transit_gateway_default_route_table_propagation` is now set to `false` by default
26+
27+
### Removed
28+
29+
- `aws_ram_resource_share_accepter` resource has been removed and should be managed outside of the module as needed.
30+
31+
### Variable and output changes
32+
33+
1. Removed variables:
34+
35+
- `tgw_vpc_attachment_tags`
36+
- `create_tgw_routes`
37+
- `transit_gateway_route_table_id`
38+
- `tgw_route_table_tags`
39+
- `ram_resource_share_arn`
40+
41+
2. Renamed variables:
42+
43+
- `create_tgw` -> `create`
44+
- `enable_default_route_table_association` -> `default_route_table_association`
45+
- `enable_default_route_table_propagation` -> `default_route_table_propagation`
46+
- `enable_auto_accept_shared_attachments` -> `auto_accept_shared_attachments`
47+
- `enable_vpn_ecmp_support` -> `vpn_ecmp_support`
48+
- `enable_multicast_support` -> `multicast_support`
49+
- `enable_dns_support` -> `dns_support`
50+
- `share_tgw` -> `enable_ram_share`
51+
52+
3. Added variables:
53+
54+
- `security_group_referencing_support`
55+
- `peering_attachments`
56+
- `create_flow_log`
57+
- `flow_logs`
58+
59+
4. Removed outputs:
60+
61+
- `ec2_transit_gateway_vpc_attachment_ids`
62+
- `ec2_transit_gateway_vpc_attachment`
63+
- `ec2_transit_gateway_route_table_id`
64+
- `ec2_transit_gateway_route_table_default_association_route_table`
65+
- `ec2_transit_gateway_route_table_default_propagation_route_table`
66+
- `ec2_transit_gateway_route_ids`
67+
- `ec2_transit_gateway_route_table_association_ids`
68+
- `ec2_transit_gateway_route_table_association`
69+
- `ec2_transit_gateway_route_table_propagation_ids`
70+
- `ec2_transit_gateway_route_table_propagation`
71+
- `ram_principal_association_id`
72+
73+
5. Renamed outputs:
74+
75+
- `ec2_transit_gateway_arn` -> `arn`
76+
- `ec2_transit_gateway_id` -> `id`
77+
- `ec2_transit_gateway_owner_id` -> `owner_id`
78+
- `ec2_transit_gateway_association_default_route_table_id` -> `association_default_route_table`
79+
- `ec2_transit_gateway_propagation_default_route_table_id` -> `propagation_default_route_table`
80+
81+
6. Added outputs:
82+
83+
- `vpc_attachments`
84+
- `peering_attachments`
85+
86+
## Upgrade Migrations
87+
88+
### Before v2.x Example
89+
90+
```hcl
91+
module "transit_gateway" {
92+
source = "terraform-aws-modules/transit-gateway/aws"
93+
version = "~> 2.12"
94+
95+
name = "example"
96+
description = "Example Transit Gateway connecting multiple VPCs"
97+
amazon_side_asn = 64532
98+
transit_gateway_cidr_blocks = ["10.99.0.0/24"]
99+
100+
enable_auto_accept_shared_attachments = true
101+
enable_multicast_support = true
102+
103+
vpc_attachments = {
104+
vpc1 = {
105+
vpc_id = "vpc-1234556abcdef"
106+
subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
107+
ipv6_support = true
108+
109+
transit_gateway_default_route_table_association = false
110+
transit_gateway_default_route_table_propagation = false
111+
112+
tgw_routes = [
113+
{
114+
destination_cidr_block = "30.0.0.0/16"
115+
},
116+
{
117+
blackhole = true
118+
destination_cidr_block = "0.0.0.0/0"
119+
}
120+
]
121+
}
122+
123+
vpc2 = {
124+
vpc_id = module.vpc2.vpc_id
125+
subnet_ids = module.vpc2.private_subnets
126+
127+
tgw_routes = [
128+
{
129+
destination_cidr_block = "50.0.0.0/16"
130+
},
131+
{
132+
blackhole = true
133+
destination_cidr_block = "10.10.10.10/32"
134+
}
135+
]
136+
}
137+
}
138+
139+
tags = {
140+
Environment = "Development"
141+
Project = "Example"
142+
}
143+
}
144+
```
145+
146+
### After v3.x Example
147+
148+
```hcl
149+
module "transit_gateway" {
150+
source = "terraform-aws-modules/transit-gateway/aws"
151+
version = "3.0.0"
152+
153+
name = "example"
154+
description = "Example Transit Gateway connecting multiple VPCs"
155+
amazon_side_asn = 64532
156+
transit_gateway_cidr_blocks = ["10.99.0.0/24"]
157+
158+
auto_accept_shared_attachments = true
159+
multicast_support = true
160+
161+
# Maintain backwards compatibility
162+
security_group_referencing_support = false
163+
default_route_table_association = true
164+
default_route_table_propagation = true
165+
166+
vpc_attachments = {
167+
vpc1 = {
168+
vpc_id = "vpc-1234556abcdef"
169+
subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"]
170+
ipv6_support = true
171+
172+
# Maintain backwards compatibility
173+
security_group_referencing_support = true
174+
}
175+
176+
vpc2 = {
177+
vpc_id = "vpc-98765432d1aad"
178+
subnet_ids = ["subnet-334de012", "subnet-6vfe012a", "subnet-agfi435a"]
179+
180+
# Maintain backwards compatibility
181+
security_group_referencing_support = true
182+
transit_gateway_default_route_table_association = true
183+
transit_gateway_default_route_table_propagation = true
184+
}
185+
}
186+
187+
tags = {
188+
Environment = "Development"
189+
Project = "Example"
190+
}
191+
}
192+
193+
module "transit_gateway_route_table" {
194+
source = "terraform-aws-modules/transit-gateway/aws//modules/route-table"
195+
196+
name = "example"
197+
transit_gateway_id = module.transit_gateway.id
198+
199+
associations = {
200+
vpc1 = {
201+
transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc1"].id
202+
propagate_route_table = true
203+
}
204+
}
205+
206+
routes = {
207+
blackhole = {
208+
blackhole = true
209+
destination_cidr_block = "0.0.0.0/0"
210+
}
211+
blackhole2 = {
212+
blackhole = true
213+
destination_cidr_block = "10.10.10.10/32"
214+
}
215+
vpc1-thing = {
216+
destination_cidr_block = "30.0.0.0/16"
217+
transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc1"].id
218+
}
219+
vpc2-thing = {
220+
destination_cidr_block = "50.0.0.0/16"
221+
transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc2"].id
222+
}
223+
}
224+
225+
tags = {
226+
Environment = "Development"
227+
Project = "Example"
228+
}
229+
}
230+
```
231+
232+
### State Move Commands
233+
234+
In conjunction with the changes above, users can elect to move their external capacity provider(s) under this module using the following move command. Command is shown using the values from the example shown above, please update to suit your configuration names:
235+
236+
```sh
237+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route_table.this[0]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route_table.this[0]'
238+
239+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route_table_association.this["vpc1"]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route_table_association.this["vpc1"]'
240+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route_table_propagation.this["vpc1"]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route_table_propagation.this["vpc1"]'
241+
242+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route.this[0]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route.this["vpc1-thing"]'
243+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route.this[1]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route.this["blackhole"]'
244+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route.this[2]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route.this["vpc2-thing"]'
245+
terraform state mv 'module.transit_gateway.aws_ec2_transit_gateway_route.this[3]' 'module.transit_gateway_route_table.aws_ec2_transit_gateway_route.this["blackhole2"]'
246+
```

0 commit comments

Comments
 (0)