Home

Elastic Load Balancing

Create and manage Elastic Load Balancers

Overview

Cumulus makes configuring Elastic Load Balancers simpler. Easily configure load balancers, listeners, and policies. Read the following sections to learn about configuring your load balancers with Cumulus. Example configuration can be found in the Cumulus repo.

Load Balancer Definition

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

Here is an example of a load balancer with all options configured:

{
  "listeners": {
    "includes": [
      {
         "template": "example-listener",
         "vars": {
            "ssl-cert": "value"
         }
      }
    ],
    "inlines": [
      {
        "load-balancer-protocol": "HTTP",
        "load-balancer-port": 80,
        "instance-protocol": "HTTP",
        "instance-port": 9001,
        "policies": ["ExampleCustomPolicy"]
      }
    ]
  },
  "subnets": [
    "named-subnet-1",
    "subnet-1111111a"
  ],
  "security-groups": [
    "SecurityGroup1"
  ],
  "internal": true,
  "tags": {
    "tag-name": "tag-value"
  },
  "manage-instances": [
    "instance-id-1"
  ],
  "health-check": {
    "target": "HTTP:80/healthcheck.php",
    "interval": 10,
    "timeout": 8,
    "healthy": 2,
    "unhealthy": 5
  },
  "backend-policies": [
    {
      "port": 9001,
      "policies": ["ExampleCustomPolicy"]
    }
  ],
  "cross-zone": true,
  "access-log": {
    "s3-bucket": "my-bucket",
    "emit-interval": 5,
    "bucket-prefix": ""
  },
  "connection-draining": 100,
  "idle-timeout": 200
}

Listeners

In Cumulus listeners can be configured on a load balancer using templates or inline. The configurations are identical, except that templates can have variables in the form of {variable-name} that will be overriden by the "vars" property in the load balancer config. Listener templates are stored in a configurable listeners directory. A listener has the following properties:

Here is an example of a listener template that routes HTTPS traffic and the ssl certificate id is a variable:

{
  "load-balancer-protocol": "HTTPS",
  "load-balancer-port": 443,
  "instance-protocol": "HTTPS",
  "instance-port": 443,
  "ssl-certificate-id": "{{ssl-cert}}",
  "policies": ["ExampleSecurityPolicy"]
}

Policies

The AWS API for load balancer policies is very limiting. There is a set of default policies that can be set on listeners and backend servers when creating a load balancer from the web interface that are not allowed to be used in the API. Cumulus works around this by requiring policies on an already-created load balancer to either be defined locally, already created for the load balancer in AWS, or in the set of default policies provided by AWS. When creating new load balancers with Cumulus, all policies must be locally configured. When migrating policies will automatically be migrated with load balancers so that they can be managed by Cumulus. A local version of the list of default policies can also be obtained using migration.

A local policy configuration will have a file name that is the same as the policy name and has the following properties:

Here is an example of a policy that enables ProxyProtocol:

{
  "type": "ProxyProtocolPolicyType",
  "attributes": {
    "ProxyProtocol": "True"
  }
}

For detailed information on policies see AWS Documentation

Diffing and Syncing Load Balancers

Cumulus’s ELB module has the following usage:

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

Load balancers can be diffed, listed, and synced (migration is covered in the following section). The three actions do the following:

Unlike Cumulus’ other modules, when syncing with the ELB module a bad configuration can put your load balancers in a bad state because of the ELB API’s inability to perform updates transactionally. To combat this, we will attempt to rollback to a more stable configuration if any of the following properties fail to sync:

Any time a rollback is required, it will be printed in the console with a message explaining what happened. Doing another diff to figure out which attributes were or were not updated is recommended, followed by properly configuring the load balancer and syncing again.

Migration

If your environment is anything like ours, you have dozens of load balancers, and would rather not write Cumulus configuration for them by hand. Luckily, Cumulus provides a set of migrate tasks that will pull down your load balancers and produce configuration for them.

cumulus elb migrate default-policies

This command will migrate all of the default policies from AWS into identical local json versions in the elb-default-policies directory, each named Cumulus-<PolicyName>.json. This is necessary if you want to change the security policy of migrated load balancers to one of the other default policies or create a load balancer using the default policies because the ELB API does not allow you to update using the default-named policies.

cumulus elb migrate elbs

This command will migrate all of your load balancers from AWS to local configuration in the elb-load-balancers directory. As load balancers are migrated, any non-default policies defined on a load balancer will be migrated to the elb-policies directory.

After migration you should copy the policies in elb-default-policies and elb-policies to the configurable policies directory so that diffing and syncing will be able to read the policy definitions.

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 ELB module:

➜