Руководство администратора Deckhouse Stronghold: Механизм секретов KV

Механизм секретов KV (key-value / ключ-значение)

Механизм секретов kv представляет собой общее хранилище ключ-значение для хранения произвольных секретов в настроенном физическом хранилище для Stronghold. Этот механизм секретов может работать в двух режимах:

• kv версии 1, для хранения одного значения для ключа
• kv версии 2, с версионностью и возможностью хранения произвольно настроиваемового количества версий для каждого ключа.

KV версия 1

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

KV версия 2

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

При удалении версии данные, лежащие в ее основе, не удаляются, а помечаются как удаленные. Удаление версии может быть отменено. Для окончательного удаления данных версии можно использовать консольную команду destroy или отправить запрос в соответствующий путь API. Кроме того, все версии и метаданные для ключа могут быть удалены командой delete по метаданным или конечной точкой API. На каждую из этих операций можно наложить различные ACL, ограничивающие права на мягкое удаление, удаление без удаления или полное удаление данных.

Включение механизма секретов

Для начала работы с механизмом секретов KV, необходимо включить его по пути kv. Каждый путь полностью изолирован и не может взаимодействовать с другими путями. Например, механизм KV-секретов, включенный в foo, не может взаимодействовать с механизмом KV-секретов, включенным в bar.

1vault secrets enable -path=kv kv
2Success! Enabled the kv secrets engine at: kv/

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

1vault secrets enable kv

Выполнение этой команды приведет к ошибке path is already in use at kv/.

Чтобы проверить успешность операции и получить дополнительные сведения о механизме управления секретами, используйте команду vault secrets list:

1vault secrets list
2Path Type Accessor Description
3---- ---- -------- -----------
4cubbyhole/ cubbyhole cubbyhole_78189996 per-token private secret storage
5identity/ identity identity_ac07951e identity store
6kv/ kv kv_15087625 n/a
7secret/ kv kv_4b990c45 key/value secret storage
8sys/ system system_adff0898 system endpoints used for control, policy and debugging

Это подтверждает наличие на сервере Deckhouse Stronghold пяти активных механизмов управления секретами. Можно увидеть тип такого механизма, соответствующий путь и необязательное описание (или «n/a», если оно не указано). При выполнении вышеуказанной команды с флагом -detailed становится доступной информация о версии KV системы управления секретами, а также многое другое.

Путь sys/ соответствует бэкенду системы. Эти пути взаимодействуют с основной системой Stronghold и не являются обязательными для новичков.

Потратьте несколько минут на чтение и запись некоторых данных в новый KV-механизм управления секретами, расположенный по адресу kv/. Ниже приведены несколько примеров для старта.

Для создания секретов используйте команду kv put.

1vault kv put kv/hello target=world
2Success! Data written to: kv/hello

Для чтения секретов, хранящихся в пути kv/hello, используйте команду kv get, как представлено на примере:

1vault kv get kv/hello
2===== Data =====
3Key Value
4--- -----
5target world

Создайте секреты по пути kv/my-secret, как представлено на примере:

1vault kv put kv/my-secret value="s3c(eT"
2Success! Data written to: kv/my-secret

Читайте секреты по пути kv/my-secret, как представлено на примере:

1vault kv get kv/my-secret
2==== Data ====
3Key Value
4--- -----
5value s3c(eT

Удалите секреты по адресу kv/my-secret, как представлено на примере:

1vault kv delete kv/my-secret
2Success! Data deleted (if it existed) at: kv/my-secret

Перечислите существующие ключи на пути kv, как представлено на примере:

1vault kv list kv/
2Keys
3----
4hello

Отключение механизма секретов

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

1vault secrets disable kv/
2Success! Disabled the secrets engine (if it existed) at: kv/

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

Управление секретами

Механизм секретов Key/Value - это универсальное хранилище ключевых значений, используемое для хранения произвольных секретов в пределах настроенного физического хранилища Deckhouse Stronghold.

Секреты, записанные в Deckhouse Stronghold, шифруются и затем записываются во внутреннее хранилище. Внутренний механизм хранения данных не имеет доступа к незашифрованным значениям и не обладает средствами, необходимыми для их расшифровки без использования Deckhouse Stronghold.

Механизм секретов ключ/значение имеет версии 1 и 2. Разница в том, что v2 обеспечивает версионность секретов, а v1 - нет.

Для взаимодействия с механизмом секретов K/V используйте команду vault kv <подкоманда> [options] [args].

Доступные подкоманды перечислены в следующей таблице:

Получение справки по командам

Взаимодействовать с механизмом секретов ключ/значение можно с помощью команды vault kv.

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

1vault kv -help
2Usage: vault kv <subcommand> [options] [args]
3This command has subcommands for interacting with Stronghold's key-value
4store. Here are some simple examples, and more detailed examples are
5available in the subcommands or the documentation.
6Create or update the key named "foo" in the "secret" mount with the value
7"bar=baz":
8$ vault kv put -mount=secret foo bar=baz
9Read this value back:
10$ vault kv get -mount=secret foo
11Get metadata for the key:
12$ vault kv metadata get -mount=secret foo
13Get a specific version of the key:
14$ vault kv get -mount=secret -version=1 foo
15The deprecated path-like syntax can also be used, but this should be avoided
16for KV v2, as the fact that it is not actually the full API path to
17the secret (secret/data/foo) can cause confusion:
18$ vault kv get secret/foo
19Please see the individual subcommand help for detailed usage information.
20Subcommands:
21delete Deletes versions in the KV store
22destroy Permanently removes one or more versions in the KV store
23enable-versioning Turns on versioning for a KV store
24get Retrieves data from the KV store
25list List data or secrets
26metadata Interact with Stronghold's Key-Value storage
27patch Sets or updates data in the KV store without overwriting
28put Sets or updates data in the KV store
29rollback Rolls back to a previous version of data
30undelete Undeletes versions in the KV store

Записывание секрета

Перед началом работы ознакомьтесь со справкой по команде:

1vault kv put -help

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

Запишите ключ-значение secret в путь hello, с ключом foo и значением world, используя команду vault kv put против пути mount path secret, на котором установлен механизм управления секретами KV v2. Эта команда создаст новую версию секрета и заменит все ранее существовавшие данные по указанному пути, если они существуют.

1vault kv put -mount=secret hello foo=world
2== Secret Path ==
3secret/data/hello
4======= Metadata =======
5Key Value
6--- -----
7created_time 2022-06-15T19:36:54.389113Z
8custom_metadata <nil>
9deletion_time n/a
10destroyed false
11version 1

Важно, чтобы путь монтирования к механизму секретов KV v2 был указан с параметром -mount=secret, иначе данный пример не будет работать. Путь монтирования secret (который был автоматически задан при запуске сервера Deckhouse Stronghold в режиме -dev) - это место, где можно читать и записывать произвольные секреты.

С помощью kv put можно записывать несколько фрагментов данных.

1vault kv put -mount=secret hello foo=world excited=yes
2== Secret Path ==
3secret/data/hello
4======= Metadata =======
5Key Value
6--- -----
7created_time 2022-06-15T19:49:06.761365Z
8custom_metadata <nil>
9deletion_time n/a
10destroyed false
11version 2

Обратите внимание, что версия теперь равна 2. В примерах этого руководства для отправки секретов в Stronghold используется ввод <ключ>=<значение>. Однако отправка данных в составе команды CLI часто попадает в историю оболочки в незашифрованном виде.

Чтение секрета

Cекреты могут быть получены с помощью vault kv get.

1vault kv get -mount=secret hello
2== Secret Path ==
3secret/data/hello
4======= Metadata =======
5Key Value
6--- -----
7created_time 2022-01-15T01:40:09.888293Z
8custom_metadata <nil>
9deletion_time n/a
10destroyed false
11version 2
12===== Data =====
13Key Value
14--- -----
15excited yes
16foo world

Deckhouse Stronghold возвращает последнюю версию (в данном случае версию 2) секретов по адресу secret/hello.

Чтобы вывести только значение заданного поля, используйте флаг -field=<имя_ключа>.

1vault kv get -mount=secret -field=excited hello
2yes

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

1vault kv get -mount=secret -format=json hello | jq -r .data.data.excited
2yes

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

Удалить секрет можно с помощью команды vault kv delete.

1vault kv delete -mount=secret hello
2Success! Data deleted (if it existed) at: secret/data/hello

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

1vault kv get -mount=secret hello
2== Secret Path ==
3secret/data/hello
4======= Metadata =======
5Key Value
6--- -----
7created_time 2022-01-15T01:40:09.888293Z
8custom_metadata <nil>
9deletion_time 2022-01-15T01:40:41.786995Z
10destroyed false
11version 2

На выходе отображаются только метаданные со временем удаления (deletion_time). Сами данные после удаления недоступны. Обратите внимание, что параметр destroyed со значением false указывает на возможность восстановления удаленных данных, если удаление произошло случайно.

1vault kv undelete -mount=secret -versions=2 hello
2Success! Data written to: secret/undelete/hello

Теперь данные восстановлены, как представлен на примере:

1vault kv get -mount=secret hello
2======= Metadata =======
3Key Value
4--- -----
5created_time 2022-01-15T01:40:09.888293Z
6custom_metadata <nil>
7deletion_time n/a
8destroyed false
9version 2
10===== Data =====
11Key Value
12--- -----
13excited yes
14foo world