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.
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
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
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 |
| 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 | ||
| 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 | |
| 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 |
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 |
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.
Outputs HAProxy configuration
The address is [PROXY_IP]:[PROXY_PORT]/v1/docker-flow-proxy/config
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.