From 03c7e76d421c303d4df105a95bf0abe82eee3153 Mon Sep 17 00:00:00 2001 From: Bryant Biggs Date: Thu, 26 Dec 2024 19:49:50 -0600 Subject: [PATCH] chore: Initial start of upgrade guide --- README.md | 28 +---- UPGRADE-3.0.md | 231 ++++++++++++++++++++++++++++++++++ modules/route-table/README.md | 114 +++++++++++++++++ 3 files changed, 349 insertions(+), 24 deletions(-) create mode 100644 UPGRADE-3.0.md diff --git a/README.md b/README.md index 70f7605..253da74 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Terraform module which creates AWS Transit Gateway resources. +[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) + ## Usage ```hcl @@ -54,36 +56,14 @@ module "transit_gateway" { vpc1 = { vpc_id = "vpc-1234556abcdef" security_group_referencing_support = true - subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"] + subnet_ids = ["sub-abcde012", "sub-bcde012a", "sub-fghi345a"] ipv6_support = true } vpc2 = { vpc_id = "vpc-98765432d1aad" security_group_referencing_support = true - subnet_ids = ["subnet-334de012", "subnet-6vfe012a", "subnet-agfi435a"] - } - } - - vpc_attachments = { - vpc = { - attachment_type = "vpc" - create_vpc_attachment = true - vpc_id = - subnet_ids = - - dns_support = true - ipv6_support = true - - tgw_routes = { - vpc = { - destination_cidr_block = "30.0.0.0/16" - }, - blackhole = { - blackhole = true - destination_cidr_block = "40.0.0.0/20" - } - } + subnet_ids = ["sub-334de012", "sub-6vfe012a", "sub-agfi435a"] } } diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md new file mode 100644 index 0000000..f2fb79a --- /dev/null +++ b/UPGRADE-3.0.md @@ -0,0 +1,231 @@ +# Upgrade from v2.x to v3.x + +Please consult the `examples` directory for reference example configurations. If you find a bug, please open an issue with supporting configuration to reproduce. + +## List of backwards incompatible changes + +- Minimum supported version of Terraform AWS provider updated to v5.78 to support the latest resources utilized +- Minimum supported version of Terraform updated to v1.3 +- 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. +- `aws_ram_resource_share_accepter` resource has been removed and should be managed outside of the module as needed. + +## Additional changes + +### Added + +- Added support for security group referencing +- Added support for flow logs on the Transit Gateway itself, as well as any attachments (as specified) +- Added support for Transit Gateway peering attachments + +### Modified + +- `vpc_attachments` type definition changed from `any` to full object definition +- RAM sharing of gateway is now set to `false` by default; users must opt into sharing by setting `enable_ram_share = true` +- `transit_gateway_default_route_table_association` is now set to `false` by default +- `transit_gateway_default_route_table_propagation` is now set to `false` by default + +### Removed + +- `aws_ram_resource_share_accepter` resource has been removed and should be managed outside of the module as needed. + +### Variable and output changes + +1. Removed variables: + + - `tgw_vpc_attachment_tags` + - `create_tgw_routes` + - `transit_gateway_route_table_id` + - `tgw_route_table_tags` + - `ram_resource_share_arn` + +2. Renamed variables: + + - `create_tgw` -> `create` + - `enable_default_route_table_association` -> `default_route_table_association` + - `enable_default_route_table_propagation` -> `default_route_table_propagation` + - `enable_auto_accept_shared_attachments` -> `auto_accept_shared_attachments` + - `enable_vpn_ecmp_support` -> `vpn_ecmp_support` + - `enable_multicast_support` -> `multicast_support` + - `enable_dns_support` -> `dns_support` + - `share_tgw` -> `enable_ram_share` + +3. Added variables: + + - `security_group_referencing_support` + - `peering_attachments` + - `create_flow_log` + - `flow_logs` + +4. Removed outputs: + + - `ec2_transit_gateway_vpc_attachment_ids` + - `ec2_transit_gateway_vpc_attachment` + - `ec2_transit_gateway_route_table_id` + - `ec2_transit_gateway_route_table_default_association_route_table` + - `ec2_transit_gateway_route_table_default_propagation_route_table` + - `ec2_transit_gateway_route_ids` + - `ec2_transit_gateway_route_table_association_ids` + - `ec2_transit_gateway_route_table_association` + - `ec2_transit_gateway_route_table_propagation_ids` + - `ec2_transit_gateway_route_table_propagation` + - `ram_principal_association_id` + +5. Renamed outputs: + + - `ec2_transit_gateway_arn` -> `arn` + - `ec2_transit_gateway_id` -> `id` + - `ec2_transit_gateway_owner_id` -> `owner_id` + - `ec2_transit_gateway_association_default_route_table_id` -> `association_default_route_table` + - `ec2_transit_gateway_propagation_default_route_table_id` -> `propagation_default_route_table` + +6. Added outputs: + + - `vpc_attachments` + - `peering_attachments` + +## Upgrade Migrations + +### Before v2.x Example + +```hcl +module "transit_gateway" { + source = "terraform-aws-modules/transit-gateway/aws" + version = "~> 2.12" + + name = "example" + description = "Example TGW connecting multiple VPCs" + amazon_side_asn = 64532 + + transit_gateway_cidr_blocks = ["10.99.0.0/24"] + + enable_auto_accept_shared_attachments = true + enable_multicast_support = true + + vpc_attachments = { + vpc1 = { + vpc_id = "vpc-1234556abcdef" + subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"] + ipv6_support = true + + transit_gateway_default_route_table_association = false + transit_gateway_default_route_table_propagation = false + + tgw_routes = [ + { + destination_cidr_block = "30.0.0.0/16" + }, + { + blackhole = true + destination_cidr_block = "0.0.0.0/0" + } + ] + } + + vpc2 = { + vpc_id = module.vpc2.vpc_id + subnet_ids = module.vpc2.private_subnets + + tgw_routes = [ + { + destination_cidr_block = "50.0.0.0/16" + }, + { + blackhole = true + destination_cidr_block = "10.10.10.10/32" + } + ] + } + } + + tags = { + Environment = "Development" + Project = "Example" + } +} +``` + +### After v3.x Example + +```hcl +module "transit_gateway" { + source = "terraform-aws-modules/transit-gateway/aws" + version = "3.0.0" + + name = "example" + description = "Example TGW connecting multiple VPCs" + amazon_side_asn = 64532 + + transit_gateway_cidr_blocks = ["10.99.0.0/24"] + + auto_accept_shared_attachments = true + multicast_support = true + + vpc_attachments = { + vpc1 = { + vpc_id = "vpc-1234556abcdef" + subnet_ids = ["subnet-abcde012", "subnet-bcde012a", "subnet-fghi345a"] + ipv6_support = true + } + + vpc2 = { + vpc_id = "vpc-98765432d1aad" + subnet_ids = ["subnet-334de012", "subnet-6vfe012a", "subnet-agfi435a"] + } + } + + tags = { + Environment = "Development" + Project = "Example" + } +} + +module "transit_gateway_route_table" { + source = "terraform-aws-modules/transit-gateway/aws//modules/route-table" + + name = "example" + transit_gateway_id = module.transit_gateway.id + + associations = { + vpc1 = { + transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc1"].id + propagate_route_table = true + } + vpc2 = { + transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc2"].id + propagate_route_table = true + } + } + + routes = { + blackhole = { + blackhole = true + destination_cidr_block = "0.0.0.0/0" + } + } + + vpc_routes = { + vpc1 = { + destination_cidr_block = "10.0.0.0/16" + route_table_id = "rtb-a73c2ede" + } + vpc2 = { + destination_cidr_block = 10.1.0.0/16" + route_table_id = "rtb-852956e2", + } + } + + tags = { + Environment = "Development" + Project = "Example" + } +} +``` + +### State Move Commands + +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: + +```sh +# Cluster +terraform state mv 'xx' 'xx' +``` diff --git a/modules/route-table/README.md b/modules/route-table/README.md index e69de29..338623d 100644 --- a/modules/route-table/README.md +++ b/modules/route-table/README.md @@ -0,0 +1,114 @@ +# AWS Transit Gateway Route Table Terraform module + +Terraform module which creates AWS Transit Gateway route table and route resources. + +## Usage + +```hcl +module "transit_gateway" { + source = "terraform-aws-modules/transit-gateway/aws" + + name = "example" + description = "Example TGW connecting multiple VPCs" + + # Truncated for brevity ... +} + +module "transit_gateway_route_table" { + source = "terraform-aws-modules/transit-gateway/aws//modules/route-table" + + name = "example" + transit_gateway_id = module.transit_gateway.id + + associations = { + vpc1 = { + transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc1"].id + propagate_route_table = true + } + vpc2 = { + transit_gateway_attachment_id = module.transit_gateway.vpc_attachments["vpc2"].id + propagate_route_table = true + } + } + + routes = { + blackhole = { + blackhole = true + destination_cidr_block = "0.0.0.0/0" + } + } + + vpc_routes = { + vpc1 = { + destination_cidr_block = "10.0.0.0/16" + route_table_id = "rtb-a73c2ede" + } + vpc2 = { + destination_cidr_block = 10.1.0.0/16" + route_table_id = "rtb-852956e2", + } + } + + tags = { + Environment = "Development" + Project = "Example" + } +} +``` + +## Examples + +- [Complete example](https://github.com/terraform-aws-modules/terraform-aws-transit-gateway/tree/master/examples/complete) shows TGW in combination with the [VPC module](https://github.com/terraform-aws-modules/terraform-aws-vpc). +- [Multi-account example](https://github.com/terraform-aws-modules/terraform-aws-transit-gateway/tree/master/examples/multi-account) shows TGW resources shared with different AWS accounts (via [Resource Access Manager (RAM)](https://aws.amazon.com/ram/)). + + +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.3 | +| [aws](#requirement\_aws) | >= 5.78 | + +## Providers + +| Name | Version | +|------|---------| +| [aws](#provider\_aws) | >= 5.78 | + +## Modules + +No modules. + +## Resources + +| Name | Type | +|------|------| +| [aws_ec2_transit_gateway_route.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ec2_transit_gateway_route) | resource | +| [aws_ec2_transit_gateway_route_table.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ec2_transit_gateway_route_table) | resource | +| [aws_ec2_transit_gateway_route_table_association.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ec2_transit_gateway_route_table_association) | resource | +| [aws_ec2_transit_gateway_route_table_propagation.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ec2_transit_gateway_route_table_propagation) | resource | +| [aws_route.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route) | resource | + +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [associations](#input\_associations) | A map of transit gateway attachment IDs to associate with the Transit Gateway route table | 
map(object({
    transit_gateway_attachment_id = optional(string)
    replace_existing_association  = optional(bool)
    propagate_route_table         = optional(bool, false)
  }))
| `{}` | no | +| [create](#input\_create) | Controls if resources should be created (it affects almost all resources) | `bool` | `true` | no | +| [name](#input\_name) | Name to be used on all the resources as identifier | `string` | `""` | no | +| [routes](#input\_routes) | A map of Transit Gateway routes to create in the route table | 
map(object({
    destination_cidr_block        = string
    blackhole                     = optional(bool, false)
    transit_gateway_attachment_id = optional(string)
  }))
| `{}` | no | +| [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no | +| [transit\_gateway\_id](#input\_transit\_gateway\_id) | The ID of the EC2 Transit Gateway | `string` | `""` | no | +| [vpc\_routes](#input\_vpc\_routes) | A map of VPC routes to create in the route table provided | 
map(object({
    route_table_id              = string
    destination_cidr_block      = optional(string)
    destination_ipv6_cidr_block = optional(string)
  }))
| `{}` | no | + +## Outputs + +| Name | Description | +|------|-------------| +| [arn](#output\_arn) | EC2 Transit Gateway Route Table Amazon Resource Name (ARN) | +| [id](#output\_id) | EC2 Transit Gateway Route Table identifier | + + +## License + +Apache 2 Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-transit-gateway/tree/master/LICENSE) for full details.