{"id":13599805,"url":"https://github.com/aws-samples/aws-vpc-builder-cdk","last_synced_at":"2025-04-10T17:32:32.311Z","repository":{"id":38834533,"uuid":"486002398","full_name":"aws-samples/aws-vpc-builder-cdk","owner":"aws-samples","description":"Using a configuration file alone, deploy complex AWS Network Architectures using the AWS CDK to learn from and explore!","archived":false,"fork":false,"pushed_at":"2024-07-23T20:02:14.000Z","size":1789,"stargazers_count":39,"open_issues_count":4,"forks_count":14,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-08-02T17:39:00.815Z","etag":null,"topics":["aws","aws-vpc","aws-vpc-flowlogs","aws-vpc-gateway","aws-vpc-subnet","cdk","cdk-examples","firewall","internet-egress","networking","route53","vpc","vpc-endpoints","vpn"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-27T01:20:37.000Z","updated_at":"2024-08-01T22:18:53.000Z","dependencies_parsed_at":"2024-07-23T23:11:35.713Z","dependency_job_id":"e3687aa1-3d93-4983-bc46-caafc9690fbd","html_url":"https://github.com/aws-samples/aws-vpc-builder-cdk","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-vpc-builder-cdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-vpc-builder-cdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-vpc-builder-cdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Faws-vpc-builder-cdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-samples","download_url":"https://codeload.github.com/aws-samples/aws-vpc-builder-cdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223442661,"owners_count":17145815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-vpc","aws-vpc-flowlogs","aws-vpc-gateway","aws-vpc-subnet","cdk","cdk-examples","firewall","internet-egress","networking","route53","vpc","vpc-endpoints","vpn"],"created_at":"2024-08-01T17:01:12.027Z","updated_at":"2024-11-07T01:30:54.648Z","avatar_url":"https://github.com/aws-samples.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# AWS VPC Builder\n\nThe `aws-vpc-builder-cdk` project has two primary goals:\n\n1. Provide a simple and repeatable way to deploy and explore complex networking architectures on AWS.\n2. Showcase the capabilities of the AWS Cloud Development Kit (CDK) to create and orchestrate a complex architecture.\n\n## Getting Started\n\nUsing a configuration file alone - build a complex network setup including:  \n- Amazon Virtual Private Cloud (VPC)s\n- An AWS Transit Gateway\n- AWS VPN Connections to the AWS Transit Gateway\n- Centralized Egress to the Internet\n- AWS Firewall Inspection for inter-VPC traffic\n- Centralized Interface endpoints for private access to AWS service endpoints\n- AWS Resource Access Manager (RAM) share subnets to accounts, an Organization Unit, or an entire Organization.\n- Amazon Route53 private hosted zones shared with Amazon VPCs, Inbound and Outbound DNS Resolvers.\n\nThe 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.\n\nThe app supports multiple configuration files. So you can mirror setups between regions, or create isolated configurations in your account.\n\nTaking an example from [this](https://aws.amazon.com/blogs/networking-and-content-delivery/deployment-models-for-aws-network-firewall/) blog post let's consider this network architecture:\n\n![](images/index-1024x523.png)\n\nThis deployment is realized using the following configuration file:\n\n```yaml\nglobal:\n  stackNamePrefix: sample-firewall-blog\n  ssmPrefix: /sample-firewall-blog/network\n  region: us-east-1\n  availabilityZones:\n    - us-east-1a\n  tags:\n    - aws-vpc-builder: sample-firewall-blog\n\nvpns:\n  vpnToGround:\n    style: transitGatewayAttached\n    newCustomerGatewayIp: 5.6.7.8\n    newCustomerGatewayAsn: 65012\n    newCustomerGatewayName: toGround-DataCenterA\n    useTransit: central\n\nproviders:\n  internet:\n    centralEgress:\n      vpcCidr: 10.10.0.0/16\n      useTransit: central\n      style: natEgress\n  firewall:\n    inspectionVpc:\n      vpcCidr: 100.64.0.0/16\n      useTransit: central\n      style: awsNetworkFirewall\n      firewallDescription: For Inspection Vpc\n      firewallName: InspectionEgress\n\nvpcs:\n  SpokeVpcA:\n    style: workloadIsolated\n    vpcCidr: 10.1.0.0/16\n    providerInternet: centralEgress\n    subnets:\n      workloadSubnet:\n        cidrMask: 24\n  SpokeVpc:\n    style: workloadIsolated\n    vpcCidr: 10.3.0.0/16\n    subnets:\n      workloadSubnet:\n        cidrMask: 24\n\ntransitGateways:\n  central:\n    style: transitGateway\n    tgwDescription: Central Transit Gateway\n    dynamicRoutes:\n      - vpcName: SpokeVpcA\n        routesTo: SpokeVpc\n        inspectedBy: inspectionVpc\n    defaultRoutes:\n      - vpcName: SpokeVpcA\n        routesTo: centralEgress\n        inspectedBy: inspectionVpc\n      - vpcName: SpokeVpc\n        routesTo: centralEgress\n        inspectedBy: inspectionVpc\n      - vpcName: inspectionVpc\n        routesTo: centralEgress\n    staticRoutes:\n      - vpcName: SpokeVpcA\n        routesTo: vpnToGround\n        staticCidr: 192.168.168.0/24\n      - vpcName: SpokeVpc\n        routesTo: vpnToGround\n        staticCidr: 192.168.168.0/24\n```\n\nWhen the configuration file above is ingested by this app, it will create multiple CloudFormation stacks which the CDK can deploy in the correct order.\n\nThe ~70 lines of configuration file have generated \u003e5000 lines of CloudFormation.\n\nAfter you've completed the 'Environment Setup' section below you can deploy this by running:\n\n```bash\ncdk deploy -c config=sample-firewall-blog.vpcBuilder.yaml --all --require-approval never\n```\n\nRemove the `--require-approval never` if you'd like to be asked before any IAM resources, or Security Groups are created.\n\nAfter 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!\n\n## Environment Setup\n\nAn 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!\n\nYou can follow the getting started guide for Cloud9 [here](https://aws.amazon.com/cloud9/getting-started/)\n\n### CDK\n\nIf you're using Cloud9, you should already have the CDK installed (use version 2).\n\nOtherwise, you can follow [these instructions](https://docs.aws.amazon.com/cdk/latest/guide/getting_started.html#getting_started_install) to install the CDK (use version 2).\n\n### Modules \n\nAfter installing the CDK, install the required NPM modules for the project by running:\n\n```bash\nnpm install\n```\n\n### Tests\n\nNow run the test cases to assure your environment is complete!\n\n```bash\nnpm run build ; npm run test\n```\n\nIf test cases don't pass, try deleting the `node_modules` folder and `package-lock.json` file.  Then re-run `npm install` and try again.\n\n### Deployment Account\n\nConfigure your AWS CLI Credentials to work against the account you will deploy to.\n\nIf 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) instructions.\n\nBe sure to set the region to match the region you wish to deploy to.  eg:\n\n```bash\nexport AWS_REGION=us-east-1\n```\n\nRun a quick test to make sure the credentials are working\n\n```bash\naws s3 ls \n```\n\nThis command should list buckets in your deployment account.\n\n### Bootstrap\n\nThe 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.\n\n```bash\ncdk bootstrap\n```\n\n## Configure\n\nCreate your own configuration file in the 'config' folder in this project.  Or deploy a sample one that's included.\n\nEach 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](config/README.md).\n\nAlternately a complete configuration file with many comments and every available option is in the `config-walkthrough.yaml` file.\n\nCopy this file to a new file, and set it up the way you want for a deployment!\n\nThis 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!\n\n### AWS Resource Access Manager (RAM) Sharing\n\nThis project makes use of / prefers a centralized managed model for networking by utilizing [AWS RAM shared subnets](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html) from a central Network account.\n\nThis simplifies the deployment (All regional Amazon VPCs in one account) and helps centralize governance of the estate.\n\nIf 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-'.\n\nYou'll also need the 'ou-' that you wish to share with.  That can be found by clicking the ou and copying the 'ou-' identifier.\n\nAlternately you can AWS RAM share with a specific account ID by putting the Accounts ID in the `sharedWith` field.\n\n### VPC Endpoint Configuration\n\nThere are hundreds of available VPC Interface Endpoints.  The ones you wish to deploy are kept in a separate configuration file in the `config/` directory.\n\nThe interface endpoint configuration refers to a filename prefix in the `endpointConfigFile:` value.  ie:\n\n```yaml\n  endpoints:\n    vpcEndpoints:\n      style: serviceInterfaceEndpoint\n      vpcCidr: 10.2.0.0/19\n      endpointConfigFile: sample-vpc-endpoints\n```\n\nThe 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.\n\nThe contents of the text file should be one interface endpoint name per line.  ie:\n\n```text\ncom.amazonaws.us-east-1.ssmmessages\ncom.amazonaws.us-east-1.kms\n```\n\nThis 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.\n\nNOTE: 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.\n\n### Synth Test\n\nAfter your configuration is set up the way you wish, execute this command to verify the configuration file contents are correct.\n\nNOTE: Nothing gets deployed by an 'ls' command, but instead it just validates the configuration contents and generates templates in the `cdk.out` folder.\n\nYou will need pass the configuration file as an option on the command line.\n\n```bash\ncdk ls -c config=[configuration-file]\n```\n\n(replace `[configuration-file]` with the filename in the 'config' directory you want to synth / test)\n\nErrors 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.\n\n### Deploy!\n\nOnce you're comfortable that everything looks good, execute a deployment!\n\n```bash\ncdk deploy -c config=[configuration-file] --all --require-approval never\n```\n\nLeave 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.\n\n### Redeploy!\n\nFeel 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.\n\n```text\ncdk deploy -c config=[configuration-file] --all --require-approval never\n```\n\n### Destroy!\n\nYou can destroy the stacks deployed by the configuration file by running:\n\n```text\ncdk destroy -c config=[configuration-file] --all\n```\n\n## Developer\n\nWe'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!\n\n### Re-generating the JSON Schema\n\nAfter changes to the IConfig Type the schema will need to be regenerated.\n\n```bash\ntypescript-json-schema --required --noExtraProps tsconfig.json IConfig \u003e lib/config/config-schema.json\n```\n\n### Prettier\n\nAll typescript is formatted using Prettier.\n\n```text\nnpx prettier --write **/**/*.ts\nnpx prettier --check **/**/*.ts\n```\n\n### Re-running Interface Endpoint Discovery\n\nInterface 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.\n\nIt verifies the configuraiton will function by looking at all available VPC Endpoints and their Availability Zones using the contents of the `discovery/` folder.\n\nDiscovery 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.\n\nDiscovery 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.\n\n.... more to come.\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis library is licensed under the MIT-0 License. See the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Faws-vpc-builder-cdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-samples%2Faws-vpc-builder-cdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Faws-vpc-builder-cdk/lists"}