Перейти к содержанию

upstream-healthcheck: Проверка состояния для upstream-серверов NGINX на чистом Lua

Установка

Если вы еще не подписались на RPM-репозиторий, зарегистрируйтесь. Затем вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

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 lua-resty-upstream-healthcheck

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-upstream-healthcheck

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что установлен nginx-module-lua.

Этот документ описывает lua-resty-upstream-healthcheck v0.8, выпущенный 7 марта 2023 года.

http {
    # пример блока upstream:
    upstream foo.com {
        server 127.0.0.1:12354;
        server 127.0.0.1:12355;
        server 127.0.0.1:12356 backup;
    }

    # размер зависит от количества серверов в upstream {}:
    lua_shared_dict healthcheck 1m;

    lua_socket_log_errors off;

    init_worker_by_lua_block {
        local hc = require "resty.upstream.healthcheck"

        local ok, err = hc.spawn_checker{
            shm = "healthcheck",  -- определено "lua_shared_dict"
            upstream = "foo.com", -- определено "upstream"
            type = "http", -- поддерживает "http" и "https"

            http_req = "GET /status HTTP/1.0\r\nHost: foo.com\r\n\r\n",
                    -- сырой HTTP-запрос для проверки

            port = nil,  -- порт проверки, он может отличаться от оригинального порта бэкенд-сервера, по умолчанию означает тот же, что и оригинальный бэкенд-сервер
            interval = 2000,  -- запуск цикла проверки каждые 2 секунды
            timeout = 1000,   -- 1 секунда - это тайм-аут для сетевых операций
            fall = 3,  -- количество последовательных сбоев, прежде чем отключить пир
            rise = 2,  -- количество последовательных успехов, прежде чем включить пир
            valid_statuses = {200, 302},  -- список допустимых HTTP-кодов состояния
            concurrency = 10,  -- уровень параллелизма для тестовых запросов
            -- ssl_verify = true, -- только для https, проверять ssl-сертификат или нет, по умолчанию true
            -- host = foo.com, -- только для https, имя хоста в ssl-рукопожатии, по умолчанию nil
        }
        if not ok then
            ngx.log(ngx.ERR, "не удалось запустить проверку состояния: ", err)
            return
        end

        -- Просто вызовите hc.spawn_checker() больше раз здесь, если у вас есть
        -- больше групп upstream для мониторинга. Один вызов для одной группы upstream.
        -- Они могут все использовать одну и ту же shm-зону без конфликтов, но им
        -- нужна большая shm-зона по очевидным причинам.
    }

    server {
        ...

        # страница состояния для всех пиров:
        location = /status {
            access_log off;
            allow 127.0.0.1;
            deny all;

            default_type text/plain;
            content_by_lua_block {
                local hc = require "resty.upstream.healthcheck"
                ngx.say("PID рабочего процесса Nginx: ", ngx.worker.pid())
                ngx.print(hc.status_page())
            }
        }

        # страница состояния для всех пиров (формат prometheus):
        location = /metrics {
            access_log off;
            default_type text/plain;
            content_by_lua_block {
                local hc = require "resty.upstream.healthcheck"
                st, err = hc.prometheus_status_page()
                if not st then
                    ngx.say(err)
                    return
                end
                ngx.print(st)
            }
        }
    }
}

Описание

Эта библиотека выполняет проверку состояния для серверов-пиров, определенных в группах NGINX upstream, указанных по именам.

Методы

spawn_checker

синтаксис: ok, err = healthcheck.spawn_checker(options)

контекст: init_worker_by_lua*

Запускает фоновый таймер на основе "легких потоков" для выполнения периодических проверок состояния на указанной группе upstream NGINX с заданным хранилищем shm.

Проверка состояния не требует клиентского трафика для функционирования. Проверки выполняются активно и периодически.

Этот вызов метода асинхронный и возвращает сразу.

Возвращает true в случае успеха или nil и строку, описывающую ошибку, в противном случае.

Несколько Upstream

Можно выполнять проверки состояния на нескольких группах upstream, вызывая метод spawn_checker несколько раз в обработчике init_worker_by_lua*. Например,

upstream foo {
    ...
}

upstream bar {
    ...
}

lua_shared_dict healthcheck 1m;

lua_socket_log_errors off;

init_worker_by_lua_block {
    local hc = require "resty.upstream.healthcheck"

    local ok, err = hc.spawn_checker{
        shm = "healthcheck",
        upstream = "foo",
        ...
    }

    ...

    ok, err = hc.spawn_checker{
        shm = "healthcheck",
        upstream = "bar",
        ...
    }
}

Проверки состояния разных upstream используют разные ключи (всегда добавляя префикс с именем upstream к ключам), поэтому использование одного lua_shared_dict среди нескольких проверок не должно вызывать никаких проблем. Но вам нужно учесть размер общего словаря для нескольких пользователей (т.е. нескольких проверок). Если у вас много upstream (тысячи или даже больше), то более оптимально использовать отдельные shm-зоны для каждой (группы) upstream.

nginx.conf

http { ... } ```

Смотрите также

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-upstream-healthcheck.