chore: Initial start of upgrade guide

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"]
     }
   }
 

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'
+```

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/)).
+
+<!-- BEGIN_TF_DOCS -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 5.78 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [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 |
+|------|-------------|------|---------|:--------:|
+| <a name="input_associations"></a> [associations](#input\_associations) | A map of transit gateway attachment IDs to associate with the Transit Gateway route table | <pre>map(object({<br/>    transit_gateway_attachment_id = optional(string)<br/>    replace_existing_association  = optional(bool)<br/>    propagate_route_table         = optional(bool, false)<br/>  }))</pre> | `{}` | no |
+| <a name="input_create"></a> [create](#input\_create) | Controls if resources should be created (it affects almost all resources) | `bool` | `true` | no |
+| <a name="input_name"></a> [name](#input\_name) | Name to be used on all the resources as identifier | `string` | `""` | no |
+| <a name="input_routes"></a> [routes](#input\_routes) | A map of Transit Gateway routes to create in the route table | <pre>map(object({<br/>    destination_cidr_block        = string<br/>    blackhole                     = optional(bool, false)<br/>    transit_gateway_attachment_id = optional(string)<br/>  }))</pre> | `{}` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no |
+| <a name="input_transit_gateway_id"></a> [transit\_gateway\_id](#input\_transit\_gateway\_id) | The ID of the EC2 Transit Gateway | `string` | `""` | no |
+| <a name="input_vpc_routes"></a> [vpc\_routes](#input\_vpc\_routes) | A map of VPC routes to create in the route table provided | <pre>map(object({<br/>    route_table_id              = string<br/>    destination_cidr_block      = optional(string)<br/>    destination_ipv6_cidr_block = optional(string)<br/>  }))</pre> | `{}` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_arn"></a> [arn](#output\_arn) | EC2 Transit Gateway Route Table Amazon Resource Name (ARN) |
+| <a name="output_id"></a> [id](#output\_id) | EC2 Transit Gateway Route Table identifier |
+<!-- END_TF_DOCS -->
+
+## License
+
+Apache 2 Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-transit-gateway/tree/master/LICENSE) for full details.