Pular para conteúdo

upsync: Módulo NGINX para sincronização de upstreams do consul ou etcd

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upsync

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-upsync

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_upsync_module.so;

Este documento descreve o nginx-module-upsync v2.1.3 lançado em 20 de novembro de 2020.

Módulo C do Nginx, que pode sincronizar upstreams do Consul ou outros. Ele modifica dinamicamente os atributos dos servidores de backend (peso, max_fails, ...) sem a necessidade de recarregar o NGINX.

Pode não ser sempre conveniente modificar arquivos de configuração e reiniciar o NGINX. Por exemplo, se você estiver enfrentando grandes quantidades de tráfego e alta carga, reiniciar o NGINX e recarregar a configuração nesse momento aumenta ainda mais a carga no sistema e pode degradar temporariamente o desempenho.

O módulo permite expandir e reduzir sem afetar o desempenho.

Outro módulo, nginx-stream-upsync-module, suporta o módulo de stream do NGINX (protocolo TCP), por favor, esteja ciente.

Sinopse

nginx-consul: 

http {
    upstream test {
        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;

        include /usr/local/nginx/conf/servers/servers_test.conf;
    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

    }
}
nginx-etcd: 
http {
    upstream test {
        upsync 127.0.0.1:2379/v2/keys/upstreams/test upsync_timeout=6m upsync_interval=500ms upsync_type=etcd strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;

        include /usr/local/nginx/conf/servers/servers_test.conf;
    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

    }
}
upsync_lb: 
http {
    upstream test {
        least_conn; //hash $uri consistent;

        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;
        upsync_lb least_conn; //hash_ketama;

        include /usr/local/nginx/conf/servers/servers_test.conf;
    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

    }
}

NOTA: recomenda-se que strong_dependency esteja configurado como off e que o arquivo incluído pela primeira vez inclua todos os servidores.

Descrição

Este módulo fornece um método para descobrir servidores de backend. Suportando a adição ou remoção dinâmica de servidores de backend através do consul ou etcd e ajustando dinamicamente o peso dos servidores de backend, o módulo puxará rapidamente a nova lista de servidores de backend do consul ou etcd para sincronizar o roteador IP do NGINX. O NGINX não precisa ser recarregado. Possui algumas vantagens em relação a outros:

  • pontual

    O módulo envia a chave para consul/etcd com índice, o consul/etcd comparará com seu índice, se o índice não mudar, a conexão ficará suspensa por cinco minutos, durante esse período qualquer operação na chave-valor será respondida imediatamente.

  • desempenho

    Puxar do consul/etcd equivale a uma solicitação ao NGINX, atualizando o roteador IP o NGINX não precisa ser recarregado, portanto, o impacto no desempenho do NGINX é pequeno.

  • estabilidade

    Mesmo que uma puxada falhe, ela puxará no próximo upsync_interval, garantindo que o servidor de backend forneça serviço de forma estável. E suporta a exportação da configuração mais recente para o local, então mesmo que o consul/etcd fique fora do ar, o NGINX pode ser recarregado a qualquer momento.

  • health_check

    O nginx-upsync-module suporta a adição ou remoção de verificações de saúde dos servidores, necessitando do nginx_upstream_check_module. Recomenda-se o nginx-upsync-module + nginx_upstream_check_module.

Diretrizes

upsync

syntax: upsync $consul/etcd.api.com:$port/v1/kv/upstreams/$upstream_name/ [upsync_type=consul/etcd] [upsync_interval=second/minutes] [upsync_timeout=second/minutes] [strong_dependency=off/on]
default: none, se os parâmetros forem omitidos, os parâmetros padrão são upsync_interval=5s upsync_timeout=6m strong_dependency=off

context: upstream

description: Puxar servidores upstream do consul/etcd... .

Os significados dos parâmetros são:

  • upsync_interval

    tempo de intervalo para puxar servidores do consul/etcd.

  • upsync_timeout

    tempo limite para a solicitação de puxar servidores do consul/etcd.

  • upsync_type

    tipo de servidor de configuração para puxar.

  • strong_dependency

    quando strong_dependency está ativado, o NGINX puxará servidores do consul/etcd toda vez que o NGINX iniciar ou recarregar.

upsync_dump_path

syntax: upsync_dump_path $path

default: /tmp/servers_$host.conf

context: upstream

description: despejar os backends upstream no $path.

upsync_lb

syntax: upsync_lb $load_balance

default: round_robin/ip_hash/hash modula

context: upstream

description: principalmente para least_conn e hash consistente, ao usar um deles, você deve indicar o uso de upsync_lb.

upstream_show

syntax: upstream_show

default: none

context: upstream

description: Mostrar todos os servidores de backend específicos do upstream.

     location /upstream_list {
         upstream_show;
     }

curl http://127.0.0.1:8500/upstream_list?test;

curl http://127.0.0.1:8500/upstream_list;

mostrar todos os upstreams.

Consul_interface

Os dados podem ser retirados do armazenamento de chave/valor ou do catálogo de serviços. No primeiro caso, o parâmetro upsync_type da diretiva deve ser consul. Por exemplo

        upsync 127.0.0.1:8500/v1/kv/upstreams/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;

No segundo caso, deve ser consul_services.

        upsync 127.0.0.1:8500/v1/catalog/service/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul_services strong_dependency=off;

No terceiro caso, deve ser consul_health:

        upsync 127.0.0.1:8500/v1/health/service/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul_health strong_dependency=off;

Serviços com verificações de saúde falhando são marcados como fora do ar com a API de saúde.

Você pode adicionar ou deletar servidores de backend através do consul_ui ou http_interface. Abaixo estão exemplos para o armazenamento de chave/valor.

exemplo de http_interface:

  • adicionar 
        curl -X PUT http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port
    default: weight=1 max_fails=2 fail_timeout=10 down=0 backup=0;

    curl -X PUT -d "{\"weight\":1, \"max_fails\":2, \"fail_timeout\":10}" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
ou
    curl -X PUT -d '{"weight":1, "max_fails":2, "fail_timeout":10}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
o valor suporta formato json.

  • deletar 

        curl -X DELETE http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port

  • ajustar-peso 

        curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10}" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
ou
    curl -X PUT -d '{"weight":2, "max_fails":2, "fail_timeout":10}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port

  • marcar servidor-fora-do-ar 

        curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10, \"down\":1}" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
ou
    curl -X PUT -d '{"weight":2, "max_fails":2, "fail_timeout":10, "down":1}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port

  • verificar 

        curl http://$consul_ip:$port/v1/kv/upstreams/$upstream_name?recurse

Etcd_interface

você pode adicionar ou deletar servidores de backend através do http_interface.

principalmente como etcd, exemplo de http_interface:

  • adicionar 
        curl -X PUT http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name/$backend_ip:$backend_port
    default: weight=1 max_fails=2 fail_timeout=10 down=0 backup=0;

    curl -X PUT -d value="{\"weight\":1, \"max_fails\":2, \"fail_timeout\":10}" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port
o valor suporta formato json.

  • deletar 

        curl -X DELETE http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name/$backend_ip:$backend_port

  • ajustar-peso 

        curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10}" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port

  • marcar servidor-fora-do-ar 

        curl -X PUT -d value="{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10, \"down\":1}" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port

  • verificar 

        curl http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name

Check_module

suporte ao módulo de verificação.

check-conf: 

http {
    upstream test {
        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;

        check interval=1000 rise=2 fall=2 timeout=3000 type=http default_down=false;
        check_http_send "HEAD / HTTP/1.0\r\n\r\n";
        check_http_expect_alive http_2xx http_3xx;

    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

        location = /upstream_status {
            check_status;
            access_log off;
        }

    }
}

Estilo de código

O estilo de código é baseado principalmente em style

veja também

dependência de fonte

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-upsync.