Конфигурация

Ключевые понятия кластера описаны на странице Кластеризация. Здесь — справочник для развёртывания и настройки.

Архитектура

Gossip и синхронизация

Каждая нода:

• берёт список пиров из cluster_config.peers и подключается к ним по gossip-протоколу (memberlist);
• передаёт метаданные и события по UDP и TCP на gossip-порту;
• участвует в Raft-группах _meta и шардов.

Если peers пуст или все пиры недоступны, нода работает в single-node mode как один из нормальных режимов.

Через gossip синхронизируются:

• метаданные нод: node_id, регион;
• инвалидации конфигурации (ключи _invalidate:*) — они запускают hot-reload на других нодах;
• записи распределённого KV-хранилища. Конфликты разрешаются по правилу Last-Write-Wins по системным часам.

Условия включения Raft

Raft-координация работает, когда одновременно:

• cluster_config.enabled: true;
• config_store указывает на PostgreSQL.

Блок cluster_config.raft необязателен: при включённом кластере недостающие параметры получают значения по умолчанию. В режиме файлового config store Raft не используется.

Каталог данных ноды

Meta-группа топологии и бюджетные шарды хранят durable-состояние в локальном каталоге ноды:

<data_dir>/
  node.bolt        журнал событий отказоустойчивости
  raft/              права 0700
    _meta.bolt         meta-группа топологии
    budget/            бюджетные шарды, по каталогу на шард
      shard0/
        identity.json    привязка ноды, кластера, шарда и реплики
        state.bolt       applied index, граница компакции, маркер снапшота
        wal/             сегменты etcd WAL
        snap/            снапшоты с проверкой CRC32C

Требования к каталогу:

• Постоянное хранилище на каждой ноде. Каталог должен переживать перезапуск процесса и пода. emptyDir в Kubernetes не подходит.
• Не общий volume. Каждая нода владеет своим каталогом. Общий NFS или один PVC на все реплики недопустим.
• Привязка identity. raft/_meta.bolt закрепляет {node_name, cluster_id, member_id}, каждый identity.json — {node_name, cluster_id, shard_id, replica_id}. Если каталог стёрт или подключён не к той ноде, старт завершается фатальной ошибкой. Это защита от небезопасного возврата в кворум.
• Две единицы резервного копирования. Бэкап базы данных не содержит Raft-журнал. Для бэкапа узла нужно копировать всю директории. Размер локальных данных очень компактент, так как содержит только журнал еще не сохраненных в PostgreSQL изменений бюджета и топологию кластера. Журнал операций бюджета сбрасывается каждые 10 секунд при настройки по умолчанию.

Потеря всего raft/ — потеря identity ноды. Нода входит в кластер заново под новыми идентификаторами, реплики шардов реплицируются кворумом. Потеря одного raft/budget/<shard_id> при живом _meta.bolt паркует реплику — см. Локальная реплика на ноде.

Путь каталога определяется так: переменная MERIDIAN_DATA_DIR → поле data_dir → /var/lib/meridian/data. Значение указывает на каталог, а не на файл.

Размер кластера

Документ топологии допускает не более 5 нод. Фактор репликации не превышает 5.

Используйте нечётное число нод: чётное не повышает отказоустойчивость.

Первый старт кластера

При первом старте с пустой базой кластер создаёт топологию v1: список нод, группу _meta и шард shard0. Это происходит, только когда каждая нода из peers запустилась и активировалась. До этого нода:

• отвечает 200 на /internal/live и /health, поэтому оркестратор её не перезапускает;
• отвечает 503 на /internal/ready с телом {"status":"not_ready","reason":"greenfield founding: waiting for all configured cluster members — not yet ready"};
• не запускает плагины и не обслуживает /api.

Ожидание завершается само, когда запустятся недостающие ноды. Ограничить его можно полем founding_wait_timeout_seconds.

Обновление работающего кластера, перезапуски и присоединение новой ноды это ожидание не затрагивают.

Параметры cluster_config

Минимальный пример

{
  "cluster_config": {
    "enabled": true,
    "node_name": "node-1.meridian.internal",
    "region": "eu-central-1",
    "cluster_token": "change_me",
    "peers": [
      "node-1.meridian.internal:7946",
      "node-2.meridian.internal:7946",
      "node-3.meridian.internal:7946"
    ],
    "gossip": {
      "port": 7946,
      "config": {
        "timeout_seconds": 10,
        "success_threshold": 3,
        "failure_threshold": 3
      }
    },
    "raft": {
      "grpc_port": 9090,
      "reservation_ttl": "1h"
    }
  }
}

Поля верхнего уровня

gossip

Если меняете порт, откройте его в сетевых политиках на UDP и TCP.

Идентичность ноды

node_id определяется по приоритету:

1. Переменная MERIDIAN_NODE_ID.
2. Поле cluster_config.node_name.
3. Hostname операционной системы.
4. node1.

В кластерном режиме имя из пунктов 3 и 4 — ошибка старта. Задайте MERIDIAN_NODE_ID или node_name явно.

Имена clusterLeader и имена, начинающиеся с shardLeader:, зарезервированы под селектор ?target=. В режимах с PostgreSQL нода с таким именем не запускается, а POST /api/cluster/v1/nodes отвечает 400.

raft

raft.storage

backend переопределяется переменной MERIDIAN_RAFT_STORAGE_BACKEND. Приоритет: переменная → config.json → wal. Неизвестное имя бэкенда — ошибка старта.

raft.timing

Блок необязателен. Длительности задаются в формате Go: "100ms", "5s".

wal_write_wait — компромисс. При высоком ровном потоке запросов он снижает число записей на диск лидера. При низком — только добавляет задержку.

Каждое поле переопределяется переменной окружения. Приоритет: переменная → config.json → умолчание.

raft.admission

Блок необязателен. Он задаёт, когда шард начинает отвечать 503 с заголовком Retry-After вместо того, чтобы копить очередь резервирований.

Отбрасываются только RESERVE. FINALIZE, RELEASE, компенсации, конфигурационные и миграционные предложения принимаются всегда: они закрывают уже выполненную работу.

Максимальная доля строго меньше 1: пропущенные запросы дают измерения задержки, по которым шард видит своё восстановление.

Клиент получает 503 с телом overloaded. Retry-After — задержка коммита в секундах, от 1 до 30.

Некорректное значение — ошибка старта. Несогласованный набор значений останавливает старт, только если Raft действительно включён. Иначе пишется предупреждение.

Состояние сброса нагрузки на ноде: GET /api/cluster/v1/shards/{shard_id}/admission и GET /api/cluster/v1/node/metrics. В Prometheus — семейство meridian_raft_admission_*.

Гео-распределённый кластер

Значения по умолчанию рассчитаны на локальную сеть с задержкой меньше миллисекунды. Для кластера между регионами поднимайте значения вместе:

• интервал heartbeat ≈ p99 RTT между самыми удалёнными нодами;
• таймаут выборов ≥ 10 × интервал heartbeat;
• dial_timeout и send_timeout меньше таймаута выборов, но заметно больше p99 RTT.

Пример для p99 RTT около 50 мс:

{
  "cluster_config": {
    "raft": {
      "timing": {
        "tick_interval": "50ms",
        "election_ticks": 20,
        "heartbeat_ticks": 1,
        "dial_timeout": "800ms",
        "send_timeout": "800ms"
      }
    }
  }
}

Больший таймаут выборов — более долгое переключение лидера. Значения по умолчанию между регионами — постоянные ложные перевыборы. Итоговые значения нода пишет в лог при старте.

pubsub_health

Ноды публикуют сообщения HealthPing в канал _pubsub_health. Проба готовности открывается, когда нода услышала каждого ожидаемого пира. Результат попадает в поле cluster.pubsub ответа /health и в /internal/ready.

auto_repair

Лидер _meta каждые 30 секунд возвращает кластер к объявленной топологии. Шард без кворума он не трогает. Подробнее — Авто-восстановление.

event_journal

Журнал событий отказоустойчивости в <data_dir>/node.bolt. См. События отказоустойчивости.

promotion

Service discovery

Автоматическое обнаружение нод не реализовано и не запланировано. cluster_config.discovery.enabled: true приводит к ошибке старта: service discovery is not implemented, use static peers: <type>.

Используйте статический список peers во всех сценариях, включая Kubernetes: StatefulSet даёт стабильные DNS-имена.

Переменные окружения

У кластерных переменных нет псевдонимов BIFROST_*.

Шаблоны развёртывания

Все шаблоны используют образ Enterprise ghcr.io/neria-cloud/meridian-ent. Образ:

• слушает порт 8080 на 0.0.0.0;
• читает конфигурацию из /app/data/config.json;
• хранит durable-состояние в /app/data (MERIDIAN_DATA_DIR), поле data_dir не нужно;
• работает от пользователя 1000:0.

Docker Compose

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: meridian
      POSTGRES_USER: meridian
      POSTGRES_PASSWORD: change_me
    volumes:
      - postgres_data:/var/lib/postgresql/data

  meridian-1:
    image: ghcr.io/neria-cloud/meridian-ent:latest
    hostname: meridian-1
    environment:
      MERIDIAN_NODE_ID: meridian-1
    volumes:
      - ./data-1:/app/data
    ports:
      - "8081:8080"

  meridian-2:
    image: ghcr.io/neria-cloud/meridian-ent:latest
    hostname: meridian-2
    environment:
      MERIDIAN_NODE_ID: meridian-2
    volumes:
      - ./data-2:/app/data
    ports:
      - "8082:8080"

  meridian-3:
    image: ghcr.io/neria-cloud/meridian-ent:latest
    hostname: meridian-3
    environment:
      MERIDIAN_NODE_ID: meridian-3
    volumes:
      - ./data-3:/app/data
    ports:
      - "8083:8080"

volumes:
  postgres_data:

В каждом каталоге ./data-N/ создайте config.json с одинаковым cluster_config:

{
  "cluster_config": {
    "enabled": true,
    "region": "local",
    "cluster_token": "change_me",
    "peers": [
      "meridian-1:7946",
      "meridian-2:7946",
      "meridian-3:7946"
    ],
    "gossip": {
      "port": 7946
    },
    "raft": {
      "grpc_port": 9090
    }
  },
  "config_store": {
    "enabled": true,
    "type": "postgres",
    "config": {
      "host": "postgres",
      "port": "5432",
      "user": "meridian",
      "password": "change_me",
      "db_name": "meridian",
      "ssl_mode": "disable"
    }
  }
}

Каталоги ./data-N должны быть доступны на запись пользователю с UID 1000.

Kubernetes (StatefulSet)

StatefulSet с headless-сервисом даёт стабильные DNS-имена meridian-0.meridian-cluster.meridian.svc.cluster.local. Эти же имена используются и в peers, и в MERIDIAN_NODE_ID.

apiVersion: v1
kind: ConfigMap
metadata:
  name: meridian-config
  namespace: meridian
data:
  config.json: |
    {
      "cluster_config": {
        "enabled": true,
        "region": "eu-central-1",
        "cluster_token": "change_me",
        "peers": [
          "meridian-0.meridian-cluster.meridian.svc.cluster.local:7946",
          "meridian-1.meridian-cluster.meridian.svc.cluster.local:7946",
          "meridian-2.meridian-cluster.meridian.svc.cluster.local:7946"
        ],
        "gossip": { "port": 7946 },
        "raft": { "grpc_port": 9090 }
      },
      "config_store": {
        "enabled": true,
        "type": "postgres",
        "config": {
          "host": "postgres.meridian.svc.cluster.local",
          "port": "5432",
          "user": "meridian",
          "password": "change_me",
          "db_name": "meridian",
          "ssl_mode": "require"
        }
      }
    }
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: meridian
  namespace: meridian
spec:
  serviceName: meridian-cluster
  replicas: 3
  # Обязательно для первого старта: при OrderedReady под-1 не создаётся,
  # пока под-0 не станет Ready, а под-0 ждёт все ноды.
  podManagementPolicy: Parallel
  selector:
    matchLabels:
      app: meridian
  template:
    metadata:
      labels:
        app: meridian
    spec:
      securityContext:
        fsGroup: 0
      containers:
      - name: meridian
        image: ghcr.io/neria-cloud/meridian-ent:latest
        env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: MERIDIAN_NODE_ID
          value: "$(POD_NAME).meridian-cluster.meridian.svc.cluster.local"
        ports:
        - containerPort: 8080
          name: http
        - containerPort: 7946
          name: gossip-tcp
          protocol: TCP
        - containerPort: 7946
          name: gossip-udp
          protocol: UDP
        - containerPort: 9090
          name: raft-grpc
        - containerPort: 3320
          name: olric
        - containerPort: 3322
          name: olric-ml
        volumeMounts:
        - name: data
          mountPath: /app/data
        - name: config
          mountPath: /app/data/config.json
          subPath: config.json
        livenessProbe:
          httpGet:
            path: /internal/live
            port: 8080
          initialDelaySeconds: 15
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /internal/ready
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5
      volumes:
      - name: config
        configMap:
          name: meridian-config
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi
---
apiVersion: v1
kind: Service
metadata:
  name: meridian-cluster
  namespace: meridian
spec:
  clusterIP: None
  publishNotReadyAddresses: true
  selector:
    app: meridian
  ports:
  - port: 8080
    name: http
  - port: 7946
    name: gossip-tcp
    protocol: TCP
  - port: 7946
    name: gossip-udp
    protocol: UDP
  - port: 9090
    name: raft-grpc
  - port: 3320
    name: olric
  - port: 3322
    name: olric-ml
---
apiVersion: v1
kind: Service
metadata:
  name: meridian
  namespace: meridian
spec:
  type: LoadBalancer
  selector:
    app: meridian
  ports:
  - port: 80
    targetPort: 8080
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: meridian-pdb
  namespace: meridian
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: meridian

publishNotReadyAddresses: true нужен при первом старте: пока ноды не Ready, их DNS-имена должны разрешаться, иначе они не найдут друг друга.

Виртуальные машины (systemd)

{
  "cluster_config": {
    "enabled": true,
    "region": "eu-central-1",
    "data_dir": "/var/lib/meridian/data",
    "cluster_token": "change_me",
    "peers": [
      "meridian-1.internal:7946",
      "meridian-2.internal:7946",
      "meridian-3.internal:7946"
    ],
    "gossip": { "port": 7946 },
    "raft": { "grpc_port": 9090 }
  }
}

Файл кладите в /var/lib/meridian/config.json. Блок config_store — как в примере для Docker Compose.

# /etc/systemd/system/meridian.service
[Unit]
Description=Meridian Gateway
After=network.target

[Service]
Type=simple
User=meridian
Group=meridian
Environment="MERIDIAN_NODE_ID=meridian-1.internal"
ExecStart=/usr/local/bin/meridian -app-dir /var/lib/meridian -host 0.0.0.0 -port 8080
Restart=always
RestartSec=10

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/meridian

[Install]
WantedBy=multi-user.target

DNS-имена meridian-{1,2,3}.internal должны разрешаться на всех нодах. MERIDIAN_NODE_ID на каждой ноде — её имя из peers.

API управления

Эндпоинты шардов и миграций — на странице Шардинг.

Изменяющие топологию эндпоинты требуют заголовка If-Match с текущей Latest-версией: без него — 428, с устаревшей — 412. dry_run=true возвращает версию и план с 200 без записи. apply=false сохраняет версию без применения и возвращает 200. По умолчанию сервер сохраняет версию, запускает применение в фоне и возвращает 202 с execution_id.

topology.discovered[] — ноды, которые кластер видит, но документ не размещает. source — канал обнаружения (gossip, parked, gossip+parked). reason — что даст добавление: new — просто добавить, excluded_returning — выдать новую identity и пересобрать реплики. replace_existing передаётся в POST /api/cluster/v1/nodes как есть.

Запрос к конкретной ноде: ?target=

Селектор ?target= выполняет запрос на выбранной ноде, куда бы его ни направил балансировщик. Его принимают 14 маршрутов: topology/versions, topology/versions/{version}, topology/versions/{version}/plan, topology/executions/{id}, events, shards, shards/{id}, shards/{id}/counters, shards/{id}/admission, node/metrics, shards/refresh, shards/{id}/stop, shards/{id}/start и groups/{group_id}/replicas/{node_name}/reseat.

Ответ несёт заголовок X-Meridian-Served-By с именем ответившей ноды. Остальные маршруты /api/cluster/v1 с ?target= отвечают 400. Коды ошибок: 400 — shardLeader: без идентификатора; 503 — цель не найдена; 502 — цель недоступна.

Пересылка требует глобального права cluster.config.read. Запрос идёт на API-порт ноды, по умолчанию 8080, — откройте его между нодами.

Ответ /api/cluster/v1/status

{
  "enabled": true,
  "mode": "cluster",
  "active_nodes": 3,
  "this_node": {
    "node_id": "meridian-1.internal",
    "region": "eu-central-1",
    "gossip_port": 7946
  },
  "members": [
    {
      "node_id": "meridian-1.internal",
      "address": "10.0.1.10:7946",
      "region": "eu-central-1",
      "state": "alive",
      "is_self": true
    }
  ],
  "config": {
    "gossip_port": 7946,
    "peers": ["meridian-1.internal:7946", "meridian-2.internal:7946", "meridian-3.internal:7946"],
    "region": "eu-central-1",
    "timeout_seconds": 10
  },
  "gossip_health": {
    "health_score": 0,
    "num_members": 3
  }
}

Дополнительные поля ответа:

• mode — cluster, если активных нод больше одной, иначе single-node;
• serving — {ready, reason}: принимает ли нода трафик;
• topology — документ, курсоры версий, ноды, _meta и шарды с лидерами и здоровьем, состояние авто-восстановления (reconciliation), обнаруженные ноды (discovered);
• promotion — взведённый аварийный промоушен;
• local_shards — локальные реплики шардов на этой ноде;
• gossip_health.health_score — 0 означает идеальное состояние, больше — хуже.

Устранение неполадок

Сетевые порты

API-порт используется и между нодами: через него пересылаются запросы с ?target= и синхронизация LDAP. Без него страницы Events и Shards при выборе другой ноды отвечают 502. Межнодовый трафик не шифруется и несёт учётные данные вызывающего — он рассчитан на доверенную сеть.