aws-samples / aws-vpc-builder-cdk

Using a configuration file alone, deploy complex AWS Network Architectures using the AWS CDK to learn from and explore!

AWS VPC Builder

The aws-vpc-builder-cdk project has two primary goals:

1. Provide a simple and repeatable way to deploy and explore complex networking architectures on AWS.
2. Showcase the capabilities of the AWS Cloud Development Kit (CDK) to create and orchestrate a complex architecture.

Getting Started

Using a configuration file alone - build a complex network setup including:

• Amazon Virtual Private Cloud (VPC)s
• An AWS Transit Gateway
• AWS VPN Connections to the AWS Transit Gateway
• Centralized Egress to the Internet
• AWS Firewall Inspection for inter-VPC traffic
• Centralized Interface endpoints for private access to AWS service endpoints
• AWS Resource Access Manager (RAM) share subnets to accounts, an Organization Unit, or an entire Organization.
• Amazon Route53 private hosted zones shared with Amazon VPCs, Inbound and Outbound DNS Resolvers.

The deployed setup can be as complex as everything above (and multiple types of each thing) to as simple as a single Amazon VPC with a single subnet in a single availability Zone.

The app supports multiple configuration files. So you can mirror setups between regions, or create isolated configurations in your account.

Taking an example from this blog post let's consider this network architecture:

This deployment is realized using the following configuration file:

global:
  stackNamePrefix: sample-firewall-blog
  ssmPrefix: /sample-firewall-blog/network
  region: us-east-1
  availabilityZones:
    - us-east-1a
  tags:
    - aws-vpc-builder: sample-firewall-blog

vpns:
  vpnToGround:
    style: transitGatewayAttached
    newCustomerGatewayIp: 5.6.7.8
    newCustomerGatewayAsn: 65012
    newCustomerGatewayName: toGround-DataCenterA
    useTransit: central

providers:
  internet:
    centralEgress:
      vpcCidr: 10.10.0.0/16
      useTransit: central
      style: natEgress
  firewall:
    inspectionVpc:
      vpcCidr: 100.64.0.0/16
      useTransit: central
      style: awsNetworkFirewall
      firewallDescription: For Inspection Vpc
      firewallName: InspectionEgress

vpcs:
  SpokeVpcA:
    style: workloadIsolated
    vpcCidr: 10.1.0.0/16
    providerInternet: centralEgress
    subnets:
      workloadSubnet:
        cidrMask: 24
  SpokeVpc:
    style: workloadIsolated
    vpcCidr: 10.3.0.0/16
    subnets:
      workloadSubnet:
        cidrMask: 24

transitGateways:
  central:
    style: transitGateway
    tgwDescription: Central Transit Gateway
    dynamicRoutes:
      - vpcName: SpokeVpcA
        routesTo: SpokeVpc
        inspectedBy: inspectionVpc
    defaultRoutes:
      - vpcName: SpokeVpcA
        routesTo: centralEgress
        inspectedBy: inspectionVpc
      - vpcName: SpokeVpc
        routesTo: centralEgress
        inspectedBy: inspectionVpc
      - vpcName: inspectionVpc
        routesTo: centralEgress
    staticRoutes:
      - vpcName: SpokeVpcA
        routesTo: vpnToGround
        staticCidr: 192.168.168.0/24
      - vpcName: SpokeVpc
        routesTo: vpnToGround
        staticCidr: 192.168.168.0/24

When the configuration file above is ingested by this app, it will create multiple CloudFormation stacks which the CDK can deploy in the correct order.

The ~70 lines of configuration file have generated >5000 lines of CloudFormation.

After you've completed the 'Environment Setup' section below you can deploy this by running:

cdk deploy -c config=sample-firewall-blog.vpcBuilder.yaml --all --require-approval never

Remove the --require-approval never if you'd like to be asked before any IAM resources, or Security Groups are created.

After it's deployed feel free to explore. You can make changes and re-deploy and the environment will adjust automatically. Try removing the 'inspectedBy' from the routes and see what happens!

Environment Setup

An AWS Cloud9 environment will contain all the tools and software to use this repository right away. Alternately anything with a command line and a text editor should do the trick!

You can follow the getting started guide for Cloud9 here

CDK

If you're using Cloud9, you should already have the CDK installed (use version 2).

Otherwise, you can follow these instructions to install the CDK (use version 2).

Modules

After installing the CDK, install the required NPM modules for the project by running:

npm install

Tests

Now run the test cases to assure your environment is complete!

npm run build ; npm run test

If test cases don't pass, try deleting the node_modules folder and package-lock.json file. Then re-run npm install and try again.

Deployment Account

Configure your AWS CLI Credentials to work against the account you will deploy to.

If you're in an AWS Cloud9 environment this should already be done for you! If you're not using AWS Cloud9 configure the AWS CLI using these instructions.

Be sure to set the region to match the region you wish to deploy to. eg:

export AWS_REGION=us-east-1

Run a quick test to make sure the credentials are working

aws s3 ls 

This command should list buckets in your deployment account.

Bootstrap

The CDK requires a place to put assets it builds. Bootstrap this account to handle this by running. If you've done this before in this account you can skip this step.

cdk bootstrap

Configure

Create your own configuration file in the 'config' folder in this project. Or deploy a sample one that's included.

Each sample in the config directory includes a markdown file with deployment instructions and an architecture diagram. See what samples aare available and how to deploy them here.

Alternately a complete configuration file with many comments and every available option is in the config-walkthrough.yaml file.

Copy this file to a new file, and set it up the way you want for a deployment!

This project makes every effort to deploy configuration files that pass validation checks. If you arrive at a configuration file that fails to deploy after passing validation checks, please submit a bug!

AWS Resource Access Manager (RAM) Sharing

This project makes use of / prefers a centralized managed model for networking by utilizing AWS RAM shared subnets from a central Network account.

This simplifies the deployment (All regional Amazon VPCs in one account) and helps centralize governance of the estate.

If you are AWS RAM sharing with an OU you will need the 'organizationId' from the AWS Organizations Service page. The value will begin with 'o-'.

You'll also need the 'ou-' that you wish to share with. That can be found by clicking the ou and copying the 'ou-' identifier.

Alternately you can AWS RAM share with a specific account ID by putting the Accounts ID in the sharedWith field.

VPC Endpoint Configuration

There are hundreds of available VPC Interface Endpoints. The ones you wish to deploy are kept in a separate configuration file in the config/ directory.

The interface endpoint configuration refers to a filename prefix in the endpointConfigFile: value. ie:

  endpoints:
    vpcEndpoints:
      style: serviceInterfaceEndpoint
      vpcCidr: 10.2.0.0/19
      endpointConfigFile: sample-vpc-endpoints

The stanza above will look for a file in the config/ directory named sample-vpc-endpoints-{region}.txt where {region} is the regional value in the global section.

The contents of the text file should be one interface endpoint name per line. ie:

com.amazonaws.us-east-1.ssmmessages
com.amazonaws.us-east-1.kms

This will deploy ssmmessages and kms Interface Endpoints into the shared VPC and make them available via Route53 Private Hosted Zones, and routing via the Transit Gateway.

NOTE: There is a regional component in the interface name, however vpcBuilder ignores this value. It is over-ridden by the region: specified in global:. So you can copy this file to a new region and refer to it without modification.

Synth Test

After your configuration is set up the way you wish, execute this command to verify the configuration file contents are correct.

NOTE: Nothing gets deployed by an 'ls' command, but instead it just validates the configuration contents and generates templates in the cdk.out folder.

You will need pass the configuration file as an option on the command line.

cdk ls -c config=[configuration-file]

(replace [configuration-file] with the filename in the 'config' directory you want to synth / test)

Errors in the configuration file will be caught and shown. Missing values, values not the right type, extra values etc. are all caught and shown in the error messages.

Deploy!

Once you're comfortable that everything looks good, execute a deployment!

cdk deploy -c config=[configuration-file] --all --require-approval never

Leave off the --require-aproval never if you'd like to be prompted when security groups / IAM roles will be created to allow it to proceed.

Redeploy!

Feel free to modify the configuration file to add or remove contents. At any point you can re-run the deploy command and the AWS CDK will handle the changes.

cdk deploy -c config=[configuration-file] --all --require-approval never

Destroy!

You can destroy the stacks deployed by the configuration file by running:

cdk destroy -c config=[configuration-file] --all

Developer

We'd love additional contributions to this project by way of new Amazon VPC styles, new network functions etc. Open an issue to discuss your idea before submitting a pull request please!

Re-generating the JSON Schema

After changes to the IConfig Type the schema will need to be regenerated.

typescript-json-schema --required --noExtraProps tsconfig.json IConfig > lib/config/config-schema.json

Prettier

All typescript is formatted using Prettier.

npx prettier --write **/**/*.ts
npx prettier --check **/**/*.ts

Re-running Interface Endpoint Discovery

Interface endpoints are not uniformly available across all availability zones. The vpcBuilder verifies interface endpoints in the configuration files are actually present in the availability zones the Interface VPC will use.

It verifies the configuraiton will function by looking at all available VPC Endpoints and their Availability Zones using the contents of the discovery/ folder.

Discovery may need to be re-generated on occasion as more endpoints are added. Run npm run discoverEndpoints to re-run discovery and re-create the discovery files.

Discovery looks only at 'non-opt-in' regions, and the 'aws' partition. The tools/discoverEndpoints/index.ts file can be modified to expand the criteria assuming your local credentials have access to DescribeVpcEndpointServices in those regions / partitions.

.... more to come.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

aws-vpc-builder-cdk's Issues

Enhancement: Include and improve documentation around endpoint discovery and multi-region.

The usage of the Discovery tooling is not present in the readme. Multi-region instructions are missing from the readme.

Tag Propagation with RAM Sharing

RAM shared resources do not have parent resource tags. I believe this is a known RAM issue however would be nice to include a fix for this so parent and child resource such as subnets have synchronized tags at creation time.

Region Portability Issue

Trying to get vpc builder running in a different region is not that straight forward. Tried to stand-up in us-west-2 with global: global:

** Replace with overall organizational ID **

Uncomment below if you'd like to use RAM Sharing

organizationId: o-hjw5j8o5mo
stackNamePrefix: sample-complex
ssmPrefix: /sample-complex/network
region: us-west-2
availabilityZones:
- us-west-2a
- us-west-2b

This leads to error with:
Endpoint vpc-endpoints: Service interface file sample-complex-endpoints-us-west-2.txt not found in the config directory

After creating the interface endpoint file it was looking for based on the us-east-1.txt reference and updating to us-west-2 values I'm still getting endpoint erorrs:
Error: Interface Endpoint named not found in discovery files
at VpcInterfaceEndpointsStack.lookupPrivateDnsName (/Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/vpc-interface-endpoints-stack.ts:198:13)
at /Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/vpc-interface-endpoints-stack.ts:105:43
at Array.forEach ()
at new VpcInterfaceEndpointsStack (/Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/vpc-interface-endpoints-stack.ts:75:25)
at StackMapper.providerEndpointStacks (/Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/stack-mapper.ts:151:26)
at StackBuilderClass.createEndpointServiceInterfaceStack (/Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/stack-builder.ts:365:37)
at StackBuilderClass.buildEndpointStacks (/Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/stack-builder.ts:334:20)
at StackBuilderClass.build (/Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/lib/stack-builder.ts:128:18)
at processTicksAndRejections (node:internal/process/task_queues:95:5)
at /Users/kennschr/IAC/CDK/aws-vpc-builder-cdk/bin/vpc-builder.ts:15:7

Resulting RAM Share names all contain 'Share-workload'

Describe the bug
RAM Share names for VPCs are not descriptive

To Reproduce
RAM Share multiple VPCs. They will all be named 'share-workload'.

Expected behavior
Name of the RAM share should at minimum describe the VPC being shared.

Enhancement: Include SSM EC2 Role and SSM Bastion

Immediate first step after deploying VPC builder was to launch a basic instance with SSM connectivity. Would be nice to bootstrap the IAM Role for EC2 SSM Access and launch a bastion in each VPC as part of initial deploy.

Bug: Newlines and extraneous vertical whitespace in endpoint configuration files causes failures

Describe the bug
When a newline or newlines are inserted into endpoint configuration files ie: sample-complex-endpoints-us-east-1.txt synthesis will fail with a message Error: Interface Endpoint named not found in discovery files.

To Reproduce
Add a newline to sample-complex-endpoints-us-east-1.txt then attempt to synthesize the sample-complex example.

Expected behavior
Newlines should be ignored

RAM Sharing to an OU no longer functioning.

Describe the bug
Share within an OU

To Reproduce
Any VPC with an ou shared with

  dev:
    style: workloadIsolated
    vpcCidr: 10.0.0.0/16
    subnets:
      workload:
        cidrMask: 18
        sharedWith:
          - ou-abcd-efg

Expected behavior
RAM Share works

Additional context
CloudFormation returns 'OperationNotPermittedException;'

TGW Peer Comments in Config Walkthrough incorrect

Describe the bug
README contains example for Transit Gateway Peer import:

  toUsEast2:
    # REQUIRED: Existing Transit Gateway (see above if you're relying on vpcBuilder to create the TGW)
    existingTgwId: tgw-12345
    # REQUIRED: Existing Transit Gateway Attachment Identifier for the Direct Connect Gateway
    existingTgwPeerTransitGatewayAttachId: tgw-attach-12345
    # REQUIRED: Existing Transit Gateway Route Table associated with the Direct Connect Gateway
    existingTgwPeerTransitGatewayRouteTableId: tgw-rtb-12345

Comments indicate this should be the one for a Direct Connect gateway which is not correct.

Model a Direct Connect Transit Gateway so it can be included in TGW routesTo

Is your feature request related to a problem? Please describe.
For use-cases where the Transit Gateway is associated with a Direct Connect Transit Gateway a model should exist that permits including the DX Gateway attachment as a destination for a routesTo: in supported Routes.

Describe the solution you'd like
A model for a DX Gateway in the configuration file. The required configuration items would be imported as existing (route table and attachment identifiers) similar to how an existing TGW or existing VPN is imported today.

CloudFormation currently has no support (aws-cloudformation/cloudformation-coverage-roadmap#876) for creating the Direct Connect Gateway itself, but we can model it by importing required attributes to support routesTo: within the Transit Gateway Route tables.

When a routesTo: destination is the modeled Direct Connect Gateway - static routes, dynamic routes and/or default routes would be configured in the same way they are today for VPC and VPN connections.

Support for Transit Gateway Peers in the Routes: section.

Is your feature request related to a problem? Please describe.
When a peer transit gateway is created you must manage the VPC routes to that Transit Gateway manually.

Describe the solution you'd like
Ability to model a Transit Gateway Peer Attachment in the configuration file and be able to use it in the 'routes' section as a destination.

Describe alternatives you've considered
None

Additional context
None

Could you submit a PR to implement this feature?
Yes

Permit use of existing VPC Names in `blackholeRoutes:` instead of requiring CIDR addresses.

Is your feature request related to a problem? Please describe.
Today when configuring a black hole route you need to specify a CIDR address.

Describe the solution you'd like
Often the Black Hole Route is for a VPC That is already defined in the same configuration file (ie: the CIDR is known). It is safer and more convenient to reefer to the VPC by-name instead of needing to copy and paste it's CIDR address.

Support specifying a VPC by-name in the Black Hole Route section. This should functionally work the same as providing a CIDR address, but the resolution of the CIDR address is handled by the definition in the configuration file under the vpcs: block.