Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

/sys/replication/dr

Конечные точки /sys/replication/dr используются для управления репликацией Disaster Recovery (DR). Через них включают и отключают роли основного и вторичного кластеров, выпускают токены активации, повышают и понижают роль кластера, обновляют основной кластер для вторичного и обслуживают токен операций DR.

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

Инструкции по настройке репликации DR приведены в разделе Disaster Recovery. Порядок включения описан в статье Настройка репликации DR. Порядок повышения роли вторичного кластера описан в статье Повышение роли вторичного кластера DR до первичного. Порядок понижения роли или отключения исходного первичного кластера описан в статье Понижение роли или отключение исходного первичного кластера. Порядок возврата к исходной топологии описан в статье Возврат к исходной топологии. Большинство операций вызывайте из корневого пространства имен. Описание пространств имен приведено в разделе Пространства имен (namespaces).

1. Проверка статуса DR

Конечная точка выводит сведения о статусе репликации: режим, ход синхронизации и связанные поля.

Конечная точка не требует аутентификации.

Метод

Путь

GET

/sys/replication/dr/status
Пример запроса:
curl \
  http://127.0.0.1:8200/v1/sys/replication/dr/status
Пример ответа основного кластера:
{
  "data": {
    "cluster_id": "eef2a5ab-51e2-1c05-407c-8b4dc8d09ebf",
    "corrupted_merkle_tree": false,
    "known_secondaries": [
      "4ca6b639-046b-5bb1-8043-6788ddf09121"
    ],
    "last_corruption_check_epoch": "-62135596800",
    "last_dr_wal": 223,
    "last_reindex_epoch": "0",
    "last_wal": 223,
    "merkle_root": "2494830f1a1c304829b5742a232d39b5457bce9a",
    "mode": "primary",
    "primary_cluster_addr": "",
    "secondaries": [
      {
        "api_address": "https://127.0.0.1:65531",
        "clock_skew_ms": "0",
        "cluster_address": "https://127.0.0.1:65534",
        "connection_status": "connected",
        "last_heartbeat": "2024-03-04T10:05:56-05:00",
        "last_heartbeat_duration_ms": "0",
        "node_id": "4ca6b639-046b-5bb1-8043-6788ddf09121",
        "replication_primary_canary_age_ms": "696"
      }
    ],
    "ssct_generation_counter": 0,
    "state": "running"
  }
}
Пример ответа вторичного кластера:
{
  "data": {
    "cluster_id": "eef2a5ab-51e2-1c05-407c-8b4dc8d09ebf",
    "connection_state": "ready",
    "corrupted_merkle_tree": false,
    "known_primary_cluster_addrs": [
      "https://127.0.0.1:65524",
      "https://127.0.0.1:65525",
      "https://127.0.0.1:65526"
    ],
    "last_corruption_check_epoch": "-62135596800",
    "last_reindex_epoch": "1709564746",
    "last_remote_wal": 223,
    "last_start": "2024-03-04T10:05:46-05:00",
    "merkle_root": "2494830f1a1c304829b5742a232d39b5457bce9a",
    "mode": "secondary",
    "primaries": [
      {
        "api_address": "https://127.0.0.1:65521",
        "clock_skew_ms": "0",
        "cluster_address": "https://127.0.0.1:65524",
        "connection_status": "connected",
        "last_heartbeat": "2024-03-04T10:05:56-05:00",
        "last_heartbeat_duration_ms": "0",
        "replication_primary_canary_age_ms": "697"
      }
    ],
    "primary_cluster_addr": "https://127.0.0.1:65524",
    "secondary_id": "4ca6b639-046b-5bb1-8043-6788ddf09121",
    "ssct_generation_counter": 0,
    "state": "stream-wals"
  }
}

2. Включение репликации DR на основном кластере

Конечная точка включает репликацию DR в роли основного. Используйте ее, если репликация DR на кластере отключена. Если кластер уже является вторичным, сначала повысьте его роль.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/primary/enable

2.1. Параметры

  • primary_cluster_addr (string: "") — адрес кластера, который основной кластер передает вторичному. Укажите значение, если адрес основного кластера недоступен напрямую и доступен через другой путь, например через балансировщик TCP

Пример тела запроса:
{}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/primary/enable

3. Понижение роли основного кластера

Конечная точка понижает основной кластер DR до вторичного. После понижения кластер не подключается к основному. См. вызов update-primary. Кластер переходит в состояние, готовое к роли вторичного. При последующем update-primary локальное хранилище очищается.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/primary/demote
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/replication/dr/primary/demote

4. Отключение репликации DR на основном кластере

Конечная точка полностью отключает репликацию DR на кластере. Вторичный кластер больше не сможет подключиться. Кластер покидает пару репликации DR.

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

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/primary/disable
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/replication/dr/primary/disable

5. Генерация токена активации вторичного кластера

Конечная точка формирует токен активации вторичного кластера с заданным произвольным идентификатором. Идентификатор должен быть уникальным. По нему можно отозвать доступ вторичного кластера.

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

Конечная точка требует возможности sudo.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/primary/secondary-token

5.1. Параметры

  • id (обязательный, string: <required>) — произвольный идентификатор, например us-east

  • ttl (необязательный, string: "30m") — TTL токена активации вторичного кластера

  • secondary_public_key (необязательный, string: "") — открытый ключ вторичного кластера, если защита учетных данных выполняется шифрованием, а не response wrapping. Используйте параметр, чтобы не вызывать API основного кластера во время активации вторичного кластера

Пример тела запроса:
{
  "id": "us-east-1"
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data '{"id": "dr-secondary"}' \
  http://127.0.0.1:8200/v1/sys/replication/dr/primary/secondary-token
Пример запроса с открытым ключом вторичного кластера:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data '{"id": "dr-secondary", "secondary_public_key": "<secondary_public_key>"}' \
  http://127.0.0.1:8200/v1/sys/replication/dr/primary/secondary-token
Пример ответа:
{
  "request_id": "string",
  "lease_id": "string",
  "lease_duration": 0,
  "renewable": true,
  "data": {},
  "warnings": [
    "string"
  ],
  "wrap_info": {
    "token": "string",
    "ttl": 0,
    "creation_time": "string",
    "wrapped_accessor": "string"
  }
}

6. Отзыв токена активации вторичного кластера

Конечная точка отзывает возможность вторичного кластера подключаться к основному кластеру DR. Вторичный кластер отключается сразу и не сможет подключиться снова без нового токена активации вторичного кластера. Команду можно выполнить с любого узла основного кластера DR.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/primary/revoke-secondary

6.1. Параметры

  • id (string: <required>) — произвольный идентификатор, например us-east

Пример тела запроса:
{
  "id": "us-east"
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/primary/revoke-secondary

7. Генерация открытого ключа вторичного кластера

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

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/generate-public-key
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-public-key

8. Включение репликации DR на вторичном кластере

Конечная точка включает репликацию на вторичном кластере DR с помощью токена активации вторичного кластера.

Операция полностью очищает пользовательские данные во встроенном хранилище Raft на вторичном кластере. Затем начинается синхронизация с основным кластером.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/enable

8.1. Параметры

  • token (string: <required>) — токен активации вторичного кластера, полученный с основного кластера

  • primary_api_addr (обязательный, string: <required>) — API-адрес, который переопределяет значение из токена. Укажите параметр, если адрес перенаправления основного кластера недоступен с вторичного напрямую

  • ca_certificate (string: "") — сертификат CA, которому должен доверять клиент

Пример тела запроса:
{
  "token": "..."
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/enable

9. Повышение роли вторичного кластера

Конечная точка повышает вторичный кластер DR до основного. Кластер проверяет запрос повышения роли и инициализирует WAL для роли основного. Одновременно не должно быть более одного основного. К основному кластеру можно подключить только один вторичный кластер.

Конечная точка требует токен операций DR. Описание токена приведено в статье Токен операций DR.

Одновременно в конфигурации DR может быть активен только один основной кластер и один вторичный. При переводе вторичного в основной (promote) и наличии активного основного репликация данных остановится.

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

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/promote

9.1. Параметры

  • dr_operation_token (string: <required>) — токен операций DR для авторизации запроса

  • primary_cluster_addr (string: "") — адрес кластера, который основной кластер передает вторичному. Укажите значение, если адрес основного кластера недоступен напрямую, например через балансировщик

  • force (bool: false) — если true, кластер будет повышен даже при ошибках отдельных проверок безопасности. Принудительное повышение может привести к потере данных, если репликация не завершена

Пример тела запроса:
{
  "dr_operation_token": "ijH8tphEHaBtgx+IvPfxDsSi2LV4j9k+Lad6eqT5cJw="
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/promote
Пример ответа:
{
  "progress": 0,
  "required": 1,
  "complete": false,
  "request_id": "ad8f9074-0e24-d30e-83cd-595c9652ff89",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "complete": false,
    "progress": 0,
    "required": 1
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

10. Отключение репликации DR на вторичном кластере

Конечная точка полностью отключает репликацию DR на кластере. Кластер больше не сможет подключиться к основному кластеру DR.

Конечная точка требует токен операций DR.

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

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/disable

10.1. Параметры

  • dr_operation_token (string: <required>) — токен операций DR для авторизации запроса

Пример тела запроса:
{
  "dr_operation_token": "..."
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/disable

11. Обновление основного кластера для вторичного

Конечная точка обновляет основной кластер, назначенный вторичному кластеру DR.

Операция полностью очищает пользовательские данные в локальном хранилище Raft. Затем кластер подключается к новому основному и получает данные через WAL.

Конечная точка требует токен операций DR и токен активации вторичного кластера.

Основной кластер обновляется токеном активации вторичного кластера в параметре token.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/update-primary

11.1. Параметры

  • dr_operation_token (string, required) — токен операций DR для авторизации запроса

  • token (string, required) — токен активации вторичного кластера с основного кластера. Пустая строка оставляет кластер вторичным, очищает сведения о предыдущем основном кластере и прекращает попытки повторного подключения

  • primary_api_addr (обязательный, string: <required>) — API-адрес, который переопределяет значение, встроенное в токен

  • ca_certificate (string, optional) — сертификат CA, которому должен доверять клиент

Пример тела запроса:
{
  "dr_operation_token": "...",
  "token": "..."
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/update-primary

12. Генерация токена операций DR

Путь /sys/replication/dr/secondary/generate-operation-token создает токен операций Disaster Recovery для вторичного кластера DR. Токены авторизуют отдельные операции DR. Обращайтесь с ними как с корневыми токенами: выпускайте по необходимости и удаляйте сразу после использования.

12.1. Чтение хода генерации

Конечная точка читает конфигурацию и ход текущей попытки генерации.

Метод

Путь

GET

/sys/replication/dr/secondary/generate-operation-token/attempt
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/attempt
Пример ответа:
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "encoded_token": "",
  "pgp_fingerprint": "",
  "complete": false
}

Если генерация начата, progress показывает, сколько ключей распечатывания уже передано. Значение required нужно достичь для завершения. В ответе также отображаются nonce текущей попытки и признак завершения. Если для шифрования итогового токена используется ключ PGP, возвращается его отпечаток. Если для кодирования токена используется OTP, OTP в ответе не возвращается.

12.2. Запуск генерации токена

Конечная точка инициализирует новую попытку генерации. Одновременно может идти только одна попытка.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/generate-operation-token/attempt

12.2.1. Параметры

  • pgp_key (string: "") — открытый ключ PGP в кодировке Base64. Необработанные байты токена шифруются этим значением перед возвратом последнему держателю ключа распечатывания

Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/attempt
Пример ответа:
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "encoded_token": "",
  "otp": "2vPFYG8gUSW9npwzyvxXMug0",
  "otp_length": 24,
  "complete": false
}

12.3. Отмена генерации

Конечная точка отменяет текущую попытку генерации и сбрасывает ход. Вызов обязателен, если нужно сменить OTP или ключ PGP.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

DELETE

/sys/replication/dr/secondary/generate-operation-token/attempt
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request DELETE \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/attempt

12.4. Передача ключей распечатывания (unseal key) для генерации токена

Конечная точка принимает один ключ распечатывания (unseal key) и продвигает попытку генерации. Когда число ключей распечатывания достигает порога, StarVault завершает генерацию и выпускает токен. Иначе вызывайте API повторно до достижения порога. В каждом вызове передавайте nonce попытки.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/generate-operation-token/update

12.4.1. Параметры

  • key (string: <required>) — один ключ распечатывания (unseal key)

  • nonce (string: <required>) — nonce попытки

Пример тела запроса:
{
  "key": "acbd1234",
  "nonce": "ad235"
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/generate-operation-token/update
Пример ответа:
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 3,
  "required": 3,
  "pgp_fingerprint": "",
  "complete": true,
  "encoded_token": "FPzkNBvwNDeFh4SmGA8c+w=="
}

Ответ содержит JSON-объект с nonce попытки, признаком завершения и закодированным токеном, если попытка завершена.

После выпуска токен возвращается в зашифрованном виде: с OTP или ключом PGP. Чтобы расшифровать закодированный токен операций DR (encoded_token), выполните команду:

starvault operator generate-root -dr-token \
  -decode="djw4BR1iaDUFIBxaAwpiCC1YGhQHHDMf" \
  -otp="EYHAkPQYvvz93e8iI3pg1maQ"
Пример вывода:
hvs.5xsAyncmt1OPEHhMFPMKcYAG

13. Удаление токена операций DR

Конечная точка отзывает токен операций DR. У токена нет TTL. Удалите его, когда он больше не нужен. Успешный ответ возвращает код 204. Тело ответа пустое.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/operation-token/delete

13.1. Параметры

  • dr_operation_token (string: <required>) — токен операций DR для авторизации запроса

Пример тела запроса:
{
  "dr_operation_token": "..."
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/operation-token/delete

14. Переиндексация репликации

Конечная точка переиндексирует локальное хранилище данных на вторичном кластере DR. Операция может занять длительное время. Длительность зависит от числа и размера объектов в хранилище.

Конечная точка требует токен операций DR.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/reindex

14.1. Параметры

  • diff (bool: false) — включает более медленную переиндексацию с проверкой на уровне ключей для диагностики. Значение по умолчанию — false

  • force (bool: false) — принудительно выполняет полную переиндексацию только по данным, доступным в хранилище. Значение по умолчанию — false

  • skip_flush (bool: false) — пропускает этап сброса дерева. Параметр сокращает время блокировки дерева. Если узел будет остановлен до полной асинхронной записи дерева, переиндексация может примениться не полностью. Тогда потребуется новая переиндексация. Значение по умолчанию — false

  • dr_operation_token (string: <required>) — токен операций DR для авторизации запроса

Пример тела запроса:
{
  "dr_operation_token": "..."
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/reindex
Пример ответа:
{
  "warnings": ["..."]
}

15. Проверка дерева Меркла

Конечная точка возвращает сведения о повреждении и состоянии составного дерева Меркла на вторичном кластере DR.

Параметров пути нет. Конечная точка требует токен операций DR в теле запроса.

Вызывайте конечную точку из корневого пространства имен.

Метод

Путь

POST

/sys/replication/dr/secondary/merkle-check

15.1. Параметры

  • dr_operation_token (string: <required>) — токен операций DR для авторизации запроса

Пример тела запроса:
{
  "dr_operation_token": "..."
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/replication/dr/secondary/merkle-check
Пример ответа:
{
  "request_id": "d4b2ad1a-6e5f-7f9e-edfe-558eb89a40e6",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": true,
  "data": {
    "merkle_corruption_report": {
      "corrupted_root": true,
      "corrupted_tree_map": {
        "1": {
          "corrupted_index_tuples_map": {
            "5": {
              "corrupted": false,
              "subpages": [
                28
              ]
            }
          },
          "corrupted_subtree_root": false,
          "root_hash": "DyGc6rQTV9XgyNSff3zimhi3FJM=",
          "tree_type": "replicated"
        },
        "2": {
          "corrupted_index_tuples_map": null,
          "corrupted_subtree_root": false,
          "root_hash": "EXmRTdfYCZTm5i9wLef9RQqyLCw=",
          "tree_type": "local"
        }
      },
      "last_corruption_check_epoch": "2023-09-11T11:25:59.44956-07:00"
    }
  }
}

Ответ описывает состояние составного дерева Меркла. Поля ответа 200:

  • request_id (string) — идентификатор запроса

  • lease_id (string) — идентификатор аренды

  • lease_duration (integer) — длительность аренды, например 0

  • renewable (boolean) — признак возобновляемости, например true

  • data.merkle_corruption_report.corrupted_root (boolean) — признак повреждения корня, например true

  • data.merkle_corruption_report.corrupted_tree_map (object) — карта повреждений поддеревьев. Ключи — идентификаторы деревьев. Для каждого дерева могут быть corrupted_index_tuples_map, признак corrupted и массив subpages