Skip to content

Commit 8a2c9a8

Browse files
apmcleanapmclean
authored
Initial Commit
Initial Commit
1 parent 5ad9112 commit 8a2c9a8

File tree

87 files changed

+83618
-6
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+83618
-6
lines changed

‎.github/workflows/node.js.yml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
2+
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
3+
4+
name: Node.js CI
5+
6+
on:
7+
push:
8+
branches: [ main ]
9+
pull_request:
10+
branches: [ main ]
11+
12+
jobs:
13+
build:
14+
15+
runs-on: ubuntu-latest
16+
17+
strategy:
18+
matrix:
19+
node-version: [14.x, 16.x]
20+
# See supported Node.js release schedule at https://nodejs.org/en/about/releases/
21+
22+
steps:
23+
- uses: actions/checkout@v3
24+
- name: Use Node.js ${{ matrix.node-version }}
25+
uses: actions/setup-node@v3
26+
with:
27+
node-version: ${{ matrix.node-version }}
28+
cache: 'npm'
29+
- run: npx prettier --check **/**/*.ts
30+
- run: npm ci
31+
- run: npm run build --if-present
32+
- run: npm test
33+

‎.gitignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
*.js
2+
!jest.config.js
3+
*.d.ts
4+
node_modules
5+
6+
# CDK asset staging directory
7+
.cdk.staging
8+
cdk.out

‎.npmignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
*.ts
2+
!*.d.ts
3+
4+
# CDK asset staging directory
5+
.cdk.staging
6+
cdk.out

‎README.md

Lines changed: 259 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,265 @@
1-
## My Project
1+
# AWS VPC Builder
22

3-
TODO: Fill this README out!
3+
The `aws-vpc-builder-cdk` project has two primary goals:
44

5-
Be sure to:
5+
1. Provide a simple and repeatable way to deploy and explore complex networking architectures on AWS.
6+
2. Showcase the capabilities of the AWS Cloud Development Kit (CDK) to create and orchestrate a complex architecture.
67

7-
* Change the title in this README
8-
* Edit your repository description on GitHub
8+
## Getting Started
9+
10+
Using a configuration file alone - build a complex network setup including:
11+
- Amazon Virtual Private Cloud (VPC)s
12+
- An AWS Transit Gateway
13+
- AWS VPN Connections to the AWS Transit Gateway
14+
- Centralized Egress to the Internet
15+
- AWS Firewall Inspection for inter-VPC traffic
16+
- Centralized Interface endpoints for private access to AWS service endpoints
17+
- AWS Resource Access Manager (RAM) share subnets to accounts, an Organization Unit, or an entire Organization.
18+
- Amazon Route53 private hosted zones shared with Amazon VPCs, Inbound and Outbound DNS Resolvers.
19+
20+
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.
21+
22+
The app supports multiple configuration files. So you can mirror setups between regions, or create isolated configurations in your account.
23+
24+
Taking 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:
25+
26+
![](images/index-1024x523.png)
27+
28+
This deployment is realized using the following configuration file:
29+
30+
```yaml
31+
global:
32+
stackNamePrefix: sample-firewall-blog
33+
ssmPrefix: /sample-firewall-blog/network
34+
region: us-east-1
35+
availabilityZones:
36+
- us-east-1a
37+
tags:
38+
- aws-vpc-builder: sample-firewall-blog
39+
40+
vpns:
41+
vpnToGround:
42+
style: transitGatewayAttached
43+
newCustomerGatewayIp: 5.6.7.8
44+
newCustomerGatewayAsn: 65012
45+
newCustomerGatewayName: toGround-DataCenterA
46+
useTransit: central
47+
48+
providers:
49+
internet:
50+
centralEgress:
51+
vpcCidr: 10.10.0.0/16
52+
useTransit: central
53+
style: natEgress
54+
firewall:
55+
inspectionVpc:
56+
vpcCidr: 100.64.0.0/16
57+
useTransit: central
58+
style: awsNetworkFirewall
59+
firewallDescription: For Inspection Vpc
60+
firewallName: InspectionEgress
61+
62+
vpcs:
63+
SpokeVpcA:
64+
style: workloadIsolated
65+
vpcCidr: 10.1.0.0/16
66+
providerInternet: centralEgress
67+
subnets:
68+
workloadSubnet:
69+
cidrMask: 24
70+
SpokeVpc:
71+
style: workloadIsolated
72+
vpcCidr: 10.3.0.0/16
73+
subnets:
74+
workloadSubnet:
75+
cidrMask: 24
76+
77+
transitGateways:
78+
central:
79+
style: transitGateway
80+
tgwDescription: Central Transit Gateway
81+
dynamicRoutes:
82+
- vpcName: SpokeVpcA
83+
routesTo: SpokeVpc
84+
inspectedBy: inspectionVpc
85+
defaultRoutes:
86+
- vpcName: SpokeVpcA
87+
routesTo: centralEgress
88+
inspectedBy: inspectionVpc
89+
- vpcName: SpokeVpc
90+
routesTo: centralEgress
91+
inspectedBy: inspectionVpc
92+
- vpcName: inspectionVpc
93+
routesTo: centralEgress
94+
staticRoutes:
95+
- vpcName: SpokeVpcA
96+
routesTo: vpnToGround
97+
staticCidr: 192.168.168.0/24
98+
- vpcName: SpokeVpc
99+
routesTo: vpnToGround
100+
staticCidr: 192.168.168.0/24
101+
```
102+
103+
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.
104+
105+
The ~70 lines of configuration file have generated >5000 lines of CloudFormation.
106+
107+
After you've completed the 'Environment Setup' section below you can deploy this by running:
108+
109+
```bash
110+
cdk deploy -c config=sample-firewall-blog.vpcBuilder.yaml --all --require-approval never
111+
```
112+
113+
Remove the `--require-approval never` if you'd like to be asked before any IAM resources, or Security Groups are created.
114+
115+
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!
116+
117+
## Environment Setup
118+
119+
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!
120+
121+
You can follow the getting started guide for Cloud9 [here](https://aws.amazon.com/cloud9/getting-started/)
122+
123+
### CDK
124+
125+
If you're using Cloud9, you should already have the CDK installed (use version 2).
126+
127+
Otherwise, 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).
128+
129+
### Modules
130+
131+
After installing the CDK, install the required NPM modules for the project by running:
132+
133+
```bash
134+
npm install
135+
```
136+
137+
### Tests
138+
139+
Now run the test cases to assure your environment is complete!
140+
141+
```bash
142+
npm run build ; npm run test
143+
```
144+
145+
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.
146+
147+
### Deployment Account
148+
149+
Configure your AWS CLI Credentials to work against the account you will deploy to.
150+
151+
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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) instructions.
152+
153+
Be sure to set the region to match the region you wish to deploy to. eg:
154+
155+
```bash
156+
export AWS_REGION=us-east-1
157+
```
158+
159+
Run a quick test to make sure the credentials are working
160+
161+
```bash
162+
aws s3 ls
163+
```
164+
165+
This command should list buckets in your deployment account.
166+
167+
### Bootstrap
168+
169+
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.
170+
171+
```bash
172+
cdk bootstrap
173+
```
174+
175+
## Configure
176+
177+
Create your own configuration file in the 'config' folder in this project. Or deploy a sample one that's included.
178+
179+
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](config/README.md).
180+
181+
Alternately a complete configuration file with many comments and every available option is in the `config-walkthrough.yaml` file.
182+
183+
Copy this file to a new file, and set it up the way you want for a deployment!
184+
185+
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!
186+
187+
### AWS Resource Access Manager (RAM) Sharing
188+
189+
This 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.
190+
191+
This simplifies the deployment (All regional Amazon VPCs in one account) and helps centralize governance of the estate.
192+
193+
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-'.
194+
195+
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.
196+
197+
Alternately you can AWS RAM share with a specific account ID by putting the Accounts ID in the `sharedWith` field.
198+
199+
### Synth Test
200+
201+
After your configuration is set up the way you wish, execute this command to verify the configuration file contents are correct.
202+
203+
NOTE: Nothing gets deployed by a 'synth' command, but instead it just validates the configuration contents and generates templates in the `cdk.out` folder.
204+
205+
You will need pass the configuration file as an option on the command line.
206+
207+
```bash
208+
cdk synth -c config=[configuration-file]
209+
```
210+
211+
(replace `[configuration-file]` with the filename in the 'config' directory you want to synth / test)
212+
213+
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.
214+
215+
### Deploy!
216+
217+
Once you're comfortable that everything looks good, execute a deployment!
218+
219+
```bash
220+
cdk deploy -c config=[configuration-file] --all --require-approval never
221+
```
222+
223+
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.
224+
225+
### Redeploy!
226+
227+
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.
228+
229+
```text
230+
cdk deploy -c config=[configuration-file] --all --require-approval never
231+
```
232+
233+
### Destroy!
234+
235+
You can destroy the stacks deployed by the configuration file by running:
236+
237+
```text
238+
cdk destroy -c config=[configuration-file] --all
239+
```
240+
241+
## Developer
242+
243+
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!
244+
245+
### Re-generating the JSON Schema
246+
247+
After changes to the IConfig Type the schema will need to be regenerated.
248+
249+
```bash
250+
typescript-json-schema --required --noExtraProps tsconfig.json IConfig > lib/config/config-schema.json
251+
```
252+
253+
### Prettier
254+
255+
All typescript is formatted using Prettier.
256+
257+
```text
258+
npx prettier --write **/**/*.ts
259+
npx prettier --check **/**/*.ts
260+
```
261+
262+
.... more to come.
9263

10264
## Security
11265

@@ -14,4 +268,3 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform
14268
## License
15269

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

‎bin/vpc-builder.ts

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#!/usr/bin/env node
2+
import "source-map-support/register";
3+
import { StackBuilderClass } from "../lib/stack-builder";
4+
import { Stack } from "aws-cdk-lib"
5+
6+
(async () => {
7+
try {
8+
const stackBuilder = new StackBuilderClass();
9+
const cdkApp = stackBuilder.stackMapper.app;
10+
11+
const configFile = cdkApp.node.tryGetContext("config");
12+
// If a configuration file is provided we will use it to build our stacks
13+
if (configFile) {
14+
stackBuilder.configure(configFile);
15+
await stackBuilder.build();
16+
} else {
17+
// When no configuration context provided, we will warn but not fail. This allows 'cdk bootstrap', 'cdk help'
18+
// to continue to work as expected.
19+
const dummyStack = new Stack(cdkApp, 'dummyStack', {})
20+
console.warn(
21+
"\nNo configuration provided. Use a configuration file from the 'config' directory using the '-c config=[filename]' argument\n"
22+
);
23+
}
24+
} catch (e) {
25+
console.error(e);
26+
process.exit(1);
27+
}
28+
})();

‎cdk.json

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"app": "npx ts-node --prefer-ts-exts bin/vpc-builder.ts",
3+
"watch": {
4+
"include": [
5+
"**"
6+
],
7+
"exclude": [
8+
"README.md",
9+
"cdk*.json",
10+
"**/*.d.ts",
11+
"**/*.js",
12+
"tsconfig.json",
13+
"package*.json",
14+
"yarn.lock",
15+
"node_modules",
16+
"test"
17+
]
18+
},
19+
"context": {
20+
"@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
21+
"@aws-cdk/core:stackRelativeExports": true,
22+
"@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
23+
"@aws-cdk/aws-lambda:recognizeVersionProps": true,
24+
"@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true,
25+
"@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
26+
"@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
27+
"@aws-cdk/aws-iam:minimizePolicies": true,
28+
"@aws-cdk/core:target-partitions": [
29+
"aws",
30+
"aws-cn"
31+
]
32+
}
33+
}

0 commit comments

Comments
 (0)