Docker Flow: Proxy

Introduction

The goal of the Docker Flow: Proxy project is to provide an easy way to reconfigure proxy every time a new service is deployed, or when a service is scaled. It does not try to "reinvent the wheel", but to leverage the existing leaders and combine them through an easy to use integration. It uses HAProxy as a proxy and adds custom logic that allows on-demand reconfiguration.

Modes

Since the Docker 1.12 release, Docker Flow: Proxy supports two modes. The default mode is designed to work with any setup and requires Consul and Registrator. The swarm mode aims to leverage the benefits that come with Docker Swarm and new networking introduced in the 1.12 release. The later mode (swarm) does not have any dependency but Docker Engine. The swarm mode is recommended for all who use Docker Swarm features introduced in v1.12.

### The Swarm Mode (Docker 1.12+) with automatic configuration ### The Swarm Mode (Docker 1.12+) with manual configuration ### The Default Mode

Usage

Container Config

The Docker Flow: Proxy container can be configured through environment variables

The following environment variables can be used to configure the Docker Flow: Proxy.

Variable	Description	Required	Default	Example
CONSUL_ADDRESS	The address of a Consul instance used for storing proxy information and discovering running nodes. Multiple addresses can be separated with comma (e.g. 192.168.0.10:8500,192.168.0.11:8500).	Only in default mode		192.168.0.10:8500
LISTENER_ADDRESS	The address of the Docker Flow: Swarm Listener used for automatic proxy configuration.	Only in swarm mode		swarm-listener
PROXY_INSTANCE_NAME	The name of the proxy instance. Useful if multiple proxies are running inside a cluster	No	docker-flow	docker-flow
MODE	Two modes are supported. The default mode should be used for general purpose. It requires a Consul instance and service data to be stored in it (e.g. through Registrator). The swarm mode is designed to work with new features introduced in Docker 1.12 and assumes that containers are deployed as Docker services (new Swarm).	No	default	swarm
SERVICE_NAME	The name of the service. It must be the same as the value of the `--name` argument used to create the proxy service. Used only in the swarm mode.	No	proxy	my-proxy
STATS_USER	Username for the statistics page		admin	my-user
STATS_PASS	Password for the statistics page		admin	my-pass
TIMEOUT_CONNECT	The connect timeout in seconds		5	3
TIMEOUT_CLIENT	The client timeout in seconds		20	5
TIMEOUT_SERVER	The server timeout in seconds		20	5
TIMEOUT_QUEUE	The queue timeout in seconds		30	10
TIMEOUT_HTTP_REQUEST	The HTTP request timeout in seconds		5	3
TIMEOUT_HTTP_KEEP_ALIVE	The HTTP keep alive timeout in seconds		15	10
USERS	A comma-separated list of credentials(:) for HTTP basic auth, which applies to all the backend routes.			user1:pass1,user2:pass2

The base HAProxy configuration can be found in haproxy.tmpl. It can be customized by creating a new container. An example Dockerfile is as follows.

FROM vfarcic/docker-flow-proxy
COPY haproxy.tmpl /cfg/tmpl/haproxy.tmpl

Reconfigure

Reconfigures the proxy using information stored in Consul

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

Query	Description	Required	Default	Example
aclName	ACLs are ordered alphabetically by their names. If not specified, serviceName is used instead.	No		05-go-demo-acl
consulTemplateBePath	The path to the Consul Template representing a snippet of the backend configuration. If specified, the proxy template will be loaded from the specified file.			/consul_templates/tmpl/go-demo-be.tmpl
consulTemplateFePath	The path to the Consul Template representing a snippet of the frontend configuration. If specified, the proxy template will be loaded from the specified file.			/consul_templates/tmpl/go-demo-fe.tmpl
distribute	Whether to distribute a request to all the instances of the proxy. Used only in the swarm mode.	No	false	true
outboundHostname	The hostname where the service is running, for instance on a separate swarm. If specified, the proxy will dispatch requests to that domain.	No		machine123.internal.ecme.com
pathType	The ACL derivative. Defaults to path_beg. See HAProxy path for more info.	No		path_beg
port	The internal port of a service that should be reconfigured. The port is used only in the swarm mode	Only in swarm mode
reqRepReplace	A regular expression to apply the modification. If specified, `reqRepSearch` needs to be set as well.	No		\1\ /demo/\2
reqRepSearch	A regular expression to search the content to be replaced. If specified, `reqRepReplace` needs to be set as well.	No		^([^\ ])\ /something/(.)
serviceCert	Content of the PEM-encoded certificate to be used by the proxy when serving traffic over SSL.	No
serviceDomain	The domain of the service. If specified, the proxy will allow access only to requests coming to that domain. Multiple domains should be separated with comma (`,`).	No		ecme.com
serviceName	The name of the service. It must match the name of the Swarm service or the one stored in Consul.	Yes		go-demo
servicePath	The URL path of the service. Multiple values should be separated with comma (`,`).	Yes (unless consulTemplatePath is present)		/api/v1/books
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. If specified, `templateFePath` must be set as well			/templates/go-demo-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. If specified, `templateBePath` must be set as well			/templates/go-demo-fe.tmpl
skipCheck	Whether to skip adding proxy checks. This option is used only in the default mode.	No	false	true
users	A comma-separated list of credentials(:) for HTTP basic auth, which applies only to the service that will be reconfigured.	No		user1:pass1,user2:pass2

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 stored in Consul	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

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.

Config

Outputs HAProxy configuration

The address is [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/config

Feedback and Contribution

I'd appreciate any feedback you might give (both positive and negative). Feel fee to create a new issue, send a pull request, or tell me about any feature you might be missing. You can find my contact information in the About section of my blog.

Please follow the Contributing To The Project instructions before submitting a pull request.

zittix / docker-flow-proxy Goto Github PK