Расширение DuckDB для хранилища секретов Vault/OpenBao
Расширение Vault/OpenBao для DuckDB позволяет хранить постоянные секреты DuckDB во внешней системе управления секретами. Расширение поддерживает HashiCorp Vault и OpenBao с использованием движка секретов KV v2.
По умолчанию DuckDB хранит секреты локально. При включении хранилища Vault/OpenBao команда CREATE PERSISTENT SECRET сохраняет секреты в настроенном серверном хранилище Vault/OpenBao. Это позволяет нескольким процессам DuckDB и хостам совместно использовать секреты через централизованное хранилище секретов.
Расширение входит в состав сервиса DuckDB в ADO и управляется через ADCM. Отдельная установка не требуется.
Расширение поддерживает:
-
Аутентификацию по токену, имени пользователя и паролю, а также через LDAP.
-
Настраиваемые точки монтирования KV v2 и префиксы путей к секретам.
-
Пространства имен Vault и пользовательские пути аутентификации.
-
HTTPS, пользовательские сертификаты CA и взаимную аутентификацию TLS (mTLS).
-
Настройку HTTP-прокси, тайм-аутов подключения и запросов, а также повторных попыток подключения.
-
Ограничение количества версий секретов, проверки compare-and-set (CAS) и мягкое удаление.
Предварительные требования
Перед включением расширения убедитесь, что:
-
Сервер Vault или OpenBao доступен и к нему можно подключиться из сервиса DuckDB.
-
В указанной точке монтирования существует движок секретов KV v2, который планируется использовать.
-
На сервере включен какой-либо метод аутентификации, а учетные данные обладают необходимыми разрешениями.
-
Доступны URL сервера, пространство имен, сертификаты TLS и настройки прокси, если они требуются в вашей среде.
Для HashiCorp Vault создайте точку монтирования KV v2 с именем secret, если она еще не существует:
$ vault secrets enable -path=secret kv-v2
Для OpenBao используйте команду:
$ bao secrets enable -path=secret kv-v2
Если точка монтирования уже существует, не создавайте ее повторно. Расширение использует настроенные точку монтирования и префикс пути для поиска секретов.
Включение и отключение расширения
Чтобы включить или отключить расширение Vault/OpenBao через ADCM:
-
На странице Clusters выберите нужный кластер.
-
Откройте вкладку Services и выберите DuckDB.
-
В разделе конфигурации ADO extensions включите или отключите расширение хранилища секретов Vault/OpenBao с помощью соответствующего переключателя. Настройте необходимые параметры.
-
Нажмите Save.
-
В выпадающем меню Actions выберите Restart. Убедитесь, что параметр Apply configs from ADCM имеет значение
true, и нажмите Run.
После перезапуска сервиса DuckDB использует обновленную конфигурацию сервиса.
Если параметру secret_vault_enabled присвоено значение true, Vault/OpenBao становится дефолтным хранилищем постоянных секретов DuckDB. Существующие локальные секреты автоматически не переносятся. Если необходимо сохранить их во внешнем хранилище, спланируйте и выполните миграцию отдельно.
Ограничение для неподписанных расширений
В ADO 3.0.0 параметр allow_unsigned_extensions доступен в ADCM, но его значение не применяется при запуске DuckDB через /usr/bin/duckdb. В результате расширение, предоставляемое ADO и не имеющее цифровой подписи, может не загрузиться, даже если этот параметр включен.
Расширение необходимо загружать с помощью параметра командной строки -unsigned. Если расширение не загружается, проверьте параметры запуска DuckDB и конфигурацию сервиса.
Для задач Airflow, использующих провайдер DuckDB, можно применить следующий обходной способ:
-
В интерфейсе Airflow откройте страницу Connections.
-
Отредактируйте подключение, используемое оператором
DuckDbOperator. -
В поле Extra укажите:
{ "cli_params": ["-unsigned"] } -
Сохраните подключение и повторно запустите задачу.
Конфигурация
Настройте расширение с помощью параметров сервиса DuckDB в ADCM. Полный список параметров конфигурации DuckDB приведен в разделе Параметры конфигурации DuckDB.
Расширение использует глобальные настройки DuckDB. В автономном процессе DuckDB эти параметры можно задавать с помощью SQL-операторов SET или переменных окружения. Настройки SQL имеют приоритет над соответствующими переменными окружения.
В ADO настройте параметры на уровне сервиса через ADCM и перезапустите сервис, чтобы применить изменения. Настройки, переданные другому процессу DuckDB, автоматически не становятся доступными процессам, выполняющимся в среде ADO.
Включение хранилища Vault/OpenBao
Для минимальной конфигурации требуются следующие параметры:
-
secret_vault_enabled— включает постоянное хранилище секретов на базе Vault/OpenBao. -
secret_vault_url— URL сервера Vault/OpenBao. -
Метод аутентификации и учетные данные — настройте их в соответствии с параметрами аутентификации сервера.
Движок секретов KV v2 также должен быть доступен в настроенной точке монтирования, а указанные учетные данные должны иметь разрешения на доступ к соответствующим путям секретов.
URL сервера и настройки KV v2
Следующие параметры управляют подключением к Vault/OpenBao и расположением сохраненных секретов.
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
secret_vault_enabled |
Включает постоянное хранилище секретов на базе Vault/OpenBao |
false |
secret_vault_url |
URL сервера Vault/OpenBao, например |
— |
secret_vault_flavor |
Тип сервера: |
vault |
secret_vault_api_version |
Версия API, используемая в путях запросов |
v1 |
secret_vault_mount |
Точка монтирования KV v2 |
secret |
secret_vault_path_prefix |
Префикс, используемый для формирования путей к секретам |
duckdb/secrets |
secret_vault_cas |
Версия для проверки compare-and-set. Значение |
0 |
secret_vault_soft_delete |
Помечает секреты как удаленные вместо их физического удаления |
false |
secret_vault_max_versions |
Максимальное количество сохраняемых версий секрета. Значение |
0 |
При использовании дефолтных точки монтирования и префикса пути секрет с именем my_s3 сохраняется по следующему пути API Vault/OpenBao: /v1/secret/data/duckdb/secrets/my_s3.
Путь состоит из версии API, точки монтирования KV v2, конечной точки data, префикса пути и имени секрета. При изменении точки монтирования или префикса результирующий путь также изменяется.
Аутентификация
Расширение поддерживает три метода аутентификации:
-
Токен (
secret_vault_auth_method,secret_vault_token); -
Имя пользователя и пароль (
secret_vault_auth_method,secret_vault_username,secret_vault_password); -
LDAP (
secret_vault_auth_method,secret_vault_ldap_username,secret_vault_ldap_password,secret_vault_ldap_auth_path).
По умолчанию используется аутентификация по токену. Токен должен обладать разрешениями, необходимыми для выполнения предполагаемых операций, включая чтение, создание, обновление, удаление и перечисление секретов, если эти операции применимы.
Для аутентификации по имени пользователя и паролю присвойте параметру secret_vault_auth_method значение userpass и укажите имя пользователя и пароль. Для аутентификации через LDAP присвойте ему значение ldap и настройте учетные данные LDAP и путь монтирования аутентификации.
Расширение также поддерживает следующие параметры:
-
secret_vault_auth_path— пользовательский путь монтирования аутентификации. -
secret_vault_auth_namespace— пространство имен для запросов аутентификации. -
secret_vault_namespace— задает HTTP-заголовокX-Vault-Namespaceдля Vault Enterprise или совместимых развертываний с поддержкой пространств имен.
Используйте метод аутентификации, настроенный на сервере. Убедитесь, что учетные данные обладают необходимыми разрешениями для настроенных точки монтирования KV v2 и путей секретов.
TLS, сертификаты и настройки прокси
Расширение поддерживает HTTPS, а при наличии поддержки TLS в сборке DuckDB — пользовательские сертификаты CA и взаимную аутентификацию TLS (mTLS).
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
secret_vault_tls_skip_verify |
Отключает проверку сертификата TLS, если установлено значение |
false |
secret_vault_tls_ca_cert |
Путь к сертификату CA |
— |
secret_vault_tls_client_cert |
Путь к клиентскому сертификату для mTLS |
— |
secret_vault_tls_client_key |
Путь к закрытому ключу клиента для mTLS |
— |
secret_vault_tls_min_version |
Минимальная версия TLS |
1.2 |
secret_vault_http_proxy |
URL HTTP-прокси |
— |
secret_vault_http_proxy_username |
Имя пользователя прокси |
— |
secret_vault_http_proxy_password |
Пароль прокси |
— |
В промышленных развертываниях не отключайте проверку сертификатов и настройте необходимые сертификаты CA. Отключение проверки может привести к перехвату соединений, поэтому его следует использовать только в контролируемых сценариях диагностики.
Поддержка HTTPS зависит от наличия OpenSSL в сборке расширения DuckDB. Если расширение собрано без поддержки OpenSSL, использовать HTTPS в этой сборке невозможно.
Тайм-ауты, повторные попытки и настройки HTTP
Расширение предоставляет параметры для настройки тайм-аутов подключения и запросов, повторных попыток и поведения HTTP.
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
secret_vault_connect_timeout |
Тайм-аут подключения в секундах |
10 |
secret_vault_request_timeout |
Тайм-аут запроса в секундах |
30 |
secret_vault_max_retries |
Максимальное количество повторных попыток при временных ошибках |
3 |
secret_vault_retry_backoff_ms |
Начальная задержка перед повторной попыткой в миллисекундах |
100 |
secret_vault_retry_max_backoff_ms |
Максимальная задержка перед повторной попыткой в миллисекундах |
5000 |
secret_vault_http_keep_alive |
Включает HTTP keep-alive |
true |
secret_vault_headers |
Дополнительные HTTP-заголовки, заданные в формате JSON |
— |
secret_vault_debug |
Выводит сведения об HTTP-запросах и ответах в стандартный поток ошибок для диагностики |
false |
Дефолтные значения тайм-аутов и параметров повторных попыток подходят в качестве отправной точки для многих сред. Если сервер доступен через сеть с высокой задержкой, при необходимости скорректируйте тайм-ауты и параметры повторных попыток. Повторные попытки могут увеличить время до завершения запроса с ошибкой, если сервер недоступен.
Параметр secret_vault_debug помогает диагностировать ошибки подключения и API. В отладочных сообщениях расширения конфиденциальные значения маскируются, однако диагностические журналы все равно необходимо обрабатывать с соблюдением требований безопасности.
Конфиденциальные параметры
Токены аутентификации, пароли пользователей, пароли LDAP и прокси, а также закрытые ключи клиентов относятся к конфиденциальной информации. Настраивайте их с помощью соответствующих защищенных параметров сервиса в ADCM. Не включайте реальные учетные данные в документацию, систему контроля версий или журналы задач.
Используйте учетные данные с минимальным набором разрешений, необходимым для рабочей нагрузки. Не используйте административный токен Vault/OpenBao, если достаточно токена с ограниченными разрешениями для необходимых путей KV v2.
Примеры использования
В следующих примерах SQL показано, как использовать расширение. В ADO перед выполнением SQL-операторов настройте параметры подключения и учетные данные через ADCM.
Создание постоянного секрета
После включения расширения и настройки URL Vault/OpenBao и учетных данных для аутентификации создайте постоянный секрет S3:
CREATE PERSISTENT SECRET my_s3 (
TYPE S3,
KEY_ID 'example-key-id',
SECRET 'example-secret-key',
REGION 'eu-central-1'
);
DuckDB сохраняет секрет в Vault/OpenBao, а не в локальном файле постоянных секретов.
Чтобы проверить метаданные секрета, выполните запрос:
SELECT name, type, provider, persistent, storage
FROM duckdb_secrets();
Результат содержит имя секрета, тип, провайдер, признак постоянного хранения и серверное хранилище. Для секрета, сохраненного этим расширением, значение storage указывает на Vault в качестве хранилища.
Затем секрет можно использовать в операциях DuckDB, поддерживающих учетные данные S3. Например:
SELECT *
FROM read_parquet('s3://analytics-bucket/events.parquet')
LIMIT 10;
В этом примере предполагается, что необходимые параметры конечной точки S3 и дополнительные настройки подключения уже сконфигурированы для данной среды.
Удаление постоянного секрета
Чтобы удалить секрет, выполните команду:
DROP SECRET my_s3;
Расширение удаляет секрет из настроенного серверного хранилища и соответствующую запись из локального каталога. Если параметр secret_vault_soft_delete включен, серверное хранилище помечает секрет как удаленный вместо его физического удаления.
Настройка аутентификации по имени пользователя и паролю
Если сервер Vault/OpenBao использует аутентификацию по имени пользователя и паролю вместо аутентификации по токену, задайте для secret_vault_auth_method значение userpass и укажите учетные данные.
Для автономного процесса DuckDB эквивалентная конфигурация SQL выглядит следующим образом:
SET secret_vault_auth_method = 'userpass';
SET secret_vault_username = 'alice';
SET secret_vault_password = 'example-password';
SET secret_vault_url = 'https://vault.example.com:8200';
SET secret_vault_enabled = true;
В ADO настройте соответствующие параметры через ADCM и перезапустите сервис, чтобы применить изменения.
Настройка аутентификации LDAP
Для аутентификации LDAP задайте для secret_vault_auth_method значение ldap и настройте учетные данные LDAP и путь монтирования аутентификации.
Для автономного процесса DuckDB:
SET secret_vault_auth_method = 'ldap';
SET secret_vault_ldap_username = 'alice';
SET secret_vault_ldap_password = 'example-password';
SET secret_vault_ldap_auth_path = 'ldap';
SET secret_vault_url = 'https://vault.example.com:8200';
SET secret_vault_enabled = true;
В ADO настройте соответствующие параметры через ADCM. Убедитесь, что на сервере включена аутентификация LDAP, а аутентифицированная учетная запись имеет доступ к настроенной точке монтирования KV v2.
Устранение неполадок
Если DuckDB не удается подключиться к Vault/OpenBao или получить доступ к сохраненному секрету, проверьте следующее:
-
Расширение включено в ADCM, а сервис DuckDB перезапущен с параметром Apply configs from ADCM, установленным в
true. -
URL сервера указан правильно и сетевое подключение работает.
-
Выбран правильный метод аутентификации, указаны корректные учетные данные, путь монтирования аутентификации и пространство имен.
-
Движок секретов KV v2 существует в настроенной точке монтирования.
-
Учетные данные обладают необходимыми разрешениями для настроенной точки монтирования и путей секретов.
-
Сертификаты TLS, настройки прокси, тайм-ауты подключения и ограничения повторных попыток настроены правильно.
Если расширение не загружается, проверьте ограничение для неподписанных расширений, описанное в разделе о включении расширения, и параметры запуска DuckDB.
Для получения дополнительных диагностических сведений включите отладку расширения. В автономном процессе DuckDB выполните команду:
SET secret_vault_debug = true;
Расширение выводит диагностические сведения об HTTP-запросах и ответах в стандартный поток ошибок. Конфиденциальные значения маскируются, однако журналы необходимо обрабатывать в соответствии с требованиями безопасности вашей среды.
Чтобы просмотреть постоянные секреты, известные DuckDB, выполните запрос:
SELECT name, type, provider, persistent, storage
FROM duckdb_secrets();
Убедитесь, что секрет является постоянным и что в качестве серверного хранилища указан Vault. Если секрет был записан непосредственно с помощью CLI Vault/OpenBao, проверьте, что его структура JSON соответствует формату, ожидаемому расширением, и что секрет записан в настроенные точку монтирования и префикс пути.
Особенности хранения постоянных секретов
Расширение хранит постоянные секреты DuckDB в Vault/OpenBao KV v2 в виде структурированных объектов. Сохраненное представление включает тип секрета, провайдер, область действия, метаданные маскирования и пары ключ-значение, специфичные для секрета.
При создании постоянного секрета в DuckDB расширение записывает его во внешнее хранилище и добавляет его в кеш локального каталога DuckDB. При поиске секрета расширение синхронизирует сохраненные секреты с внешним хранилищем и выбирает наиболее подходящий вариант по типу секрета и области действия.
Обновления записываются во внешнее хранилище. Версионирование KV v2 и настройки compare-and-set определяют, как обновления взаимодействуют с сохраненными версиями и параллельными изменениями. При удалении секрета расширение удаляет его из внешнего хранилища в соответствии с настроенным поведением удаления и удаляет соответствующую запись из локального каталога.
При включении хранилища Vault/OpenBao существующие локальные постоянные секреты автоматически не переносятся. При необходимости спланируйте миграцию отдельно.
Секрет с именем my_s3, сохраненный с дефолтными точкой монтирования и префиксом пути, имеет следующую структуру данных KV v2:
{
"data": {
"data": {
"type": "s3",
"provider": "config",
"persistent": true,
"scope": [],
"redact_keys": ["secret"],
"extra_config": {},
"KEY_ID": "example-key-id",
"SECRET": "example-secret-key",
"REGION": "eu-central-1"
},
"options": {
"cas": 0,
"max_versions": 0
}
}
}
Внешние поля data и options соответствуют формату API KV v2 Vault/OpenBao. Внутренние данные секрета содержат поля, необходимые для восстановления секрета DuckDB.
Если секрет необходимо создать непосредственно через CLI Vault/OpenBao, используйте настроенные точку монтирования и префикс пути и сохраните ожидаемую структуру секрета. Например, создайте JSON-файл, содержащий внутренние поля секрета:
{
"type": "s3",
"provider": "config",
"scope": [],
"redact_keys": ["secret"],
"KEY_ID": "example-key-id",
"SECRET": "example-secret-key",
"REGION": "eu-central-1"
}
Для OpenBao запишите секрет в настроенные точку монтирования KV v2 и путь:
$ export BAO_ADDR='https://openbao.example.com:8200'
$ export BAO_TOKEN='your-token'
$ bao kv put -mount=secret duckdb/secrets/my_s3 @my_s3.json
Секрет становится доступен DuckDB, если расширение может получить доступ к указанному пути, а сохраненные данные соответствуют ожидаемому формату. Убедитесь, что учетные данные, используемые DuckDB, обладают необходимыми разрешениями на чтение секрета.