Configuring the Native Load Balancer

In the portal, the native load balancer is configurable by accessing the load balancer modal in any given environment

To get there:

Environments from the main, left-hand navigation.
Select the environment from the first column.
Scroll down to the services tile, and click on the manage tab of the load balancer.
Select the Controllers page.

Load Balancer Controller Ports

Each port, selectable from the first column, has 4 accessory pages to support it.

Overview

Field	Description
Instance	The load balancer instance.
Data Transfer	Total amount of data received and transmitted.
Connections	Total amount of connections made.
Requests	Total number of requests.
Disconnects	Total number of connections that have ended, with and without error. <br /> destination_unavailable - The intended target container is not reachable from the load balancer. <br /> no_error - The connection ended normally without any errors. <br /> timeout_idle - The connection was closed due to inactivity. <br /> timeout_init - The connection timed out before initialization of the request completed - this is often related to bots scanning for access. <br /> unknown_error - An unexpected error caused the connection to close. <br /> connection_invalid - The inbound client connection was invalid or malformed. <br /> router_none - No router configuration exists for this request. <br /> router_nomatch - No matching route was found for the request. <br /> waf_blocked - The client connection was blocked by the web application firewall.

URLs

Field	Description
Host	The domain and path of the incoming call.
Method	The HTTP method used for the call.
Responses	The number of responses sent on that domain + path.
Handler	Number (total) and type (graphed) of the handler. Example: 2 total, both forwarded.
Average Time	The average time to complete the request.

Routers

Field	Description
Destination	Container destination for the request.
Latency	The latency of the connection between load balancer and destination (measured by ICMP packet).
Requests	The total number of requests.
Connections	Amount of traffic transmitted and received.
Success Rate	Percentage of times the connection was successful.

Config

In the portal, port configuration is done on the config page.

General

The general section has port specific general settings.

Field	Description
Identifier	The identifier is a way for the user to give a resource a name, useful for interacting with the API and CLI after creation.
Ingress Port	The literal ingress port that this configuration pertains to.
Mode	Either TCP, HTTP, or UDP.
Logging Verbosity	This setting determines the verbosity of the logs printed to the instance console; higher settings record more detail.
Idle Timeout	The amount of time of inactivity between either side of the connections before the load balancer drops the connection.
Performance	A toggle for performance mode. When enabled, telemetry is disabled to allocate all resources to load balancer functionality.
TLS Enable	Enables TLS for the given controller.

Controller Routers

Each controller can have N number of routers. Routers are used to set specific functionality on internal ports, paths, or urls. These will execute in order they are defined if specificity is the same. Users can add a router by using the Add Router button and then adding to the configuration with more specific settings. To move routers up and down in priority use the ^ and v arrows, then save.

Each router has its own mode, match, configuration, and extension settings.

Router Mode

Field	Description
Mode	The type of load balancing, either round-robin, source-ip, or random.

Match

Field	Description
Match Domains	An array of domains to match for.
Match Internal Ports	An array of internal ports to match for.
Match Path	A path to match for. Users can submit a static path or a regex.
Include Containers	If a match is made include the following containers (by ID or identifier) in the pool of available downstream connections.
Exclude Containers	If a match is made exclude the following containers (by ID or identifier) in the pool of available downstream connections.

Regex

When entering a regex string into any of the match fields, use the ^ character at the beginning of the string to tell the platform to use the regex engine.

Config

Field	Description
Destination Retries	The number of times the load balancer will retry reaching the intended target for the traffic.
Destination Connection Timeout	The allowed amount of time to establish a connection between the load balancer and a destination container. (per retry)
Destination Prioritization	Hints to the load balancer on how to prioritize traffic to instances. random: Chooses a random instance. latency: Prioritizes lower latency instances. fixed: the order of the destinations will be the same regardless of instance or load balancer location. Used primarily with source IP routing.
Sticky Sessions	Ensures that requests from the same client are routed to the same instance.

Sticky sessions are enabled by default, to turn this off find the controller -> router to change and update the checkbox then save.

For more granular control of sticky sessions in http2 connections, the platform exposes a special header.

Extensions

There are two types of extensions transport and router.

For Router type, the only configurable extension requires HTTP mode.

Router Extension

An HTTP router can have many extensions. Extensions are used to define specific behavior and are configured in the portal through a JSON blob.

Field	Description
redirect	Defines a built-in redirect for HTTP mode routers.
forward	Defines a built-in forwarding scheme for HTTP mode routers.
proxy	Defines proxy settings for the given router.
cache	Defines cache settings for the given router.

If there are any matches to the optional Match Path field they can be assigned to domains or URLs as shown in the following sections examples.

In the below redirect example the url shows https://user-$$1.otherurl.com. This will take the first match from the Match Path field on this router and write it to $$1 as it is defined in the url field.

In the case where Match Domains is set to otherurl.com and Match Path is set to ^/users/([0-9]+), if someone were to visit https://otherurl.com/user/1234 they would be redirected to https://user-1234.otherurl.com.

Redirect

The redirect option allows a user to set incoming matches to redirect.

Field	Description
auto_https_redirect	If enabled and a sibling controller exists for port 443, requests will be auto redirected to it. Essentially sets up automatic TLS redirection for this router.
remove_www	If true, any matching inbound request with www attached will have www removed.
port	The port to redirect traffic to.
scheme	The scheme to redirect traffic to.
url	A specific URL to redirect traffic to.

{
	"redirect": {
		"auto_https_redirect": true,
		"remove_www": true,
		"port": 34567,
		"scheme": "https",
		"url": "https://user-$$1.otherurl.com"
	}
}

Submitting a redirect config, Port, Scheme, and url are optional settings, but auto_https_redirect and remove_www need a boolean submitted.

Forward

The forward option exposes mechanics to change certain aspects of the request that is incoming for a container IN the environment.

Field	Description
scheme	The scheme to forward traffic to.
url	A specific URL to forward traffic to.

{
	"forward": {
		"scheme": "https",
		"url": "/example/old/images/$$1"
	}
}

Proxy

The proxy setting allows for the router to act as a proxy to a specified domain. Using the content modification the content can be mutated before the proxy is passed through.

Field	Description
domain	The domain that will be proxied to.
content_mod	On the response of the request, the match on the response will be replaced with the value defined.
url	A URL that can be appended to the domain.

{
	"proxy": {
		"domain": "remote-domain.com",
		"content_mod": {
			"replace": [
				{
					"match": "remote-domain.com/main.js",
					"value": "current-domain.com/main.js"
				}
			]
		},
		"url": "/example/$$1"
	}
}

Cache

The cache configuration exposes a way for users to set caching of files up at the load balancer(s).

{
	"caching": {
		"files": [
			{
				"match": "(.*)\\.(js|css|png|svg)",
				"ttl": "5m"
			}
		]
	}
}

files array

Field	Description
match	A regex pattern used to match files.
ttl	A value in a time string, ttl (time to live) is how long the files will be cached before another lookup. This accepts a string with modifiers. Example for 3 days 15 hours 10 minutes 5 seconds 3d15h10m5s

Advanced

The advanced section holds configuration settings for TLS at the router level.

Field	Description
Allow Insecure	Instructs the load balancer to allow traffic even if an insecure certificate is being used.
Server Name	Used with client authentication, specifies the server name associated with the client certificate authentication.
Client Auth	Specifies the type of client authentication to allow through.
Client Cert Auth	The client Certificate Authority (CA), typically used with client auth type require-verify for mTLS (Mutual TLS).

Client Auth: Values and Descriptions

Client Auth Type	Description
none	Does not require a TLS certificate to be sent.
request	Asks the client to send a TLS certificate, but does not require or validate it.
require	Requires a certificate to be sent for the request to be valid, but does not validate the certificate.
require-verify	Requires both that the client sends a certificate and that the certificate is valid. This is required when using HTTPS.

Firewall

In addition to the Controllers page, the load balancer modal includes a Firewall page where a Web Application Firewall (WAF) can be configured per-controller. The WAF runs on the v1 native load balancer and supports IP, geo, URL, method, header, and body-based rules with `allow`, `deny`, and `block` actions.

For full configuration details, see [Configuring Web Application Firewall.

Transport Extension

The other type of extension is transport extension. The main difference between transport and router extensions (other than what they actually do!) is the fact that a user can only define 1 transport level extension per controller.

In the portal, a user will describe the:

Field	Description
Connections > Max Idle Connections	Maximum number of simultaneous connections (via HTTP/2) per connection.
Telemetry	Configuration options for excluding certain traffic from telemetry and how long to track certain connections.

Telemetry UDP

Telemetry options if mode for the controller is UDP.

Field	Description
Persist Restarts	(persist_restarts) If true, Cycle will maintain telemetry/metrics across load balancer restarts.
Disable Router Metrics	(disable_router_metrics) Determines if the load balancer will track router metrics. Defaults to false.
Tracking Window	(tracking_window) A string signifying a duration of time. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d", "w", "y".

Telemetry HTTP

Telemetry options if mode for the controller is HTTP.

Field	Description
Persist Restarts	(persist_restarts) If true, Cycle will maintain telemetry/metrics across load balancer restarts.
Disable URL Tracking	(disable_url_tracking) Determines if the load balancer will track URL metrics. Defaults to false.
Disable Router Metrics	(disable_router_metrics) Determines if the load balancer will track router metrics. Defaults to false.
Max Trackable URLs	(max_trackable_urls) Determines how many URLs the load balancer will track at one time. Defaults to 150.
Tracking Window	(tracking_window) A string signifying a duration of time. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d", "w", "y".
Track Invalid Requests	(track_invalid_requests) Whether or not to track invalid requests. An invalid request is a request that no router existed for. Usually means bot requests. Defaults to false.
Group Paths	(group_paths) Group paths is used to group URLs. The key is the URL and the value is the regex used to match URLs.
Ignore Paths	(ignore_paths) An array of paths to exclude from tracking.

Telemetry TCP

Telemetry options if mode for the controller is TCP.

Field	Description
Persist Restarts	(persist_restarts) If true, Cycle will maintain telemetry/metrics across load balancer restarts.
Disable Router Metrics	(disable_router_metrics) Determines if the load balancer will track router metrics. Defaults to false.
Tracking Window	(tracking_window) A string signifying a duration of time. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d", "w", "y".

EU Control Plane Goes Live

Loading...

Challenge the Status Quo

Configuring the Native Load Balancer.

Load Balancer Controller Ports

Overview

URLs

Routers

Config

General

Controller Routers

Router Mode

Match

Regex

Config

Extensions

Router Extension

Redirect

Forward

Proxy

Cache

Advanced

Client Auth: Values and Descriptions

Firewall

Transport Extension

Telemetry UDP

Telemetry HTTP

Telemetry TCP

Cookies Preferences

EU Control Plane Goes Live