Home

Virtual Private Cloud

Create and manage VPCs

Overview

Cumulus makes configuring Virtual Private Clouds simpler. Easily configure VPCs, route table definitions, subnets, and network acls. Read the following sections to learn about configuring your VPCs with Cumulus. Example configuration can be found in the Cumulus repo.

Virtual Private Cloud

Each VPC is defined in its own file where the file name is the name of the VPC. These files are located in a configurable folder. VPCs are JSON objects with the following attributes:

Here is an example of a VPC configuration:

{
  "cidr-block": "10.0.0.0/16",
  "tenancy": "default",
  "dhcp": {
    "domain-name-servers": [
      "AmazonProvidedDNS"
    ],
    "domain-name": "ec2.internal"
  },
  "route-tables": [
    "route-table-1",
    "route-table-2"
  ],
  "endpoints": [
    {
      "service-name": "com.amazonaws.us-east-1.s3",
      "policy": null,
      "route-tables": [
        "route-table-1"
      ]
    }
  ],
  "address-associations": {
    "50.20.50.160": "eni-abc123"
  },
  "network-acls": [
    "network-acl-1"
  ],
  "subnets": [
    "subnet-1"
  ],
  "tags": {
    "Name": "vpc-1"
  }
}

Route Tables

In Cumulus, route tables are configured in separate files from the VPC config to keep the VPC config simple for higher level changes. Route table configurations are stored in a configurable directory for route tables. A route table has the following properties:

Here is an example of a route table with two routes that excludes routes with the address "0.0.0.0/0"

{
  "routes": [
    {
      "dest-cidr": "10.3.0.0/16",
      "gateway-id": "vgw-abc123"
    },
    {
      "dest-cidr": "10.0.0.0/0",
      "network-interface-id": "eni-abc123"
    }
  ],
  "propagate-vgws": ["vgw-abc123"],
  "tags": {
    "Name": "route-table-1"
  },
  "exclude-cidr-blocks": [
    "0.0.0.0/0"
  ]
}

Endpoint Policies

The EC2 API requires you to specify a policy when configuring a service endpoint. These policies are in the same format as IAM policies and are stored in a configurable policies directory

Here is an example of the current default policy used for service endpoints which allows all access to the service

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "*",
      "Resource": "*"
    }
  ]
}

For more information see the IAM module

Network ACLs

Network ACLs provide an optional layer of security for the instances in your VPC. In Cumulus, network acls are configured in separate files from the VPC config to keep the VPC config simple for higher level changes. Network ACL configurations are stored in a configurable directory for network acls. A Network ACL has the following properties:

Here is an example of a Network ACL Configuration:

{
  "inbound": [
    {
      "rule": 100,
      "protocol": "icmp",
      "action": "allow",
      "cidr-block": "10.1.0.0/16",
      "icmp-type": -1,
      "icmp-code": -1
    },
    {
      "rule": 200,
      "protocol": "tcp",
      "action": "allow",
      "cidr-block": "10.2.0.0/16",
      "ports": "8000-8080"
    },
    {
      "rule": 300,
      "protocol": "all",
      "action": "deny",
      "cidr-block": "0.0.0.0/0"
    }
  ],
  "outbound": [
    {
      "rule": 300,
      "protocol": "all",
      "action": "deny",
      "cidr-block": "0.0.0.0/0"
    }
  ],
  "tags": {
    "Name": "network-acl-1"
  }
}

Subnets

In Cumulus, subnets are configured in separate files from the VPC config to keep the VPC config simple for higher level changes. Subnet configurations are stored in a configurable subnets directory. A subnet has the following properties:

Here is an example of a subnet configuration

{
  "cidr-block": "10.0.0.0/16",
  "map-public-ip": true,
  "route-table": "route-table-1",
  "network-acl": "network-acl-1",
  "availability-zone": "us-east-1e",
  "tags": {
    "Name": "subnet-1"
  }
}

Diffing and Syncing VPCs

Cumulus’s VPC module has the following usage:

cumulus vpc [diff|help|list|migrate|sync|rename] <asset>

VPCs can be diffed, listed, and synced (migration is covered in the following section, and renaming is covered in a later section). The three actions do the following:

Migration

If your environment is anything like ours, you have dozens of VPCs, route tables, and subnets and would rather not write Cumulus configuration for them by hand. Luckily, Cumulus provides a migrate command that will pull down the needed configuration from AWS and save them to the local file system.

cumulus vpc migrate

This command will migrate all of the VPC configurations from AWS into identical local json versions in the vpc/vpcs directory, each named with the VPC name or id. Any route tables defined on the VPC will be migrated into vpc/route-tables and named with the route table name or id. Similarly, network acls and subnets will be migrated into the vpc/network-acls and vpc/subnets directories and named with network acl name or id and subnet name or id, respectively. Finally, endpoint policies that are attached to VPC endpoints will be migrated to vpc/policies and named with the Version of the policy.

After migration, you will notice that network acls will have a Name tag added to their tags (if there was not one previously) with the id of the Network ACL as the value. This is because we prefer to refer to network acls from Subnet config (instead of referring to subnets from ACL config) and need a way to identify a Network ACL besides its ID. We suggest using the rename command to update the name of migrated network acls and other assets to be more descriptive.

Renaming Assets

The VPC module provides a rename commmand to easily update the names of the various assets needed to manage a vpc. The rename command can be used as follows:

cumulus vpc rename [network-acl|policy|route-table|subnet|vpc] <old-asset-name> <new-asset-name>

Renaming an asset does 3 things:

  1. The file name of the asset is updated to the new name
  2. The value of the "Name" tag is updated with the new name (or created if it did not exist)
  3. All references in other assets using the old name are updated to the new name, and affected files are saved again

Configuration

Cumulus reads configuration from a configuration file, conf/configuration.json (the location of this file can also be specified by running cumulus with the --config option). The values in configuration.json can be changed to customized to change some of Cumulus’s behavior. The following is a list of the values in configuration.json that pertain to the VPC module:

➜