Topics

#amazon-web-services #automation #aws #aws-orga #centralised-networking #example #hashicorp #iac #iam #infrastructure-as-code #network #network-firewall #network-hub #ram #route53 #route53-resolver #terraform #transit-gateway #vpc-endpoints #vpc-flowlogs

Language breakdown

HCL 100.0%

▸ Files click to expand

README

Network Hub Account with Terraform

This repository demonstrates a scalable, segregated, secured AWS network for multi-account organizations. Using Transit Gateway to separate production, non-production and shared services traffic, it deploys an advanced AWS networking pattern using centralized ingress and egress behind Network Firewall, centralizes private VPC endpoints to share across all VPCs, and manages IP address allocation using Amazon VPC IPAM.

Perfect for a central networking hub account, potentially alongside Account Factory for Terraform
Solution itself can be deployed into nonprod, test and production deployments for safe iteration and testing.
Written using clean, composable modules: the solution is easily extended and customised.

Spoke VPCs for organization members can be created using the provided sister example in this repo.

The following resources will be deployed by this example:

VPC Transit Gateway
VPC Endpoints
AWS Network Firewall
Route 53 Resolver
Amazon VPC IP Address Manager

The resources deployed and the architectural pattern they follow are provided for demonstration and testing purposes but are based on and inspired by AWS best practice and articles.

Overview

Diagrams

Solution Diagram diagram

Transit Gateway tgw

VPC Endpoints vpc_endpoints

Network Firewall nfw

Route 53 Resolver dns

References

Prerequisites

Minimal tooling is required for this solution. However, there are hard requirements around AWS configuration.

Tooling

Terraform ~> 1.1

- AWS provider >= 4.4.0

AWS CLI
Git CLI

AWS account configuration

AWS Organization
Centralised network account
IAM role with required permissions
RAM sharing enabled for the Organisation

aws ram enable-sharing-with-aws-organization

ram

Troubleshooting tip

If you experience any issue with the RAM share disable and re-enable RAM.

aws organizations disable-aws-service-access --service-principal ram.amazonaws.com

IPAM delegated from the master account to the Centralised network account

aws ec2 enable-ipam-organization-admin-account \
    --delegated-admin-account-id <Network-Account-ID>

ipam

Customisation

If you do not define a remote backend Terraform will use the local directory to store the backend files including tfstate. Examples of how to customise the Terraform backend are included but commented out. Usual caveats around safe storage of Terraform state must be considered.

backend

Example GitLab HTTP backend for use with GitLab CI.

Variables

| Type | Variable Name | Description | Notes | | ------------------------------ | ---------------- | ---------------------------------------------------------------- | ------------------------------------------- | | Global variables | environment | Environment to deploy into. | Accepted values \* dev, test, preprod, prod | | | aws_region | Region to deploy in. | | | | vpc_endpoints | List of centralised VPC endpoints to be deployed | | | Environment specific variables | ipam_cidr | CIDR to be allocated to the IP Address Manager | | | | tgwroutetables | Transit Gateway Router Tables to create | | | | root_domain | Root DNS domain to create private hosted zone and resolver rules | |

Input Variable - config.auto.tfvars

aws_region    = "eu-west-2"
vpc_endpoints = ["ec2", "rds", "sqs", "sns", "ssm", "logs", "ssmmessages", "ec2messages", "autoscaling", "ecs", "athena"]
env_config = {   dev = {     ipam_cidr        = "10.0.0.0/10"     tgwroutetables = ["prod", "dev", "shared"]     root_domain      = "network-dev.internal"   }   test = {     ipam_cidr        = "10.64.0.0/10"     tgwroutetables = ["prod", "dev", "shared"]     root_domain      = "network-test.internal"   }   preprod = {     ipam_cidr        = "10.128.0.0/10"     tgwroutetables = ["prod", "dev", "shared"]     root_domain      = "network-preprod.internal"   }   prod = {     ipam_cidr        = "10.192.0.0/10"     tgwroutetables = ["prod", "dev", "shared"]     root_domain      = "network-prod.internal"   } }

Quick Start

Deploy from client machine

When deploying from your local machine having configured the TF Backend in the code you need to ensure you have access to read and write to the backend - possible backends include HTTP, Consul, Postgres, Artifactory, S3 or S3 + DynamoDB. We initialise the Terraform, complete the validate and format. Review the plan and then apply.

terraform init
terraform validate
set environment for deployment

- export TFVARenvir - Set-Item -Path env:TFVARenvironment -Value "$ENV" (Possible $ENV values - dev, test, preprod, prod)

terraform plan
terraform apply or terraform apply --auto-approve

Tagging

Tags are added to all AWS resources through use of the tag configuration of the AWS Provider.

As not all AWS resources support default tags passed from the provider (EC2 Auto-Scaling Group + Launch Template) We pass the tags as a variable (Map(string) - these are defined in the root locals.tf file.

provider

Example Tags - locals.tf

tags = {
  Product    = "Network_Automation"
  Owner      = "GitHub"
  Project_ID = "12345"
}

Clean Up

Remember to clean up after your work is complete. You can do that by doing terraform destroy.

Note that this command will delete all the resources previously created by Terraform.

Terraform Docs

Terraform Deployment

Requirements

| Name | Version | |------|---------| | terraform | ~> 1.1 | | aws | >= 4.4.0 |

Providers

| Name | Version | |------|---------| | aws | 4.5.0 |

Modules

| Name | Source | Version | |------|--------|---------| | dns | ./modules/dns | n/a | | ipam | ./modules/ipam | n/a | | networkfirewallvpc | ./modules/networkfirewallvpc | n/a | | tgw | ./modules/tgw | n/a | | vpcendpoints | ./modules/vpcendpoints | n/a |

Resources

| Name | Type | |------|------| | awsiampolicy.central_network | resource | | awsiampolicyattachment.central_network | resource | | awsiamrole.central_network | resource | | awsiamrole.flow_logs | resource | | awsiamrolepolicy.flow_logs | resource | | awskmskey.log_key | resource | | awsavailabilityzones.available | data source | | awscalleridentity.current | data source | | awsiampolicydocument.policykmslogs_document | data source | | awsorganizationsorganization.main | data source |

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | aws_region | AWS region being deployed to | string | n/a | yes | | envconfig | Map of objects for per environment configuration |

map(object({
    ipamcidr        = string
    tgwroutetables = list(string)
    root_domain      = string
  }))

| n/a | yes | | environment | Deployment environment passed as argument or environment variable | string | n/a | yes | | tags | Default tags to apply to all resources | map(string) | n/a | yes | | vpc_endpoints | Which VPC endpoints to use | list(string) | n/a | yes |

Outputs

No outputs.

TGW Module

Requirements

No requirements.

Providers

| Name | Version | |------|---------| | aws | n/a |

Modules

No modules.

Resources

| Name | Type | |------|------| | awsec2transitgateway.org_tgw | resource | | awsec2transitgatewayroute.blackhole_route | resource | | awsec2transitgatewayroute.default_route | resource | | awsec2transitgatewayroute.defaultrouteipv6 | resource | | awsec2transitgatewayroutetable.org_tgw | resource | | awsramprincipalassociation.org | resource | | awsramresourceassociation.tgw | resource | | awsramresourceshare.main | resource |

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | az_names | A list of the Availability Zone names available to the account | list(string) | n/a | yes | | cidr | Corporate CIDR range for use with blackholing traffic between production and development environments | string | n/a | yes | | environment | Deployment environment passed as argument or environment variable | string | n/a | yes | | inspection_attachment | Inspection VPC attachment for default route | string | n/a | yes | | org_arn | The ARN of the AWS Organization this account belongs to | string | n/a | yes | | tgwroutetables | List of route tables to create for the transit gateway | list(string) | n/a | yes |

Outputs

| Name | Description | |------|-------------| | tgw | TGW ID for VPC attachments | | tgwroutetable | Map of route tables used for association and propagation |

IPAM Module

Requirements

No requirements.

Providers

| Name | Version | |------|---------| | aws | n/a |

Modules

No modules.

Resources

| Name | Type | |------|------| | awsramprincipalassociation.org | resource | | awsramresourceassociation.ipam | resource | | awsramresourceshare.main | resource | | awsssmparameter.ipampoolid | resource | | awsvpcipam.org_ipam | resource | | awsvpcipampool.privateorgipam_pool | resource | | awsvpcipampoolcidr.privateorgipam_pool | resource | | awsvpcipamscope.privateorgipam_scope | resource |

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | aws_region | AWS region being deployed to | string | n/a | yes | | ipam_cidr | CIDR block assigned to IPAM pool | string | n/a | yes | | org_arn | The ARN of the AWS Organization this account belongs to | string | n/a | yes |

Outputs

| Name | Description | |------|-------------| | org_ipam | Org IPAM ID | | orgipampool | Org IPAM pool ID |

VPC Endpoint Module

Requirements

No requirements.

Providers

| Name | Version | |------|---------| | aws | n/a |

Modules

No modules.

Resources

| Name | Type | |------|------| | awscloudwatchloggroup.flow_logs | resource | | awsdefaultsecuritygroup.default | resource | | awsec2transitgatewayroutetableassociation.shared | resource | | awsec2transitgatewayroutetablepropagation.org | resource | | awsec2transitgatewayvpcattachment.vpc_endpoint | resource | | awsflowlog.vpc | resource | | awsroute.default_route | resource | | awsroute.defaultrouteipv6 | resource | | awsroute53record.dev_ns | resource | | awsroute53zone.interface_phz | resource | | awsroutetable.endpoint_vpc | resource | | awsroutetableassociation.attachment_subnet | resource | | awsroutetableassociation.endpoint_subnet | resource | | awssecuritygroup.allowvpcendpoint | resource | | awssecuritygrouprule.org_cidr | resource | | awssubnet.attachment_subnet | resource | | awssubnet.endpoint_subnet | resource | | awsvpc.endpoint_vpc | resource | | awsvpcdhcpoptions.endpoint_vpc | resource | | awsvpcdhcpoptionsassociation.endpoint_vpc | resource | | awsvpcendpoint.interface | resource |

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | az_names | A list of the Availability Zone names available to the account | list(string) | n/a | yes | | cidr | Corporate CIDR range for use with blackholing traffic between production and development environments | string | n/a | yes | | environment | Deployment environment passed as argument or environment variable | string | n/a | yes | | iamrolearn | IAM role to allow VPC Flow Logs to write to CloudWatch | string | n/a | yes | | interface_endpoints | Object representing the region and services to create interface endpoints for | map(string) | n/a | yes | | kmskeyid | VPC Flow Logs KMS key to encrypt logs | string | n/a | yes | | orgipampool | IPAM pool ID to allocate CIDR space | string | n/a | yes | | tgw | TGW ID for VPC attachments | string | n/a | yes | | tgwroutetables | TGW route tables for VPC association and propagation | map(string) | n/a | yes |

Outputs

No outputs.

DNS Module

Requirements

No requirements.

Providers

| Name | Version | |------|---------| | aws | n/a |

Modules

No modules.

Resources

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | az_names | A list of the Availability Zone names available to the account | list(string) | n/a | yes | | cidr | Corporate CIDR range for use with blackholing traffic between production and development environments | string | n/a | yes | | environment | Deployment environment passed as argument or environment variable | string | n/a | yes | | iamrolearn | IAM role to allow VPC Flow Logs to write to CloudWatch | string | n/a | yes | | interface_endpoints | Object representing the region and services to create interface endpoints for | map(string) | n/a | yes | | kmskeyid | VPC Flow Logs KMS key to encrypt logs | string | n/a | yes | | org_arn | The ARN of the AWS Organization this account belongs to | string | n/a | yes | | orgipampool | IPAM pool ID to allocate CIDR space | string | n/a | yes | | root_domain | Root domain for private hosted zone delegation | string | n/a | yes | | tgw | TGW ID for VPC attachments | string | n/a | yes | | tgwroutetables | TGW route tables for VPC association and propagation | map(string) | n/a | yes |

Outputs

No outputs.

Network Firewall Module

Requirements

No requirements.

Providers

| Name | Version | |------|---------| | aws | n/a |

Modules

No modules.

Resources

Inputs

| Name | Description | Type | Default | Required | |------|-------------|------|---------|:--------:| | aws_region | AWS region being deployed to | string | n/a | yes | | az_names | A list of the Availability Zone names available to the account | list(string) | n/a | yes | | cidr | Corporate CIDR range for use with blackholing traffic between production and development environments | string | n/a | yes | | environment | Deployment environment passed as argument or environment variable | string | n/a | yes | | iamrolearn | IAM role to allow VPC Flow Logs to write to CloudWatch | string | n/a | yes | | kmskeyid | VPC Flow Logs KMS key to encrypt logs | string | n/a | yes | | orgipampool | IPAM pool ID to allocate CIDR space | string | n/a | yes | | tgw | TGW ID for VPC attachments | string | n/a | yes | | tgwroutetables | TGW route tables for VPC association and propagation | map(string) | n/a | yes |

Outputs

| Name | Description | |------|-------------| | eni_map | Output ENI map | | firewall_info | Info of network firewall for routing | | inspection_attachment | Inspection TGW attachment ID for default route in TGW | | route_table | Output route tables used for NFW | | rt_map | Output RT map |