Note: With the introduction of Application Load Balancers, Amazon have rebranded Elastic Load Balancers as Classic Load Balancers, a change which has also been reflected in the Engine Yard dashboard. Previous versions of this document referred to Elastic Load Balancers (ELBs) as the name of the specific load balancing devices rather than Amazon's general load balancing service, and Classic Load Balancers may still be referred to as ELBs in places.

Introduction

The default load balancing tool on Engine Yard Cloud is HAProxy running on the Application Master Instance. If advanced load balancing is required Amazon Load Balancers can be deployed, at additional cost.

Deploying an Amazon Load Balancer into your Engine Yard environment(s) allows you to make use of Amazon's Elastic Load Balancing service with your AWS environments.

Classic Load Balancers are Amazon's previous generation load balancers, offering a simpler setup but less configuration options than the newer Application Load Balancers. Classic Load Balancers also support EC2-Classic, whilst Application Load Balancers require a VPC. For a comparison of Application and Classic Load Balancers, please see this blog post.

Classic Load Balancing distributes requests to multiple instances (servers) across multiple AWS availability zones (AZs) in order to distribute traffic evenly across all instances, keeping the instances as evenly loaded as possible. Classic Load Balancers exist in all AZs where attached instances reside, so if an entire AZ goes offline the CLB continues to function, routing traffic to instances in the remaining AZs. Engine Yard provisioned CLBs use cross-zone load balancing, which allows each load balancer node to route requests across availability zones. This means requests will not be sent to an already over-loaded availability zone. However, it is still recommended practice to distribute instances evenly across all available AZs. The health of instances registered with the load balancer is also monitored and requests are sent only to the healthy instances. If an instance becomes unhealthy, the CLB stops sending traffic to that instance and spreads the traffic across the remaining healthy instances.

Note: Only load balancers added after June 11, 2014 will have the cross-zone load balancing behaviour, those added prior will use a round-robin method to decide the AZ for the request, then route requests only to instances in that AZ. If you have an old load balancer then Support can check and update this setting for you upon request.

Utilising an Amazon Classic Load Balancer has the following advantages:

It takes some of the load off the Application Master (which, by default, balances traffic across all instances using HAProxy).
It reveals the client's IP address for HTTPS connections (with HAProxy, the client's IP is seen as the Application Master IP unless stunnel is utilised).
It allows an environment running multiple apps with SSL to easily have multiple certificates. Other options are available if this is required, please contact Support to discuss your requirements.

Get started with Classic Load Balancing

This document describes how to use Classic Load Balancing on Engine Yard Cloud:

Add a load balancer
Add an SSL certificate for a load balancer
Activate a load balancer
Verify a load balancer
Move a load balancer
Delete a load balancer
FAQs

Add a load balancer

You need to name your load balancer and decide on the SSL configuration.

Note: You can create up to 10 elastic load balancers per region. If you need more than this, contact Engine Yard Support.

To add a load balancer

On the dashboard, click Classic Load Balancers in the main Tools menu.

The Load Balancers page displays.
Click the Add Classic Load Balancer button.
Select the Account (if applicable) and Environment the CLB will be used with.
Enter the CLB name (only letters, numbers and hypens) and the other corresponding fields.
Confirm the Location has correctly automatically set for the selected Environment.
Determine the SSL configuration that you need.

Select if and how to terminate SSL:

Disabled - The ELB does not respond to SSL requests.
AppServer - This is an SSL pass-through method, where the ELB acts as a TCP proxy, passing SSL requests through to the app instances still encrypted (which then use existing mechanisms for SSL decryption).
Load Balancer - The CLB itself decrypts requests. By default decrypted traffic is passed through to the app instances, though traffic can be re-encrypted before being passed to the instances (this is usually unnecessary and only required for compliance reasons). Load Balancer terminated SSL requires an SSL certificate to be uploaded via the Dashboard's SSL Certificates page and selected in the Certificate dropdown.

Set a Health Check Path - this is dependent on the Health Check Protocol. For HTTP and HTTPS checks a 200 response will be required from the Path, otherwise the instances will be seen as unhealthy. For TCP and SSL checks this Path is not required to be set.

Leave the Health Check Port unless you require a custom port, otherwise it will default to the selected protocol port upon form submission.

Set a Health Check Protocol - if this is set to HTTP or HTTPS then a valid Health Check Path must be set, as above. If the protocol is set to TCP or SSL then the instance just needs to respond to pings to pass the health check.

Note: A HTTP(S) health check is recommended, using a path that makes a database call. With such a check you are ensuring a holistic check of the instance and application, rather than just ensuring the instance is pinging, thus reducing the chances of requests being directed to a failing instance.

Click Create Classic Load Balancer. It may take a few minutes to create the load balancer, refreshing the page will show you the updating progress.

If you are ready to activate your load balancer, see Activate a load balancer.

Add an SSL certificate for a load balancer

Note: There is a limit of 20 SSL certificates per region, per account. If you need more than this, contact Engine Yard Support.

To add an SSL certificate to your Engine Yard account, you need your key file; the CRT file from your vendor; and, if your vendor provided one, the certificate chain file. See obtain and install SSL certificates for more information.

To add an SSL certificate

If you are not on the SSL Certificates page:

a. From the dashboard, click Tools -> SSL Certificates on the toolbar.

The SSL Certificates page appears.

b. Click Add SSL Certificate (under the required Account if you have more than one).

The Create New SSL Certificate page appears.
Enter a name in the SSL Certificate Name field.
Select the Upload SSL Certificate option.
In the SSL Certificate text box, paste the contents of the CRT file.
In the SSL Certificate Key text box, paste the SSL Certificate Key.
If you have a certificate chain file, paste it into the SSL Certificate Chain field.
Click Add Certificate.

Engine Yard Cloud uploads your SSL certificate information.

Continue to Activate a load balancer.

Error when Adding SSL Certificates

If you encounter an error message while adding the SSL certificate, it is likely due to the key not using an encoding that is accepted by AWS. You can re-encode the key using the following command (run from any MacOS/Linux/Unix/BSD machine):

openssl rsa -in sslcert.key -out sslcert.new

After you have run this command, you can verify that the new key is compatible with the existing key and certificate file by running the following command over the three files and verifying the modulus is identical:

deploy$ openssl rsa -text -noout -modulus -in sslcert.key | grep Modulus
 Modulus=C0B5265F2DC6147476F1791C81...AE1A71293E64641471F9B1E4A6F
 deploy$ openssl rsa -text -noout -modulus -in sslcert.new | grep Modulus
 Modulus=C0B5265F2DC6147476F1791C81...AE1A71293E64641471F9B1E4A6F
 deploy$ openssl x509 -text -noout -modulus -in sslcert.crt | grep Modulus
 Modulus=C0B5265F2DC6147476F1791C81...AE1A71293E64641471F9B1E4A6F

During one rewrite, we found the original key was 1705 bytes long and the rewrite was 1679 bytes long. The difference came from the hex code, not just spacing or EOL's.

After the rewrite, the certificate was accepted by Amazon.

Test a load balancer

Before directing production traffic to a Classic Load Balancer it is recommended to test it. To test it you can visit it via its public hostname.

In the dashboard, navigate to Tools -> Classic Load Balancers.
Expand out the relative load balancer and find the Hostname.

For example:
```
EYelb-866271027.us-west-2.elb.amazonaws.com
```
Copy the Hostname and paste it into your browser.
If your site redirects to HTTPS you will see a certificate mismatch error, but accept this to view and test your application.
If you see an error page rather than your application, it is likely your instances are failing the health check. This can be confirmed via the AWS Console as per the Monitor a load balancer section. Please check the OutOfService message for the instances and update the Health Check Protocol and Port as appropriate, wait a couple of minutes, then test the URL again. Please contact EY Support for further assistance in correctly configuring the Health Check if required.

Activate a load balancer

To activate the new load balancer, you need to repoint the DNS records for your domain(s).

Note: By default DNS for an application would be configured as an A record pointing to the EIP attached to the Application Master instance. This A record should be replaced with a CNAME record pointing to the Hostname of the ALB. It should be noted that CNAME records are only allowed to be configured against FQDNs, e.g. www.engineyard.com. If you make use of the root domain, e.g engineyard.com, then you must either keep this record as an A record pointing to the EIP (and therefore have the traffic bypass the ALB) or preferably setup an ALIAS record to point the root domain to the ALB's hostname. Not all DNS providers support ALIAS records, so please check with your DNS provider if you have any questions about setting this up.

To activate a load balancer

In the dashboard, navigate to Tools -> Classic Load Balancers.
Find the Hostname for your load balancer; this is the DNS (Domain Name System) name.

For example:
```
EYelb-866271027.us-west-2.elb.amazonaws.com
```
Copy the Hostname.
At your DNS provider, update any records currently pointing to the EIP to point to the CLB Hostname. Please see the above Note with regards to the record types required.
Continue to Verify a load balancer.

Verify a load balancer

To verify the new load balancer and its new DNS name, you can use a simple shell command.

To verify a load balancer

Open a UNIX shell.
Type:
```
dig your.customdomainname.com +short
```
Depending on your DNS configuration, it may return the hostname for the load balancer.

For example:
```
EYelb-866271027.us-west-2.elb.amazonaws.com
```
Or it may return a list of IP addresses. In this case run a dig on the load balancer hostname:
```
dig EYelb-866271027.us-west-2.elb.amazonaws.com +short
```
This will also return a list of IP addresses. The two lists should contain the same IPs.
If the address is still the Environment's EIP you might need to wait for DNS propagation; try again after a few minutes or contact your domain name provider.

Move a load balancer

A load balancer can be moved between environments, re-assigning the instances attached to it. This is useful in the case of an environment migration, negating the need for any updates to the DNS for domains pointing to CLB(s).

Moving load balancers is dependent on the following conditions:

The environments are in the same AWS Region.
The Classic Load Balancer was created under EC2-Classic and both environments run under EC2-Classic.
The Classic Load Balancer was created under the Default-VPC and both environments run under the Default-VPC, regardless of the attachment state of the Network in the EY dashboard.
The Classic Load Balancer was created under a Custom-VPC Network and both environments run under this same VPC.

To move a load balancer

To move an CLB simply expand out the required CLB on the Classic Load Balancers page, change the environment to the required one in the Environment dropdown menu, then click Update. The available environments will be limited by the conditions listed above. This process will detach the current environment's instances from the CLB and attach the new environment's instances. You will see a short period where your application returns a 503 error while no instances are attached to the CLB. Please also ensure that the CLB SSL along with the CLB's specified Health Check Path, Protocol and Port are valid on the new environment.

Important: If moving from a v4 to a v5 environment, the Health Check Port will also need to be updated from 81 to 8081 to compensate for the change in Nginx listening port on the v5 stack.

Delete a load balancer

Before deleting a load balancer, ensure that traffic is no longer being directed to that hostname. You should have configured and verified a replacement load balancer (or use the regular elastic IP method) to serve traffic before removing it.

Warning: Deleting a load balancer can cause a service disruption to any customers connected to the load balancer.

To delete a load balancer

On the dashboard, click Classic Load Balancers in the main Tools menu.
Find the Hostname for your load balancer. For example:
```
EYelb-866271027.us-west-2.elb.amazonaws.com
```
Once you have confirmed that the load balancer is no longer receiving traffic, then you can click Delete next to the load balancer name.
Refresh the page to verify that the load balancer has been deleted.

Monitor a load balancer

You can monitor the state of your Classic Load Balancer via the AWS Console. On the Classic Load Balancers page, expand out the relevant load balancer and click the View this load balancer in the AWS console link. This will provide limited access to the AWS Console, allowing you to review the status of the CLB. Note: No changes can be made here and all configuration updates must be made via the EY Dashboard.

Instances tab - This will list the instances and availability zones attached to the ELB. Each instance has a Status field, with any OutOfService instances stating the reason why. If all instances are out of service then the load balancer will return a 503 error. In most cases the cause of this is a misconfigured Health Check, so please consult Support should you require any assistance.
Monitoring tab - This shows you graphical representations of the CloudWatch statistics for the load balancer, giving you insights into the traffic levels, errors and instance failures.

FAQs

You might have these questions about the Classic Load Balancers.

How do I know that the load balancer is working?

The easiest way to check that a load balancer is working is to visit it. The hostname of the load balancer is listed on the Load Balancers page for an environment. Click the hostname to visit the app; your application should appear.

How can I tell which instances are attached to a load balancer?

All app instances in the environment are automatically added to all load balancers in the environment. If you wish to confirm this please access the AWS Console as per the Monitor a load balancer section.

Can I see the amount of traffic going through a load balancer?

This can be seen via the CloudWatch graphs as per the Monitor a load balancer section.

Are there any health warnings or other health-check stats I can review?

We'd like to offer a status page showing which app instances the load balancer thinks are healthy and unhealthy, but have not released it yet. For now this information can be accessed via the AWS console as per the Monitor a load balancer section.

Can I have multiple SSL certificates on a single environment?

Yes. Each SSL will need its own CLB. Follow the directions above for each SSL you need to use, creating a new CLB for each SSL certificate.

How do I update an expired certificate?

On the Classic Load Balancers page expand the relevant Load Balancer, update the Certificate field to the required SSL and click the Update button. If you make use of custom Provisioned Services you may need to delete these and recreate them with the new certificate - this method will result in a brief downtime between deletion and recreation, so should be done during planned maintenance.

Note: Amazon does not provide a way to update an existing in-use certificate.

How can I change the SSL Protocols and Ciphers offered by the Classic Load Balancer?

The SSL Protocols and Ciphers offered by the CLB are defined by its Security Policy. The Policy is not currently shown or selectable in the EY Dashboard, so please submit a support request if you require to change the Policy. The default Security Policies can be seen in this document, and AWS support custom policies if you require a non-default protocol and/or cipher selection.

Note: The Security Policy in use will be the latest available at the time of creation. If will not automatically update after that, so if you require a later Policy you must request this.

Why are my Classic Load Balancers not balanced?

CLBs use round-robin based on availability zones (AZ), not on instances. This means if your traffic comes from different sources, the total traffic on each AZ should be equal.

Engine Yard CLBs don't use session stickiness, but CLBs still go to a particular AZ because of the way CLBs work. A CLB has one IP address per AZ unless scaling is occurring. With scaling, AWS will have two IP addresses but drain traffic to the old IP address. For example, if you have two IP addresses and users visit your web site, these users will get one of the 2 IP addresses. The first IP address will be cached for 1 minute before they can possibly get to the other IP address.

An alternative is to use a single AZ, but that AZ will be a single point of failure. When you have 8 instances, the total per AZ will be closer to each other, but this won't solve the single IP source issue.

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.

Using Amazon Classic Load Balancers