Load Balancer

Cycle provides powerful, automatic load balancing to every environment.

How It Works

The load balancer container is an instance (or instances) of HAProxy that Cycle will automatically configure and run. Every environment gets its own load balancer container, and will start when a container with a network mode set to "enable" is started. The load balancer receives the public IP assigned to the environment, and all containers are run behind it using private IPs.

Port Forwarding

By configuring and exposing ports on your containers, the load balancer will automatically update to reflect your changes. For example, if a container has a port configuration of 8888, the load balancer will accept traffic for the container on it's public IP over port 8888, and route it over the private network to the container on the same port. If you set up port mapping, such as 8888:3000, the load balancer will accept traffic over port 8888 publicly, and route it over the private network to your container on port 3000.

Binding To An IP

In order to receive data, your container will need to bind to an IP address. By default, Cycle will only use IPv6 to send data behind the load balancer. If your application requires IPv4 bind capabilities, you must enable Legacy Mode.

Each provider gives a different amount of IPv6 addresses for your load balancer. While both Packet and Vultr give a /121 (128 IPs), AWS provides a single address /128.

It is highly recommended if running in legacy mode to bind to both IPv6 and IPv4. You can do this by passing ::80 to your application.

Special Headers

Cycle load balancers are configured to pass along the following special headers.

HeaderPossible Return ValuesDescription
X-Forwarded-ProtoHTTP, HTTPS Information about the protocol of the incoming traffic.
X-Forwarded-PortAny port The port that received the traffic on the load balancer.
X-Cycle-Listening-HTTPSyes, no Carries a yes if the load balancer is currently listening for traffic on HTTPS.

Running Multiple Public Sites In The Same Environment

Containers exposing port 80 are automatically configured on the load balancer to run in "HTTP" mode, allowing a single environment to expose multiple public sites behind the same IP. To take advantage of this, you'll need to have a LINKEDrecord configured via Cycle DNS to point to the container. Everything else is handled automatically. Cycle will route traffic to the load balancer in front of the specified container, and the load balancer will route traffic to the appropriate container. Any time you update or change your LINKED record, the load balancer will be updated to reflect your changes automatically.

SSL Termination

The load balancer will do automatic SSL termination for any container that has a LINKED record pointed at it with SSL certificate generation turned on. This means your containers never worry about SSL certificates or encrypted web traffic if they are serving over port 80, and provides benefits such as faster load times and increased volume of simultaneous connections.

If you are using a LINKED record with automatic SSL generation, your container should only expose and bind to port 80, as all decrypted web traffic will be sent to your container over that port.

Configuring The Load Balancer - Ingress

The load balancer is configurable directly from the interface. You are able to adjust modes, create specific port configurations, and override timeout settings with ease.

  1. Click the Environments link in the navigation menu to the left.
  2. Select the environment who's load balancer you wish to configure from the list.
  3. Click the "Load Balancer" tab at the top of the page.
  4. Enable "Custom Config" by toggling the switch in the upper right hand corner of the form. This will allow you to override the Cycle defaults with custom settings. Disabling custom config after updating the load balancer will cause it to revert back to Cycle's default config and your settings may be lost!

Default Config

The load balancer comes with a "default config", which is how it treats all ports (that aren't 80 or customized otherwise). These settings will be applied to all ports that aren't explicitly defined in this configuration. The mode cannot be changed for the default config.

Frontend Options

Frontend configuration options are related to how inbound traffic is treated.

  • Mode
    • TCP - Traffic is forwarded without any parsing or additional manipulation
    • HTTP - Traffic is treated as web traffic. If a LINKED record is configured for a container exposing this port, the domain will be parsed and it will be forwarded to the proper container. This allows multiple services to run on port 80 in the same environment.
  • Max Connections - The number of simultaneous connections that can be processed at a time.
  • Client Timeout - The number of seconds the load balancer will wait for a response from a client before disconnecting.
  • Client Finish Timeout - The number of milliseconds the load balancer will wait for a client to send it data when one direction is already closed. This is particularly useful to avoid keeping connections in a waiting state for too long when clients do not disconnect cleanly.
  • HTTP Keep Alive [HTTP mode only] - The number of milliseconds the load balancer will wait for a new HTTP request to start coming after a response was set. See the HAProxy Docs for more information.
  • HTTP Request Timeout [HTTP mode only] - The number of milliseconds the load balancer will wait for a complete HTTP request. See the HAProxy Docs for more information.

Backend Options

Backend configuration options are related to how the load balancer handles and routes connections

  • Balance - How connections are balanced across your container instances
    • Round Robin - Each container instance is used in turns.
    • Static Round Robin - Each container instance is used in turns, but is faster than Round Robin at the expense of being less dynamic.
    • Least Connection - Routes traffic to the instance with the least number of active connections.
    • First - Routes traffic to the first available instance.
    • Source - The same client IP always reaches the same container instance as long as no instance goes down or up.
  • Server Request Timeout - The number of seconds the load balancer will wait for a response from the container instance. See the HAProxy Docs for more information.
  • Server Finish Timeout - The number of milliseconds the load balancer will wait for the server to send data when one direction is already closed. See the HAProxy Docs for more information.
  • Server Finish Timeout - The number of milliseconds the load balancer will wait for a successful connection to a container instance. See the HAProxy Docs for more information.
  • Queue Timeout - The number of milliseconds the load balancer will hold connections in a queue when the maximum number of connections has been reached. See the HAProxy Docs for more information.
  • Tunnel Timeout - The number of milliseconds the load balancer will allow for inactivity on a bidirectional tunnel. See the HAProxy Docs for more information.

Configuring The Load Balancer - Egress

To describe how you would like egress traffic to leave the container and be handled by the load balancer, configurations will need to be made to the egress section of the load balancer. To handle these settings a new gateway needs to be made. That gateway will have a name, ports, and a destination.

Options

  • Name - Naming the gateway is straightforward. If there is a need for many egress gateways, give each gateway a meaningful name.
  • Ports - This is the port combination for egress traffic. So this port description would be the opposite way that would normally be set. The first number is the port "from" the container and the second would be the port on the load balancer that is being targeted.
  • Destination - A url where the load balancer will send the traffic.

Updating or Deleting a Gateway

Once the gateway has been created, the information can be changed and updated or even deleted.

Updating a gateway is as simple as typing a new value in the field and then clicking Update Gateways. If there is a new port or destination and the old port or destination is no longer valid click the x next to the invalid port or destination.

To delete a gateway, make sure the correct gateway is highlighted from the list by clicking on it and then click Delete Gateway.

Troubleshooting

Need Help?

If you've got questions about the platform or need some help getting started, our team is more than happy to assist. Whether you're new to containers or just new to Cycle, reach out to us via livechat by clicking the blue circle in the bottom right corner. Join our Slack channel, and get help from the dev team or other members of the community, and check out our Roadmap to see what's planned for the future!