Восстановление при потере кворума

Благодаря интегрированному хранилищу поддержка кворума Raft необходима для настройки и эксплуатации среды StarVault. Кластер StarVault безвозвратно теряет кворум, если нет возможности восстановить достаточное количество серверов для достижения согласия и избрания лидера. Без кворума серверов кластера StarVault больше не могут выполнять операции чтения и записи.

Кворум кластера динамически обновляется, когда к кластеру присоединяются новые сервера. StarVault рассчитывает кворум по формуле (n+1)/2, где n - количество серверов в кластере. Например, для кластера из 3 серверов вам потребуется как минимум 2 работающих сервера, чтобы кластер функционировал должным образом, (3+1)/2 = 2. В частности, вам понадобятся 2 постоянно активных сервера для выполнения операций чтения и записи.

1. Сценарий

Когда на двух из трех серверов произошел сбой, кластер теряет кворум и становится неработоспособным.

Несмотря на то, что один из серверов полностью функционирует, кластер не сможет обрабатывать запросы на чтение или запись. Это показано в примерах вывода следующих команд:

$ starvault operator raft list-peers

Пример вывода:

Error reading the raft cluster configuration: Error making API request.

URL: GET https://127.0.0.1:8200/v1/sys/storage/raft/configuration
Code: 500. Errors:

* local node not active but active cluster node not found

$ starvault kv get kv/apikey

Пример вывода:

Error reading the raft cluster configuration: Error making API request.

URL: GET https://127.0.0.1:8200/v1/sys/storage/raft/configuration
Code: 500. Errors:

* local node not active but active cluster node not found

В данном руководстве представлена инструкция по восстановлению работы StarVault после безвозвратной потери двух из трех серверов с помощью преобразования их в кластер из одного сервера.

Для завершения данной процедуры оставшийся сервер должен быть полностью работоспособен.

Иногда StarVault теряет кворум из-за автопилота и серверов, помеченных как неработоспособные, но сервис все еще работает. На неработоспособных серверах необходимо остановить сервисы перед запуском процедуры peers.json.

В кластере из 5 серверов или в случае, когда пользователи не имеют права голоса, необходимо остановить работу других серверов, прежде чем выполнять восстановление peers.json.

2. Размещение каталога хранилища

На работоспособном сервере StarVault найдите каталог хранилища Raft. Чтобы узнать расположение каталога, просмотрите файл конфигурации StarVault. Раздел storage будет содержать путь к каталогу.

storage "raft" {
  path    = "/opt/starvault/data" (1)
  server_id = "starvault_1" (2)
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  cluster_address     = "0.0.0.0:8201"
  tls_disable = true
}

api_addr = "http://192.0.2.1:8200"
cluster_addr = "http://10.0.101.22:8201"
disable_mlock = true
ui=true

1	`path` - это путь к файловой системе, в которой StarVault хранит данные;
2	`server_id` - это идентификатор сервера в кластере Raft.

3. Создайте json-файл с информацией о сервере

Создайте файл peers.json. Внутри каталога хранилища (opt/starvault/data) есть директория с именем raft.

starvault
└── data
    ├── raft
    │   ├── raft.db
    │   └── snapshots
    └── vault.db

Чтобы дать единственному оставшемуся серверу StarVault достичь кворума и выбрать себя в качестве лидера, создайте файл raft/peers.json, содержащий информацию о сервере. Формат файла представляет собой массив JSON, содержащий идентификатор сервера, адрес:порт и информацию о праве голоса исправного сервера StarVault (например, starvault_1). Пример представлен ниже.

cat > /opt/starvault/data/raft/peers.json << EOF
[
  {
    "id": "starvault_1", (1)
    "address": "10.0.101.22:8201", (2)
    "non_voter": false (3)
  }
]
EOF

1	`id` (`string: <required>`) - указывает идентификатор сервера.
2	`address` (`string: <required>`) - указывает хост и порт сервера. Порт является портом кластера сервера.
3	`non_voter` (`bool: <false>`) - оопределяет, является ли сервер неголосующим.

4. Перезапустите StarVault

Перезапустите StarVault, чтобы StarVault мог загружить новый файл peers.json.

$ sudo systemctl restart starvault

Если вы используете Systemd, сигнал SIGHUP работать не будет.

5. Распечатайте StarVault

Если функция автоматического распечатывания не настроена, распечатайте StarVault и затем проверьте его статус. Для этого используйте следующую команду:

$ starvault operator unseal

Пример вывода:

Unseal Key (will be hidden):

Чтобы посмотреть статус StarVault, выполните:

starvault status

Пример вывода:

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            5
Threshold               3
Version                 1.1.0
Build Date              n/a
Storage Type            raft
Cluster Name            vault-cluster-ca47427f
Cluster ID              263f0950-b1b3-05b0-498f-835055ac7909
HA Enabled              true
HA Cluster              https://10.0.101.22:8201
HA Mode                 active
Active Since            2025-10-10T11:46:10.126776465Z
Raft Committed Index    242
Raft Applied Index      242

6. Проверка успешного завершения

Процедура восстановления завершается успешно, когда StarVault запускается и отображает следующие сообщения в логах:

...snip...
[INFO]  core.cluster-listener: serving cluster requests: cluster_listen_address=[::]:8201
[INFO]  storage.raft: raft recovery initiated: recovery_file=peers.json
[INFO]  storage.raft: raft recovery found new config: config="{[{Voter starvault_1 https://10.0.101.22:8201}]}"
[INFO]  storage.raft: raft recovery deleted peers.json
...snip...

7. Проверка peer list

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

$ starvault operator raft list-peers

Пример вывода:

server       Address                     State     Voter
----       -------                     -----     -----
starvault_1    https://10.0.101.22:8201    leader    true

8. Заключение

Если неисправные серверы подлежат восстановлению, лучшим вариантом будет вернуть их в рабочее состояние и повторно подключить к кластеру, используя те же адреса хостов. Это вернет кластер в полностью работоспособное состояние. В таком случае файл raft/peers.json должен содержать идентификатор сервера, адрес: порт и информацию о праве голоса для каждого сервера StarVault, который вы хотите включить в кластер.

[
  {
    "id": "server1",
    "address": "server1.starvault.local:8201",
    "non_voter": false
  },
  {
    "id": "server2",
    "address": "server2.starvault.local:8201",
    "non_voter": false
  },
  {
    "id": "server3",
    "address": "server3.starvault.local:8201",
    "non_voter": false
  }
]