V1 Pool Reference

Reference for all Edge-LB pool configurations options in the V1 API

V1 Pool Reference

The tables below describe all possible configuration options. The majority of fields have sensible defaults and should be modified with caution.

Configuration Guidelines

  • If a default is not set, it will be left empty, even for objects.
  • Set defaults in the object that is furthest from the root object.
  • Always set a default for arrays.
  • The purpose of “nullable” is to allow the output JSON field to be set to the golang “zero value”. Without “nullable”, the field will be removed altogether from the resulting JSON.
  • Actual validation is done in the code, not expressed in swagger.
  • Since an empty boolean is interpreted as “false”, do not set a default.
  • Use CamelCase.
  • Swagger will only do enum validation if it is a top level definition.

pool

The pool contains information on resources that the pool needs. Changes made to this section will relaunch the tasks.

Key Type Nullable Properties Description
apiVersion string The api/schema version of this pool object. Should be V2 for new pools.
name string The pool name.
namespace string true The DC/OS space (sometimes also referred to as a “group”).
packageName string
packageVersion string
role string Mesos role for load balancers. Defaults to “slave_public” so that load balancers will be run on public agents. Use “*” to run load balancers on private agents. Read more about Mesos roles at http://mesos.apache.org/documentation/latest/roles/.
cpus number
cpusAdminOverhead number
mem int32 Memory requirements (in MB).
memAdminOverhead int32 Memory requirements (in MB).
disk int32 Disk size (in MB).
count integer true Number of load balancer instances in the pool.
constraints string true Marathon style constraints for load balancer instance placement.
ports array
  • Override ports to allocate for each load balancer instance.
  • Defaults to {{haproxy.frontend.objs[].bindPort}} and {{haproxy.stats.bindPort}}.
  • Use this field to pre-allocate all needed ports with or without the frontends present. For example: [80, 443, 9090].
  • If the length of the ports array is not zero, only the ports specified will be allocated by the pool scheduler.
items int32
secrets array DC/OS secrets.
environmentVariables object additionalProperties Environment variables to pass to tasks. Prefix with ELB_FILE_ and it will be written to a file. For example, the contents of ELB_FILE_MYENV will be written to $ENVFILE/ELB_FILE_MYENV.
autoCertificate boolean Autogenerate a self-signed SSL/TLS certificate. It is not generated by default. It will be written to $AUTOCERT.
virtualNetworks array Virtual networks to join.
haproxy
poolHealthcheckGracePeriod int32 Defines the period of time after start of the pool container when failed healtchecks will be ignored (default: 180s). Introduced in v1.2.3.
poolHealthcheckInterval int32 Defines healthcheck execution interval. At most one healtcheck is going to execute at any given time (default: 12s). Introduced in v1.2.3.
poolHealthcheckMaxFail int32 Defines how many consecutive failures mark the task as failed and force Mesos to kill it (default: 5). Introduced in v1.2.3.
poolhealthcheckTimeout int32 Defines the timeout enforced by Mesos on the healthcheck execution. It includes the container startup (fetch, setup, start, etc…) as well as the time spent by the healthcheck command executing the test. Introduced in v1.2.3.

pool.secrets

Key Type Description
secret object

pool.secrets.secret

Key Type Description
secret string Secret name.
file string File name.
The file myfile will be found at $SECRETS/myfile.

pool.environmentVariables

Key type Description
additionalProperties string Environment variables to pass to tasks.
Prefix with “ELB_FILE_” and it will be written to a file. For example, the contents of “ELB_FILE_MYENV” will be written to “$ENVFILE/ELB_FILE_MYENV”.

pool.virtualNetworks

Key Type Description
name string The name of the virtual network to join.
labels string Labels to pass to the virtual network plugin.

pool.haproxy

Key Type Description
stats
frontends array Array of frontends.
backends array Array of backends.

pool.stats

Key Type
bindAddress string
bindPort int 32

pool.frontend

Key Type Properties Description x-nullable Format
name string Defaults to frontend_{{bindAddress}}_{{bindPort}}.
bindPort integer The port (e.g. 80 for HTTP or 443 for HTTPS) that this frontend will bind to. int32
bindModifier string Additional text to put in the bind field
certificates array SSL/TLS certificates in the load balancer.

For secrets, use $SECRETS/my_file_name
For environment files, use $ENVFILE/my_file_name
For autoCertificate, use $AUTOCERT.
type: string
redirectToHttps object Setting this to the empty object is enough to redirect all traffic from HTTP (this frontend) to HTTPS (port 443). Default: except: []
miscStrs array of strings Additional template lines inserted before use_backend
protocol The frontend protocol is how clients/users communicate with HAProxy.
linkBackend object
  • defaultBackend
  • map
 This describes what backends to send traffic to. This can be expressed with a variety of filters such as matching on the hostname or the HTTP URL path.
Default: map: []

pool.frontend.redirectToHttps

Key Type Properties Description
except array You can additionally set a whitelist of fields that must be matched to allow HTTP.
items object Boolean AND will be applied with every selected value.

pool.frontend.redirectToHttps.items

Key Type Description
host string Match on host.
pathBeg string Math on path.

pool.frontend.linkBackend

Key Type Properties Description
defaultBackend string This is default backend that is routed to if none of the other filters are matched.
map array This is an optional field that specifies a mapping to various backends. These rules are applied in order.
“Backend” and at least one of the condition fields must be filled out. If multiple conditions are filled out, they will be combined with a boolean “AND”.

pool.frontend.linkBackend.map

Key Type Description
backend string
hostEq string Must be all lowercase.
hostReg string Must be all lowercase. It is possible for a port (e.g. foo.com:80) to be in this regex.
pathBeg string
pathEnd string
pathReg string

pool.backend

Key Type Properties Description
name string The name the frontend refers to.
protocol string The backend protocol is how HAProxy communicates with the servers it is load balancing.
rewriteHttp Manipulate HTTP headers. There is no effect unless the protocol is either HTTP or HTTPS.
balance string Load balancing strategy. E.g., roundrobin, leastconn, etc.
customCheck object Specify alternate forms of healthchecks.
miscStrs array of strings Additional template lines inserted before servers
servers array Array of backend network sources / selectors.

pool.backend.customCheck

Key Type
httpchk boolean
httpchkMiscStr string
sslHelloChk boolean
miscStr string

pool.backend.rewriteHttp

Key Type Properties Description
host string Set the host header value.
path object Rewrite the HTTP URL path. All fields required, otherwise it’s ignored.
request
response
sticky object Sticky sessions via a cookie.
To use the default values (recommended), set this field to the empty object.

pool.backend.rewriteHttp.path

Key Type
fromPath string
toPath string

pool.backend.rewriteHttp.sticky

Key Type nullable
enabled boolean true
customStr string

pool.backend.rewriteHttp.request

Key Type nullable
forwardfor boolean true
xForwardedPort boolean true
xForwardedProtoHttpsIfTls boolean true
setHostHeader boolean true
rewritePath boolean true

pool.backend.rewriteHttp.response

Key Type nullable
rewriteLocation boolean true

pool.backend.server

Key Type Properties Default Description
type
framework object match: EXACT The Mesos framework. If unsure, the value should probably be “marathon”.
task object match: EXACT The Task name. This field is not needed for VIPs.
For Marathon pods, this is the container name, NOT the pod name.
check object enabled: true Enable health checks. These are by default TCP health checks. For more options see “customCheck”.
These are required for DNS resolution (and hence VIPs) to function properly
port
miscStr string Append an arbitrary string to the “server” directive.

pool.backend.server.framework

Key Type
values string
match

pool.backend.server.task

Key Type Description
value string The Task name. This field is not needed for VIPs.
For Marathon pods, this is the container name, NOT the pod name.
match

pool.backend.server.check

Key Type nullable
enabled boolean true
customStr string

pool.backend.server.port

Key Type description
name string The name of the port. This is used for AUTO_IP, AGENT_IP and CONTAINER_IP.
all boolean For AUTO_IP, AGENT_IP and CONTAINER_IP,this can be used to expose all defined ports.
This should only be used if a name is not defined for the port and there is a single port defined for the service.
vip strings Set the VIP definition directly (e.g. “/myvip:1234”).

error

Key Type
code int32
message string