Docker#
The module provides dynamic configuration of proxied server groups
in both HTTP and stream
contexts based on Docker container labels.
For the functionality to work, a shared memory zone must be configured
in the group (see the zone description for http and stream).
Note
The module supports working with both Docker and its alternatives, such as Podman, which implement a compatible API.
The module connects to the Docker daemon via API,
the interaction method with which is specified by the docker_endpoint directive.
After obtaining a list of running containers,
Angie analyzes them for the presence of suitable labels.
If a container description contains a label with a port,
then the address and port of such a container,
as well as parameters from other labels of this container,
are automatically added to the corresponding upstream block
in the Angie configuration.
Note
The same container can be added to multiple upstream groups;
just specify multiple sets of labels with different group names and ports.
This is especially useful if the container runs several different services on different ports; each service can be associated with its own group.
The module then subscribes to container lifecycle events and begins updating the proxied server configuration without reloading Angie:
when starting a container with suitable labels, its internal IP address is added to the specified group;
when stopping or removing a container, it is automatically removed from the group;
when pausing a container with the docker pause command, the server is marked as
down, and with docker unpause — asup.
Configuration Example#
The module's directives are always located in the http context,
but proxied server groups can be defined
in both the http context and the stream context.
Configuration example for http:
http {
# Examples of connection options:
# docker_endpoint http://127.0.0.1:2375;
# docker_endpoint https://127.0.0.1:2376;
docker_endpoint unix:/var/run/docker.sock;
# maximum Docker response buffer size (optional)
# docker_max_object_size 128k;
upstream u {
zone z 1m; # shared memory zone is required
}
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://u;
}
}
}
Similarly in stream context:
http {
# Examples of connection options:
# docker_endpoint http://127.0.0.1:2375;
# docker_endpoint https://127.0.0.1:2376;
docker_endpoint unix:/var/run/docker.sock;
# maximum Docker response buffer size (optional)
# docker_max_object_size 128k;
}
stream {
upstream u {
zone z 1m;
}
server {
listen 12345;
proxy_pass u;
}
}
Upon receiving an event for a container,
Angie looks for labels of the form
angie.http.upstreams.<name>.port=<port> (for HTTP context)
or angie.stream.upstreams.<name>.port=<port> (for stream context).
When a label is present, the container's address in the specified Docker network
(or the first available one if the angie.network label is not specified)
is added to the corresponding proxied server group.
If a container stops or is removed, the server is removed from the group;
if a container is paused, the server is marked as down.
Fragment of a docker-compose.yml file with labels that Angie recognizes:
services:
myapp:
image: myapp:latest
labels:
- "angie.http.upstreams.u.port=8080"
- "angie.network=my_bridge"
- "angie.http.upstreams.u.weight=2"
- "angie.http.upstreams.u.max_conns=50"
- "angie.http.upstreams.u.max_fails=3"
- "angie.http.upstreams.u.fail_timeout=10s"
- "angie.http.upstreams.u.backup=true"
Labels#
Labels specify server parameters in the proxied server group
similar to the arguments of the server directive:
Label | Purpose |
|---|---|
| Container port that Angie will connect to;
the container itself is added to the group named |
| Name of the Docker network from which to take the container's IP address. |
| Value of the |
| Maximum number of simultaneous connections ( |
| Threshold for failed attempts ( |
| Interval for counting failed attempts ( |
| Marks the server as |
| Sets a custom server identifier ( |
| Enables |
Directives#
docker_endpoint#
Specifies the method of connecting to the Docker daemon and enables tracking of container events. The following options are supported:
| Connection via Unix socket (e.g., |
| Connection via HTTP or HTTPS to a remote Docker API. |
The connection can be additionally configured using the client context,
where the module adds two named location blocks:
@docker_eventsis used to receive container events;@docker_containers— to get container information.
By default, they contain the proxy_pass directive with the connection address and several other optimal default settings, to which other settings from the Proxy module can be added.
If the directive is specified, Angie opens a connection to Docker using the specified method, requests a list of running containers, analyzes their labels and processes all subsequent container events, adding or removing servers in proxied server groups according to the labels.
Tip
To access the Docker daemon via Unix socket
(/var/run/docker.sock or another),
the user which Angie runs as
must have read and write permissions for this socket.
docker_max_object_size#
Sets the maximum buffer size that is used for both JSON responses to Docker requests and for the container event stream.
For regular requests (API version, container list, container information): the entire response must fit in the buffer, otherwise an error occurs.
For container events, streaming processing is used with buffer reuse, which allows processing an unlimited stream of events.
The typical value of 64k is sufficient for approximately 25 containers.
When Docker API connection errors or response processing errors occur, the module automatically retries at specific time intervals. The maximum number of retry attempts for getting information about a specific container is limited to two additional attempts; after that, the module stops attempting for that container.
Content