config-walkthrough.yaml

# This is a good place to start to understand the available parameters to build your network environment with
# Feel free to copy this and make your own that reflects the environment you want to build.

# REQUIRED: Global contains variables that are used throughout all stacks
global:
  # OPTIONAL:DEPENDANT - If you will RAM share to Organizational units this is required
  # This must start with 'o-'.  You can find it in the Organizations service on the left pane
  organizationId: o-1234
  # OPTIONAL:DEPENDANT - If you will RAM share to Organizational units this is required
  # This is the AWS Account identifier for account owning the Organization
  organizationMainAccountId: "123456789012"
  # REQUIRED - This prefix will pre-pend ALL stacks created, and will be used within the SSM Prefix below
  # This assures that you can deploy multiple environments with similar resources without name collision.
  stackNamePrefix: Core
  # REQUIRED - Stacks will create SSM exports in order to exchange information with each other.  This will be the prefix
  # This must begin with a / but not end with a /.  The stackNamePrefix will follow, then all the resources we create
  # will follow with their own path.  ie: /infrastructure/Core/vpcs/dev/vpcid will contain the vpc ID for the vpc named dev
  ssmPrefix: /infrastructure
  # REQUIRED - The region this stack will deploy to
  region: us-east-1
  # REQUIRED - A list of availability zones to deploy to.  This will be used by default for all VPC and AZ aware services.
  # You may over-ride this on a case-by-base basis by declaring the availabilityZones statement in each items configuration section.
  availabilityZones:
    - us-east-1a
    - us-east-1b
  # OPTIONAL - this defaults to 'discovery'.  This folder contains details about which VPC Interface Endpoints are available
  # in which region.  This is automatically generated by an SDK call - you shouldn't need to fiddle.
  discoveryFolder: discovery
  # OPTIONAL - Whether to use the legacy scheme for naming CloudFormation identifiers for Transit Gateway.
  # Only early adopters wishing to update historical deployments created using this tool should consider setting this to true.
  useLegacyIdentifiers: true
  # OPTIONAL - A list of tags to apply in the form of name: value.  These will be applied to ALL stacks deployed by this app!
  tags:
    - ProjectCode: configWalkThrough
    # Add more . . .

# REQUIRED: The project is vpcBuilder, so we need at least one VPC defined to function!  This is where your VPCs for
# workload are defined.  'specialized' VPCs like firewall, endpoints, or internet egress are defined elsewhere.
vpcs:
  # REQUIRED: The name of your VPC.  This uniquely identifies the VPC within the configuration file so should be chosen wisely.
  # NOTE: After the VPC has been deployed this *cannot be changed*.  CloudFormation will see the VPC as being deleted and attempt to delete
  # it.  I've added protections to prevent that from happening (fn:export/fn:import prevents).
  workload:
    # REQUIRED: This helps our framework decide which 'kind' of VPC you'd like.
    # - 'workloadIsolated' provisions a VPC with no IGW (effectively an isolated VPC).
    # - 'workloadPublic' provisions a VPC with an IGW (effectively a public VPC)
    style: workloadIsolated
    # REQUIRED: The CIDR Address of the VPC.  Use a subnet calculator to make sure you're starting at the beginning of the address space
    # otherwise you'll run into bugs when the CDK carves up your subnets!.  ie: 10.2.3.0/19 is not the start of the CIDR range.  Instead
    # use 10.2.0.0/19.  The configuration parser verifies valid start addresses, so you're safe!
    vpcCidr: 10.10.0.0/16
    # OPTIONAL - A list of availability zones to deploy to which over-rides the global: section
    availabilityZones:
      - us-east-1a
      - us-east-1b
    # OPTIONAL DEPENDANT: Historically we could RAM Share a Subnet by using 'this' accounts ID even if 'this' account didn't own the organization.
    # That ARN construction no longer works.  If you have an existing RAM share under this method and want to not trigger an update, set this value to true
    # See for more details: https://github.com/aws-samples/aws-vpc-builder-cdk/issues/15
    legacyRamShare: true
    # OPTIONAL: Normally we dynamically decide whether to attach a VPC to a TGW based on it having routes defined in the transitGateways
    # section.  If you want to force, or prevent this VPC attaching to a TGW, then set this to true (always) or false (never).
    attachTgw: true
    # REQUIRED: Definition section for the subnets to deploy.
    # NOTE: Once initially deployed - the Subnet Names in this section cannot be changed.  This is meant to be an 'additive' section
    # after your initial deployment you can add more Subnets, but consider it a 1-way door.
    subnets:
      # REQUIRED: A unique name for the subnet WITHIN the definition of the VPC.  Ie: all VPCs can use 'web', 'app', 'db' subnet names
      # however within the VPC you can't create two subnets with the name 'web'.  YAML should prevent this normally anyways.
      app:
        # REQUIRED: The CIDR mask to use for the subnet.  Bear in mind these will be decided by the CDK based on the VPC CIDR
        # range specified above.
        # In the future version I will support specifying a full CIDR here versus just a Mask
        cidrMask: 21
        # OPTIONAL: A list of RAM shares for this subnet with either a) An AWS Account ID specified.  b) The full organization specified
        # by the organization ID (starts with o-) or c) An organizational unit within the organization specified by th OU ID (this one
        # starts with ou- and can be found on the OU details page).
        sharedWith:
        - 123456789101
        - ou-12345
    # OPTIONAL: Where an 'endpoint' provider has been provisioned, this establishes the right for this VPC to use it.  The value
    # here should match the name of the endpoint in the 'providers:' section.  NOTE: You do not need to specifically route to the
    # endpoint VPC.  This relationship with create a dynamic CIDR based route so the endpoints can be reached.
    providerEndpoints: centralInterfaceEndpoints
    # OPTIONAL: Where an 'internet' provider has been provisioned, this establishes a relationship to assure this VPC is attached
    # to the TGW to be able to use it.  NOTE: This does NOT create a relationship or route automatically.  You still need to choose
    # a default route or other type of route in your transitGateways routing section.
    providerInternet: egressViaNat
  # REPEAT: X number of VPCs can be defined the same way as above.  However, assure you don't exceed account limits for VPCs
  # (these can be increased using the quota tool).  Each VPC needs a unique name within the config file.
  # Adding another one here so we can demonstrate route diversity
  workloadTwo:
    vpcCidr: 10.10.0.0/16
    style: workloadIsolated
    subnets:
      web:
        cidrMask: 24

# OPTIONAL: Route53 Private Hosted Zones may be defined, and shared with both external (to this configuration file) VPCs
# and VPCs within this configuration file.  NOTE: Where sharing with another accounts VPC is desired you will need to use
# the AWS CLI or SDK to 'handshake' between those accounts.  Currently no helpers to make that easier but maybe you'll write one?
dns:
  # REQUIRED: The name to organize our private hosted zones under.  You can specify as many as you wish to keep them within separate Stacks.
  private-zones:
    # REQUIRED: A list of domains to create private hosted zones for.
    domains:
      - example.org
    # OPTIONAL: Specify a list of VPCs (That are defined WITHIN This template) that are permitted to resolve these domains within the VPC.
    shareWithVpcs:
      - workload
    # OPTIONAL: Specify a list of existing VPC IDs, and their Regions WITHIN THIS ACCOUNT that should be permitted to resolve these domains as well.
    shareWithExistingVpcs:
        # VPC Identifier, begins with vpc-
      - vpcId: vpc-12345
        # Region the VPC is in IN THIS ACCOUNT
        vpcRegion: us-east-1
  # Additional entries with domains/shares etc.

# OPTIONAL|DEPENDANT: Providers are 'special VPCs' that provide a network function.  ie: Internet access, firewall services,
# endpoint services etc.  They are purpose built to best practices and can be used by our VPCs to provide centralized services.
# This becomes required if there are references above to providers, or references in the transit gateway routing section.
providers:
  # OPTIONAL: The internet provider.  This provider provides centralized internet access.
  internet:
    # REQUIRED: The name of the internet provider.  This must be unique within the config file.  It is referred to by VPCs and Transit routes.
    egressViaNat:
      # REQUIRED: This VPC will create (per availability zone) A Transit Gateway subnet of /28.  A public subnet of /28.  So in a three AZ
      # deployment you will need a /25 VPC Cidr provided.  Adjust up or down to suit your needs.
      vpcCidr: 10.1.2.0/25
      # OPTIONAL - A list of availability zones to deploy to which over-rides the global: section
      availabilityZones:
        - us-east-1a
        - us-east-1b
      # REQUIRED: All providers are Transit Gateway attached in our model.  This is the name of the transit gateway to attach to.
      # it must exist with the same name in the transitGateways section.
      useTransit: central
      # REQUIRED: Currently only natEgress is available but this is meant to have more plugins developed.  Will you write another style and share?
      style: natEgress
  # OPTIONAL: The endpoint provider.  This provider provides centralized endpoint access for private / controlled access to AWS Service endpoints.
  endpoints:
    # REQUIRED: the name of the interface provider.  This must be unique within the config file.  It is referred to by the VPCs and Transit routes
    # style: 'serviceInterfaceEndpoint' - provides AWS Service Endpoints in a private VPC with Route53 private hosted zone name resolution
    centralInterfaceEndpoints:
      # REQUIRED: This VPC will create (per availability zone) a Transit Gateway subnet of /28.  An endpoints' subnet of /22 by default.  This
      # allows us to accommodate up to 1024 endpoint IPs.  Reduce that mask below if you like.  For three AZs a /19 should suffice.
      vpcCidr: 10.2.0.0/19
      # OPTIONAL - A list of availability zones to deploy to which over-rides the global: section.  This information will inform the possible
      #  interface endpoints that can be provisioned in the combination of all AZs.  We will prevent deployment of interface endpoints that aren't
      #  available in all AZs noted below.
      availabilityZones:
        - us-east-1a
        - us-east-1b
      # OPTIONAL: If you would like a smaller set of IPs used for endpoints this will over-ride the /22 default.
      endpointMask: 24
      # REQUIRED: this refers to a text file in the 'config' directory that contains your list of interface endpoints you wish to use.
      # Copy the samples.  The file should end with -region.txt ie: endpointlist-us-east-1.txt is what the value below would require.
      # These are the list of available endpoints to build and share with our VPCs.
      endpointConfigFile: endpointlist
      # REQUIRED: All providers are Transit Gateway attached in our model.  This is the name of the transit gateway to attach to.
      # it must exist with the same name in the transitGateways section.
      useTransit: central
      # REQUIRED: Service Interface Endpoint Style
      style: serviceInterfaceEndpoint
    # style: 'route53ResolverEndpoint' - provides Route53 resolver inbound/outbound endpoints to assist with name resolution from on premises.
    centralRoute53Resolvers:
      # REQUIRED: This VPC will create (per availability zone) A Transit Gateway subnet of /28.  A Resolver Interface Subnet of /28.
      # So in a three AZ deployment you will need a /25 VPC Cidr provided.  Adjust up or down to suit your AZ preferences
      vpcCidr: 10.12.0.0/25
      # OPTIONAL - A list of availability zones to deploy to which over-rides the global: section.
      availabilityZones:
        - us-east-1a
        - us-east-1b
      # OPTIONAL: This will create an 'inbound' Route53 resolver that will resolve cloud-based / route53 based name records for the
      # IP addresses specified.  The IP addresses here should match your on-prem environment DNS forwarders.
      resolveRequestsFromCidrs:
        - 172.31.0.0/16
      # OPTIONAL: This will create an 'outbound' Route53 resolver that will forward requests for the domains specified to the IP address
      # specified.  The domain list should match your on-premesis resolve domains, and the Ips specified should match your on prem
      # DNS servers that can provide resolution for the specified domains.
      forwardRequests:
        forDomains:
          # One or many domains to forward to the IP Addresses below.
          - onprem.example.com
        toIps:
          # IP Addresses that can provide authoritative name resolution for the domains above.
          - 172.31.1.2
      # REQUIRED: All providers are Transit Gateway attached in our model.  This is the name of the transit gateway to attach to.
      # it must exist with the same name in the transitGateways section.
      useTransit: central
      # REQUIRED: Route 53 Resolver Endpoint Style
      style: route53ResolverEndpoint
  # OPTIONAL: The endpoint provider.  This provider provides centralized interVPC inspection services.
  firewall:
    # REQUIRED: the name of the interface provider.  This must be unique within the config file.  It is referred to by the VPCs and Transit routes
    awsNetworkFirewall:
      # REQUIRED: This VPC will create (per availability zone) a Transit Gateway subnet of /28.  A Firewall subnet of /28.  For three AZs
      # a /25 should suffice.
      vpcCidr: 10.3.1.0/25
      # OPTIONAL - A list of availability zones to deploy to which over-rides the global: section.
      availabilityZones:
        - us-east-1a
        - us-east-1b
      # REQUIRED: The name of the AWS Network Firewall that will be provisioned.  No spaces!
      firewallName: centralFirewall
      # REQUIRED: The description of the AWS Network Firewall that will be provisioned.  Spaces are fine!
      firewallDescription: Central Firewall for Inspection
      # OPTIONAL: If you already have ane existing Firewall Rule ARN, or are sharing rules among many firewalls add that here.
      # NOTE: If this is not specified a new Policy Rule set is created.
      awsFirewallExistingRuleArn: arn:firewall:123451
      # REQUIRED: Currently only awsNetworkFirewall is available.  More to come, and maybe some GLB + appliance ones?
      style: awsNetworkFirewall
      # REQUIRED: All providers are Transit Gateway attached in our model.  This is the name of the transit gateway to attach to.
      # it must exist with the same name in the transitGateways section.
      useTransit: central

# OPTIONAL:  These define Transit Gateway attached VPN connections that we can route to.  Many can be defined, then advertise the
# same routes and use ECMP to increase the bandwidth of our VPN connectivity from ground.
vpns:
  toGroundDataCenterOne:
    # OPTIONAL|DEPENDANT: If an existing customer gatewayID has been defined, place its ID here.  It should start with cgw-
    #existingCustomerGatewayId: cgw-128313
    # NOTE: 'existingCustomerGatewayId' is commented so we can actually deploy this config as-is.  Use it if you need, but not specify the new* below if you do.
    # OPTIONAL|DEPENDANT: If you don't specify an existing customer gateway one will be created for you.
    # This specifies the IP Address (the internet Egress IP address the on-premises equipment uses to establish VPN).
    newCustomerGatewayIp: 1.2.3.4
    # This specifies the BGP ASN for the on-prem equipment
    newCustomerGatewayAsn: 60123
    # This specifies the name to use for the on-prem equipment gateway.
    newCustomerGatewayName: Rack10DCVirginia
    # OPTIONAL: Amazon typically chooses the inside tunnel CIDR addresses automatically.  Where it's desirable to set them yourself you can.
    tunnelOneOptions:
      # OPTIONAL: Take note of the valid ranges and restrictions:
      # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-vpnconnection-vpntunneloptionsspecification.html#cfn-ec2-vpnconnection-vpntunneloptionsspecification-tunnelinsidecidr
      tunnelInsideCidr: 169.254.10.0/30
    # OPTIONAL Same as above but for tunnel two
    tunnelTwoOptions:
      # OPTIONAL Same as above but for tunnel two
      tunnelInsideCidr: 169.254.11.0/30
    # OPTIONAL | DEPENDANT: You may import an existing VPN however you must have the vpn ID, Transit Gateway Attach ID, and a Transit Gateway Route Table already created
    # OPTIONAL: Existing Transit Gateway Attached Site to Site VPN.  Must begin with 'vpc-'
    existingVpnConnectionId: vpc-1234
    # OPTIONAL: Existing Transit Gateway Attachment ID for the VPN.  Must begin with 'tgw-attach-'
    existingVpnTransitGatewayAttachId: tgw-attach-1234
    # OPTIONAL: Existing Transit Gateway Route Table associated with the VPN.  Must begin with 'tgw-rtb-'
    existingVpnTransitGatewayRouteTableId: tgw-rtb-1234
    # Currently, only transitGatewayAttached is available using Amazons Managed VPN.
    style: transitGatewayAttached
    # REQUIRED: VPNs are Transit Gateway attached in our model.  This is the name of the transit gateway to attach to.
    # it must exist with the same name in the transitGateways section.
    useTransit: central

# OPTIONAL:  These define an EXISTING Direct Connect Gateway attached to an EXISTING Transit Gateway
# The Transit Gateway must be the same one you define under `transitGateways`.
# When creating the Transit Gateway using vpcBuilder:
# 1) Deploy the transit Gateway without modelling the `dxgws:`.
# 2) Attach Direct Connect Gateway to the Transit Gateway deployed in 1)
# 3) Create a Transit Gateway Route Table and associate it with the Direct Connect Gateway
# 4) Model the `dxgws:` section below with the Transit Gateway ID, Route Table ID, and Attachment ID from above
# 5) Refer to the dxgw in `routesTo:` sections in you Transit Gateway Below
dxgws:
  toGroundDataCentersDx:
    # 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
    existingDxGwTransitGatewayAttachId: tgw-attach-12345
    # REQUIRED: Existing Transit Gateway Route Table associated with the Direct Connect Gateway
    existingDxGwTransitGatewayRouteTableId: tgw-rtb-12345

# OPTIONAL:  These define EXISTING Transit Gateway Peers attached to an EXISTING Transit Gateway
# The Transit Gateway must be the same one you define under `transitGateways`.
# When creating the Transit Gateway using vpcBuilder:
# 1) Deploy the transit Gateway without modelling the `tgwPeers:`.
# 2) Attach / Accept the Transit Gateway Peer to the Transit Gateway deployed in 1)
# 3) Create a Transit Gateway Route Table and associate it with the Transit Gateway Peer
# 4) Model the `tgwPeers:` section below with the Transit Gateway ID, Route Table ID, and Attachment ID from above
# 5) Refer to the tgwPeers in `routesTo:` sections (static and default are supported) in your Transit Gateway Below
tgwPeers:
  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

# OPTIONAL|DEPENDANT.  If any VPCs refer to, providers are defined, or VPNs are defined, this section is required.
# this describes the transit gateways to create (NOTE: at-present we only support one per config file).
transitGateways:
  # REQUIRED: the name of the transit gateway.  This must be unique within the config file.  It is referred to by the VPCs and Transit routes
  central:
    # REQUIRED: Currently, only transitGateway is available which should be fine for most needs.
    style: transitGateway
    # REQUIRED: Description for the Transit gateway (spaces are fine)
    tgwDescription: Central Transit Gateway
    # OPTIONAL: If you wish to us an existing Transit Gateway specify the identifier of the existing  gateway here.  This must start with 'tgw-'
    useExistingTgwId: tgw-1234
    # NOTE: **Return routes are automatically provisioned without you needing to declare them specifically**
    # OPTIONAL: Default routes.  These will send all traffic without a more specific route to these connections.
    defaultRoutes:
        # REQUIRED: The name of the thing we're routing from.  This can be a VPC, or a Provider name.
      - vpcName: workload
        # REQUIRED: The name of the thing we're routing toward.  This can be a VPC, VPN, DxGw, TgwPeer, or Provider name.
        routesTo: egressViaNat
        # OPTIONAL: If we're going to inspect the traffic.  This must be the name of a firewall provider.  Routes are adjusted automatically
        # to assure it passes through the inspection VPC before arriving at its routesTo and vice versa.
        inspectedBy: awsNetworkFirewall
        # ANOTHER NOTE: We will not automatically create a default route for the Firewall!  So if your pattern requires inspection of a default
        # route - you must specify that here (shown below to under default routes to make it clear)
      # More Lists of Objects supported.
    # OPTIONAL: Dynamic routes.  These are achieved using a 'propagation' between entities.  This allows the transit gateway to manage
    # the CIDR address ranges, so you don't need to.  Just define the relationship and the TGW does the rest.
    dynamicRoutes:
        # REQUIRED: The name of the thing we're routing from.  This can be a VPC, or a Provider name.
      - vpcName: workload
        # REQUIRED: The name of the thing we're routing toward.  This can be a VPC, VPN, DxGw, or Provider name (TgwPeers do not support propagation).
        routesTo: workloadTwo
        # OPTIONAL: The name of the firewall provider to inspect traffic.  Routes adjust automatically.
        # NOTE: inspectedBy is not available for VPN connections with a dynamic route.  Use Static, or Default route instead.
        inspectedBy: awsNetworkFirewall
      # More Lists of Objects supported.
    # OPTIONAL: Static routes.  These create a static entry in the transit route table with associations for return path.
    # Generally Dynamic routes should be preferred.
    staticRoutes:
        # REQUIRED: The name of the thing we're routing from.  This can be a VPC, or a Provider name.
      - vpcName: workload
        # REQUIRED: The name of the thing we're routing toward.  This can be a VPC, VPN, DxGw, TgwPeer or Provider name.
        routesTo: toGroundDataCenterOne
        # REQUIRED: the CIDR address for the static route entry
        staticCidr: 192.168.168.0/24
        # OPTIONAL: The name of the firewall provider to inspect traffic.  Routes adjust automatically.
        inspectedBy: inspectionVpc
      # More Lists of Objects supported.
    # OPTIONAL: A blackhole route on the Transit Gateway essentially means any traffic destined for this CIDR Address will
    # be tossed into the garbage.  Use this when you have some 'must not' rules to enforce.  Ie: Blacklisting all Production
    # CIDR Addresses on your Development VPC is a good idea!  That way traffic can never get there regardless of routing rules.
    blackholeRoutes:
        # REQUIRED: The name of the thing we're setting the blackhole for.  This can be a VPC, or a Provider name.
      - vpcName: workloadTwo
        # REQUIRED: CIDR addresses to discard traffic from OR the name of a VPC from the `vpc:` section above.  When a vpcName
        # is specified the vpcCidr is used from the configuration definition above.
        blackholeCidrs:
        - 192.168.168.0/24
        - workload
        # More blackholeCidrs supported
      # More Lists of Objects supported.