Механизм секретов KV

Механизм секретов KV (сокращение от "Key-Value") — это универсальное хранилище значений ключей, используемое для хранения произвольных секретов в настроенном физическом хранилище для StarVault. Этот механизм может работать в одном из двух режимов:

KV версии 1 (KV v1) – не поддерживает версионирование значений ключа. Хранит одно значение для ключа
KV версии 2 (KV v2) – поддерживает версионирование значений ключа. Хранит настраиваемое количество версий для каждого ключа.

1. KV версии 1

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

При записи в ключ в механизме kv старое значение будет заменено; подполя не объединяются.

Имена ключей всегда должны быть строками. Если вы напрямую записываете значения, не являющиеся строками, через интерфейс командной строки (CLI), они будут преобразованы в строки. Однако вы можете сохранить значения, не являющиеся строками, записав пары ключ/значение в StarVault из JSON-файла или используя HTTP API.

Этот механизм учитывает различие между операциями create и update в политиках контроля доступа (ACL).

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

1.1. Активация

Перейдите в пользовательский интерфейс (UI).
Авторизуйтесь с токеном или учетной записью, имеющей права достаточные для активации механизма секретов.
На странице Секреты нажмите Добавить.
Выберите KV и нажмите Далее.
Введите необходимые настройки для механизма:
- В поле Путь укажите путь.
- Раскройте группу параметров Опции и настройте в ней необходимые параметры:
  
  В поле Версия выберите версию 1.
  
  При необходимости настройте дополнительные параметры. Описание параметров см. в разделе Общие параметры для механизмов.
Нажмите Включить механизм.
Убедитесь, что механизм секретов добавлен.

CLI

В командной оболочке сервера StarVault аутентифицируйтесь с вашим токеном (если аутентификация ещё не пройдена).

starvault login
Token (will be hidden):

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "starvault login"
again. Future StarVault requests will automatically use this token.

<Output omitted>

Введите команду активации механизма kv v1:

starvault secrets enable -version=1 kv

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

Проверьте успешность выполнения запроса:

starvault secrets list -detailed -format=yaml

...
kv/: (1)
  accessor: kv_a80dd2b7
  config:
    default_lease_ttl: 0
    force_no_cache: false
    max_lease_ttl: 0
  deprecation_status: supported
  description: ""
  external_entropy_access: false
  local: false
  options:
    version: "1" (2)
  plugin_version: ""
  running_plugin_version: v0.15.0+builtin
  running_sha256: ""
  seal_wrap: false
  type: kv
  uuid: 58c7e328-4217-ed2c-d405-a22d551ebe2a
...

1	В выводе ожидается наличие активированного механизма.
2	В выводе ожидается версия 1.

1.2. Использование

Через пользовательский интерфейс можно выполнять все основные операции с секретами в механизме KV.

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

Создание секрета

В примере ниже в механизме kv-v1 создается секрет my-secret с двумя ключами: name и password.

На странице Секреты нажмите на карточку нужного механизма.
Нажмите Создать секрет +.
Введите необходимые данные:
- путь к секрету
- имя ключа
- значение ключа
Если необходимо добавить несколько ключей, нажмите кнопку Добавить.

Данные секрета также можно ввести в формате JSON. Для этого активируйте переключатель JSON.
Нажмите Сохранить для сохранения.

Изменение секрета

На странице Секреты нажмите на карточку нужного механизма.
В строке нужного секрета нажмите Изменить.
Внесите необходимые изменения и нажмите Сохранить.

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

На странице Секреты нажмите на карточку нужного механизма.
В строке нужного секрета нажмите кнопку удаления () или нажмите на секрет для перехода на страницу просмотра секрета, нажмите Удалить и подтвердите удаление кнопкой Удалить.

CLI

Механизм KV версии 1 поддерживает следующие команды StarVault CLI для работы с секретами.

Команда Описание

starvault kv get [-format=<string>] [-field=<string>] <secret-path>

Извлекает данные из секрета по пути <secret-path>.

С помощью опции -format=<string> можно указать формат представления данных. Допустимые значения: table (по умолчанию), yaml, 'json', 'raw'.

Опция -field=<string> позволяет указать значение какого ключа необходимо вывести.

starvault kv put <secret-path> <key=value list>

Создает или изменяет секрет по пути <secret-path>. Данные для записи в секрет передаются в формате key=value. Для добавления нескольких ключей со значениями, их необходимо перечислить через пробел..

Для KV версии 1 данная операция при применении к существующему секрету удаляет старые данные и заменяет их новыми.

starvault kv list [-format=<string>] <path>

Возвращает список секретов в пути <path>.

С помощью опции -format=<string> можно указать формат представления данных. Допустимые значения: table (по умолчанию), yaml, 'json'.

starvault kv delete <secret-path>

Удаляет секрет по указанному пути.

Для использования StarVault CLI подключитесь к любому серверу в кластере по SSH и аутентифицируйтесь с вашим токеном:

starvault login
Token (will be hidden):

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "starvault login"
again. Future StarVault requests will automatically use this token.

<Output omitted>

При использовании самоподписанного сертификата ЦС его обязательно необходимо добавить в доверенные. Подробнее см. в разделе Подготовка рабочей среды.

Примеры

Пример 1. Создание секрета по пути kv-v1/my-secret с ключами name и password

starvault kv put kv-v1/my-secret name=user password=pass

Пример 2. Просмотр списка секретов по пути kv-v1

starvault kv list kv-v1

Keys
my-secret

Пример 3. Просмотр содержимого секрета по пути kv-v1/my-secret в формате JSON

starvault kv get -format=json kv-v1/my-secret

{
  "request_id": "99dffb37-2c2e-55c1-c745-d69b6ba012e9",
  "lease_id": "",
  "lease_duration": 2764800,
  "renewable": false,
  "data": {
    "name": "user",
    "password": "pass"
  },
  "warnings": null
}

Пример 4. Извлечение значения ключа password из секрета по пути kv-v1/my-secret

starvault kv get -field=password kv-v1/my-secret

pass

Пример 5. Изменение секрета по пути kv-v1/my-secret

В примере ниже в секрете kv-v1/my-secret из предыдущего примера будет изменено значение ключа name, а также добавлен ключ domain.

starvault kv put kv-v1/my-secret name=new-user password=pass domain=example.com

Обратите внимание, что в команде также присутствует ключ password. Если не указать его — он будет удалён из секрета, поскольку команда put перезаписывает содержимое секрета новыми данными.

Пример 6. Удаление секрета по пути kv-v1/my-secret

starvault kv delete kv-v1/my-secret

2. KV версии 2

При записи в ключ в механизме kv старое значение будет заменено; подполя не объединяются.

Этот механизм учитывает различие между операциями create и update в политиках контроля доступа (ACL).

KV версии 2 может сохранять настраиваемое количество версий секретов. Это позволяет восстановить данные старых версий в случае нежелательного удаления или обновления данных. Кроме того, операции Check-and-Set могут использоваться для защиты данных от непреднамеренной перезаписи.

2.1. Активация

Перейдите UI.
Авторизуйтесь с токеном или учетной записью, имеющей права, достаточные для активации механизма секретов.
На странице Секреты нажмите на карточку Добавить.
Выберите KV и нажмите Далее.

Введите необходимые настройки для механизма:

Укажите путь в поле Путь.
При необходимости укажите максимальное количество сохраняемых версий каждого ключа в поле Максимальное количество версий. Если установлено значение 0 - StarVault будет хранить 10 версий каждого ключа. Как только количество ключей превысит максимальное число, самая старая версия будет удалена навсегда. Этот параметр может быть переопределён для каждого отдельного секрета.

При необходимости активируйте опцию Требовать проверку и установку. Данный параметр может быть переопределен для каждого отдельного секрета.

Операция Check-and-Set (CAS) в StarVault используется для реализации атомарных обновлений. Атомарные обновления происходят только в случае, если текущее значение ключа соответствует ожидаемому. Это предотвращает одновременные конфликтующие изменения от разных клиентов.

В контексте механизма KV версии 2 (kv-v2), который поддерживает версионирование, параметр cas используется для указания версии ключа, которую клиент ожидает обновить. Если текущая версия ключа в хранилище не совпадает с указанной в параметре cas, операция записи будет отклонена. Это гарантирует, что запись будет выполнена только если состояние ключа не изменилось с момента последнего чтения клиентом.

При необходимости активируйте переключатель Автоматическое удаление секрета для включения функции автоматического удаления секретов и введите время, через которое будут удаляться все новые версии. Этот параметр может быть переопределён для каждого отдельного секрета.
Раскройте группу параметров Опции и настройте в ней необходимые параметры:
- Убедитесь, что в поле Версия установлена версия 2.
- При необходимости настройте дополнительные параметры. Описание параметров см. в разделе Общие параметры для механизмов.

Нажмите Включить механизм.
На странице Секреты убедитесь, что механизм добавлен.

CLI

В командной оболочке сервера StarVault аутентифицируйтесь с вашим токеном (если аутентификация еще не пройдена).

starvault login
Token (will be hidden):

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "starvault login"
again. Future StarVault requests will automatically use this token.

<Output omitted>

Введите команду активации механизма kv v2:

starvault secrets enable -version=2 kv

Проверьте успешность выполнения запроса:

starvault secrets list -detailed -format=yaml

...
kv/: (1)
  accessor: kv_009494e8
  config:
    default_lease_ttl: 0
    force_no_cache: false
    max_lease_ttl: 0
  deprecation_status: supported
  description: ""
  external_entropy_access: false
  local: false
  options:
    version: "2" (2)
  plugin_version: ""
  running_plugin_version: v0.15.0+builtin
  running_sha256: ""
  seal_wrap: false
  type: kv
  uuid: dbe70068-d6cc-fca1-50f2-adb2783eab61
...

1	В выводе ожидается наличие активированного механизма.
2	В выводе ожидается версия 2.

2.2. Обновление с v1 до v2

Существующий механизм KV версии 1 можно обновить до KV версии 2. При этом начнется процесс обновления существующих данных ключей/значений до версионного формата. Во время этого процесса хранилище будет недоступно. Этот процесс может занять много времени, поэтому планируйте его заранее.

После обновления до версии 2 прежние пути, по которым можно было получить доступ к данным, больше не будут достаточными. Вам нужно будет настроить политики пользователей, чтобы добавить доступ к путям версии 2, как описано в разделе Правила ACL ниже. Аналогично, пользователям/приложениям необходимо будет обновить пути, по которым они взаимодействуют с данными KV после обновления до версии 2.

Для обновления KV с версии 1 до версии 2 можно использовать следующие способы:

Способ 1

starvault kv enable-versioning <path> (1)

1	<path> - путь к механизму KV версии 1

Например:

starvault kv enable-versioning kv/

Способ 2

starvault secrets tune -version=2 <path> (1)

1	<path> - путь к механизму KV версии 1

Например:

starvault secrets tune -version=2 kv/

2.3. Правила ACL

Подробнее о политиках и правилах доступа можно прочитать в разделе Политики.

Для механизма секретов KV версии 2 (kv-v2), пути для записи и чтения версий секретов имеют префикс data/. Это отличается от версии 1 (kv-v1), где такой префикс не использовался. Поэтому, если у вас есть политика, которая работала для kv-v1, вам необходимо обновить её, чтобы она соответствовала структуре путей kv-v2.

Например, следующая политика для kv-v1:

path "secret/dev/team-1/*" {
  capabilities = ["create", "update", "read"]
}

Должна быть изменена для kv-v2 на следующую:

path "secret/data/dev/team-1/*" { (1)
  capabilities = ["create", "update", "read"]
}

1	Обратите внимание на наличие префикса data/

Далее приведены примеры политик, разрешающих различные операции с секретом:

Право на удаление последней версии ключа:

path "secret/data/dev/team-1/*" {
  capabilities = ["delete"]
}

Право на удаление любой версии ключа:

path "secret/delete/dev/team-1/*" {
  capabilities = ["update"]
}

Право на отмену удаления данных:

path "secret/undelete/dev/team-1/*" {
  capabilities = ["update"]
}

Право на уничтожение версии:

path "secret/destroy/dev/team-1/*" {
  capabilities = ["update"]
}

Право на просмотр списка ключей:

path "secret/metadata/dev/team-1/*" {
  capabilities = ["list"]
}

Право на просмотр метаданных для каждой версии:

path "secret/metadata/dev/team-1/*" {
  capabilities = ["read"]
}

Право на окончательное удаление всех версий и метаданных для ключа:

path "secret/metadata/dev/team-1/*" {
  capabilities = ["delete"]
}

Поля allowed_parameters, denied_parameters и required_parameters не поддерживаются для политик, используемых с механизмом KV версии 2.

2.4. Использование

После того как механизм секретов настроен и у пользователя/машины есть токен StarVault с соответствующими правами, он может генерировать учетные данные. Механизм секретов KV позволяет записывать ключи с произвольными значениями.

Через пользовательский интерфейс можно выполнять все основные операции с секретами в механизме KV.

Создание секрета

В примере ниже в механизме kv-v2 создается секрет my-secret с двумя ключами: name и password.

На странице Секреты нажмите на карточку нужного механизма.
Нажмите Создать секрет.
Введите необходимые данные:
- Путь к секрету.
- Имя ключа.
- Значение ключа.
- При необходимости в разделе Метаданные можно переопределить глобальные метаданные, установленные на уровне механизма.
Если необходимо добавить несколько ключей, нажмите кнопку Добавить.

Данные секрета также можно ввести в формате JSON. Для этого активируйте переключатель JSON.
Нажмите Сохранить для сохранения.

Создание новой версии секрета

В примере ниже в механизме kv-v2 создается новая версия секрета my-secret с изменением значения ключа name.

На странице Секреты нажмите на карточку нужного механизма.
В строке нужного секрета нажмите Создать новую версию.
Измените необходимые данные:

Если необходимо добавить ключи, нажмите кнопку Добавить.

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

Просмотр списка версий секретов

На странице Секреты нажмите на карточку нужного механизма.
В строке нужного секрета нажмите История версии.

Просмотр данных в выбранной версии секрета

На странице Секреты нажмите на карточку нужного механизма.
Нажмите на секрет для перехода на страницу просмотра секрета и в меню Версия выберите нужную версию.

Сравнение версий секрета

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

В выпадающих меню над областью отображения можно выбрать, какие версии будут сравниваться.

Удаление версий секрета

На странице Секреты нажмите на карточку нужного механизма.
В строке нужного секрета нажмите кнопку удаления () или нажмите на секрет для перехода на страницу просмотра секрета, в меню Версии выберите нужную версию и нажмите Удалить.
В появившемся окне выберите способ удаления (описание в порядке расположения опций):
- Пометка выбранной версии на удаление. Позволяет в будущем восстановить версию. Соответствует операции delete.
- Уничтожение выбранной версии. Окончательно удаляет версию без возможности восстановления. Соответствует операции destroy.
- Уничтожение всех версий и метаданных секрета.
Подтвердите выбор, нажав Удалить.
Введите учетные данные для авторизации.

Восстановление версии секрета, помеченной на удаление

Восстановить можно только версии, помеченные на удаление.

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

CLI

Механизм KV версии 2 поддерживает следующие команды StarVault CLI для работы с секретами.

Команда Описание

starvault kv get [-format=<string>] [-field=<string>] -mount=<path> <secret-name>

Извлекает данные из секрета с именем <secret-name> из механизма по пути <path>.

Опция -field=<string> позволяет указать значение какого ключа необходимо вывести.

starvault kv put [-cas=<version>] -mount=<path> <secret-name> <key=value list>

Создает новый секрет или версию секрета с именем <secret-name> в механизме по пути <path>. Данные для записи в секрет передаются в формате key=value. Для добавления нескольких ключей со значениями, их необходимо перечислить через пробел..

Если в настройках механизма или секрета указано требование к использованию операции CAS, необходимо использовать опцию -cas=<version>.

Для того чтобы запись была успешной, cas должен быть установлен на текущую версию секрета. Если установлено значение 0, запись будет разрешена только в том случае, если ключ не существует. Также помните, что мягкое удаление не удаляет из хранилища никаких данных о версии. Для записи в ключ с мягким удалением параметр cas должен соответствовать текущей версии ключа.

Для KV версии 2 данная операция при применении к существующему секрету создаёт новую версию секрета. При этом в новой версии будут присутствовать только те данные, которые переданы в команде.

starvault kv list [-format=<string>] -mount=<path>

Возвращает список секретов в пути <path>.

starvault kv delete -mount=<path> [-versions=<version>] <secret-name>

Помечает на удаление версию секрета с именем <secret-name> в механизме по пути <path>.

С помощью опции -versions=<version> можно указать, какую версию секрета необходимо пометить на удаление. Для указания нескольких версий, достаточно ввести их через запятую, например, -versions=1,2. Если опция не указана - помечается последняя версия.

starvault kv patch [-cas=<version>] [-method=<string>] -mount=<path> <secret-name> <key=value list>

Создает новую версию секрета. Важное отличие от put заключается в том, что patch позволяет выполнить частичное обновление, т.е. она объединяет изменения с существующими данными, а не заменяет их.

Опция -method=<string> позволяет указать метод исправления. Допустимые методы:

patch (по умолчанию) — использует HTTP-запрос PATCH для применения частичного обновления.
rw — получает данные секрета, выполняет обновление в памяти и записывает обновленные данные.

starvault kv rollback -mount=<path> -version=<version> <secret-name>

Выполняет откат до указанной в -version=<version> версии секрета.

Результат отката записывается как новая версия. Например, если текущая версия - 5, а версия отката - 2, данные из версии 2 станут версией 6.

starvault kv undelete -mount=<path> -versions=<version> <secret-name>

Восстанавливает версии, помеченные на удаление. Для указания восстанавливаемых версий используется -versions=<version>. Для указания нескольких версий, достаточно ввести их через запятую, например, -versions=1,2.

starvault kv destroy -mount=<path> -versions=<version> <secret-name>

Окончательно удаляет данные указанной в -versions= версии секрета с именем <secret-name> из механизма секретов по пути <path>. Для указания нескольких версий, достаточно ввести их через запятую, например, -versions=1,2. Если по указанному пути не существует данных, никаких действий не производится.

starvault kv metadata <subcommand> [options] -mount=<path> <secret-name>

Позволяет выполнять операции с метаданными секретов.

Включает следующие субкоманды:

delete - удаляет все метаданные, связанные с указанным секретом. Поскольку в метаданных содержится также информация о версионировании, после выполнения этой команды, версии секрета хоть и не удаляются физически, но становятся недоступны.
get - возвращает метаданные указанного секрета.
put - создает или изменяет ключи метаданных в указанном секрете.

Для операции put доступны следующие опции:

-cas-required=<bool> - включает (true) или отключает (false) требование CAS.
-max-versions=<int> - позволяет указать количество хранимых версий секрета.
-delete-version-after=<string> - позволяет указать временной интервал, по прошествии которого будут автоматически помечаться на удаление новые версии секрета. Если это значение больше, чем установленное на уровне механизма, используется значение механизма.
-custom-metadata=<string> - позволяет добавить в метаданные пользовательские ключи.

starvault login
Token (will be hidden):

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "starvault login"
again. Future StarVault requests will automatically use this token.

<Output omitted>

Синтаксис KV-v1, использующий путь, для ссылки на секрет (secret/foo) по-прежнему можно использовать в KV-v2, но мы рекомендуем использовать синтаксис с флагом -mount=<path> (), чтобы не перепутать его с реальным путем к секрету (secret/data/foo - это реальный путь).

Примеры

Пример 7. Создание секрета по пути kv-v2/data/my-secret с ключами name и password

В примере ниже создаётся новый секрет (версия 1).

В результате выполнения команды возвращаются параметры и метаданные секрета. Благодаря опции -format=yaml вывод представлен в формате YAML.

starvault kv put -mount=kv-v2 -format=yaml my-secret name=user password=pass

data:
  created_time: "2024-05-24T11:50:09.502694424Z"
  custom_metadata: null
  deletion_time: ""
  destroyed: false
  version: 1 (1)
lease_duration: 0
lease_id: ""
renewable: false
request_id: 0c9b6d19-685b-4b65-0a1b-c751bc9aafd6
warnings: null

1	Версия секрета

Пример 8. Просмотр списка секретов по пути kv-v2

starvault kv list -mount=kv-v2

Keys
my-secret

Пример 9. Просмотр содержимого секрета по пути kv-v2/data/my-secret в формате YAML

starvault kv get -mount=kv-v2 -format=yaml my-secret

data:
  data: (1)
    name: user
    password: pass
  metadata: (2)
    created_time: "2024-05-24T11:50:09.502694424Z"
    custom_metadata: null
    deletion_time: ""
    destroyed: false
    version: 1
lease_duration: 0
lease_id: ""
renewable: false
request_id: 11c8e909-9598-a166-cb95-ea0a807a9a54
warnings: null

1	Данные секрета текущей версии
2	Метаданные секрета

Пример 10. Создание новой версии секрета по пути kv-v2/data/my-secret

starvault kv put -mount=kv-v2 my-secret name=new-user domain=example.com
==== Secret Path ====
kv-v2/data/my-secret

======= Metadata =======
Key                Value
---                -----
created_time       2024-05-24T12:06:53.363417213Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2 (1)

1	Создана новая версия секрета (версия 2)

После выполнения этой операции в данные секрета попали только те ключи, которые были переданы в команде:

starvault kv get -mount=kv-v2 -format=yaml my-secret

data:
  data: (1)
    domain: example.com
    name: new-user
  metadata:

1	В выводе отсутствует поле `password` из предыдущего примера.

Решить проблему частичного обновления (так, чтобы ключи, которые не изменяются, также попали в новую версию) может команда patch

Пример 11. Создание новой версии секрета по пути kv-v2/data/my-secret с обновлением

starvault kv patch -mount=kv-v2 my-secret domain=example.local

==== Secret Path ====
kv-v2/data/my-secret

======= Metadata =======
Key                Value
---                -----
created_time       2024-05-24T12:14:40.39981112Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            3 (1)

1	Создана новая версия секрета (версия 3)

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

starvault kv get -mount=kv-v2 -format=yaml my-secret

data:
  data:
    domain: example.local (1)
    name: new-user (2)
  metadata:

1	Значение обновлено.
2	Значение получено из версии 2 секрета.

Пример 12. Просмотр данных версии 2 секрета по пути kv-v2/data/my-secret

starvault kv get -mount=kv-v2 -format=yaml -version=2 my-secret
data:
  data: (1)
    domain: example.com
    name: new-user
  metadata:
    created_time: "2024-05-24T12:06:53.363417213Z"
    custom_metadata: null
    deletion_time: ""
    destroyed: false
    version: 2 (2)

1	Содержимое секрета
2	Версия соответствует указанной в команде

Пример 13. Извлечение значения ключа domain из секрета по пути kv-v2/data/my-secret

starvault kv get -mount=kv-v2 -field=domain my-secret

example.local (1)

1	Полученное значение ключа

Пример 14. Пометка на удаление версии 1 секрета по пути kv-v2/data/my-secret

starvault kv delete -mount=kv-v2 -versions=1 my-secret

Для проверки успешности операции можно запросить данные секрета версии 1:

starvault kv get -mount=kv-v2 -format=yaml -version=1 my-secret

data:
  data: null (1)
  metadata:
    created_time: "2024-05-24T11:50:09.502694424Z"
    custom_metadata: null
    deletion_time: "2024-05-24T12:28:29.557084744Z" (2)
    destroyed: false
    version: 1

1	Данные недоступны для чтения (но не удалены)
2	Время, когда версия помечена на удаление

Пример 15. Отмена пометки на удаление версии 1 секрета по пути kv-v2/data/my-secret

starvault kv undelete -mount=kv-v2 -versions=1 my-secret

Для проверки успешности операции можно запросить данные секрета версии 1:

starvault kv get -mount=kv-v2 -format=yaml -version=1 my-secret

data:
  data: (1)
    name: user
    password: pass
  metadata:
    created_time: "2024-05-24T11:50:09.502694424Z"
    custom_metadata: null
    deletion_time: "" (2)
    destroyed: false
    version: 1

1	Данные снова доступны для чтения.
2	Время пометки удаления снято.

Пример 16. Откат на версию 2 секрета по пути kv-v2/data/my-secret

starvault kv rollback -mount=kv-v2 -version=2 my-secret

Key                Value
---                -----
created_time       2024-05-24T13:03:20.515186547Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            4 (1)

1	Создана новая версия

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

starvault kv get -mount=kv-v2 -format=yaml my-secret

data:
  data:
    domain: example.com (1)
    name: new-user

1	Значение ключа `domain` восстановлено из версии 2 секрета.

Пример 17. Окончательное удаление версий 1 и 2 секрета по пути kv-v2/data/my-secret

starvault kv destroy -mount=kv-v2 -versions=1,2 my-secret

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

starvault kv metadata get -mount=kv-v2 my-secret

===== Metadata Path =====
kv-v2/metadata/my-secret

========== Metadata ==========
...

====== Version 1 ======
Key              Value
---              -----
created_time     2024-05-24T11:50:09.502694424Z
deletion_time    n/a
destroyed        true (1)

====== Version 2 ======
Key              Value
---              -----
created_time     2024-05-24T12:06:53.363417213Z
deletion_time    n/a
destroyed        true (1)

====== Version 3 ======
Key              Value
---              -----
...

1	Версии 1 и 2 отмечены как уничтоженные. Их восстановление невозможно.

Пример 18. Изменение метаданных секрета по пути kv-v2/data/my-secret

В примере ниже в секрете kv-v2/data/my-secret будет активировано требование CAS.

starvault kv metadata put -mount=kv-v2 -cas-required=true my-secret

Для проверки достаточно запросить метаданные секрета:

starvault kv metadata get -mount=kv-v2 my-secret

===== Metadata Path =====
kv-v2/metadata/my-secret

========== Metadata ==========
Key                     Value
---                     -----
cas_required            true (1)
created_time            2024-05-24T11:50:09.502694424Z
...

1	Требование CAS включено.

Для проверки достаточно попытаться обновить секрет без указания текущей версии, чтобы убедиться в том, что CAS работает:

starvault kv patch -mount=kv-v2 my-secret name=test-user

Error writing data to kv-v2/data/my-secret: Error making API request.

URL: PATCH https://127.0.0.1:8200/v1/kv-v2/data/my-secret
Code: 400. Errors:

* check-and-set parameter required for this call (1)

1	Описание ошибки указывает на необходимость использования CAS

При указании текущей версии для CAS команда отрабатывает успешно:

starvault kv patch -mount=kv-v2 -cas=4 my-secret name=test-user

==== Secret Path ====
kv-v2/data/my-secret

======= Metadata =======
Key                Value
---                -----
created_time       2024-05-24T13:25:12.309711248Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            5 (1)

1	Данные успешно обновлены до версии 5.

Пример 19. Удаление всех метаданных секрета по пути kv-v2/data/my-secret

starvault kv metadata delete -mount=kv-v2 my-secret

Для проверки достаточно запросить метаданные секрета:

starvault kv metadata get -mount=kv-v2 my-secret

No value found at kv-v2/metadata/my-secret (1)

1	Указывает на то, что метаданные отсутствуют.

Запрос списка секретов в механизме также указывает на отсутствие секрета kv-v2/data/my-secret

starvault kv list -mount=kv-v2

No value found at kv-v2/metadata

Данная операция не уничтожает данные физически, но из-за отсутствия метаданных доступ к ним невозможен.