Upstream

Proporciona un contexto para describir grupos de servidores que pueden usarse en la directiva proxy_pass.

Ejemplo de configuración

upstream backend {
    hash $remote_addr consistent;
    zone backend 1m;

    server backend1.example.com:1935  weight=5;
    server unix:/tmp/backend3;
    server backend3.example.com       service=_example._tcp resolve;

    server backup1.example.com:1935   backup;
    server backup2.example.com:1935   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    listen 1936;
    proxy_pass backend;
}

Directivas

upstream

Sintaxis	upstream nombre { ... }
Predeterminado	—
Contexto	stream

Describe un grupo de servidores. Los servidores pueden escuchar en diferentes puertos. Además, se pueden mezclar servidores que escuchen en sockets TCP y de dominio UNIX.

Ejemplo:

upstream backend {
    server backend1.example.com:1935 weight=5;
    server 127.0.0.1:1935            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:1935 resolve;

    server backup1.example.com:1935  backup;
}

De forma predeterminada, las conexiones se distribuyen entre los servidores utilizando un método de balanceo round-robin ponderado. En el ejemplo anterior, cada 7 conexiones se distribuyen de la siguiente forma: 5 conexiones van a backend1.example.com:1935 y una conexión a cada uno de los servidores segundo y tercero.

Si ocurre un error durante la comunicación con un servidor, la conexión se pasará al siguiente servidor, y así sucesivamente hasta que se prueben todos los servidores en funcionamiento. Si la comunicación con todos los servidores falla, la conexión se cerrará.

server

Sintaxis	server dirección [parámetros];
Predeterminado	—
Contexto	upstream

Define la dirección y otros parámetros de un servidor. La dirección puede especificarse como un nombre de dominio o una dirección IP con un puerto obligatorio, o como una ruta de socket de dominio UNIX especificada tras el prefijo unix:. Un nombre de dominio que resuelva en varias direcciones IP define múltiples servidores a la vez.

Se pueden definir los siguientes parámetros:

weight=número	Establece el peso del servidor; por defecto, 1.
max_conns=número	Limita el número máximo de conexiones activas simultáneas al servidor proxy. El valor por defecto es 0, lo que significa que no hay límite. Si el grupo de servidores no reside en la memoria compartida, la limitación funciona por cada proceso worker.

max_fails=número — establece el número de intentos fallidos de comunicación con el servidor que deben ocurrir en el período definido por fail_timeout para considerar al servidor como no disponible; luego se reintenta tras el mismo período.

Aquí, un intento fallido es un error o timeout al establecer una conexión con el servidor.

Nota

Si una directiva server en un grupo resuelve en varios servidores, su configuración max_fails se aplica a cada servidor individualmente.

Si un upstream contiene solo un servidor después de que todas sus directivas server se resuelvan, la configuración max_fails no tiene efecto y será ignorada.

max_fails=1	Número de intentos por defecto.
max_fails=0	Desactiva el cómputo de intentos.

fail_timeout=tiempo — establece el período de tiempo durante el cual debe ocurrir un número especificado de intentos fallidos de comunicación con el servidor (max_fails) para considerarlo no disponible. El servidor permanece no disponible durante la misma cantidad de tiempo antes de que se vuelva a intentar.

Por defecto, está configurado en 10 segundos.

Nota

Si una directiva server en un grupo resuelve en varios servidores, su configuración fail_timeout se aplica a cada servidor individualmente.

Si un upstream contiene solo un servidor después de que todas sus directivas server se resuelvan, la configuración fail_timeout no tiene efecto y será ignorada.

backup	Marca el servidor como servidor de respaldo. Se le pasarán peticiones cuando los servidores principales no estén disponibles.
down	Marca el servidor como no disponible de forma permanente.
drain (PRO)	Marca el servidor como en drenaje; esto significa que solo recibe peticiones de las sesiones que fueron vinculadas anteriormente con sticky. De lo contrario, se comporta de forma similar a down.

Advertencia

El parámetro backup no puede usarse junto con los métodos de balanceo de carga hash y random.

Los parámetros down y drain son mutuamente excluyentes.

resolve

Habilita la monitorización de cambios en la lista de direcciones IP que corresponde a un nombre de dominio, actualizándola sin necesidad de recargar la configuración. El grupo debe residir en una zona de memoria compartida; además, debe definirse un resolver.

service=nombre

Habilita la resolución de registros DNS SRV y establece el nombre del servicio. Para que este parámetro funcione, también debe especificarse el parámetro resolve, sin especificar el puerto del servidor en el nombre de host. Si no hay puntos en el nombre del servicio, el nombre se forma de acuerdo con el estándar RFC: el nombre del servicio se antepone con _, luego se añade _tcp tras un punto. Así, el nombre de servicio http resultará en _http._tcp. Angie resuelve los registros SRV combinando el nombre de servicio normalizado y el nombre de host, y obteniendo la lista de servidores para la combinación vía DNS, junto con sus prioridades y pesos. Los registros SRV de máxima prioridad (los que comparten el valor de prioridad mínima) se resuelven en servidores principales, y los demás registros se convierten en servidores de respaldo. Si se configura backup con server, los registros SRV de máxima prioridad se resuelven como servidores de respaldo, y los demás registros se ignoran. El peso es similar al parámetro weight de la directiva server. Si el peso está configurado tanto en la directiva como en el registro SRV, se usa el peso definido en la directiva.

Este ejemplo buscará el registro _http._tcp.backend.example.com:

server backend.example.com service=http resolve;

sid=id

Establece el ID del servidor en el grupo. Si el parámetro no se especifica, el ID se establece como un hash MD5 hexadecimal de la dirección IP y el puerto o de la ruta del socket de dominio UNIX.

slow_start=tiempo

Establece el tiempo que tarda un servidor en recuperar su peso al volver a estar en servicio con los métodos de balanceo de carga round-robin o least_conn. Si el parámetro está configurado y un servidor vuelve a considerarse saludable tras un fallo según max_fails y upstream_probe (PRO), el servidor recupera gradualmente su peso designado durante el período de tiempo especificado. Si el parámetro no está configurado, en una situación similar el servidor comienza a trabajar inmediatamente con su peso designado.

Nota

Si solo se especifica un server en el upstream, slow_start no tiene efecto y será ignorado.

state (PRO)

Sintaxis	state archivo;
Predeterminado	—
Contexto	upstream

Especifica el archivo donde se almacena de forma persistente la lista de servidores del upstream. Al instalar desde nuestros paquetes, se crea un directorio dedicado /var/lib/angie/state/ (/var/db/angie/state/ en FreeBSD) con los permisos adecuados para almacenar dichos archivos, por lo que solo es necesario añadir el nombre de archivo en la configuración:

upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<NOMBRE DE ARCHIVO>;
}

El formato de la lista de servidores aquí es similar a s_server. El contenido del archivo cambia siempre que los servidores se modifiquen en la sección /config/stream/upstreams/ mediante la API de configuración. El archivo se lee al iniciar Angie o al recargar la configuración.

Advertencia

Para usar la directiva state en un bloque upstream, no debe haber directivas server en él, pero se requiere una zona de memoria compartida (zone).

zone

Sintaxis	zone nombre [tamaño];
Predeterminado	—
Contexto	upstream

Define el nombre y tamaño de la zona de memoria compartida que almacena la configuración y el estado en tiempo de ejecución del grupo, compartido entre los procesos worker. Varios grupos pueden usar la misma zona. En este caso, basta con especificar el tamaño una sola vez.

backup_switch (PRO)

Sintaxis	backup_switch permanent[=tiempo];
Predeterminado	—
Contexto	upstream

La directiva habilita la capacidad de iniciar la selección de servidores no desde el grupo principal, sino desde el grupo activo, es decir, aquel en el que previamente se encontró un servidor con éxito. Si no se puede encontrar un servidor en el grupo activo para la siguiente petición, y la búsqueda se traslada al grupo de respaldo, este grupo de respaldo se convierte en activo, y las siguientes peticiones se dirigen primero a los servidores de este grupo.

Si se define el parámetro permanent sin un valor de tiempo, el grupo permanece activo tras la selección, y no se produce la re-comprobación automática de grupos con niveles de prioridad más bajos. Si se especifica tiempo, el estado activo del grupo expira tras el intervalo definido, y el balanceador de carga vuelve a comprobar los grupos con niveles de prioridad más bajos, retornando a ellos si los servidores funcionan normalmente.

Ejemplo:

upstream media_backend {
    server primary1.example.com:1935;
    server primary2.example.com:1935;

    server reserve1.example.com:1935 backup;
    server reserve2.example.com:1935 backup;

    backup_switch permanent=2m;
}

Si el balanceador de carga cambia de los servidores principales al grupo de respaldo, todas las peticiones posteriores son gestionadas por este grupo de respaldo durante 2 minutos. Tras expirar los 2 minutos, el balanceador vuelve a comprobar los servidores principales y los hace activos de nuevo si funcionan con normalidad.

feedback (PRO)

Sintaxis	feedback variable [inverse] [factor=número] [account=variable_condición];
Predeterminado	—
Contexto	upstream

Habilita un mecanismo de balanceo de carga basado en retroalimentación para el upstream. Ajusta dinámicamente las decisiones de balanceo de carga multiplicando el peso de cada servidor proxy por el valor promedio de retroalimentación, que cambia con el tiempo según el valor de variable y está sujeto a una condición opcional.

Se pueden especificar los siguientes parámetros:

variable	La variable de la que se toma el valor de retroalimentación. Debe representar una métrica de rendimiento o salud; se asume que la proporciona el servidor. El valor se evalúa con cada respuesta del servidor y se incorpora al promedio móvil según la configuración de inverse y factor.
inverse	Si se establece el parámetro, el valor de retroalimentación se interpreta de forma inversa: valores más bajos indican mejor rendimiento.
factor	El factor por el cual se pondera el valor de retroalimentación al calcular el promedio. Valores válidos son enteros de 0 a 99. El valor por defecto es 90. El promedio se calcula usando la fórmula de suavizado exponencial. Cuanto mayor sea el factor, menos afectarán los valores nuevos al promedio; si se especifica 90, se tomará el 90% del valor anterior y solo el 10% del valor nuevo.
account	Especifica una variable de condición que controla cómo se contabilizan las conexiones en el cálculo. El valor promedio se actualiza con el valor de retroalimentación solo si la variable de condición no es igual a "" ni a "0". Nota Por defecto, el tráfico de las sondas no se incluye en el cálculo; combinar la variable $upstream_probe con account permite incluirlas o incluso excluir todo lo demás.

Ejemplo:

upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com:1935  weight=1;
    server backend2.example.com:1935  weight=2;
}

map $protocol $feedback_value {
    "TCP"                      100;
    "UDP"                      75;
    default                    10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}

Esta configuración clasifica los servidores por niveles de retroalimentación basados en los protocolos usados en sesiones individuales, y además añade una condición sobre $upstream_probe para contabilizar solo las sondas de high_priority o las sesiones de clientes normales.

hash

Sintaxis	hash clave [consistent];
Predeterminado	—
Contexto	upstream

Especifica un método de balanceo de carga para el grupo donde la asignación cliente-servidor se determina usando un valor hash de la clave. La clave puede contener texto, variables y sus combinaciones. Tenga en cuenta que cualquier adición o eliminación de servidores del grupo puede resultar en la reasignación de la mayoría de las claves a diferentes servidores. El método es compatible con la librería Perl Cache::Memcached.

Ejemplo de uso:

hash $remote_addr;

Al usar nombres de dominio que se resuelven en múltiples direcciones IP (por ejemplo, con el parámetro resolve), el servidor no ordena las direcciones recibidas, por lo que su orden puede diferir entre diferentes servidores, lo que afecta a la distribución de clientes. Para garantizar una distribución consistente, use el parámetro consistent.

Si se especifica el parámetro consistent, se usará el método de hash consistente ketama en lugar del método anterior. Este método garantiza que, al añadir o eliminar un servidor del grupo, solo un número mínimo de claves se reasignará a otros servidores. Usar el método para servidores de caché proporciona una mayor tasa de aciertos de caché. El método es compatible con la librería Perl Cache::Memcached::Fast con el parámetro ketama_points configurado en 160.

least_conn

Sintaxis	least_conn;
Predeterminado	—
Contexto	upstream

Especifica un método de balanceo de carga para el grupo donde una conexión se pasa al servidor con el menor número de conexiones activas, teniendo en cuenta los pesos de los servidores. Si varios servidores son adecuados, se seleccionan cíclicamente (round-robin) con sus pesos tenidos en cuenta.

least_time (PRO)

Sintaxis	least_time connect | first_byte | last_byte [factor=número] [account=variable_condición];
Predeterminado	—
Contexto	upstream

Especifica un método de balanceo de carga para el grupo donde la probabilidad de pasar una conexión a un servidor activo es inversamente proporcional a su tiempo promedio de respuesta; cuanto menor sea, más conexiones recibirá el servidor.

connect	La directiva tiene en cuenta el tiempo promedio para establecer una conexión.
first_byte	La directiva usa el tiempo promedio para recibir el primer byte de la respuesta.
last_byte	La directiva usa el tiempo promedio para recibir la respuesta completa.

factor	Realiza la misma función que response_time_factor (PRO), y lo anula si se especifica el parámetro.
account	Especifica una variable de condición que controla qué conexiones se contabilizan en el cálculo. El valor promedio se actualiza solo si la variable de condición de la conexión no es igual a "" ni a "0". Nota Por defecto, las sondas no se incluyen en el cálculo; combinar la variable $upstream_probe con account permite incluirlas o incluso excluir todo lo demás.

Los valores actuales se presentan como connect_time, first_byte_time y last_byte_time en el objeto health del servidor entre las métricas de upstream en la API.

random

Sintaxis	random [two];
Predeterminado	—
Contexto	upstream

Especifica un método de balanceo de carga para el grupo donde una conexión se pasa a un servidor seleccionado aleatoriamente, teniendo en cuenta los pesos de los servidores.

Si se especifica el parámetro opcional two, Angie selecciona aleatoriamente dos servidores y luego elige un servidor usando el método especificado. El método predeterminado es least_conn, que pasa la conexión al servidor con el menor número de conexiones activas.

response_time_factor (PRO)

Sintaxis	response_time_factor número;
Predeterminado	response_time_factor 90;
Contexto	upstream

Especifica para el método de balanceo de carga least_time (PRO) el factor de suavizado para el valor anterior al calcular el tiempo promedio de respuesta usando la fórmula de media móvil ponderada exponencialmente.

Cuanto mayor sea el número especificado, menos afectarán los valores nuevos al promedio; si se especifica 90, se tomará el 90% del valor anterior y solo el 10% del valor nuevo. Los valores válidos son de 0 a 99 inclusive.

Los resultados actuales del cálculo se presentan como connect_time (tiempo para establecer una conexión), first_byte_time (tiempo para recibir el primer byte de la respuesta) y last_byte_time (tiempo para recibir la respuesta completa) en el objeto health del servidor entre las métricas de upstream en la API.

Nota

Solo se consideran las respuestas exitosas en el cálculo; lo que constituye una respuesta no exitosa se determina por las directivas proxy_next_upstream.

sticky

Sintaxis	sticky route $variable...; sticky learn zone=zona create=$var_create1... lookup=$var_lookup1... [connect] [norefresh] [timeout=tiempo]; sticky learn lookup=$var_lookup1... remote_action=uri remote_result=$var_remoto [remote_uri=uri];
Predeterminado	—
Contexto	upstream

Configura sesiones persistentes entre clientes y servidores upstream, dependiendo del modo especificado en el primer parámetro. Para retirar gradualmente servidores con sticky de la rotación, puede usarse la opción drain (PRO) en el bloque server.

Advertencia

La directiva sticky debe aparecer después de todas las directivas de método de balanceo de carga, de lo contrario no funcionará.

Modo routeModo learn (PRO)Modo learn con remote_action (PRO 1.10.0+)

Este modo utiliza identificadores de ruta predefinidos que pueden estar integrados en propiedades de conexión accesibles para Angie. Es menos flexible ya que depende de valores predefinidos, pero es más adecuado si dichos identificadores ya están en uso.

Aquí, al establecer una conexión, el servidor upstream puede asignar una ruta al cliente y devolver su identificador de una manera conocida por ambas partes. El identificador de ruta debe usar el valor del parámetro sid de la directiva server. Tenga en cuenta que el parámetro se hashea adicionalmente si se especifica la directiva sticky_secret.

Las conexiones posteriores de clientes que deseen usar esta ruta deben contener el identificador emitido por el servidor, de tal manera que termine en variables de Angie.

Los parámetros de la directiva especifican variables para el enrutamiento. Para seleccionar el servidor al que se dirige la conexión entrante, se usa la primera variable no vacía; luego se compara con el parámetro sid de la directiva server. Si la selección del servidor falla o el servidor seleccionado no puede aceptar la conexión, se seleccionará otro servidor según el método de balanceo de carga configurado.

Aquí Angie busca el identificador de ruta en la variable $route, que recibe su valor basándose en $ssl_preread_server_name (tenga en cuenta que ssl_preread debe estar habilitado):

stream {

    map $ssl_preread_server_name $route {

        a.example.com            a;
        b.example.com            b;
        default                  "";
    }

    upstream backend {

        server 127.0.0.1:8081 sid=a;
        server 127.0.0.1:8082 sid=b;

        sticky route $route;
    }

    server {

        listen 127.0.0.1:8080;

        ssl_preread on;

        proxy_pass backend;
    }
}

La directiva sticky tiene en cuenta el estado de los servidores en upstream:

• Los servidores marcados como down o temporalmente no disponibles debido a fallos se excluyen de la selección.

• Los servidores que han alcanzado el número máximo de conexiones (al usar max_conns) se omiten temporalmente.

• Los servidores con la opción drain (PRO) pueden ser seleccionados para crear nuevas sesiones en modo sticky cuando los identificadores coinciden.

• Si un servidor previamente no disponible se recupera, sticky reanuda automáticamente su uso.

El comportamiento de sticky puede configurarse adicionalmente con las directivas sticky_secret y sticky_strict. Si sticky no logra seleccionar un servidor o no está disponible, la solicitud se manejará según el método de balanceo de carga seleccionado, a menos que la directiva sticky_strict esté habilitada. En modo sticky_strict on;, la solicitud se rechaza con un error.

Las zonas de memoria compartida especificadas en el parámetro zone de la directiva sticky no pueden compartirse entre diferentes grupos upstream; cada grupo debe usar su propia zona.

sticky_secret

Sintaxis	sticky_secret cadena;
Predeterminado	—
Contexto	upstream

Añade cadena como sal a la función hash MD5 para la directiva sticky en modo route. Cadena puede contener variables, por ejemplo $remote_addr:

upstream backend {
    server 127.0.0.1:8081 sid=a;
    server 127.0.0.1:8082 sid=b;

    sticky route $route;
    sticky_secret my_secret.$remote_addr;
}

La sal se añade después del valor hasheado; para verificar independientemente el mecanismo de hashing:

$ echo -n "<VALOR><SAL>" | md5sum

sticky_strict

Sintaxis	sticky_strict on | off;
Predeterminado	sticky_strict off;
Contexto	upstream

Cuando está habilitado, Angie devuelve un error de conexión al cliente si el servidor deseado no está disponible, en lugar de recurrir a otro servidor disponible, que es el comportamiento predeterminado cuando no se encuentra un servidor coincidente.

Variables integradas

El módulo stream_upstream admite las siguientes variables integradas:

$sticky_sessid

Se usa con remote_action en sticky; almacena el identificador de sesión inicial tomado de lookup.

$sticky_sid

Se usa con remote_action en sticky; almacena el identificador del servidor previamente asociado con la sesión.

sticky_sid contiene el valor del parámetro sid= de la directiva server en el bloque upstream, si se especifica, o el hash MD5 del nombre del servidor.

$upstream_addr

almacena la dirección IP y el puerto, o la ruta al socket de dominio UNIX del servidor upstream. Si se contactaron varios servidores durante el proxying, sus direcciones se separan por comas, por ejemplo:

192.168.1.1:1935, 192.168.1.2:1935, unix:/tmp/sock

Si no se puede seleccionar un servidor, la variable conserva el nombre del grupo de servidores.

$upstream_bytes_received

número de bytes recibidos desde un servidor upstream. Los valores de varias conexiones se separan por comas y dos puntos como las direcciones en la variable $upstream_addr.

$upstream_bytes_sent

número de bytes enviados a un servidor upstream. Los valores de varias conexiones se separan por comas y dos puntos como las direcciones en la variable $upstream_addr.

$upstream_connect_time

tiempo para conectarse al servidor upstream; el tiempo se mantiene en segundos con resolución de milisegundos. Los tiempos de varias conexiones se separan por comas y dos puntos como las direcciones en la variable $upstream_addr.

$upstream_first_byte_time

tiempo para recibir el primer byte de datos; el tiempo se mantiene en segundos con resolución de milisegundos. Los tiempos de varias conexiones se separan por comas como las direcciones en la variable $upstream_addr.

$upstream_session_time

duración de la sesión en segundos con resolución de milisegundos. Los tiempos de varias conexiones se separan por comas como las direcciones en la variable $upstream_addr.

$upstream_sticky_status

Estado de las conexiones sticky.

""	Conexión dirigida a un grupo de servidores donde sticky no está habilitado.
NEW	Conexión que no contiene información sticky.
HIT	Conexión con información sticky dirigida al servidor deseado.
MISS	Conexión con información sticky dirigida a un servidor seleccionado por el algoritmo de balanceo de carga.

Los valores de múltiples conexiones se separan por comas y dos puntos, de manera similar a las direcciones en la variable $upstream_addr.