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

/sys/storage

В настоящее время данный подраздел API используется только для управления бэкендом хранилища Raft.

1. /sys/storage/raft

Конечные точки /sys/storage/raft используются для управления бэкендом хранения Raft в StarVault.

1.1. Присоединение к кластеру raft

Данная конечная точка присоединяет новый серверный узел к кластеру Raft. Когда используется запечатывание Shamir - как только сервер StarVault запущен, этот API должен быть использован вместо sys/init. Этот API выполняется в два этапа. После вызова присоединяющийся узел получит запрос от ведущего узла Raft. Присоединяющийся узел сможет ответить на этот запрос только после успешного распечатывания. Следовательно, присоединяющийся узел должен быть распечатан с помощью ключей распечатывания ведущего узла Raft.

Метод

Путь

POST

/sys/storage/raft/join

1.1.1. Параметры

  • leader_api_addr (string: <required>) – адрес узла-лидера в кластере Raft, к которому этот узел пытается присоединиться.

  • retry (bool: false) - в случае сбоев повторить попытку присоединения к кластеру Raft.

  • leader_ca_cert (string: "") -сертификат CA, используемый для связи с узлом-лидером Raft.

  • leader_client_cert (string: "") - клиентский сертификат, используемый для связи с узлом-лидером Raft.

  • leader_client_key (string: "") - клиентский ключ, используемый для связи с узлом-лидером Raft.

  • leader_tls_servername (string: "") - имя сервера TLS, используемое при подключении по HTTPS. Должно совпадать с одним из имён в DNS-именах SAN сертификата удалённого сервера.

  • auto_join (string: "") - определяет все метаданные автоматического присоединения. Если они указаны, StarVault попытается автоматически обнаружить одноранговые узлы в дополнение к тому, что может быть предоставлено через «leader_api_addr».

  • auto_join_scheme (string: "https") - схема URI, которая будет использоваться для auto_join.

  • auto_join_port (int: 8200) - порт, который будет использоваться для auto_join.

Пример тела запроса:
{
  "leader_api_addr": "https://127.0.0.1:8200",
  "leader_ca_cert": "-----BEGIN CERTIFICATE-----\nMIIDKTCCAhGgAwIBAgIUcd+Uyk1Tz+FhcbYP0zmynlkARoEwDQYJKoZIhvcNAQEL\nBQAwFDESMBAGA1UEAxMJbG9jYWxob3N0MB4XDTE5MDYyNDIyMjgzNVoXDTE5MDYy\nNzIyMjkwNVowADCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKdYr6rU\n21vYf7q/cpPigtBchqHvGZvpbA9DZucuUdQ0g4oAXRyShQ8omzmZOmO4A1GI3gqz\nHBePSYl+1IZCwgbPBk2CH7MhlMMINdwoEH6IxFgHNBkNK6GbwnGLyKL0Sym88ly1\n+sPP6+llS8uWNKu5GcObHLysD3Ce6QTt3usDPiw0cxp/KL1EkMi2dT7PvxTsX137\nsEsuQcylltGEtRb67xvFBP8XhQZAEGw+u4S3EmtwWMwZixB45WQhj2Ncz5U0+w8V\ncp9DSqB1QheoGPBBI62jHle05kzG85ZKmLBgHE6HEGS8biIHpannM7dgI0cRH6i2\nF69N0rcbzK+NInUCAwEAAaOBhjCBgzAOBgNVHQ8BAf8EBAMCA6gwHQYDVR0lBBYw\nFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQWBBQelJT5fthHdbCyD5zaI4tw\n7mfp8zAfBgNVHSMEGDAWgBSuG6hyoOWoiGvSA3kqwo9DirS+pzASBgNVHREBAf8E\nCDAGhwR/AAABMA0GCSqGSIb3DQEBCwUAA4IBAQCmetSH5w835RbbyHZD8e3ClHzi\n210SrvzWkx3N0JcBOjs47jlLuqVTl0HRr2xMoIkErFbhPDBXARYV8eezhQ6G5M60\n8AwVsG56rCa1l0weK2JfnEWgkwXZ/zbpZ2yNkWatWNSHdlJwGp99JTSriQYNOnMG\nWvBDA8ukoOkIJd/a8+aXZBdUiAcFvlLWmX73pYGTlnQDiIqJvhrlkgCKPvzZqvV+\njtz7kCt9EfT6sN6Xcny7GusRBSs+XfEe8u10+mbud+ufE/QSJ2D3tTYrS6eGqpVD\nrezD8jS9PfZgQfHXVaphMADyw4flaSVxfJ/ZRFxXql3oJSuj02+VX6QsXex+\n-----END CERTIFICATE-----",
  "leader_client_cert": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIULkPFG+qu7tGv21Plc1sg4eGbMPkwDQYJKoZIhvcNAQEL\nBQAwFDESMBAGA1UEAxMJbG9jYWxob3N0MB4XDTE5MDYyNDIyMjgwNVoXDTI5MDYy\nMTIyMjgzNVowFDESMBAGA1UEAxMJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF\nAAOCAQ8AMIIBCgKCAQEAwszD+A5vWD8S1N632ElHA5Px2dk97wJBKNYc/7RPNptn\n+EOmMTXPfuA3LB92FoSMCR7ye3wvSTzyK9nqafS7U2tlOF4PJrJoNZyzrVwBVLXg\n7Pd8qQxnxbonc3bscWZuEfbFsugkPHgBtnSkyCffXKhhwM5LbJqmK5cfJRZZ0eRy\nwmOCQCJ8ZmN2KfjHiGSEw9v19CNtvFNLyfiTZZLO9M5n4dgainZZCs+vdKD7tSJf\nycwWiZ4ezOwLMIgxdbLYKVglbZsPcMVVPLTskmY8WiHUM6sy3HAbFQn20Rj7JGE6\nldR3NX80YtCMt8/d+xzBfxu4x8juxHCgZFGt3nUS0wIDAQABo38wfTAOBgNVHQ8B\nAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUrhuocqDlqIhr0gN5\nKsKPQ4q0vqcwHwYDVR0jBBgwFoAUrhuocqDlqIhr0gN5KsKPQ4q0vqcwGgYDVR0R\nBBMwEYIJbG9jYWxob3N0hwR/AAABMA0GCSqGSIb3DQEBCwUAA4IBAQBRno9NOaat\n8g1ma/6OxP1JUt1VRao4+t2GQTCJ697d2SmpHr8CYanMPog+QhDj/lderA/oS0V3\n2jruH9CyH0smFMIsLBZpnRIwdhTISbIXdU3Uvcd6nne/f7LiUUmqf8YS9SHxWPFq\nI72QvtPrsjYKCZwJsHZe071lYScjrjGnlUhhbrug2g6/ZMHJ7mndGE022zMn/XD/\njrrKE6fCDCjJ4PRrta7+G7BvsFHqMSQ+2/947TGohxW69cbNyDeiQVDQ5mpJUy2b\nnOCVVnq0nafSuvBTHCCLxjd7f+9TiB/B3qT8GA9V6LANDSdQ15MRIhpup/yosmqX\nl5goCY/j3bDh\n-----END CERTIFICATE-----",
  "leader_client_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAp1ivqtTbW9h/ur9yk+KC0FyGoe8Zm+lsD0Nm5y5R1DSDigBd\nHJKFDyibOZk6Y7gDUYjeCrMcF49JiX7UhkLCBs8GTYIfsyGUwwg13CgQfojEWAc0\nGQ0roZvCcYvIovRLKbzyXLX6w8/r6WVLy5Y0q7kZw5scvKwPcJ7pBO3e6wM+LDRz\nGn8ovUSQyLZ1Ps+/FOxfXfuwSy5BzKWW0YS1FvrvG8UE/xeFBkAQbD67hLcSa3BY\nzBmLEHjlZCGPY1zPlTT7DxVyn0NKoHVCF6gY8EEjraMeV7TmTMbzlkqYsGAcTocQ\nZLxuIgelqeczt2AjRxEfqLYXr03StxvMr40idQIDAQABAoIBAHCOhhkw8hnklITX\nIAm34KSklylz2JW1eqkJfL0huogwigjYFciSBE0d0sn69fr8Wb8Nf8tSjSKLjbqd\nQ/TKEhbiSCr5yriBbb2AWDmr+OwisW1D6xaudRpN2Yrlqh1wkt2P6LPS8sehodtp\n9oEIloSqC1o1ii6czAXD3JckJzuJ66yoVyCo2oVC3NETujjJRhdRcNY0dYUGx47M\n+hQo7b4s79wlMFmccrgyJcKI7Ra3DtMrBIaVXm4WcjX2x4DduZX6L4mfG83uLWng\nhbvcEPKGamUErjPGYixKE5XOwgJT6Nzq/ZZJZpok6DbHBCtqvwwByWlfLzh8lc4o\nz+Pl5EECgYEA3pJXRM+SdVUCnWIpMFOAiNstOwz3nm0/c8GDdYYNq0ere1tKCVV0\nii+ujMQY8vEdRrp7fbqJEPJANyI6sM4Jc2nxMveFuBoEsEClZuE4KBFquW8CQU4R\nGNkzKF1W0GaTI5O4QDUag+lFG6TPCwZiejTIkt65o5bnSzGLgdC546sCgYEAwHr9\nlq9HytWkV9OLz0zbcAUEIrFAljnC32Mybsj8LzdSKIZ3wErf9Txh8zqZqMyhedxL\nOn17cpJAq5Vi71uXOaxnhkf7TPuRs8nBRRJfgyNHPXuXLkuWeuvXEe/PIC+nvOIX\nas0Ab0Pvx0fRGl4EkZ2pV9oDAEUezbVVZCoO8l8CgYEAp4p3YNfzwpj0d+5tXPBu\ngBakzJ+tQjewnP1dbLk1TuqLXjdQ2wfVyzOrbFEtCquPwy8bSICDLxt8VURR88eU\n+6kTJK+InBYR029GUtRUhmzd7qpugyQ14IOXa9ofQI8GUbCf8M1IoWWWXQHJzN3I\ngX98QHqiOU+d2k94WYb6dzMCgYA3E7p2oMdZShLRss3hzqtH/Zd2WeQSWIrjox3u\nR4Kp/Bl9UST5GDPHl7SrhcwsWgmmthusq/VkDmeE8aUyurGmJigla3mESMQjfwrX\nue8sti6PcEsNS0HPAKc1EbriCeDkkomC3RBPxk/ZZTp3YgnKpSOs6MxNCnpLAKVj\nmQlX3wKBgQCFYyYJdCKMoaoMrNjMM34sAfTqmZT4Hbxg9KM4OMDSxyvIi0ZaVcnB\nkzssvt0FOMucp4o7h8Iujt8xsgnBHwg81IV7WOw+ZwpUDAzgVc7+kCU6CLd2Q40j\n5uFnuRgiWeGm1aT4arNLWlJrDLSGbyrf59SlGJV1hmu/7SMaYIZHSQ==\n-----END RSA PRIVATE KEY-----"
}
Пример запроса:
curl \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/storage/raft/join

Распечатайте присоединяемый узел сразу после вызова этого API.

1.2. Чтение конфигурации raft

Эта конечная точка возвращает сведения обо всех узлах в кластере Raft.

Метод

Путь

GET

/sys/storage/raft/configuration
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/sys/storage/raft/configuration
Пример ответа:
{
  "request_id": "ca4b5a1d-38d6-e27e-e756-269521328a15",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "config": {
      "index": 24,
      "servers": [
        {
          "address": "127.0.0.1:8201",
          "leader": true,
          "node_id": "raft1",
          "protocol_version": "\u0003",
          "voter": true
        },
        {
          "address": "127.0.0.2:8201",
          "leader": false,
          "node_id": "raft2",
          "protocol_version": "\u0003",
          "voter": true
        }
      ]
    }
  },
  "warnings": null
}

1.3. Удаленипе узла из кластера raft

Данная конечная точка удаляет узел из кластера Raft.

Метод

Путь

POST

/sys/storage/raft/remove-peer
Пример тела запроса:
{
  "server_id": "raft1"
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/storage/raft/remove-peer

1.4. Снимок кластера raft

Данная конечная точка возвращает снимок текущего состояния кластера Raft. Снимок возвращается в виде двоичных данных и должен быть перенаправлен в файл. Недоступно, если Raft используется исключительно для ha_storage.

Метод

Путь

GET

/sys/storage/raft/snapshot

1.4.1. Большие снимки кластера raft

Создание и восстановление снимков Raft может занять больше времени, чем установлено по умолчанию и рекомендовано StarVault. Переменная окружения STARVAULT_CLIENT_TIMEOUT позволяет увеличить время создания или восстановления снимка.

Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request GET \
  http://127.0.0.1:8200/v1/sys/storage/raft/snapshot > raft.snap

1.5. Восстановление кластера raft с помощью снимка

Данная конечная точка устанавливает предоставленный снимок, возвращая кластер в состояние, заданное в нём. Недоступно, если Raft используется исключительно для ha_storage.

Метод

Путь

POST

/sys/storage/raft/snapshot

1.5.1. Большие снимки кластера raft

Создание и восстановление снимков Raft может занять больше времени, чем установлено по умолчанию и рекомендовано StarVault. Переменная окружения STARVAULT_CLIENT_TIMEOUT позволяет увеличить время создания или восстановления снимка.

Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data-binary @raft.snap \
  http://127.0.0.1:8200/v1/sys/storage/raft/snapshot

1.6. Принудительное восстановление кластера raft с использованием снимка

Устанавливает предоставленный снимок, возвращая кластер в состояние, заданное в нём. Это то же самое, что и запись, /sys/storage/raft/snapshot за исключением того, что при этом обходят проверки соответствия ключей Autounseal или shamir с данными снимка. Недоступно, если Raft используется исключительно для ha_storage.

Метод

Путь

POST

/sys/storage/raft/snapshot-force
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data-binary @raft.snap \
  http://127.0.0.1:8200/v1/sys/storage/raft/snapshot-force

1.7. Начальная загрузка узла HA

Когда узел использует Raft исключительно для ha_storage, эта конечная точка используется для активации Raft. Это аналогично использованию sys/init для инициализации хранилища, поскольку выполняется только один раз для каждого кластера, после чего starvault operator raft join используется для добавления новых узлов в кластер Raft.

Метод

Путь

POST

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

2. /sys/storage/raft/autopilot

Конечные точки /sys/storage/raft/autopilot используются для управления кластерами Raft с помощью автопилота с бэкендом встроенного хранилища StarVault.

2.1. Получение состояния кластера

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

Метод

Путь

GET

/sys/storage/raft/autopilot/state
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/sys/storage/raft/autopilot/state
Пример ответа:
{
  "healthy": true,
  "failure_tolerance": 1,
  "servers": {
    "raft1": {
      "id": "raft1",
      "name": "raft1",
      "address": "127.0.0.1:8201",
      "node_status": "alive",
      "last_contact": "0s",
      "last_term": 3,
      "last_index": 459,
      "healthy": true,
      "stable_since": "2021-03-19T20:14:11.831678-04:00",
      "status": "leader",
      "meta": null
    },
    "raft2": {
      "id": "raft2",
      "name": "raft2",
      "address": "127.0.0.2:8201",
      "node_status": "alive",
      "last_contact": "516.49595ms",
      "last_term": 3,
      "last_index": 459,
      "healthy": true,
      "stable_since": "2021-03-19T20:14:19.831931-04:00",
      "status": "voter",
      "meta": null
    },
    "raft3": {
      "id": "raft3",
      "name": "raft3",
      "address": "127.0.0.3:8201",
      "node_status": "alive",
      "last_contact": "196.706591ms",
      "last_term": 3,
      "last_index": 459,
      "healthy": true,
      "stable_since": "2021-03-19T20:14:25.83565-04:00",
      "status": "voter",
      "meta": null
    }
  },
  "leader": "raft1",
  "voters": ["raft1", "raft2", "raft3"],
  "non_voters": null
}

2.2. Получение конфигурации

Данная конечная точка используется для получения конфигурации подсистемы автопилота встроенного хранилища.

Метод

Путь

GET

/sys/storage/raft/autopilot/configuration
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  http://127.0.0.1:8200/v1/sys/storage/raft/autopilot/configuration
Пример ответа:
{
  "cleanup_dead_servers": false,
  "dead_server_last_contact_threshold": "24h0m0s",
  "last_contact_threshold": "10s",
  "max_trailing_logs": 1000,
  "min_quorum": 0,
  "server_stabilization_time": "10s"
}

2.3. Установка конфигурации

Данная конечная точка используется для изменения конфигурации подсистемы автопилота встроенного хранилища.

Метод

Путь

POST

/sys/storage/raft/autopilot/configuration

2.3.1. Параметры

  • cleanup_dead_servers (bool: false) - управляет удалением неработающих серверов из списка пиров Raft периодически или при подключении нового сервера. Требуется min_quorum также настроить этот параметр.

  • last_contact_threshold (string: "10s") - ограничение на время, в течение которого сервер может оставаться без контакта с лидером, прежде чем он будет признан нездоровым.

  • dead_server_last_contact_threshold (string: "24h") – ограничение на время, в течение которого сервер может оставаться без связи с лидером, прежде чем будет считаться неработоспособным. Действует только при значении true в cleanup_dead_servers. Значение не может быть меньше 1 мин.

  • max_trailing_logs (int: 1000) - количество записей в журнале Raft, отстающих от сервера, прежде чем он будет признан неработоспособным.

  • min_quorum (int: 3) – минимальное количество серверов, разрешенное в кластере, при котором автопилот сможет удалить неиспользуемые серверы. Должно быть не менее 3. Применимо только для голосующих узлов.

  • server_stabilization_time (string: "10s") - минимальное время, в течение которого сервер должен находиться в стабильном, работоспособном состоянии, прежде чем его можно будет добавить в кластер.

Пример тела запроса:
{
  "cleanup_dead_servers": true,
  "last_contact_threshold": "10s",
  "dead_server_last_contact_threshold": "24h",
  "max_trailing_logs": "1000",
  "min_quorum": "3",
  "server_stabilization_time": "10s"
}
Пример запроса:
curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  --data @payload.json \
  http://127.0.0.1:8200/v1/sys/storage/raft/autopilot/configuration