Интеграция с Vault

В этой главе рассматривается интеграция Hive с Hashicorp Vault. В частности:

Каким образом можно настроить хранение секретов в Vault;
Алгоритм переноса существующих секретов в Vault;
Особенности реализации интеграции с Vault.

Общая конфигурация интеграции с Vault

Для конфигурации работы с Vault необходимо выполнить реконфигурацию. В таблице ниже приведены свойства, которые поддерживаются механизмом интеграции Hive и Vault.

Свойство	Назначение и комментарии
`vault.address`	Адрес сервера `vault`. Обязательное поле.
`vault.role_id.value`	Значение role_id. Обязательное поле.
`vault.secret_id.wrapped.file_path`	Путь к файлу с запакованным (wrapped) секретом. Обязательное поле, если секрет не распаковывается (unwrapping) автоматически сторонним способом.
`vault.secret_id.unwrapped.file_path`	Путь к файлу с распакованным (unwrapped) секретом. Обязательное поле.
`vault.secret_id.unwrap.engine_type`	Тип движка Vault. Возможные значения: kv-v1, kv-v2, approle. Дефолтное значение — kv-v2. Обязательное поле, если используется запакованный (wrapped) секрет.
`vault.secret_id.unwrap.field`	Наименование поля для хранения распакованного (unwrapped) секрета. Обязательное поле, если используются kv-v1 и kv-v2. Для `approle` дефолтное значение — `secret_id`.
`vault.secret_id.unwrap.cacert`	Путь к файлу CA сертификата для доступа к vault серверу по https. Если путь не задан, то используются корневые сертификаты ОС.
`vault.secret_id.unwrap.capath`	Путь к директории с сертификатами CA для доступа к серверу vault по https. Если путь не задан, то используются корневые сертификаты ОС.
`vault.auth.mount_point`	Полный путь к логину. Может быть как однословным, например, `my-approle-1` — так и в виде пути, например, `my/dep/approle`.

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

Примеры конфигураций

Пример 1. Если секрет попадает запакованным (wrapped) на машину с Hive, и его нужно распаковать (unwrap) средствами Hive:

[main]
vault.address = https://my-vault.example.com:8200 
vault.auth.mount_point = my-approle-1 
vault.role_id.value = 7d4714da-1c96-97be-a1ce-c19158d2a1ef 
vault.secret_id.unwrapped.file_path = /opt/vault_secret/secret_id 
vault.secret_id.wrapped.file_path = opt/vault_secret/wrapped_secret_id 
vault.secret_id.unwrap.engine_type = approle

Пример 2. Если секрет попадает уже распакованным (unwrapped) на машину с Hive:

[main]
vault.address = https://my-vault.example.com:8200
vault.auth.mount_point = my-approle-1 
vault.role_id.value = 7d4714da-1c96-97be-a1ce-c19158d2a1ef 
vault.secret_id.unwrapped.file_path = /opt/vault_secret/secret_id

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

Распаковка секрета

Если секрет запакованный (wrapped), и Hive настроен, как в примере 1 выше, то этот секрет автоматически распаковывается при старте приложения. Эту операцию можно выполнить вручную при помощи утилиты vault в составе Hive:

/opt/hw-bw/bin/vault unwrap

⚠️ Примечание: для работы этой утилиты требуется утилита jq (легкий и гибкий JSON-процессор командной строки). Убедитесь, что у вас установлена jq на машине с Hive. В большинстве дистрибутивов jq доступен в базе пакетов.

Убедитесь, что jq и прочие необходимые утилиты установлены в вашей ОС. Выполните команду:

/opt/hw-bw/bin/vault check-config

Вы также можете распаковать секрет вашими средствами автоматизации с использованием /opt/hw-bw/bin/vault. Если вы делаете это при помощи ваших средств автоматизации, посмотрите главу Особенности взаимодействия с Vault.

Назначение путей хранения паролей в Vault для интеграций

После того как общая интеграция с Vault настроена, можно перенести хранение паролей к сервисным аккаунтам AD, используемых Hive.

Вы могли сохранить в Vault пароли к этим сервисным аккаунтам и настроить там на стороне Vault авторотацию. Это может быть отдельный секрет или поле в другом секрете — на ваш выбор.

Войдите в WebUI в Hive как администратор, откройте настройки AD и в поле Пароль сервисного аккаунта введите параметры подключения к Vault:

engine=kv-v2,mount_point=hw/hive-1,path=ad_accounts,key=ad_service

В данном примере:

kv-v2 — тип secret engine, которое используется в вашем Vault. В настоящее время в Hive поддерживаются kv-v1 и kv-v2.
hw/hive-1 — путь к vault secret engine (также известно как mount point), которое вы использовали, когда активировали этот secret engine в vault.
ad_accounts — путь к секрету внутри secret engine, в котором хранятся ваши секреты.
ad_service — имя ключа, в котором хранится пароль к сервисному аккаунту.

В настоящее время все четыре поля (engine, mount_point, path, key) являются обязательными.

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

Если Проверка соединения выполнена успешно, это означает, что:

Секрет для аутентификации в vault был успешно распакован (если предоставлялся запакованным) или просто успешно прочитан Hive.
При помощи указанного role_id и этого секрета удалось корректно залогиниться в Vault.
Vault secret engine по указанному в mount_point пути существует и доступно на чтение для этой approle.
Версия этого Vault secret engine указана корректно.
Путь внутри этого secret engine указан корректно.
Указанный ключ с паролем по указанному пути нашёлся.
В этом ключе хранится корректный пароль к серверу AD, и сервисному аккаунту удалось залогиниться в AD и получить список пользователей.

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

Перенос существующего секрета в Vault

Если у вас уже был настроен Hive, и все работало, вам может потребоваться перенести секреты, которые сейчас в настоящее время хранятся в ini-файлах в Vault. В данной главе описана последовательность действий для переноса остальных секретов.

Общая последовательность действий для каждого секрета выглядит так:

Получить существующее значение секрета при помощи /opt/hw-bw/bin/get-config-value из существующего в ini-файлах свойства (список свойств смотрите ниже).
Создать в Vault секрет с этим значением. Это может быть отдельный секрет или поле в существующем секрете — на ваш выбор.
Сформировать полный путь этого секрета в Vault, включая mount-point, path, key.
Сохранить полный путь секрета в новое свойство (см. список ниже) в /opt/hw-bw/config/user.ini.

Пример пути:
```
VAULT;engine=kv_v1,mount_point=role_v1_t,path=hw/hive»,key=cipher_key
```
Удалить старое свойство при помощи /opt/hw-bw/bin/rm-config-value из ini-файлов.
Для применения настроек выполните реконфигурацию.

Обратите внимание, что после применения настроек в файлах local.ini появятся новые значения для свойств, которые вы удалили. Эти значения автоматически генерируются при каждой реконфигурации системы, однако эти значения не применяются и не являются секретами для каких-либо сервисов.

Свойства, которые нужно задать для переноса паролей и ключа шифрования в Vault:

из sensdata.encrypt.key в sensdata.encrypt.key_path.
из b.postgres.password в b.postgres.password_path.
из b.graph.password в b.graph.password_path.

Теперь подробнее о каждом свойстве.

Свойство sensdata.encrypt.key_path

Путь в хранилище секретов Vault к ключу шифрования чувствительных данных, таких как пароли соединений проектов Hive — Apiary. Если путь не задан, используется ключ шифрования, указанный в свойстве sensdata.encrypt.key. При некорректном указании пути появляется сообщение об ошибке в логе приложения.
Указывается как строка в формате <ENGINE>;<PATH>, где ENGINE — в настоящее время только VAULT, а PATH — engine=<engine_type>,mount_point=<mount_point>,path=<path>,key=<key>.
Пример: VAULT;engine=kv_v1,mount_point=role_v1_t,path=new/default,key=cipher_key

Примечания:

Используйте get-config-value sensdata.encrypt.key, чтобы получить существующий ключ шифрования.
После переноса ключа шифрования в Vault рекомендуем удалить свойство при помощи утилиты rm-config-value sensdata.encrypt.key.
Ключи шифрования для Hive и Apiary различаются, хотя свойство имеет одинаковое имя.
Изменение ключа шифрования для существующих коннектов не предусмотрено.

Свойство b.postgres.password_path

Путь в хранилище секретов Vault к паролю встроенной БД postgresql. Если путь не задан, используется пароль, указанный в свойстве b.postgres.password. При некорректном указании пути появляется сообщение об ошибке в логе приложения.
Указывается как строка в формате: <ENGINE>;<PATH>, где ENGINE в настоящее время только VAULT, а PATH: engine=<engine_type>,mount_point=<mount_point>,path=<path>,key=<key>.
Пример: VAULT;engine=kv_v2,mount_point=role_v2_t,path=hw/hive/pg,key=password

Примечания:

Используйте get-config-value b.postgres.password что бы получить существующий пароль.
После переноса пароля в Vault рекомендуем удалить свойство при помощи утилиты rm-config-value b.postgres.password.
Изменение пароля в контейнере со встроенным postgresql может быть произведено вручную, если это требуется.

Свойство b.graph.password_path

Путь в хранилище секретов (Vault) к паролю встроенной БД neo4j. Если путь не задан, используется пароль, указанный в свойстве b.graph.password. При некорректном указании пути, появляется сообщение об ошибке в логе приложения.
Указывается как строка в формате <ENGINE>;<PATH>, где ENGINE — в настоящее время только VAULT, а PATH — engine=<engine_type>,mount_point=<mount_point>,path=<path>,key=<key>.
Пример: VAULT;engine=kv_v2,mount_point=role_v2_t,path=hw/hive/graph,key=password

Примечания:

Используйте get-config-value b.graph.password, чтобы получить существующий пароль.
После переноса пароля в Vault рекомендуем удалить свойство при помощи утилиты rm-config-value b.graph.password.
Изменить пароль в контейнере со встроенным postgresql можно вручную, если требуется.

Особенности взаимодействия с Vault

Как Hive логинится в Vault:

role_id — хранится на диске в ini-файле и передаётся в контейнер в виде переменной среды окружения.
Секрет для аутентификации распаковывается только один раз при старте Hive.
Запакованный secret_id — хранится на диске в директории, определённой администратором системы. Используется только для распаковки секретов.
Распакованный secret_id — хранится на диске в директории, определённой администратором системы. Передаётся в контейнер как ReadOnly том (volume).
Поскольку при старте Hive запускается несколько контейнеров, и в каждом контейнере запускается несколько процессов, которым требуется логин в Vault, файл с unwrapped_secret_id может быть прочитан несколько раз. Логин в Vault будет совершён каждым из этих процессов. Поэтому мы рекомендуем использовать большое или бесконечное число раз, с которым Hive может логиниться в Vault.
При этом часть процессов (для background-обработки) могут запускаться не сразу при старте Hive, а по мере потребности.
После успешного логина каждый процесс получает токен для доступа к секрету и далее работает с ним.

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

При истечении времени использования токена Hive выполняет автоматический повторный логин в Vault при помощи того же самого секрета.
При невозможности повторного логина с тем же секретом производится попытка повторного чтения распакованного секрета.

Особенности поведения при ротации секрета для аутентификации в Vault:

Повторная автоматическая распаковка запакованного секрета в случае, если Hive не смогла залогиниться в Vault с имеющимся секретом, не предусмотрен.
Если ваша система автоматического развёртывания меняет секрет для логина в Vault и доставляет запакованный секрет на машину с Hive, та же самая система должна будет распаковывать его, вызвав скрипт наподобие /opt/hw-bw/bin/vault unwrap.
Если распакованный секрет будет доставляться на машину другими способами (не через наш скрипт), убедитесь, что inode этого файла не изменяется.

Пример sh-скрипта для изменения содержимого файла без изменения его inode:

touch "${unwrapped_secret_file}"
truncate -s 0 "${unwrapped_secret_file}"
chmod 644 "${unwrapped_secret_file}"
echo "${new_unwrapped_value}" >> "${unwrapped_secret_file}"