Upstream

Fornece um contexto para descrever grupos de servidores que podem ser usados nas diretivas proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass e grpc_pass.

Exemplo de Configuração

upstream backend {
    zone backend 1m;
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server backend3.example.com       service=_example._tcp resolve;
    server unix:/tmp/backend3;

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

resolver 127.0.0.53 status_zone=resolver;

server {
    location / {
        proxy_pass http://backend;
    }
}

Diretivas

backup_switch (PRO)

Adicionado na versão 1.9.0: PRO

Sintaxe	backup_switch permanent[=time];
Padrão	—
Contexto	upstream

A diretiva habilita a capacidade de iniciar a seleção de servidor não a partir do grupo primário, mas a partir do grupo ativo, ou seja, aquele onde um servidor foi encontrado com sucesso na última vez. Se um servidor não puder ser encontrado no grupo ativo para a próxima requisição, e a busca se mover para o grupo de backup, então este grupo se torna ativo, e as requisições subsequentes são direcionadas primeiro para servidores neste grupo.

Se o parâmetro permanent for definido sem um valor de time, o grupo permanece ativo após a seleção, e a reverificação automática de grupos com níveis mais baixos não ocorre. Se time for especificado, o status ativo do grupo expira após o intervalo especificado, e o balanceador verifica novamente grupos com níveis mais baixos, retornando a eles se os servidores estiverem funcionando normalmente.

Exemplo:

upstream my_backend {
    server primary1.example.com;
    server primary2.example.com;

    server backup1.example.com backup;
    server backup2.example.com backup;

    backup_switch permanent=2m;
}

Se o balanceador alternar dos servidores primários para o grupo de backup, todas as requisições subsequentes são tratadas por este grupo de backup por 2 minutos. Após 2 minutos decorrerem, o balanceador verifica novamente os servidores primários e os torna ativos novamente se estiverem funcionando normalmente.

bind_conn (PRO)

Sintaxe	bind_conn value;
Padrão	—
Contexto	upstream

Permite vincular uma conexão do servidor a uma conexão do cliente quando o value, especificado como uma string de variáveis, se torna diferente de "" e "0".

Aviso

A diretiva bind_conn deve ser usada após todas as diretivas que definem um método de balanceamento de carga, caso contrário não funcionará. Se for usada junto com a diretiva sticky, então bind_conn deve vir após sticky.

Aviso

Ao usar a diretiva, as configurações do módulo Proxy devem permitir o uso de conexões persistentes, por exemplo:

proxy_http_version 1.1;
proxy_set_header Connection "";

Um caso de uso típico para a diretiva é fazer proxy de conexões com autenticação NTLM, onde é necessário garantir a vinculação cliente-servidor no início da negociação:

map $http_authorization   $ntlm {
    ~*^N(?:TLM|egotiate)  1;
}

upstream ntlm_backend {
    server 127.0.0.1:8080;
    bind_conn $ntlm;
}

server {
    # ...
    location / {
        proxy_pass http://ntlm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        # ...
    }
}

feedback (PRO)

Sintaxe	feedback variable [inverse] [factor=number] [account=condition_variable] [last_byte];
Padrão	—
Contexto	upstream

Configura um mecanismo de balanceamento de carga baseado em feedback no upstream. Ele ajusta dinamicamente as decisões de balanceamento multiplicando o peso de cada servidor proxy pelo valor médio de feedback, que muda ao longo do tempo dependendo do valor da variable e está sujeito a uma condição opcional.

Os seguintes parâmetros podem ser especificados:

variable	A variável da qual o valor de feedback é obtido. Ela deve representar uma métrica de desempenho ou saúde; assume-se que o servidor a forneça em cabeçalhos ou de outra forma. O valor é avaliado com cada resposta do servidor e é considerado na média móvel de acordo com as configurações inverse e factor.
inverse	Se o parâmetro for definido, o valor de feedback é interpretado inversamente: valores menores indicam melhor desempenho.
factor	O fator pelo qual o valor de feedback é considerado ao calcular a média. Valores válidos são inteiros de 0 a 99. O padrão é 90. A média é calculada usando a fórmula de suavização exponencial. Quanto maior o fator, menos os novos valores afetam a média; se 90 for especificado, então 90% do valor anterior e apenas 10% do novo valor serão considerados.
account	Especifica uma variável de condição que controla quais respostas são consideradas no cálculo. O valor médio é atualizado com o valor de feedback da resposta apenas se a variável de condição dessa resposta não for igual a "" ou "0". Nota Por padrão, respostas durante verificações ativas não são incluídas no cálculo; combinar a variável $upstream_probe com account permite incluir essas respostas ou até mesmo excluir todo o resto.
last_byte	Permite processar dados do servidor proxy após receber a resposta completa, não apenas o cabeçalho.

Exemplo:

upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_http_custom_score $feedback_value {
    "high"                      100;
    "medium"                    75;
    "low"                       50;
    default                     10;
}

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

Esta configuração categoriza respostas do servidor por níveis de feedback baseados em pontuações específicas dos campos de cabeçalho de resposta, e também adiciona uma condição em $upstream_probe para considerar apenas respostas da verificação ativa high_priority ou respostas a requisições regulares de clientes.

hash

Sintaxe	hash key [consistent];
Padrão	—
Contexto	upstream

Especifica um método de balanceamento de carga para um grupo de servidores onde o mapeamento cliente-servidor é determinado usando o valor da chave hash. A chave pode conter texto, variáveis e suas combinações. Note que adicionar ou remover um servidor do grupo pode resultar no remapeamento da maioria das chaves para servidores diferentes. O método é compatível com a biblioteca Perl Cache::Memcached.

hash $remote_addr;

Ao usar nomes de domínio que resolvem para múltiplos endereços IP (por exemplo, com o parâmetro resolve), o servidor não ordena os endereços recebidos, então sua ordem pode diferir entre diferentes servidores, o que afeta a distribuição de clientes. Para garantir distribuição consistente, use o parâmetro consistent.

Se o parâmetro consistent for especificado, o método de hash consistente ketama será usado. O método garante que apenas algumas chaves serão remapeadas para servidores diferentes quando um servidor for adicionado ou removido do grupo. Isso ajuda a alcançar uma taxa de acerto de cache mais alta para servidores de cache. O método é compatível com a biblioteca Perl Cache::Memcached::Fast com o parâmetro ketama_points definido como 160.

ip_hash

Sintaxe	ip_hash;
Padrão	—
Contexto	upstream

Especifica um método de balanceamento de carga para o grupo onde as requisições são distribuídas entre servidores com base nos endereços IP dos clientes. Os primeiros três octetos do endereço IPv4 do cliente ou todo o endereço IPv6 são usados como chave de hash. O método garante que requisições do mesmo cliente sempre sejam passadas para o mesmo servidor, exceto quando este servidor estiver indisponível. Neste caso, as requisições do cliente serão passadas para outro servidor. Muito provavelmente este também será o mesmo servidor.

Se um dos servidores precisar ser temporariamente removido, ele deve ser marcado com o parâmetro down para preservar o hash atual dos endereços IP dos clientes:

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

keepalive

Sintaxe	keepalive connections;
Padrão	—
Contexto	upstream

Ativa o cache de conexões para servidores upstream.

O parâmetro connections define o número máximo de conexões keepalive ociosas para servidores upstream que são preservadas no cache de cada processo worker. Quando este número é excedido, as conexões menos recentemente usadas são fechadas.

Nota

Deve ser particularmente notado que a diretiva keepalive não limita o número total de conexões para servidores upstream que os processos worker do Angie podem abrir. O parâmetro connections deve ser definido baixo o suficiente para permitir que os servidores upstream processem novas conexões de entrada também.

Aviso

A diretiva keepalive deve ser usada após todas as diretivas que definem um método de balanceamento de carga; caso contrário, não funcionará.

Exemplo de configuração de upstream memcached com conexões keepalive:

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    #...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

Para HTTP, a diretiva proxy_http_version deve ser definida como "1.1" e o campo de cabeçalho Connection deve ser limpo:

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    #...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    #    ...
    }
}

Nota

Alternativamente, conexões persistentes HTTP/1.0 podem ser usadas passando o campo de cabeçalho "Connection: Keep-Alive" para um servidor upstream, embora este método não seja recomendado.

Para servidores FastCGI, é necessário definir fastcgi_keep_conn para que as conexões keepalive funcionem:

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    #...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
    #    ...
    }
}

Nota

Os protocolos SCGI e uwsgi não têm um conceito de conexões keepalive.

keepalive_requests

Sintaxe	keepalive_requests number;
Padrão	keepalive_requests 1000;
Contexto	upstream

Define o número máximo de requisições que podem ser atendidas através de uma conexão keepalive. Após o número máximo de requisições ser feito, a conexão é fechada.

Fechar conexões periodicamente é necessário para liberar alocações de memória por conexão. Portanto, usar um número máximo de requisições muito alto pode resultar em uso excessivo de memória e não é recomendado.

keepalive_time

Sintaxe	keepalive_time time;
Padrão	keepalive_time 1h;
Contexto	upstream

Limita o tempo máximo durante o qual requisições podem ser processadas através de uma conexão keepalive. Após este tempo ser alcançado, a conexão é fechada após o processamento da requisição subsequente.

keepalive_timeout

Sintaxe	keepalive_timeout timeout;
Padrão	keepalive_timeout 60s;
Contexto	upstream

Define um timeout durante o qual uma conexão keepalive ociosa para um servidor upstream permanecerá aberta.

least_conn

Sintaxe	least_conn;
Padrão	—
Contexto	upstream

Especifica que um grupo deve usar um método de balanceamento de carga onde uma requisição é passada para o servidor com o menor número de conexões ativas, levando em conta os pesos dos servidores. Se houver vários servidores assim, eles são tentados alternadamente usando um método de balanceamento round-robin ponderado.

least_time (PRO)

Sintaxe	least_time header | last_byte [factor=number] [account=condition_variable];
Padrão	—
Contexto	upstream

Especifica que o grupo deve usar um método de balanceamento de carga onde a chance de um servidor ativo receber a requisição é inversamente proporcional ao seu tempo médio de resposta; quanto menor for, mais requisições um servidor recebe.

header	A diretiva considera o tempo médio para receber cabeçalhos de resposta.
last_byte	A diretiva usa o tempo médio para receber toda a resposta.

factor	Serve ao mesmo propósito que response_time_factor (PRO) e o substitui se o parâmetro for definido.
account	Especifica uma variável de condição que controla quais respostas são incluídas no cálculo. A média é atualizada apenas se a variável de condição para a resposta não for "" ou "0". Nota Por padrão, respostas durante sondagens de saúde ativas não são incluídas no cálculo; combinar a variável $upstream_probe com account permite incluir essas respostas ou até mesmo excluir todo o resto.

Os valores atuais são apresentados como header_time (apenas cabeçalhos) e response_time (respostas completas) no objeto health do servidor entre as métricas upstream na API.

queue (PRO)

Sintaxe	queue number [timeout=time];
Padrão	—
Contexto	upstream

Se não for possível atribuir um servidor proxy a uma requisição na primeira tentativa (por exemplo, durante uma breve interrupção de serviço ou quando há um pico de carga atingindo o limite max_conns), a requisição não é rejeitada; em vez disso, o Angie tenta enfileirá-la para processamento.

O parâmetro number da diretiva define o número máximo de requisições na fila para um processo worker. Se a fila estiver cheia, um erro 502 (Bad Gateway) é retornado ao cliente.

Nota

A lógica da diretiva proxy_next_upstream também se aplica a requisições enfileiradas. Especificamente, se um servidor foi selecionado para uma requisição mas ela não pode ser entregue a ele, a requisição pode ser retornada à fila.

Se um servidor não for selecionado para processar uma requisição enfileirada dentro do tempo definido por timeout (padrão é 60 segundos), um erro 502 (Bad Gateway) é retornado ao cliente. Requisições de clientes que fecham prematuramente a conexão também são removidas da fila; há contadores para os estados de requisições passando pela fila na API.

Aviso

A diretiva queue deve ser usada após todas as diretivas que definem o método de balanceamento de carga; caso contrário, não funcionará.

random

Sintaxe	random [two];
Padrão	—
Contexto	upstream

Especifica um método de balanceamento de carga para o grupo onde uma requisição é passada para um servidor selecionado aleatoriamente, levando em conta os pesos dos servidores.

Se o parâmetro opcional two for especificado, o Angie seleciona aleatoriamente dois servidores, então seleciona um deles usando o método least_conn, onde uma requisição é passada para o servidor com o menor número de conexões ativas.

response_time_factor (PRO)

Sintaxe	response_time_factor number;
Padrão	response_time_factor 90;
Contexto	upstream

Define o fator de suavização para o valor anterior ao calcular o tempo médio de resposta para o método de balanceamento de carga least_time (PRO) usando a fórmula de média móvel exponencialmente ponderada.

Quanto maior o number especificado, menos os novos valores afetam a média; se 90 for especificado, 90% do valor anterior e apenas 10% do novo valor serão considerados. Os valores válidos variam de 0 a 99, inclusive.

Os resultados atuais do cálculo são apresentados como header_time (apenas cabeçalhos) e response_time (respostas completas) no objeto health do servidor entre as métricas upstream na API.

Nota

Apenas respostas bem-sucedidas são incluídas no cálculo; o que é considerado uma resposta mal-sucedida é determinado pelas diretivas proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream, memcached_next_upstream, e grpc_next_upstream. Além disso, o valor header_time é recalculado apenas se todos os cabeçalhos forem recebidos e processados, e response_time — apenas se toda a resposta for recebida.

server

Sintaxe	server address [parameters];
Padrão	—
Contexto	upstream

Define o endereço e outros parâmetros de um servidor. O endereço pode ser especificado como um nome de domínio ou endereço IP, com uma porta opcional, ou como um caminho de socket de domínio UNIX especificado após o prefixo unix:. Se uma porta não for especificada, a porta 80 é usada. Um nome de domínio que resolve para vários endereços IP define múltiplos servidores de uma vez.

Os seguintes parâmetros podem ser definidos:

weight=number	Define o peso do servidor. O padrão é 1.
max_conns=number	Limita o número máximo de conexões ativas simultâneas para o servidor com proxy. O valor padrão é 0, significando que não há limite. Se o grupo não residir na zona de memória compartilhada, a limitação funciona por processo worker.

Nota

Com as conexões keepalive inativas habilitadas, múltiplos processos worker, e uma zona de memória compartilhada, o número total de conexões ativas e inativas para o servidor com proxy pode exceder o valor max_conns.

max_fails=number — define o número de tentativas malsucedidas de comunicação com o servidor que devem ocorrer durante o período especificado por fail_timeout para que o servidor seja considerado indisponível; após isso, ele será verificado novamente após o mesmo período.

O que é considerado uma tentativa malsucedida é definido pelas diretivas proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream, memcached_next_upstream, e grpc_next_upstream.

Quando max_fails é excedido, o servidor também é considerado indisponível da perspectiva das upstream_probe (PRO); requisições de clientes não serão direcionadas a ele até que as verificações determinem que ele está disponível.

Nota

Se uma diretiva server em um grupo resolve em múltiplos servidores, sua configuração max_fails se aplica a cada servidor separadamente.

Se após resolver todas as diretivas server apenas um servidor permanecer no upstream, a configuração max_fails não tem efeito e será ignorada.

max_fails=1	Número padrão de tentativas;
max_fails=0	Desabilita a contabilização de tentativas.

fail_timeout=time — define o período de tempo durante o qual um número especificado de tentativas malsucedidas de comunicação com o servidor (max_fails) deve ocorrer para que o servidor seja considerado indisponível. O servidor então permanece indisponível pelo mesmo período de tempo antes de ser verificado novamente.

O valor padrão é 10 segundos.

Nota

Se uma diretiva server em um grupo resolve em múltiplos servidores, sua configuração fail_timeout se aplica a cada servidor separadamente.

Se após resolver todas as diretivas server apenas um servidor permanecer no upstream, a configuração fail_timeout não tem efeito e será ignorada.

backup	Marca o servidor como um servidor de backup. Ele receberá requisições quando os servidores primários estiverem indisponíveis. Se a diretiva backup_switch (PRO) estiver especificada, sua lógica de backup ativo também se aplica.
down	Marca o servidor como permanentemente indisponível.
drain (PRO)	Marca o servidor como em drenagem; isso significa que ele recebe apenas requisições de sessões vinculadas anteriormente via sticky. Caso contrário, o comportamento é o mesmo do modo down.

Aviso

O parâmetro backup não pode ser usado junto com os métodos de balanceamento de carga hash, ip_hash, e random.

Os parâmetros down e drain são mutuamente exclusivos.

resolve

Permite monitorar mudanças na lista de endereços IP correspondentes a um nome de domínio e atualizá-la sem recarregar a configuração. O grupo deve residir em memória compartilhada; um resolver também deve ser definido.

service=name

Habilita a resolução de registros DNS SRV e define o nome do serviço. Para que o parâmetro funcione, o parâmetro resolve deve ser especificado para o servidor, sem especificar uma porta no hostname. Se o nome do serviço não contiver um ponto, um nome é formado de acordo com o padrão RFC: o nome do serviço é prefixado com _, então _tcp é adicionado após um ponto. Assim, o nome do serviço http resulta em _http._tcp. O Angie resolve registros SRV combinando o nome do serviço normalizado e o hostname e obtendo uma lista de servidores para a combinação resultante via DNS, junto com suas prioridades e pesos. Registros SRV com a prioridade mais alta (aqueles com o menor valor de prioridade) são resolvidos como servidores primários, enquanto outros registros se tornam servidores de backup. Se backup estiver definido com server, registros SRV com a prioridade mais alta são resolvidos como servidores de backup, e outros registros são ignorados. Peso é análogo ao parâmetro weight da diretiva server. Se o peso for especificado tanto na diretiva quanto no registro SRV, o peso definido na diretiva é usado.

Neste exemplo, uma busca é realizada pelo registro _http._tcp.backend.example.com:

server backend.example.com service=http resolve;

sid=id

Define o ID do servidor no grupo. Se o parâmetro não for especificado, o ID é definido como um hash MD5 hexadecimal do endereço IP e porta ou caminho do socket UNIX.

slow_start=time

Define o tempo para recuperação gradual do peso de um servidor que retorna ao balanceamento de carga com o método round-robin ou least_conn. Se o parâmetro for definido e o servidor for considerado operacional novamente após uma falha da perspectiva de max_fails e upstream_probe (PRO), tal servidor aumenta gradualmente para seu peso especificado durante o período de tempo determinado. Se o parâmetro não for definido, em uma situação similar o servidor imediatamente começa a operar com seu peso especificado.

Nota

Se apenas um server for especificado no upstream, slow_start não funciona e será ignorado.

state (PRO)

Sintaxe	state file;
Padrão	—
Contexto	upstream

Especifica um file onde a lista de servidores upstream é armazenada persistentemente. Ao instalar a partir dos nossos pacotes, o diretório /var/lib/angie/state/ (/var/db/angie/state/ no FreeBSD) é criado especificamente para armazenar tais arquivos com permissões de acesso apropriadas, e na configuração você só precisa adicionar o nome do arquivo:

upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<NOME DO ARQUIVO>;
}

A lista de servidores aqui tem um formato similar ao server. O conteúdo do arquivo é modificado sempre que servidores são alterados na seção /config/http/upstreams/ via API de configuração. O arquivo é lido quando o Angie inicia ou quando a configuração é recarregada.

Aviso

Para usar a diretiva state em um bloco upstream, não deve haver diretivas server nele, mas uma zona de memória compartilhada (zone) é necessária.

sticky

Sintaxe	sticky cookie name [attr=value]...; sticky route $variable...; sticky learn zone=zone create=$create_var1... lookup=$lookup_var1... [header] [norefresh] [timeout=time]; sticky learn [zone=zone] lookup=$lookup_var1... remote_action=uri remote_result=$remote_var [norefresh] [timeout=time];
Padrão	—
Contexto	upstream

Configura afinidade de sessão para vincular sessões de cliente a servidores proxy no modo especificado pelo primeiro parâmetro; para drenar servidores que têm a diretiva sticky configurada, você pode usar a opção drain (PRO) no bloco server.

Aviso

A diretiva sticky deve ser usada após todas as diretivas que especificam um método particular de balanceamento de carga, caso contrário não funcionará. Se for usada junto com a diretiva bind_conn (PRO), então bind_conn deve vir após sticky.

modo cookiemodo routemodo learn (PRO 1.4.0+)learn com remote_action (PRO 1.8.0+)

Este modo usa cookies para gerenciar sessões. É adequado quando cookies já são usados para rastreamento de sessão.

A primeira requisição do cliente, antes de qualquer aderência se aplicar, é enviada para um servidor backend de acordo com o método de balanceamento configurado. O Angie então define um cookie identificando o servidor escolhido.

O nome do cookie (name) é definido pela diretiva sticky, e seu valor corresponde ao sid da diretiva server. Este valor é posteriormente hasheado se sticky_secret estiver definido.

Requisições subsequentes com este cookie são roteadas para o servidor especificado por seu sid. Se o servidor estiver indisponível ou não puder processar a requisição, outro é escolhido através do método de balanceamento configurado.

Você pode atribuir atributos de cookie na diretiva; por padrão, apenas path=/ é definido. Valores de atributos podem conter variáveis. Para remover um atributo, defina-o como um valor vazio: attr=. Por exemplo, sticky cookie path= omite o atributo path.

Este exemplo define um cookie srv_id por 1 hora, usando um domínio de uma variável:

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie srv_id domain=$my_domain max-age=3600;
}

A diretiva sticky respeita os estados dos servidores upstream:

• Servidores marcados como down ou falhando são excluídos.

• Servidores acima do limite max_conns são ignorados.

• Servidores drain (PRO) ainda podem ser selecionados para novas sessões no modo sticky quando os identificadores correspondem.

• Servidores recuperados são reutilizados automaticamente.

Você pode ajustar ainda mais o comportamento usando sticky_secret e sticky_strict. Se a aderência falhar e sticky_strict estiver desligado, o balanceamento de fallback é usado; se ligado, a requisição é rejeitada.

Cada zone usada em sticky deve ser exclusiva de um único upstream. Zonas não podem ser compartilhadas entre múltiplos blocos upstream.

sticky_secret

Sintaxe	sticky_secret string;
Padrão	—
Contexto	upstream

Adiciona a string como valor de salt para a função de hash MD5 da diretiva sticky nos modos cookie e route. A string pode conter variáveis, por exemplo, $remote_addr:

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}

O salt é anexado ao valor sendo hasheado; para verificar o mecanismo de hash independentemente:

$ echo -n "<VALUE><SALT>" | md5sum

sticky_strict

Sintaxe	sticky_strict on | off;
Padrão	sticky_strict off;
Contexto	upstream

Quando habilitado, faz com que o Angie retorne um erro HTTP 502 para o cliente se o servidor desejado estiver indisponível, em vez de usar qualquer outro servidor disponível como faria quando nenhum servidor no upstream estiver disponível.

upstream

Sintaxe	upstream name { ... }
Padrão	—
Contexto	http

Define um grupo de servidores. Os servidores podem escutar em portas diferentes. Além disso, servidores escutando em sockets TCP e de domínio UNIX podem ser misturados.

Exemplo:

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

    server backup1.example.com  backup;
}

Por padrão, as requisições são distribuídas entre os servidores usando um método de balanceamento round-robin ponderado. No exemplo acima, cada 7 requisições serão distribuídas da seguinte forma: 5 requisições vão para backend1.example.com e uma requisição para cada um dos segundo e terceiro servidores.

Se ocorrer um erro durante a comunicação com um servidor, a requisição será passada para o próximo servidor, e assim por diante até que todos os servidores funcionais sejam tentados. Se uma resposta bem-sucedida não puder ser obtida de nenhum dos servidores, o cliente receberá o resultado da comunicação com o último servidor.

zone

Sintaxe	zone name [size];
Padrão	—
Contexto	upstream

Define o nome e tamanho da zona de memória compartilhada que mantém a configuração do grupo e o estado de tempo de execução que são compartilhados entre os processos worker. Vários grupos podem compartilhar a mesma zona. Neste caso, é suficiente especificar o tamanho apenas uma vez.

Variáveis Integradas

O módulo http_upstream suporta as seguintes variáveis integradas:

$sticky_sessid

Usada com remote_action em sticky; armazena o ID de sessão inicial obtido de lookup.

$sticky_sid

Usada com remote_action em sticky; armazena o ID do servidor previamente associado com a sessão.

$upstream_addr

armazena o endereço IP e porta, ou o caminho para o socket de domínio UNIX do servidor upstream. Se vários servidores foram contatados durante o processamento da requisição, seus endereços são separados por vírgulas, por exemplo:

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

Se um redirecionamento interno de um grupo de servidores para outro acontecer, iniciado por X-Accel-Redirect ou error_page, então os endereços dos servidores de diferentes grupos são separados por dois pontos, por exemplo:

192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80

Se um servidor não puder ser selecionado, a variável mantém o nome do grupo de servidores.

$upstream_bytes_received

número de bytes recebidos de um servidor upstream. Valores de várias conexões são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_bytes_sent

número de bytes enviados para um servidor upstream. Valores de várias conexões são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_cache_status

mantém o status de acesso a um cache de resposta. O status pode ser MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, ou HIT:

• MISS: A resposta não é encontrada no cache, e a requisição é passada para o servidor upstream.

• BYPASS: O cache é ignorado, e a requisição é passada diretamente para o servidor upstream.

• EXPIRED: A resposta em cache está obsoleta, e uma nova requisição é passada para o servidor upstream para atualizar o conteúdo.

• STALE: A resposta em cache está obsoleta, mas ainda é servida aos clientes até que o conteúdo seja eventualmente atualizado do servidor upstream.

• UPDATING: A resposta em cache está obsoleta, mas ainda é servida aos clientes enquanto a atualização atualmente em andamento do servidor upstream está em progresso.

• REVALIDATED: A resposta em cache está obsoleta, mas foi revalidada com sucesso e não precisa ser atualizada do servidor upstream.

• HIT: A resposta foi obtida do cache.

Se a requisição ignorou o cache sem acessá-lo, a variável não é definida.

$upstream_connect_time

mantém o tempo gasto estabelecendo uma conexão com o servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. No caso de SSL, inclui o tempo gasto no handshake. Tempos de várias conexões são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_cookie_<name>

cookie com o nome especificado enviado pelo servidor upstream no campo de cabeçalho de resposta Set-Cookie. Apenas os cookies da resposta do último servidor são salvos.

$upstream_header_time

mantém o tempo gasto recebendo o cabeçalho de resposta do servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias respostas são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_http_<name>

mantém campos de cabeçalho de resposta do servidor. Por exemplo, o campo de cabeçalho de resposta Server está disponível através da variável $upstream_http_server. As regras de conversão de nomes de campos de cabeçalho para nomes de variáveis são as mesmas para as variáveis que começam com o prefixo $http_. Apenas os campos de cabeçalho da resposta do último servidor são salvos.

$upstream_queue_time

mantém o tempo que a requisição passou na fila antes da próxima seleção de servidor; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias tentativas são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_response_length

mantém o comprimento da resposta obtida do servidor upstream; o comprimento é mantido em bytes. Comprimentos de várias respostas são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_response_time

mantém o tempo gasto recebendo a resposta do servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias respostas são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_status

mantém o código de status da resposta obtida do servidor upstream. Códigos de status de várias respostas são separados por vírgulas e dois pontos como endereços na variável $upstream_addr. Se um servidor não puder ser selecionado, a variável mantém o código de status 502 (Bad Gateway).

$upstream_sticky_status

Status de requisições sticky.

""	Requisição enviada para um upstream onde sticky não está habilitado.
NEW	Requisição não contém informação sticky.
HIT	Requisição com informação sticky enviada para o servidor desejado.
MISS	Requisição com informação sticky enviada para um servidor selecionado pelo algoritmo de balanceamento de carga.

Status de várias conexões são separados por vírgulas e dois pontos como endereços na variável $upstream_addr.

$upstream_trailer_<name>

mantém campos do final da resposta obtida do servidor upstream.