Docker#

Added in version 1.10.0.

El módulo proporciona configuración dinámica de grupos de servidores proxy en los contextos HTTP y stream basándose en etiquetas de contenedores Docker. Para que la funcionalidad funcione, debe configurarse una zona de memoria compartida en el grupo (consulte la descripción de zone para http y stream).

Nota

El módulo admite trabajar tanto con Docker como con sus alternativas, como Podman, que implementan una API compatible. La versión recomendada de Podman es 4.9.3 o superior.

El módulo se conecta al daemon de Docker mediante la API, cuyo método de interacción se especifica mediante la directiva docker_endpoint. Después de obtener una lista de contenedores en ejecución, Angie los analiza para detectar la presencia de etiquetas adecuadas. Las etiquetas identifican el grupo upstream de destino y determinan si la dirección del servidor incluye un puerto del contenedor. Para cada grupo correspondiente, Angie añade la dirección del contenedor en la red Docker seleccionada y aplica los demás parámetros de las etiquetas al bloque upstream correspondiente en la configuración de Angie.

Nota

El mismo contenedor puede añadirse a varios grupos upstream. Para ello, simplemente especifique varios conjuntos de etiquetas con diferentes nombres de grupo y valores de la etiqueta port.

Esto es especialmente útil si el contenedor ejecuta varios servicios diferentes en diferentes puertos; cada servicio puede asociarse con su propio grupo.

El módulo luego se suscribe a eventos del ciclo de vida del contenedor y comienza a actualizar la configuración del servidor proxy sin recargar Angie:

al iniciar un contenedor con etiquetas adecuadas, su dirección IP interna se añade al grupo especificado;
al detener o eliminar un contenedor, se elimina automáticamente del grupo;
al pausar un contenedor con el comando docker pause, el servidor se marca como down, y con docker unpause — como up.

Cuando se compila desde el código fuente, este módulo se compila por defecto; puede deshabilitarse con la opción de compilación --without-http_docker_module.

En paquetes e imágenes de nuestros repositorios, el módulo está incluido en la compilación.

Ejemplo de configuración#

Las directivas del módulo siempre se ubican en el contexto http, pero los grupos de servidores proxy pueden definirse tanto en el contexto http como en el contexto stream.

Ejemplo de configuración para 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;
        }
    }
}

De manera similar en el contexto stream:

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;
    }
}

Al recibir un evento para un contenedor, Angie busca etiquetas de la forma angie.http.upstreams.<name>.port=<port> (para el contexto HTTP) o angie.stream.upstreams.<name>.port=<port> (para el contexto stream). Cuando hay una etiqueta presente, la dirección del contenedor en la red Docker seleccionada se añade al grupo de servidores proxy correspondiente. La red se toma de la etiqueta angie.(http|stream).upstreams.<name>.network, si está definida para ese upstream; de lo contrario, de la etiqueta angie.network del contenedor; si no hay ninguna etiqueta, se usa la primera red disponible.

Si un contenedor se detiene o se elimina, el servidor se elimina del grupo; si un contenedor se pausa, el servidor se marca como down.

Fragmento de un archivo docker-compose.yml con etiquetas que Angie reconoce:

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"

Etiquetas#

Las etiquetas especifican parámetros del servidor en el grupo de servidores proxy de manera similar a los argumentos de la directiva server:

Etiqueta	Propósito
`angie.(http\|stream).upstreams.<name>.port=<value>` (obligatorio)	Añade el contenedor al grupo llamado `<name>`. Como valor se indica el puerto numérico del contenedor al que Angie se conecta, o `*` para un grupo stream sin puerto (PRO).
`angie.network=<docker-network>`	Nombre de la red Docker de la cual tomar la dirección IP del contenedor.
`angie.(http\|stream).upstreams.<name>.network=<docker-network>`	Nombre de la red Docker para este upstream proxy; tiene prioridad sobre la etiqueta `angie.network`.
`angie.(http\|stream).upstreams.<name>.weight=<n>`	Valor del parámetro `weight`.
`angie.(http\|stream).upstreams.<name>.max_conns=<n>`	Número máximo de conexiones simultáneas (`max_conns`).
`angie.(http\|stream).upstreams.<name>.max_fails=<n>`	Umbral para intentos fallidos (`max_fails`).
`angie.(http\|stream).upstreams.<name>.fail_timeout=<t>`	Intervalo para contar intentos fallidos (`fail_timeout`).
`angie.(http\|stream).upstreams.<name>.backup=true\|false`	Marca el servidor como `backup`.
`angie.(http\|stream).upstreams.<name>.sid=<string>`	Establece un identificador de servidor personalizado (`sid`) para el servidor proxy.
`angie.(http\|stream).upstreams.<name>.slow_start=<time>`	Habilita el modo `slow_start` con un período de tiempo configurable.

Directivas#

docker_endpoint#

Sintaxis	`docker_endpoint` URL;
Predeterminado	—
Contexto	http

Especifica el método de conexión al daemon de Docker y habilita el seguimiento de eventos de contenedores. Se admiten las siguientes opciones:

`unix:/var/run/docker.sock`	Conexión a través de socket Unix (por ejemplo, `/var/run/docker.sock`).
`http://host:port`, `https://host:port`	Conexión a través de HTTP o HTTPS a una API remota de Docker.

La conexión puede configurarse adicionalmente utilizando el contexto client, donde el módulo añade dos bloques location con nombre:

@docker_events se utiliza para recibir eventos de contenedores;
@docker_containers — para obtener información de contenedores.

Por defecto, contienen la directiva proxy_pass con la dirección de conexión y varias otras configuraciones predeterminadas óptimas, a las que se pueden añadir otras configuraciones del módulo Proxy.

Si se especifica la directiva, Angie abre una conexión a Docker utilizando el método especificado, solicita una lista de contenedores en ejecución, analiza sus etiquetas y procesa todos los eventos de contenedores posteriores, añadiendo o eliminando servidores en grupos de servidores proxy según las etiquetas.

Truco

Para acceder al daemon de Docker a través del socket Unix (/var/run/docker.sock u otro), el usuario con el que se ejecuta Angie debe tener permisos de lectura y escritura para este socket.

docker_max_object_size#

Sintaxis	`docker_max_object_size` `<size>`;
Predeterminado	`64k`
Contexto	http

Establece el tamaño máximo del búfer que se utiliza tanto para las respuestas JSON a las solicitudes de Docker como para el flujo de eventos de contenedores.

Para solicitudes regulares (versión de API, lista de contenedores, información de contenedor): la respuesta completa debe caber en el búfer, de lo contrario se produce un error.
Para eventos de contenedores, se utiliza procesamiento en streaming con reutilización del búfer, lo que permite procesar un flujo ilimitado de eventos.

El valor típico de 64k es suficiente para aproximadamente 25 contenedores.

Cuando se producen errores de conexión a la API de Docker o errores de procesamiento de respuestas, el módulo reintenta automáticamente en intervalos de tiempo específicos. El número máximo de intentos de reintento para obtener información sobre un contenedor específico está limitado a dos intentos adicionales; después de eso, el módulo deja de intentarlo para ese contenedor.