README.yaml

name: "aws-tgw-hub"
# Canonical GitHub repo
github_repo: "cloudposse-terraform-components/aws-tgw-hub"
# Short description of this project
description: |-
  This component is responsible for provisioning an [AWS Transit Gateway](https://aws.amazon.com/transit-gateway) `hub`
  that acts as a centralized gateway for connecting VPCs from other `spoke` accounts.

usage: |-

  **Stack Level**: Regional

  ## Basic Usage with `tgw/spoke`

  Here's an example snippet for how to configure and use this component:

  ```yaml
  components:
    terraform:
      tgw/hub/defaults:
        metadata:
          type: abstract
          component: tgw/hub
        vars:
          enabled: true
          name: tgw-hub
          expose_eks_sg: false
          tags:
            Team: sre
            Service: tgw-hub

      tgw/hub:
        metadata:
          inherits:
            - tgw/hub/defaults
          component: tgw/hub
        vars:
          connections:
            - account:
                tenant: core
                stage: network
              vpc_component_names:
                - vpc-dev
            - account:
                tenant: core
                stage: artifacts
            - account:
                tenant: core
                stage: auto
              eks_component_names:
                - eks/cluster
            - account:
                tenant: plat
                stage: dev
              vpc_component_names:
                - vpc
                - vpc/data/1
              eks_component_names:
                - eks/cluster
            - account:
                tenant: plat
                stage: staging
              vpc_component_names:
                - vpc
                - vpc/data/1
              eks_component_names:
                - eks/cluster
            - account:
                tenant: plat
                stage: prod
              vpc_component_names:
                - vpc
                - vpc/data/1
              eks_component_names:
                - eks/cluster
  ```

  To provision the Transit Gateway and all related resources, run the following commands:

  ```sh
  atmos terraform plan tgw/hub -s <tenant>-<environment>-network
  atmos terraform apply tgw/hub -s <tenant>-<environment>-network
  ```

  ## Alternate Usage with `tgw/attachment`, `tgw/routes`, and `vpc/routes`

  ### Components Overview

  - **`tgw/hub`**: Creates the Transit Gateway in the network account
  - **`tgw/attachment`**: Creates and manages Transit Gateway VPC attachments in connected accounts
  - **`tgw/hub-connection`**: Creates the Transit Gateway peering connection between two `tgw/hub` deployments
  - **`tgw/routes`**: Manages Transit Gateway route tables in the network account
  - **`vpc-routes`** (`vpc/routes/private`): Configures VPC route tables in connected accounts to route traffic through the Transit Gateway (Note: This component lives outside the `tgw/` directory since it's not specific to Transit Gateway)

  ### Architecture

  The Transit Gateway components work together in the following way:

  1. Transit Gateway is created in the network account (`tgw/hub`)
  2. VPCs in other accounts attach to the Transit Gateway (`tgw/attachment`)
  3. Route tables in connected VPCs direct traffic across accounts (`vpc-routes`)
  4. Transit Gateway route tables control routing between attachments (`tgw/routes`)

  ```mermaid
  graph TD
      subgraph core-use1-network
          TGW[Transit Gateway]
          TGW_RT[TGW Route Tables]
      end

      subgraph plat-use1-dev
          VPC1[VPC]
          VPC1_RT[VPC Route Tables]
          ATT1[TGW Attachment]
      end

      subgraph core-use1-auto
          VPC2[VPC]
          VPC2_RT[VPC Route Tables]
          ATT2[TGW Attachment]
      end

      ATT1 <--> TGW
      ATT2 <--> TGW
      TGW <--> TGW_RT
      VPC1_RT <--> VPC1
      VPC2_RT <--> VPC2
      VPC1 <--> ATT1
      VPC2 <--> ATT2
  ```

  ### Deployment Steps

  #### 1. Deploy Transit Gateway Hub

  First, create the Transit Gateway in the network account.

  > [!TIP]
  > Leave `var.connections` empty. With this refactor, the `tgw/hub` component is only responsible for creating the Transit Gateway and its route tables. We do not need to fetch and store outputs for the connected components anymore.

  ```yaml
  components:
    terraform:
      tgw/hub:
        vars:
          connections: []
  ```

  #### 2. Deploy VPC Attachments

  Important: Deploy attachments in connected accounts first, before deploying attachments in the network account.

  ##### Connected Account Attachments

  ```yaml
  components:
    terraform:
      tgw/attachment:
        vars:
          transit_gateway_id: !terraform.output tgw/hub core-use1-network transit_gateway_id
          transit_gateway_route_table_id: !terraform.output tgw/hub core-use1-network transit_gateway_route_table_id
          create_transit_gateway_route_table_association: false
  ```

  ##### Network Account Attachment

  ```yaml
  components:
    terraform:
      tgw/attachment:
        vars:
          transit_gateway_id: !terraform.output tgw/hub core-use1-network transit_gateway_id
          transit_gateway_route_table_id: !terraform.output tgw/hub core-use1-network transit_gateway_route_table_id

          # Route table associations are required so that route tables can propagate their routes to other route tables.
          # Set the following to true in the same account where the Transit Gateway and its route tables are deployed
          create_transit_gateway_route_table_association: true

          # Associate connected accounts with the Transit Gateway route table
          additional_associations:
            - attachment_id: !terraform.output tgw/attachment core-use1-auto transit_gateway_vpc_attachment_id
              route_table_id: !terraform.output tgw/hub transit_gateway_route_table_id
            - attachment_id: !terraform.output tgw/attachment plat-use1-dev transit_gateway_vpc_attachment_id
              route_table_id: !terraform.output tgw/hub transit_gateway_route_table_id
  ```

  #### 3. Configure VPC Routes

  Configure routes in all connected VPCs.

  ```yaml
  components:
    terraform:
      vpc/routes/private:
        metadata:
          component: vpc-routes
        vars:
          route_table_ids: !terraform.output vpc private_route_table_ids
          routes:
            # Route to network account
            - destination:
                cidr_block: !terraform.output vpc core-use1-network vpc_cidr
              target:
                type: transit_gateway_id
                value: !terraform.output tgw/hub core-use1-network transit_gateway_id

            # Route to core-auto account, if necessary
            - destination:
                cidr_block: !terraform.output vpc core-use1-auto vpc_cidr
              target:
                type: transit_gateway_id
                value: !terraform.output tgw/hub core-use1-network transit_gateway_id
  ```

  Configure routes in the Network Account VPCs.

  ```yaml
  components:
    terraform:
      vpc/routes/private:
        vars:
          route_table_ids: !terraform.output vpc private_route_table_ids
          routes:
            # Routes to connected accounts
            - destination:
                cidr_block: !terraform.output vpc core-use1-auto vpc_cidr
              target:
                type: transit_gateway_id
                value: !terraform.output tgw/hub transit_gateway_id
            - destination:
                cidr_block: !terraform.output vpc plat-use1-dev vpc_cidr
              target:
                type: transit_gateway_id
                value: !terraform.output tgw/hub transit_gateway_id
  ```

  ### 4. Deploy Transit Gateway Route Table Routes

  Deploy the `tgw/routes` component in the network account to create route tables and routes.

  ```yaml
  components:
    terraform:
      tgw/routes:
        vars:
          transit_gateway_route_table_id: !terraform.output tgw/hub transit_gateway_route_table_id
          # Use propagated routes to route through VPC attachments
          propagated_routes:
            # Route to this account
            - attachment_id: !terraform.output tgw/attachment core-use1-network transit_gateway_attachment_id
            # Route to any connected account
            - attachment_id: !terraform.output tgw/attachment core-use1-auto transit_gateway_attachment_id
            - attachment_id: !terraform.output tgw/attachment plat-use1-dev transit_gateway_attachment_id
  ```

tags:
  - component/tgw/hub
  - layer/network
  - provider/aws
# Categories of this project
categories:
  - component/tgw/hub
  - layer/network
  - provider/aws
# License of this project
license: "APACHE2"
# Badges to display
badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse-terraform-components/aws-tgw-hub.svg?style=for-the-badge
    url: https://github.com/cloudposse-terraform-components/aws-tgw-hub/releases/latest
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://slack.cloudposse.com
related:
  - name: "Cloud Posse Terraform Modules"
    description: Our collection of reusable Terraform modules used by our reference architectures.
    url: "https://docs.cloudposse.com/modules/"
  - name: "Atmos"
    description: "Atmos is like docker-compose but for your infrastructure"
    url: "https://atmos.tools"
contributors: [] # If included generates contribs