Расширение 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:

  1. На странице Clusters выберите нужный кластер.

  2. Откройте вкладку Services и выберите DuckDB.

  3. В разделе конфигурации ADO extensions включите или отключите расширение хранилища секретов Vault/OpenBao с помощью соответствующего переключателя. Настройте необходимые параметры.

  4. Нажмите Save.

  5. В выпадающем меню Actions выберите Restart. Убедитесь, что параметр Apply configs from ADCM имеет значение true, и нажмите Run.

Включение расширения Vault/OpenBao в ADCM
Включение расширения Vault/OpenBao в ADCM

После перезапуска сервиса 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, можно применить следующий обходной способ:

  1. В интерфейсе Airflow откройте страницу Connections.

  2. Отредактируйте подключение, используемое оператором DuckDbOperator.

  3. В поле Extra укажите:

    {
      "cli_params": ["-unsigned"]
    }
  4. Сохраните подключение и повторно запустите задачу.

Конфигурация

Настройте расширение с помощью параметров сервиса 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, например https://vault.example.com:8200

 — 

secret_vault_flavor

Тип сервера: vault или openbao

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 отключает проверку

0

secret_vault_soft_delete

Помечает секреты как удаленные вместо их физического удаления

false

secret_vault_max_versions

Максимальное количество сохраняемых версий секрета. Значение 0 означает отсутствие ограничения

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, если установлено значение true

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, обладают необходимыми разрешениями на чтение секрета.

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней