Configuring v1 Load Balancer

In the portal, the v1 load balancer is configured through the controllers page in the load balancer modal.

To get there:

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

services section

Load Balancer Controller Ports

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

Overview

controllers overview

FieldDescription
InstanceThe load balancer instance.
Data TransferTotal amount of data received and transmitted.
ConnectionsTotal amount of connections made.
RequestsTotal number of requests.
DisconnectsTotal number of connections that have ended, with and without error.

URL's

load balancer urls

FieldDescription
HostThe domain and path of the incoming call.
MethodThe HTTP method used for the call.
ResponsesThe number of responses sent on that domain + path.
HandlerNumber (total) and type (graphed) of the handler. Example: 2 total, both forwarded.
Average TimeThe average time to complete the request.

Routers

load balancer router

FieldDescription
DestinationContainer destination for the request.
LatencyThe latency of the connection between load balancer and destination (measured by ICMP packet).
RequestsThe total number of requests.
ConnectionsAmount of traffic transmitted and received.
Success RatePercentage 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.

FieldDescription
IdentifierThe identifier is a way for the user to give a resource a name, useful for interacting with the API and CLI after creation.
Ingress PortThe literal ingress port that this configuration pertains to.
ModeEither TCP, HTTP, or UDP.
Logging VerbosityThis setting determines the verbosity of the logs printed to the instance console; higher settings record more detail.
Idle TimeoutThe amount of time a connection can be idle before it's dropped.
PerformanceA toggle for performance mode. When enabled, telemetry is disabled to allocate all resources to load balancer functionality.
TLS EnableEnables TLS for the given controller.

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 general settings, configuration, and extension settings.

General

FieldDescription
ModeThe type of load balancing, either round-robin or random.
Match DomainsAn array of domains to match for.
Match Internal PortsAn array of internal ports to match for.
Match PathA path to match for. Users can submit a static path or a regex.

So for the given router, the user is setting the type of routing to be done here as well as creating some constraints around what inbound traffic qualifies to be routed by this router.

Config

FieldDescription
Destination RetriesThe number of times the load balancer will retry reaching the intended target for the traffic.
Destination Connection TimeoutThe timeout associated with the attempt to make the connection.
Destination PrioritizationHints to the load balancer on how to prioritize traffic to instances. random: Chooses a random instance. latency: Prioritizes lower latency instances.
Sticky SessionsEnsures 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.

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.

FieldDescription
redirectDefines a built-in redirect for HTTP mode routers.
forwardDefines a built-in forwarding scheme for HTTP mode routers.
proxyDefines proxy settings for the given router.
cacheDefines cache settings for the given router.

If there are any matches to the optional Match Path field they can be assigned to domains or URL's 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.

FieldDescription
auto_https_redirectIf 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_wwwIf true, any matching inbound request with www attached will have www removed.
portThe port to redirect traffic to.
schemeThe scheme to redirect traffic to.
urlA 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.

FieldDescription
schemeThe scheme to forward traffic to.
urlA 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.

FieldDescription
domainThe domain that will be proxied to.
content_modOn the response of the request, the match on the response will be replaced with the value defined.
urlA 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

FieldDescription
matchA regex pattern used to match files.
ttlA 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.

FieldDescription
Allow InsecureInstructs the load balancer to allow traffic even if an insecure certificate is being used.
Server NameUsed with client authentication, specifies the server name associated with the client certificate authentication.
Client AuthSpecifies the type of client authentication to allow through.
Client Cert AuthThe client Certificate Authority (CA), typically used with client auth type require-verify for mTLS (Mutual TLS).
Client Auth: Values and Descriptions
Client Auth TypeDescription
noneDoes not require a TLS certificate to be sent.
requestAsks the client to send a TLS certificate, but does not require or validate it.
requireRequires a certificate to be sent for the request to be valid, but does not validate the certificate.
require-verifyRequires both that the client sends a certificate and that the certificate is valid. This is required when using HTTPS.

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:

FieldDescription
Connections > Max Idle ConnectionsMaximum number of simultaneous connections (via HTTP/2) per connection.
TelemetryConfiguration 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.

FieldDescription
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.

FieldDescription
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 HTTP.

FieldDescription
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".