Deep Engineering

ЗАМЕР

bench/valkey-cluster/notready.py

Скрипт, которым получены числа в статье, и запись прогона. Файл читается на сборке из репозитория — это тот самый код, который запускали, а не его копия.

Цитируется в статье
/ru/system-design/caching/valkey-clustering
Как запустить
python3 bench/valkey-cluster/discovery.py   # блоки 1-4
python3 bench/valkey-cluster/apidiff.py     # блоки 5-7
python3 bench/valkey-cluster/failover.py    # блоки 8-10
python3 bench/valkey-cluster/notready.py    # блоки 11-12
python3 bench/valkey-cluster/quorum.py      # блок 13
python3 bench/valkey-cluster/databases.py   # блоки 14-16
python3 bench/valkey-cluster/boundaries.py  # блоки 17-19

Запись прогона

Замеры для статьи «Два способа собрать Valkey из нескольких узлов»

Файл Что делает
common.py подъём узлов в обоих режимах, разговор с ними, печать блоков. Общий модуль, сам ничего не печатает
discovery.py как клиент находит узел: MOVED против SENTINEL get-master-addr-by-name, и что клиент делает на самом деле — блоки 1–4
apidiff.py какие команды в кластере перестают работать и почему — блоки 5–7
failover.py отказ мастера в обоих режимах глазами клиента, и что бывает, когда старый мастер возвращается — блоки 8–10
notready.py окно между «кластер собран» и «кластер переживёт отказ» — блоки 11–12
quorum.py кворум против большинства: почему одно число не заменяет другое — блок 13
databases.py нумерованные базы в кластере: два кластера с разным cluster-databases — блоки 14–16
boundaries.py три утверждения статьи, проверенные на границах — блоки 17–19
python3 bench/valkey-cluster/discovery.py   # блоки 1-4
python3 bench/valkey-cluster/apidiff.py     # блоки 5-7
python3 bench/valkey-cluster/failover.py    # блоки 8-10
python3 bench/valkey-cluster/notready.py    # блоки 11-12
python3 bench/valkey-cluster/quorum.py      # блок 13
python3 bench/valkey-cluster/databases.py   # блоки 14-16
python3 bench/valkey-cluster/boundaries.py  # блоки 17-19

Нужен собранный Valkey — путь к нему берётся из VALKEY_BIN (по умолчанию /usr/local/valkey912/bin). Узлы поднимаются во временных каталогах на случайных портах и убиваются в finally; после себя скрипты не оставляют ни процессов, ни файлов. Весь набор идёт около шести минут: переключений надо дождаться несколько раз, и торопить их нечем.

Откуда здесь Valkey 9.1.2

В системных пакетах лежит 7.2.13 — ветка, к которой половина того, что стоит писать про кластер, уже не относится. Обычный путь за свежей версией закрыт: dl.google.com и сайт проекта недоступны из этой среды. Зато доступен GitHub, а Valkey собирается из исходников одной командой:

git clone --depth 1 --branch 9.1.2 https://github.com/valkey-io/valkey.git /tmp/valkey912
cd /tmp/valkey912 && make -j2 BUILD_TLS=no
install -D /tmp/valkey912/src/valkey-{server,cli,benchmark} -t /usr/local/valkey912/bin

Отдельного двоичного файла для sentinel нет и не нужно: это тот же valkey-server, запущенный с конфигом и флагом --sentinel. Свойство, а не деталь сборки, — и в блоке 7 видно, чем режимы при этом отличаются.

Что здесь важно прочитать правильно

Абсолютные секунды не переносятся никуда. Узел считается упавшим через секунду молчания (down-after-milliseconds 1000) вместо тридцати по умолчанию, а cluster-node-timeout стоит 2000 мс вместо 15 000. Это сделано ровно затем, чтобы набор укладывался в минуты. Содержательны порядок событий, текст ответов сервера и знак разницы — но не число секунд.

Порты выбираются ниже 55535, и это не придирка. Узел кластера слушает два порта: обычный и шинный, ровно на десять тысяч больше. Порт из эфемерного диапазона даёт шинный порт больше 65535, и узел не поднимается вовсе.

Опрос идёт «глупым» клиентом. Везде, где печатается ответ сервера, он снят через valkey-cli без флага -c. Библиотека-клиент прячет ровно то, что здесь интересно: сама ходит за картой слотов, сама повторяет запрос, сама спрашивает sentinel. Настоящие клиентские библиотеки используются только в блоках 3 и 4 — там вопрос как раз в том, что делает клиент, и считают это сами узлы.

Что получилось

Как клиент находит узел

нативный кластер Sentinel
кто знает топологию каждый узел данных отдельная служба
что клиент спрашивает любой узел, обычной командой SENTINEL get-master-addr-by-name
как узнаёт про чужой ключ MOVED 12182 127.0.0.1:43425 никак: вопрос не к узлу
что нужно в конфиге клиента один живой адрес узла адреса sentinel и имя набора

В блоке 3 видно, что клиент кластера, получив ОДИН адрес из шести, сходил за CLUSTER SLOTS и дальше писал напрямую нужному узлу. В блоке 4 порядок обратный: сначала вопрос службе, потом команда данным.

Что ломается в кластере из привычного

команда в кластере под sentinel
MSET foo 1 bar 2 CROSSSLOT Keys in request don't hash to the same slot OK
MSET {u}:a 1 {u}:b 2 работает: общая скобка кладёт ключи в один слот OK
SELECT 1 ERR DB index is out of range — но см. ниже OK
SWAPDB 0 1 ERR SWAPDB is not allowed in cluster mode OK

Две формы отказа различаются не случайно: SWAPDB запрещён как таковой, а SELECT 1 — выход за границу. За какую именно границу, блок 6 сам по себе не говорит, и на этом первая версия статьи ошиблась.

Нумерованные базы: настройка, а не режим

Из SELECT 1 → ERR DB index is out of range в первой версии был сделан вывод «в кластере база ровно одна». Это правило Redis и Valkey до 9.0; в Valkey 9.0 нумерованные базы в кластере появились, а их число задаёт неизменяемая настройка cluster-databases со значением по умолчанию 1. Блоки 14–16 поднимают два кластера, отличающихся ровно этой строкой:

кластер А кластер Б
cluster-databases 1 16
SELECT 1 ERR DB index is out of range OK
SELECT 15 ERR DB index is out of range OK
SELECT 16 ERR DB index is out of range ERR DB index is out of range

Номер базы в адресацию не входит: один ключ в базах 0 и 1 держит разные значения при одном слоте 12182. А вот чего базы не дают — общего на кластер представления о себе: DBSIZE и SCAN считают только ту часть базы, что лежит на узле, куда пришла команда, SWAPDB остаётся запрещён.

Границы трёх утверждений

Блоки 17–19 перемеряют места, где статья сказала шире измеренного: «никогда» из блока 12 снимается настройкой cluster-replica-validity-factor 0 (реплика повышается за четыре секунды, но пустой); границу кворума и большинства заранее показывает SENTINEL CKQUORUM; узел под sentinel знает не «ничего», а свою пару репликации — не знает он только авторитетного ответа службы.

Отказ мастера

нативный кластер Sentinel
кто замечает сами узлы, по шине отдельные наблюдатели
кто решает большинство мастеров большинство sentinel
что получает клиент в этот момент CLUSTERDOWN, потом MOVED на новый адрес молчание старого адреса
как клиент узнаёт новый адрес из ответа любого живого узла только спросив sentinel
вернувшийся старый мастер сразу реплика, отдаёт MOVED мастер на 10 с, принимает записи

Последняя строка — самое опасное место режима Sentinel и содержание блока 10. Вернувшийся узел поднимается мастером, отвечает OK на записи, а после перевода в реплику полная синхронизация их стирает. Клиент при этом не видит ни одной ошибки.

Два состояния готовности

Блоки 11 и 12 — про находку, ради которой стоило ронять узлы вручную. Между «слоты розданы» (cluster_state:ok) и «есть кому повышаться» (master_link_status:up у реплик) прошло 6,07 секунды. Мастер, упавший внутри этого окна, не заменяется НИКОГДА: у реплики, ни разу не подключавшейся, отметка «когда упал канал» осталась нулевой, возраст её данных считается от начала эпохи Unix, и она отказывается повышаться:

Currently unable to failover: Disconnected from primary for longer than
allowed. Please check the 'cluster-replica-validity-factor' configuration
option.

Условие видно в исходнике (src/cluster_legacy.c):

if (server.repl_state == REPL_STATE_CONNECTED) {
    data_age = (mstime_t)(server.unixtime - server.primary->last_interaction) * 1000;
} else {
    data_age = (mstime_t)(server.unixtime - server.repl_down_since) * 1000;
}

Практический вывод про эксплуатацию: «кластер поднялся» и «кластер держит отказ» — разные проверки, и вторая смотрит на master_link_status каждой реплики.

Кворум и большинство

Пять sentinel, кворум 2, погашены три. Кворум выполнен — и переключения всё равно нет:

+odown master cache 127.0.0.1 48147 #quorum 2/2
+try-failover master cache 127.0.0.1 48147
+vote-for-leader c92cd70b21a9dd26ec40e67185371e78ee502f9a 1
-failover-abort-not-elected master cache 127.0.0.1 48147

Стоило поднять одного из погашенных — большинство появилось, и переключение состоялось за две секунды. Кворум при этом не менялся вовсе.

Источники

Скрипт

210 строк
"""Готов к работе и готов к отказу — два разных состояния. Блок 11.

ОТКУДА ВЗЯЛСЯ ЭТОТ БЛОК. Из ошибки в соседнем замере. Скрипт про отказ мастера
поднимал кластер, дожидался `cluster_state:ok` у всех узлов и ронял мастера.
Реплика не повышалась — ни через двадцать секунд, ни через минуту, никогда, — и
кластер оставался в `fail` навсегда. Выглядело как поломка замера, оказалось
поведением Valkey, про которое нигде не написано так, чтобы это бросалось в
глаза.

ЧТО ИМЕННО ПРОВЕРЯЕТСЯ. Между «слоты розданы» и «реплика способна заменить
мастера» есть окно в несколько секунд. Внутри него кластер отвечает
`cluster_state:ok` и обслуживает запросы, но отказ мастера он НЕ переживёт: у
реплики ещё не было ни одной успешной синхронизации, и она сама отказывается
повышаться.

ПОЧЕМУ ОТКАЗЫВАЕТСЯ — из исходника, а не из догадки. В `cluster_legacy.c`
возраст данных реплики считается так:

    if (server.repl_state == REPL_STATE_CONNECTED) {
        data_age = (server.unixtime - server.primary->last_interaction) * 1000;
    } else {
        data_age = (server.unixtime - server.repl_down_since) * 1000;
    }

У реплики, ни разу не подключавшейся, `repl_down_since` равен нулю — и возраст
данных получается отсчитанным от начала эпохи Unix. Дальше он сравнивается с
допуском `repl-ping-replica-period + cluster-node-timeout × validity-factor`, и
никакой допуск такого возраста не покрывает.

ЗАПУСК: python3 bench/valkey-cluster/notready.py
"""

from __future__ import annotations

import os
import time

from common import (
    CLUSTER_NODE_TIMEOUT_MS,
    Cluster,
    cli,
    cluster_state,
    free_port,
    head,
    link_down_since,
    link_status,
    note,
    preamble,
    role_of,
    row,
)

PAD = 34


def replica_of(ports: list[int], master_port: int) -> int | None:
    """Кто реплика указанного мастера — по CLUSTER NODES."""
    raw = cli(ports[0], "cluster", "nodes")
    master_id = None
    for line in raw.splitlines():
        f = line.split()
        if f[1].startswith(f"127.0.0.1:{master_port}@"):
            master_id = f[0]
    if master_id is None:
        return None
    for line in raw.splitlines():
        f = line.split()
        if "slave" in f[2] and f[3] == master_id:
            return int(f[1].split("@")[0].split(":")[1])
    return None


def main() -> None:
    preamble("окно между «кластер собран» и «кластер переживёт отказ»")

    cluster = Cluster()
    try:
        ports = [free_port() for _ in range(6)]
        for p in ports:
            cluster.start_data(p, cluster=True)

        # Кластер создаётся БЕЗ ожидания готовности — в этом весь опыт.
        cluster.form_cluster_raw(ports, replicas=1)

        head(11, "СРАЗУ ПОСЛЕ СБОРКИ КЛАСТЕР РАБОТАЕТ, НО ОТКАЗ НЕ ПЕРЕЖИВЁТ")
        row("cluster-node-timeout", f"{CLUSTER_NODE_TIMEOUT_MS} мс", pad=PAD)
        row("cluster-replica-validity-factor",
            cli(ports[0], "config", "get", "cluster-replica-validity-factor").split()[-1], pad=PAD)
        row("repl-ping-replica-period",
            cli(ports[0], "config", "get", "repl-ping-replica-period").split()[-1], pad=PAD)
        print()

        # Первая часть: два признака готовности расходятся во времени.
        print("  как расходятся два признака готовности:")
        t0 = time.time()
        slots_at = None
        links_at = None
        while time.time() - t0 < 60 and (slots_at is None or links_at is None):
            if slots_at is None and all(cluster_state(p) == "ok" for p in ports):
                slots_at = time.time() - t0
                print(f"    t={slots_at:5.2f}  cluster_state:ok у всех узлов "
                      f"(слоты покрыты, запросы обслуживаются)")
            reps = [p for p in ports if role_of(p) == "slave"]
            if links_at is None and reps and all(link_status(p) == "up" for p in reps):
                links_at = time.time() - t0
                print(f"    t={links_at:5.2f}  master_link_status:up у всех реплик "
                      f"(есть кому повышаться)")
            time.sleep(0.1)
        print()
        if slots_at is not None and links_at is not None:
            row("окно между ними", f"{links_at - slots_at:.2f} с", pad=PAD)

        note(
            """
            Внутри этого окна кластер выглядит полностью рабочим: слоты
            покрыты, CLUSTER INFO отвечает ok, ключи пишутся и читаются. Но
            у реплик ещё нет ни одной завершённой синхронизации, и
            master_link_status у них down.
            """
        )

        # Вторая часть: то же окно, но с отказом внутри него — на свежем
        # кластере, чтобы окно было настоящим, а не воспроизведённым.
        head(12, "ЧТО БУДЕТ, ЕСЛИ МАСТЕР УПАДЁТ ВНУТРИ ЭТОГО ОКНА")
        for p in ports:
            cluster.kill(p)
        ports2 = [free_port() for _ in range(6)]
        for p in ports2:
            cluster.start_data(p, cluster=True)
        cluster.form_cluster_raw(ports2, replicas=1)

        # Ждём ровно первого признака и роняем мастера, не дожидаясь второго.
        deadline = time.time() + 60
        while time.time() < deadline and not all(cluster_state(p) == "ok" for p in ports2):
            time.sleep(0.05)
        masters = [p for p in ports2 if role_of(p) == "master"]
        victim = masters[0]
        rep = replica_of(ports2, victim)
        row("мастер, который упадёт", f"127.0.0.1:{victim}", pad=PAD)
        row("его реплика", f"127.0.0.1:{rep}", pad=PAD)
        row("master_link_status реплики", link_status(rep), pad=PAD)
        row("master_link_down_since_seconds", link_down_since(rep), pad=PAD)
        print()

        cluster.kill(victim)
        probe = next(p for p in ports2 if p != victim and role_of(p) == "master")
        print(f"  t=0.00  мастер {victim} убит, ждём переключения 40 с")
        t0 = time.time()
        promoted = False
        last = None
        while time.time() - t0 < 40:
            state = cluster_state(probe)
            role = role_of(rep)
            now = (state, role)
            if now != last:
                print(f"  t={time.time() - t0:5.2f}  состояние кластера {state}, "
                      f"роль реплики {role}")
                last = now
            if role == "master":
                promoted = True
                break
            time.sleep(0.2)

        print()
        row("реплика повысилась", "да" if promoted else "НЕТ, за 40 с", pad=PAD)
        print()
        print("  что реплика записала в журнал:")
        log = os.path.join(cluster.dir, f"node-{rep}.log")
        if os.path.exists(log):
            seen = set()
            for line in open(log, encoding="utf-8").read().splitlines():
                if "unable to failover" in line or "Disconnected from primary" in line:
                    text = line.split(" * ")[-1].split(" # ")[-1]
                    if text not in seen:
                        # Строка длиннее блока: переносится по словам, чтобы
                        # в статью попала целиком, а не обрубком.
                        words, line_out = text.split(), "   "
                        for w in words:
                            if len(line_out) + 1 + len(w) > 68:
                                print(line_out)
                                line_out = "     " + w
                            else:
                                line_out += " " + w
                        print(line_out)
                        seen.add(text)

        note(
            """
            Это не поломка и не редкий случай — это прямое следствие того,
            как считается возраст данных реплики. У реплики, ни разу не
            подключившейся к мастеру, отметка «когда канал упал» так и
            осталась нулевой, поэтому её данные считаются бесконечно
            старыми, и повышаться она отказывается — навсегда, а не до
            истечения какого-нибудь таймаута.

            Практический вывод не про Valkey, а про эксплуатацию: «кластер
            поднялся» и «кластер держит отказ» — разные проверки. Первая
            отвечает на вопрос, обслуживаются ли запросы; вторая требует
            смотреть на master_link_status каждой реплики. Автоматика,
            которая раскатывает кластер и сразу гасит старый, по первой
            проверке пройдёт, а по второй — нет.
            """
        )
    finally:
        cluster.stop_all()


if __name__ == "__main__":
    main()