HyperCloud Load-Balancer Configuration
Introduction
The HyperCloud Load-Balancer appliance provides a front-end for one or more back-end web servers allowing traffic to be balanced across these. TLS termination is also provided, allowing HTTPS encapsulation to be offloaded to the load balancer. Lets Encrypt can be utilized to provide free and secure TLS certificates that are compatible with all operating systems and browsers.
Configuration is specified as a MIME base64 encoded zlib deflated JSON array encoded in UTF-8.
Each element of the array is an object describing a configuration item, usually a server.
This configuration blob should be placed in a virtual machine's user
template attribute called HYPERCLOUD_LOADBALANCER_CONFIG
Note
If Let's Encrypt public certificates are desired, created a user
template attributed called
HYPERCLOUD_LOADBALANCER_LETSENCRYPT_PUBLIC_BOOLEAN and set the value to
YES.
If there is a desire for the SSL certificates to be persistent, be sure to attach a 1 GB blank disk to the VM prior to boot.
v1/Server
Secret: <<string: default: generated>>: A unique secret for this load balancer group.
Listen: <<int (1-65535)>>: Port for this server to listen on. Required.
SSLServer: If present, this server is a TLS server
Auto
Provider: <<string: option: letsencrypt, selfsign>>: Automatically obtain
a certificate, either from Lets Encrypt or use a self-signed
certificate. Required.
Domain: <<string>>: Domain for the certificate to contain.
Domains: [<<string>>]: Domains for the certificate to contain. Not used
Domain is specified. If neither Domain nor Domains is specified
a callback mechanism is used to automatically determine this.
Key: <<string: PEM encoded RSA private key, PKCS#1 v1.5>>
Certificate: <<string: PEM encoded certificate, X.509>>
Chain: <<string: PEM encoded certificates, X.509>>: Key, Certificate, and Chain
are used only if the Auto attribute is missing. Both Key and Certificate
are then required. Chain is optional.
ListenMode: <<string: option: http, tcp; default: http>>: Type of server
ConnectMode: <<string: option: http, http-tls, tcp, tcp-tls; default: http>>: Type of
client. The server must be of a corresponding type.
SourcePath: <<string: default: />>
DestinationPath: <<string: default: />>: If SourcePath and DestinationPath differ then
the URL request is rewritten before passing it from the client to the
destination
DestinationMaxClients: <<int>>: Maximum number of clients to balance onto a single
destination
Destination
ServiceRole
Role: <<string>>: Name of the role in the orchestrator
Port: <<int (1-65535)>>: Port to connect to
DestinationMaxClients: As above
ConnectMode: As above
VM
Id: <<string|int>>: Name or ID of VM in this service
Port: <<int (1-65535)>>: Port to connect to
DestinationMaxClients: As above
ConnectMode: As above
Hostname
IPv4: <<boolean: default: true>>: Use IPv4 addresses found for this
hostname
IPv6: <<boolean: default: true>>: Use IPv6 addresses found for this
hostname
Hostname: <<string>>: The name of the host to resolve. Required.
Port: <<int (1-65535)>>: Port to connect to
DestinationMaxClients: As above
ConnectMode: As above
IPPort
IP: <<string>>: The IP address to connect to.
Port: <<int (1-65535)>>: Port to connect to
DestinationMaxClients: As above
ConnectMode: As above
<<string: ip:port>>: A raw IP:port string. IPv6 addresses should be enclosed
in square brackets
Location
ConnectMode: As above
SourcePath: As above
DestinationPath: As above
DestinationMaxClients: As above
Destination: As above
Redirect
<<int>>: Specifies a port to redirect to. If this form is used, below are
ignored.
URL: <<string>>: Complete URL to redirect to, if this form is used, below
are ignored
Scheme: <<string>>: Scheme to redirect to, e.g., "http" or "https"
Port: <<int>>: Port to redirect to
Host: <<string>>: Host to redirect to
Path: <<string>>: Path to redirect to. If any of Scheme, Port, Host, or Path
are omitted the current URL value is retained for that part.
CountryCode
<<string>>: Two-character ISO 3166 Country Code. If present, will redirect to this
backend if source IP is from this country. Optional.
[
{
"v1/Server": {
"Secret": <<string>>,
"Listen": <<int (1-65535)>>,
"ListenMode": <<string option: http, tcp>>,
"ConnectMode": <<string option: http, http-tls, tcp, tcp-tls>>,
"SourcePath": <<string>>,
"DestinationPath": <<string>>,
"Location": {
"ConnectMode": <<string>>,
"SourcePath": <<string>>,
"DestinationPath": <<string>>,
"DestinationMaxClients": <<int>>,
"Destination": <<object>>
},
"Destination": [
{"ServiceRole": {
"Role": <<string>>,
"Port": <<int (1-65535)>>,
"DestinationMaxClients": <<int>>,
"ConnectMode": <<string>>
}},
{"VM": {
"Id": <<string|int>>,
"Port": <<int (1-65535)>>,
"DestinationMaxClients": <<int>>,
"ConnectMode": <<string>>
},
{"Hostname": {
"IPv4": <<boolean>>,
"IPv6": <<boolean>>,
"Hostname": <<string>>,
"Port": <<int (1-65535)>>,
"DestinationMaxClients": <<int>>,
"ConnectMode": <<string>>
},
{"IPPort": {
"IP": <<string>>,
"Port": <<int (1-65535)>>,
"DestinationMaxClients": <<int>>,
"ConnectMode": <<string>>
}},
<<string: ip:port>>
],
"DestinationMaxClients": <<int>>,
"SSLServer": {
"Auto": {
"Provider": <<string option: letsencrypt, selfsign>>,
"Domain": <<string>>,
"Domains": [ <<string>> ],
},
"Key": <<string: PEM encoded RSA private key, PKCS#1 v1.5>>,
"Certificate": <<string: PEM encoded certificate, X.509>>,
"Chain": <<string: PEM encoded certificates, X.509>>
},
"Redirect": <<int>> | {
"URL": <<string>>,
"Scheme": <<string>>,
"Port": <<int (1-65535)>>,
"Host": <<string>>,
"Path": <<string>>
}
}
},
{
"v1/Server": {
...
}
}
]
Examples
-
Simple SSL Termination:
-
JSON:
-
Configuration Blob:
eJyLruZSAAKlMkP94NSistQiJQUrBYgYWNwns7gkNU8JwrNSMDEx1kFIuqQWl2TmJZZk5ueBtEUrGRromegZ6hlbWRgoxSIpdM7Py0tNLvHNT0kFKVTKKCkpUEKSDw72gdmugGI/WNaxtCRfCUMYLBVQlF+WmQJxtVJxak5acWZ6nhKKulouVFYtV20sAAa9NtY= -
Possible HAProxy configuration snippet:
frontend server0 bind *:443 ssl crt /etc/ssl/lb-certificate-b960936e05134850bde4681bee3b90ddd717e805 mode http http-request del-header SSL-Client-Cert default_backend backend_abc8fe5f4d319112a3d2cadeef29d7f106af58f5 backend backend_abc8fe5f4d319112a3d2cadeef29d7f106af58f5 mode http cookie LB_368F44A746AEF5A4BF64E4EAFA254BCFE2B063ED insert indirect nocache httponly server b0d0 10.4.1.3:80 check cookie fc9ae2f77251489c11a1b1b370d0b9648fbcb6b2