edit

Usage

Docker Flow Proxy can be controlled by sending HTTP requests or through Docker Service labels when combined with Docker Flow Swarm Listener.

Reconfigure

Reconfigures the proxy

The proxy can be reconfigured to use request mode http or tcp. The default value of the request mode is http and can be changed with the parameter reqMode.

General Query Parameters

The following query parameters can be used to send a reconfigure request to Docker Flow Proxy. They apply to any request mode and should be added to the base address [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/reconfigure. They apply to any reqMode.

Query Description
aclName ACLs are ordered alphabetically by their names. If not specified, serviceName is used instead.
Example: 05-go-demo-acl
addReqHeader Additional headers that will be added to the request before forwarding it to the service. Multiple headers should be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. Please consult Add a header to the request for more info.
Example: X-Forwarded-Port %[dst_port],X-Forwarded-Ssl on if { ssl_fc }
addResHeader Additional headers that will be added to the response before forwarding it to the client. Multiple headers should be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. Please consult Add a header to the response for more info.
Example: X-Via %[env(HOSTNAME)],Server haproxy
backendExtra Additional configuration that will be added to the bottom of the service backend
connectionMode HAProxy supports 5 connection modes.

http-keep-alive: all requests and responses are processed.
http-tunnel: only the first request and response are processed, everything else is forwarded with no analysis.
httpclose: tunnel with "Connection: close" added in both directions.
http-server-close: the server-facing connection is closed after the response.
forceclose: the connection is actively closed after end of response.

In general, it is preferred to use http-server-close with application servers, and some static servers might benefit from http-keep-alive.
Connection mode is restricted to HTTP mode only. If specified, connection mode will be applied to the backend section.
Example: http-keep-alive
delReqHeader Additional headers that will be deleted in the request before forwarding it to the service. Multiple headers should be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. Please consult Delete a header in the request for more info.
Example: X-Forwarded-For,Cookie
delResHeader Additional headers that will be deleted in the response before forwarding it to the client. Multiple headers should be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. Please consult Delete a header in the response for more info.
Example: X-Varnish,X-Cache
distribute Whether to distribute a request to all the instances of the proxy. Used only in the swarm mode.
Example: true
httpsPort The internal HTTPS port of a service that should be reconfigured. The port is used only in the swarm mode. If not specified, the port parameter will be used instead.
Example: 443
ignoreAuthorization If set to true, the service destination will not require authorization. The parameter must be prefixed with the index of the service destination that should be excluded from authorization.
Default: false
Example: true
isDefaultBackend If set to true, the service will be set to the default_backend rule, meaning it will catch all requests not matching any other rules.
Default: false
Example: true
port The internal port of a service that should be reconfigured. The port is used only in the swarm mode. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. port.1, port.2, and so on). This field is mandatory when running in swarm or service mode.
Example: 8080
reqMode The request mode. The proxy should be able to work with any mode supported by HAProxy. However, actively supported and tested modes are http, tcp, and sni. The sni mode implies TCP with an SNI-based routing. The parameter can be prefixed with an index thus allowing definition of multiple modes for a single service (e.g. http, tcp, and so on).
Default: value of the DEFAULT_REQ_MODE environment variable.
Example: tcp
reqPathReplace This field is deprecated. Use reqPathSearchReplace instead.
reqPathSearch This field is deprecated. Use reqPathSearchReplace instead.
reqPathSearchReplace A regular expression to search and replace request paths. Search and replace values are separated with comma (,). Multiple search and replace combinations can be separated with colon (:).
Example: /replace-something/,/with-else/:/replace-with-empty,:/foo,/bar
serviceName The name of the service. It must match the name of the Swarm service. This parameter is mandatory. If used through Docker Flow Swarm Listener, this parameter is added automatically.
Example: go-demo
setReqHeader Additional headers that will be set to the request before forwarding it to the service. If a specified header exists, it will be replaced with the new one. Multiple headers should be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. Please consult Set a header to the request for more info.
Example: X-Forwarded-Port %[dst_port],X-Forwarded-Ssl on if { ssl_fc }
setResHeader Additional headers that will be set to the response before forwarding it to the client. If a specified header exists, it will be replaced with the new one. Multiple headers should be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. Please consult Set a header to the response for more info.
Example: X-Via %[env(HOSTNAME)],Server haproxy
srcPort The source (entry) port of a service. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. srcPort.1, srcPort.2, and so on). The parameter is mandatory when specifying multiple destinations of a single service. If this parameter is used with http mode, the port needs to be specified with the environment variable BIND_PORTS (see Environment Variables for more info) and the port needs to be published on service level.
Example: 80
timeoutServer The server timeout in seconds.
Default: 20
Example: 60
timeoutTunnel The tunnel timeout in seconds.
Default: 3600
Example: 3600

Multiple destinations for a single service can be specified by adding index as a suffix to servicePath, servicePathExclude, srcPort, port, userAgent, ignoreAuthorization, serviceDomain``allowedMethods, deniedMethods, denyHttp, httpsOnly, redirectFromDomain, ReqMode, or outboundHostname parameters. In that case, srcPort is required.

HTTP Mode Query Parameters

The following query parameters can be used only when reqMode is set to http or is empty.

Query Description
allowedMethods The list of allowed methods. If specified, a request with a method that is not on the list will be denied. Multiple methods can be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. allowedMethods.1, allowedMethods.2, and so on).
Example: GET,DELETE
compressionAlgo Enable HTTP compression for the given service. The currently supported algorithms are:
identity: this is mostly for debugging.
gzip: applies gzip compression. This setting is only available when support for zlib or libslz was built in.
deflate: same as gzip, but with deflate algorithm and zlib format. Note that this algorithm has ambiguous support on many browsers and no support at all from recent ones. It is strongly recommended not to use it for anything else than experimentation. This setting is only available when support for zlib or libslz was built in.
raw-deflate: same as deflate without the zlib wrapper, and used as an alternative when the browser wants "deflate". All major browsers understand it and despite violating the standards, it is known to work better than deflate, at least on MSIE and some versions of Safari. This setting is only available when support for zlib or libslz was built in.
Compression will be activated depending on the Accept-Encoding request header. With identity, it does not take care of that header. If backend servers support HTTP compression, these directives will be no-op: haproxy will see the compressed response and will not compress again. If backend servers do not support HTTP compression and there is Accept-Encoding header in request, haproxy will compress the matching response.
Compression is disabled when:
* the request does not advertise a supported compression algorithm in the "Accept-Encoding" header
* the response message is not HTTP/1.1
* HTTP status code is not 200
* response header "Transfer-Encoding" contains "chunked" (Temporary Workaround)
* response contain neither a "Content-Length" header nor a "Transfer-Encoding" whose last value is "chunked"
* response contains a "Content-Type" header whose first value starts with "multipart"
* the response contains the "no-transform" value in the "Cache-control" header
* User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7 and later
* The response contains a "Content-Encoding" header, indicating that the response is already compressed (see compression offload)
Example: gzip
compressionType The type of files that will be compressed.
Example: text/css text/html text/javascript application/javascript text/plain text/xml application/json
deniedMethods The list of denied methods. If specified, a request with a method that is on the list will be denied. Multiple methods can be separated with comma (,). Change the environment variable SEPARATOR if comma is to be used for other purposes. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. deniedMethods.1, deniedMethods.2, and so on).
Example: PUT,POST
denyHttp Whether to deny HTTP requests thus allowing only HTTPS. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. denyHttp.1, denyHttp.2, and so on).
Example: true
Default Value: false
httpsRedirectCode HTTP code for HTTP to HTTPS redirects. This parameter is used only if httpsOnly is set to true
Example: 301
httpsOnly If set to true, HTTP requests to the service will be redirected to HTTPS. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. httpsOnly.1, httpsOnly.2, and so on).
Example: true
Default Value: false
outboundHostname The hostname where the service is running, for instance on a separate swarm. If specified, the proxy will dispatch requests to that domain. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. outboundHostname.1, outboundHostname.2, and so on).
Example: ecme.com
pathType The ACL derivative. Defaults to path_beg. See HAProxy path for more info.
Example: path_beg
redirectFromDomain If a request is sent to one of the domains in this list, it will be redirected to one of the values of the serviceDomain. Multiple domains can be separated with comma (e.g. acme.com,something.acme.com). The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service.
Example: acme.com,something.acme.com
redirectWhenHttpProto Whether to redirect to https when X-Forwarded-Proto is set and the request is made over an HTTP port.
Example: true
Default Value: false
serviceCert Content of the PEM-encoded certificate to be used by the proxy when serving traffic over SSL.
serviceDomain The domain of the service. If set, the proxy will allow access only to requests coming to that domain. Multiple domains can be separated with comma (e.g. acme.com,something.else.com). The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. serviceDomain.1, serviceDomain.2, and so on). Asterisk sign can be placed to beginning of value and in this case serviceDomainAlgo parameter will be replaced to hdr_end(host). This parameter is mandatory if servicePath is not specified.
Example: ecme.com
serviceDomainAlgo Algorithm that should be applied to domain ACLs. Any ACL works only with one flag: -i : ignore case during matching of all subsequent patterns. If not set, the value of the environment variable SERVICE_DOMAIN_ALGO will be used instead. If defaults to hdr_beg(host)
Examples:
hdr(host): matches only if domain is the same as serviceDomain
hdr_dom(host): matches the specified serviceDomain and any subdomain (a string either isolated or delimited by dots). Example: if hdr_dom(host) contains www.ecme.com and serviceDomain equals ecme.com the rule will be passed.
req.ssl_sni: matches Server Name TLS extension
serviceHeader Headers used to filter requests. If set, the proxy will allow access only to requests that contain specified headers. A header consists of a key and value separated with colon (e.g. X-Version:3). Multiple headers can be separated with comma (e.g. X-Version:3,name:viktor). The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. serviceHeader.1, serviceHeader.2, and so on).
Example: X-Version:3,name:viktor
servicePath The URL path of the service. Multiple values should be separated with comma (,). The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. servicePath.1, servicePath.2, and so on). This parameter is mandatory unless serviceDomain is specified.
Example: /api/v1/books
servicePathExclude The URL path that should be excluded from the rules. Multiple values should be separated with comma (,). The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. servicePathExclude.1, servicePathExclude.2, and so on).
Example: /metrics
sessionType Determines the type of sticky sessions. If set to sticky-server, session cookie will be set by the proxy. Any other value means that sticky sessions are not used and load balancing is performed by Docker's Overlay network.
Example: sticky-server
sslVerifyNone If set to true, backend server certificates are not verified. This flag should be set for SSL enabled backend services.
Example: true
Default Value: false
templateBePath The path to the template representing a snippet of the backend configuration. If specified, the backend template will be loaded from the specified file. See the Templates section for more info.
Example: /tmpl/be.tmpl
templateFePath The path to the template representing a snippet of the frontend configuration. If specified, the frontend template will be loaded from the specified file. See the Templates section for more info.
Example: /tmpl/fe.tmpl
userAgent A comma-separated list of user agents. only requests with the same User-Agent will be forwarded to the backend. The parameter can be prefixed with an index thus allowing definition of multiple destinations for a single service (e.g. userAgent.1, userAgent.2, and so on). If the same service is used for multiple agents, it is recommended to use indexes with the last one being without userAgent. That way, if no match is found, the last indexed destination will be used as catch-all.
Example: googlebot,iphone
users A comma-separated list of credentials (:) for HTTP basic authentication. It applies only to the service that will be reconfigured. If used with usersSecret, or when USERS environment variable is set, password may be omitted. In that case, it will be taken from usersSecret file or the global configuration if usersSecret is not present.
Example: usr1:pwd1, usr2:pwd2
usersSecret Suffix of Docker secret from which credentials will be taken for this service. Files must be a comma-separated list of credentials (:). This suffix will be prepended with dfp_users_. For example, if the value is mysecrets the expected name of the Docker secret is dfp_users_mysecrets.
Example: mysecrets
usersPassEncrypted Indicates whether passwords provided by users or usersSecret contain encrypted data. Passwords can be encrypted with the command mkpasswd -m sha-512 password1.
Example: true
Default Value: false
verifyClientSsl Whether to verify client SSL and, if it is not valid, deny request and return 403 Forbidden status code. SSL is validated against the ca-file specified through the environment variable CA_FILE.
Example: true
Default Value: false

Multiple destinations for a single service can be specified by adding index as a suffix to servicePath, servicePathExclude, srcPort, port, userAgent, ignoreAuthorization, serviceDomain, allowedMethods, deniedMethods, denyHttp, httpsOnly, redirectFromDomain, ReqMode, or outboundHostname parameters. In that case, srcPort is required.

TCP Mode HTTP Query Parameters

The reqMode set to tcp does not have any specific parameters beyond those specified in the Reconfigure General Parameters section.

Please consult the Using TCP Request Mode section for an example of working with tcp request mode.

An example request is as follows.

[PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/reconfigure?serviceName=foo&servicePath.1=/&port.1=8080&srcPort.1=80&servicePath.2=/&port.2=8081&srcPort.2=443

The command would create a service foo that exposes ports 8080 and 8081. All requests coming to proxy port 80 with the path that starts with / will be forwarded to the service foo port 8080. Equally, all requests coming to proxy port 443 (HTTPS) with the path that starts with / will be forwarded to the service foo port 8081.

Indexes are incremental and start with 1.

Environment Variables

When a service is not part of the same Swarm cluster, a failure of a proxy instance means that the information about those services cannot be obtained through Docker API and Docker Flow Swarm Listener. In such a case, data loss can be prevented through the usage of environment variables.

Tip

In most cases, there is no need to use environment variables for services running inside the same Swarm cluster as the proxy.

The environment variables that can be used for the initial configuration of services follow the same naming standards as the HTTP Query Parameters.

The environment variables must apply the rules that follow.

  • The names of the environment variables must be prefixed with DFP_SERVICE_.
  • The names of the environment variables must be in upper case and words must be separated by an underscore (_). As an example, the HTTP query parameter aclName would be defined as the environment variable DFP_SERVICE_ACL_NAME.
  • Multiple services must be defined by adding an index to the prefix. Indexing starts from 1. As an example, the aclName of the second service would be defined as DFP_SERVICE_2_ACL_NAME.
  • All other rules applied to reconfigure HTTP query parameters apply to environment variables as well.

The map between the HTTP query parameters and environment variables is as follows.

Query Environment variable
aclName ACL_NAME
addReqHeader ADD_REQ_HEADER
addResHeader ADD_RES_HEADER
allowedMethods ALLOWED_METHODS
backendExtra BACKEND_EXTRA
compressionAlgo COMPRESSION_ALGO
compressionType COMPRESSION_TYPE
deniedMethods DENIED_METHODS
distribute DISTRIBUTE
httpsOnly HTTPS_ONLY
httpsPort HTTPS_PORT
isDefaultBackend IS_DEFAULT_BACKEND
outboundHostname OUTBOUND_HOSTNAME
pathType PATH_TYPE
port PORT
redirectFromDomain REDIRECT_FROM_DOMAIN
redirectWhenHttpProto REDIRECT_WHEN_HTTP_PROTO
reqMode REQ_MODE
reqPathSearchReplace REQ_PATH_SEARCH_REPLACE
serviceCert SERVICE_CERT
serviceDomain SERVICE_DOMAIN
serviceName SERVICE_NAME
servicePath SERVICE_PATH
servicePathExclude SERVICE_PATH_EXCLUDE
setReqHeader SET_REQ_HEADER
setResHeader SET_RES_HEADER
srcPort SRC_PORT
sslVerifyNone SSL_VERIFY_NONE
templateBePath TEMPLATE_BE_PATH
templateFePath TEMPLATE_FE_PATH
timeoutServer TIMEOUT_SERVER
timeoutTunnel TIMEOUT_TUNNEL
users Not supported
usersSecret Not supported
usersPassEncrypted Not supported
verifyClientSsl VERIFY_CLIENT_SSL

Please explore the Configuring Non-Swarm Services tutorial for more info.

Remove

Removes a service from the proxy

The following query arguments can be used to send a remove request to Docker Flow Proxy. They should be added to the base address [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/remove.

Query Description Required Default Example
aclName Mandatory if ACL name was specified in reconfigure request No 05-go-demo-acl
serviceName The name of the service. It must match the name of the service Yes go-demo
distribute Whether to distribute a request to all the instances of the proxy. Used only in the swarm mode. No false true

Certificates

All certificates stored in /certs directory are loaded automatically. If you already have a set of certificates you might choose to store them on a network drive and mount it to the service as /certs.

Docker Flow Proxy supports Docker Secrets for storing certificates. It will automatically load all certificate files added to the service as a secret. Only secrets with names that start with cert- or cert_ will be considered a certificate.

During runtime, additional certificates can be added through Put Certificate request.

Please consult Configuring SSL Certificates for a few examples of working with certificates.

Put Certificate

Puts SSL certificate to proxy configuration

The following query arguments can be used to send a cert request to Docker Flow Proxy. They should be added to the base address [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/cert. Please note that the request method MUST be PUT and the certificate must be placed in request body.

When a new replica is deployed, it will synchronize with other replicas and recuperate their certificates.

Query Description Required Default Example
certName The file name of the certificate Yes my-cert.pem
distribute Whether to distribute a request to all the instances of the proxy. Used only in the swarm mode. No false true

An example is as follows.

curl -i -XPUT \
    --data-binary @my-certificate.pem \
    "[PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/cert?certName=my-certificate.pem&distribute=true"

Please note that the internal proxy port 8080 must be published.

The example would send a certificate stored in the my-certificate.pem file. The certificate would be distributed to all replicas of the proxy.

Tip

Use this feature only if your certificates are renewed often. To be on the safe side, it is recommended to mount /certs directory to a network drive and thus ensure that certs are preserved in case of a failure.

Reload

Reloads proxy configuration

The following query arguments can be used to send a reload request to Docker Flow Proxy. They should be added to the base address [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/reload.

Query Description Required Default Example
fromListener Whether proxy configuration should be recreated from Docker Flow Swarm Listener. If set to true, configuration will be recreated independently of the recreate parameter. This operation is asynchronous. No false true
recreate Recreates configuration using the information already available in the proxy. This param is useful in case config gets corrupted. No false true

An example is as follows.

curl -i \
    "[PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/reload?recreate=false&fromListener=true"

Ping

Ping the service

The ping endpoint might be useful if implementing HEALTHCHECK.

An example Dockerfile is as follows.

FROM vfarcic/docker-flow-proxy

HEALTHCHECK --interval=5s --timeout=5s CMD wget -qO- "http://localhost:8080/v1/docker-flow-proxy/ping"

Config

Outputs HAProxy configuration

The following query arguments can be used to send a reload request to Docker Flow Proxy. They should be added to the base address [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/config.

Query Description
type If set to json, the list of services is returned in JSON format. Any other value returns HAProxy configuration in text format.
Default: text
Example: json

Metrics

Outputs Prometheus-friendly metrics

Metrics can be retrieved though the address [PROXY_IP]:[PROXY_PORT]/metrics. The metrics are in the same format as those provided with the HAProxy Exporter. This endpoint will be available only if environment variables STATS_USER and STATS_PASS are defined.

Templates

Proxy configuration is a combination of configuration files generated from templates. Base template is haproxy.tmpl. Each service appends frontend and backend templates on top of the base template. Once all the templates are combined, they are converted into the haproxy.cfg configuration file.

The templates can be extended by creating a new Docker image based on vfarcic/docker-flow-proxy and adding the templates through templateFePath and templateBePath reconfigure parameters.

Templates are based on Go Templates.

Please see the proxy/types.go for info about the structure used with templates.