Native Load Balancer (v1)

The native load balancer was created by the Cycle team to provide a fully featured, integrated solution for managing traffic into a Cycle environment. It is a powerful, IPv6 native service that handles ingress traffic, has a built-in web application firewall (WAF), support for proxying, caching, and rule-based redirects, and can operate in TCP, UDP, and HTTP/S modes on a per-port basis. It also supports detailed metric aggregation, custom controller/port configuration, and more.

The native load balancer is essentially a combination load balancer, router, and firewall, all in one.

How The Native Load Balancer Processes Ingress Traffic

1. Traffic is directed from the internet to a container using a LINKED record. The linked record "teaches" the load balancer to route traffic for the specified domain to the specified container.

2. Depending on the ingress port, the traffic will match a controller. If no controllers are specified for that port, the load balancer uses the default controller template to determine how to handle the traffic.

3. The load balancer attempts to match the traffic to a router defined on the controller, depending on the specified criteria. By default, there will be one router that matches all traffic.

4. The router defines what happens to that traffic. By default, it will forward the traffic to the matching container specified on the LINKED record. Native load balancer routers can also be configured to redirect, cache data, or forward/proxy to another destination.

Controllers

The native load balancer's configurations are called controllers, and each controller defines a configuration for a specific port. Controllers can be configured on a per-port basis for advanced routing setups.

Default Controllers

By default, a new native load balancer will come with a few preconfigured controllers.

• Port 80: A controller is configured for port 80 in HTTP mode, which will do a redirect to port 443 for HTTP traffic.
• Port 443: A controller is configured for port 443 in HTTP mode, which will handle TLS traffic.
• Port 1194: A controller is configured for port 1194 in TCP mode, which is the port the environment VPN service runs on.
• Port 8812: A controller is configured for port 8812 in TCP mode, which is used for serving the VPN configuration files for the environment VPN service.
• Controller Template: The controller template is the default configuration used for ports without an explicitly defined controller. Unless customized, it mirrors the configuration for port 443.

Custom Controller Configurations

Configurations can be added or modified to augment load balancer functionality. This isn't necessary for normal functionality, like routing traffic from a LINKED record to a container, but is useful for more advanced use cases, where specific behavior for ingress traffic is desired. Without a custom controller defined for a port, the traffic will follow the default controller template rules.

Controller Modes

Controllers can be configured to handle three kinds of network traffic:

• HTTP: The controller port will accept HTTP traffic. This mode is used for websites and other standard web traffic.
• TCP: The controller port will accept raw TCP traffic. This mode is used for custom protocols, sockets, and situations where the destination needs to work with raw net traffic.
• UDP: The controller port will accept raw UDP traffic. This mode is used for traffic that doesn't need confirmation of receipt, such as game servers.

This flexibility enables many different kinds of workloads to run on the platform.

Controller TLS

If a controller has the TLS flag enabled, it can only accept TLS encrypted traffic over that port. Any LINKED record that will match this controller must have generated a TLS certificate.

The load balancer will automatically decrypt TLS traffic and forward it to the container unencrypted (known as TLS termination). TLS encryption works for both TCP and HTTP modes.

For more advanced use cases, custom TLS settings can be configured on a per-router basis (such as mTLS).

Controller Logging

Load balancer logs are available the same as any other container instance on the platform. Each controller can define its own logging verbosity, which can be useful for identifying issues related to routing, or to provide to the Cycle team for troubleshooting. Log levels range from low to debug. Higher levels of logging come with a minor performance penalty.

Routers

Controllers contain custom routers - order-based rules for processing traffic that matches a controller. Routers dictate what the load balancer does to traffic that matches the controller. The order of routers matters, and the first match has priority.

Router Modes

Routers also define the algorithm for how traffic is routed to container instances (known as the mode).

There are currently two supported modes:

• Round Robin: The load balancer will send each request to the next instance in the list, starting over once the end of the list is reached (all instances received a request).
• Random: The load balancer will pick a random instance of the container to send traffic to.

Router Matches

Routers can match on one or a combination of domain, internal (container) port, and path. In addition, containers within the environment can be explicitly included or excluded from the match, enabling a single domain to support multiple containers based on path/port etc.

Router Extensions

Each controller mode (HTTP, TCP, UDP) has different extensions that define how the router handles traffic. Currently, only HTTP routers are configurable. The following sections refer to extensions for HTTP routers only.

Redirect Extension

The router can be configured to redirect matching traffic automatically. The load balancer will return a 308 Permanent Redirect and route to the specified destination. This is the default router configuration for port 80.

For more details on possible options, see the portal documentation.

Forward Extension

The forward extension defines how traffic is forwarded to containers within the environment. This is the default configuration for all ports - the traffic is forwarded to the container matching the LINKED record.

Forwards can be configured to change the scheme, or to target a specific endpoint at the matched container. For more details, see the portal documentation.

Proxy Extension

The proxy extension allows the router to forward traffic to an external domain, and in addition, can modify the response from the destination before returning to the requestor.

For more details, see the portal documentation.

Cache Extension

The cache extension enables the router to cache and store responses from the destination locally on the load balancer, and given identical criteria, return that response without contacting the destination again. This is used to speed up responses for requests where the content does not often change.

Caches can be configured to match specific files using regex, with custom TTLs.

For more details, see the portal documentation.

Router TLS & mTLS

More advanced TLS configuration can be configured on a per-router basis. The load balancer supports options for allowing insecure certificates for debugging, and client authorization for mTLS.

For more details, see the portal documentation.

Web Application Firewall (WAF)

Another major responsibility of the load balancer is acting as a web application firewall, or WAF. The WAF is a security system that uses a set of rules to filter and monitor HTTP traffic between the internet and the containers running within the load balancer's environment.

The native load balancer WAF matches traffic against IP, URL, and HTTP method (GET, POST, etc.), and can act as a blocklist or allowlist depending on the rule. Any traffic that fails to match a rule that allows access will be denied before ever reaching the destination.

A common use of a WAF would be denying access to certain services that are not on a company VPN.

While Cycle's WAF is new and missing some features of more mature WAFs, more powerful features are planned and being implemented. If there is a specific use-case that isn't being met, don't hesitate to reach out to our team.

• Portal

  Configure the WAF using the Portal

Troubleshooting

For troubleshooting traffic that should be going to a container, the easiest way to diagnose the issue is to utilize the public network chart on the container dashboard of the destination container. The chart diagnoses issues in real time for publically accessible containers and can provide more details on potential issues.

There are a few things to always keep in mind when configuring a container for network access:

• All containers should bind to IPv6 (::). By default, environments do not support IPv4 on the private network. While legacy mode is available, it is not recommended, and unless absolutely necessary, containers should be updated to utilize the IPv6 network instead of changing the environment to support IPv4.
• For public internet access, a container must have a LINKED record pointed to it.
• If utilizing TLS, the load balancer will automatically decrypt traffic and forward it to the container unencrypted. This means that for a container to receive unencrypted traffic over i.e. port 80, the ports should be configured as 443:80, where 443 is the ingress port on the load balancer (handled by a TLS enabled controller), and 80 is the open port on the container.

For all other load balancer related issues, be sure to enable Debug logging, and review the load balancer's output in the instance console.

Get Started with the Native Load Balancer on Cycle

Follow one of our interface-specific guides to set up and customize the native load balancer on Cycle:

• Portal
• API