V2 Pool Reference

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

V2 Pool Reference

The tables below describe the possible configuration options. The majority of fields have sensible defaults - modify them with caution.


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 Apache® 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 Auto-generate a self-signed SSL/TLS certificate. The certificate is not generated by default, and will be written to $AUTOCERT.
virtualNetworks array Virtual networks to join.
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.


Key Type Description
secret object


Key Type Description
secret string DC/OS Secret name.
file string File name in a pool container’s sandbox.
The file myfile will be found at $SECRETS/myfile.


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


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


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


Key Type
bindAddress string
bindPort int 32


Key Type Properties Description x-nullable Format
name string Defaults to frontend_{{bindAddress}}_{{bindPort}}.
bindPort integer The port (for exmaple port 80 for HTTP or 443 for HTTPS) to which this frontend will bind. 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 which backends to which to send traffic. This can be expressed with a variety of filters such as matching on the hostname or the HTTP URL path.
Default: map: []


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.


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


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


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


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, for example, roundrobin, leastconn, and so on.
customCheck object Specify alternate forms of healthchecks.
miscStrs array of strings Additional template lines inserted before servers
services array Array of backend service selectors.


Key Type
httpchk boolean
httpchkMiscStr string
sslHelloChk boolean
miscStr string


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


Key Type
fromPath string
toPath string


Key Type nullable
enabled boolean true
customStr string


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


Key Type nullable
rewriteLocation boolean true


Key Type
marathon object
mesos object
endpoint object


Key Type Description
serviceID string Marathon pod or application ID.
serviceIDPattern string serviceID as a regex pattern.
containerName string Marathon pod container name, optional unless using Marathon pods.
containerNamePattern string containerName as a regex pattern.


Key Type Description
frameworkName string Mesos framework name.
frameworkNamePattern string frameworkName as a regex pattern.
frameworkID string Mesos framework ID.
frameworkIDPattern string frameworkID as a regex pattern.
taskName string Mesos task name.
taskNamePattern string taskName as a regex pattern.
taskID string Mesos task ID.
taskIDPattern string taskID as a regex pattern.


Key Type Description
type string Enum field, can be AUTO_IP, AGENT_IP, CONTAINER_IP, or ADDRESS. Default is AUTO_IP.
miscStr string Append arbitrary string to add to the end of the “server” directive.
check object Enable health checks. These are required for DNS resolution to function properly, and are, by default, TCP health checks. For more options see “customCheck”.
address string Server address override, can be used to specify a cluster internal address such as a VIP. Only allowed when using type ADDRESS.
port integer Port number.
portName string Name of port.
allPorts boolean Selects all ports defined in service when true.


Key Type
enabled boolean
customStr string


Key Type
code int32
message string