Работа с Iceberg через CedrusData Catalog#

CedrusData Catalog — это высокопроизводительный каталог для Iceberg с поддержкой материализованных представлений и протокола Iceberg REST.

Данный документ описывает особенности конфигурации CedrusData Catalog для работы Iceberg.

Общая информация#

CedrusData Catalog представляет собой сервис для хранения метаданных Apache Iceberg.

Коннектор Iceberg может работать с CedrusData Catalog одним из следующих способов:

Нативный режим, CedrusData Catalog запущен отдельно — подключение к CedrusData Catalog происходит по высокопроизводительному нативному протоколу с поддержкой материализованных представлений. Рекомендуемый режим работы, если с данными Apache Iceberg работает несколько продуктов. Например, CedrusData и Apache Spark, или несколько кластеров CedrusData
Нативный режим, CedrusData Catalog запущен в одном процессе с CedrusData — аналогичен предыдущему, но сервис CedrusData Catalog запущен непосредственно внутри координатора CedrusData. Обеспечивает более высокую производительность за счет отсутствия сетевого взаимодействия. Рекомендуемый режим работы, если с данными Apache Iceberg работает только текущий кластер CedrusData
Iceberg REST Protocol — подключение к CedrusData Catalog происходит по протоколу Iceberg REST Catalog. Legacy-режим, не поддерживает материализованные представления.

Нативный режим#

Для подключения к CedrusData Catalog в нативном режиме необходимо:

Задать тип и параметры подключения к каталогу в файле конфигурации etc/config.properties
Задать параметры каталога в конфигурации каталога Iceberg

Если вы используете Docker-образ CedrusData, то тип подключения к CedrusData Catalog может быть задан через переменные окружения CEDRUSDATA_CATALOG_MODE и CEDRUSDATA_CATALOG_COORDINATOR_MODE.

Примеры полной конфигурации приведены в конце раздела.

Локальное развертывание Apache Iceberg с помощью CedrusData Catalog демонстрирует последовательность пример быстрого начала работы с Iceberg с помощью CedrusData Catalog, запущенного в embedded режиме.

Параметры подключения#

Параметры подключения к каталогу необходимо задать в файле etc/config.properties. Данные параметры должны быть заданы на всех узлах кластера CedrusData.

Общая конфигурация CedrusData Catalog#
Параметр	Описание
`cedrusdata-catalog.mode`	Задает режим работы каталога. `DISABLED` — подключение к каталогу отсутствует. `REMOTE` — подключение к каталогу происходит через протокол HTTP(S). `EMBEDDED` — каталог будет запущен совместно с узлом. Данный режим можно использовать только на координаторе. При использовании Docker-образа с конфигурацией по умолчанию, режим может быть задан через переменную окружения `CEDRUSDATA_CATALOG_MODE`. Значение по умолчанию: `DISABLED`
`cedrusdata-catalog.coordinator-mode`	Задает режим работы каталога на координаторе. Позволяет переопределить значение `cedrusdata-catalog.mode` на координаторе. Используйте данный параметр, если вы хотите запустить каталог в embedded режим в кластере, состоящем из нескольких узлов. В этом случае вы можете задать в одном файле конфигурации параметры `cedrusdata-catalog.mode=REMOTE` и `cedrusdata-catalog.coordinator-mode=EMBEDDED`, что позволяет удобно распространять конфигурацию без необходимости изменения `cedrusdata-catalog.mode` значения в зависимости от типа узла. При использовании Docker-образа с конфигурацией по умолчанию, режим может быть задан через переменную окружения `CEDRUSDATA_CATALOG_COORDINATOR_MODE`.
`cedrusdata-catalog.access-token`	Постоянный токен доступа. Процесс получения постоянного токена доступа описан в документации. Параметр является обязательным при использовании `REMOTE` режима. В `EMBEDDED` режиме, если значение не задано, то узел попробует прочитать токен из файла согласно правилам первоначальной аутентификации CedrusData Catalog.
`cedrusdata-catalog.uri`	Обязательный параметр. URI для подключения к CedrusData Catalog. Например: `http://cedrusdata-catalog:9080`.

Подключение в REMOTE режиме#

Задайте параметр cedrusdata-catalog.mode=remote.

Для подключения в remote режиме необходимо задать сетевой адрес CedrusData Catalog и, при необходимости, сконфигурировать параметры HTTPS.

Подключение к CedrusData Catalog по HTTP(S)#
Параметр	Описание
`cedrusdata-catalog.remote.uri`	Обязательный параметр. URI для подключения к CedrusData Catalog. Например: `http://cedrusdata-catalog:9080`.
`cedrusdata-catalog.remote.keystore-path`	Путь к файлу keystore в формате PEM или JKS в локальной файловой системе узла.
`cedrusdata-catalog.remote.keystore-password`	Пароль keystore.
`cedrusdata-catalog.remote.truststore-path`	Путь к файлу truststore в формате PEM или JKS в локальной файловой системе узла.
`cedrusdata-catalog.remote.truststore-password`	Пароль truststore.
`cedrusdata-catalog.remote.ssl-verification`	Способ валидации сертификата сервера CedrusData Catalog. Допустимые значения: `full` — проверять сертификат и hostname сервера; `ca` — проверять только сертификат сервера, `none` — не проверять сертификат сервера. Используйте режим `none` только для тестирования (например, с самоподписанными сертификатами). Значение по умолчанию: `full`

Подключение в EMBEDDED режиме#

Задайте параметр cedrusdata-catalog.coordinator-mode=embedded.

При использовании embedded режима, CedrusData Catalog будет запущен как отдельный сервис координатора CedrusData. Embedded режим может быть использован только на координаторе. Остальные узлы должны работать с каталогом в режиме remote.

Подключение к CedrusData Catalog в embedded режиме#
Параметр	Описание
`cedrusdata-catalog.embedded.config`	Путь к файлу конфигурации CedrusData Catalog. Возможные параметры описаны в документации CedrusData Catalog. Обязательный параметр. Значение по умолчанию: `etc/cedrusdata-catalog.properties` (относительно `data-dir`)
`cedrusdata-catalog.embedded.local-iceberg`	Создать ли в CedrusData Catalog локальную файловую систему и логический каталог, который работает с локальной файловой системой. Позволяет быстро начать работу с данными Apache Iceberg. В основном используется для экспериментов. Значение по умолчанию: `true`
`cedrusdata-catalog.embedded.local-iceberg.catalog-name`	Какое имя использовать для логического каталога CedrusData Catalog, если параметр `cedrusdata-catalog.embedded.local-iceberg` равен `true`. Значение по умолчанию: `local`
`cedrusdata-catalog.embedded.local-iceberg.file-system-name`	Какое имя использовать для локальной файловой системы CedrusData Catalog, если параметр `cedrusdata-catalog.embedded.local-iceberg` равен `true`. Значение по умолчанию: `local`
`cedrusdata-catalog.embedded.local-iceberg.file-system-location`	Задает путь локальной файловой системы CedrusData Catalog, если параметр `cedrusdata-catalog.embedded.local-iceberg` равен `true`. Может быть абсолютным или относительным. Если путь относительный, он будет разрешен относительно `data-dir` узла. Значение по умолчанию: `iceberg` (относительно `data-dir` узла)

Параметры Iceberg#

После конфигурации подключения к CedrusData Catalog, необходимо сконфигурировать ваш каталог Iceberg для работы с CedrusData Catalog в нативном режиме. Для этого задайте следующие параметры в конфигурации каталога Iceberg:

iceberg.catalog.type=cedrusdata_catalog
iceberg.cedrusdata-catalog.catalog-name=<имя_логического_каталога>

Параметр iceberg.cedrusdata-catalog.catalog-name задает имя логического каталога в CedrusData Catalog.

По умолчанию выполнение операций каталога будет происходить от имени владельца постоянного ключа доступа. Задайте параметр iceberg.cedrusdata-catalog.impersonation-enabled=true, чтобы включить имперсонацию. В этом случае выполнение операций каталога будет происходить от имени текущего пользователя CedrusData.

Примеры#

REMOTE режим#

Если вы хотите создать каталог Iceberg my_iceberg с включенной имперсонацией для работы с объектами логического каталога sales в экземпляре CedrusData Catalog по адресу http://192.168.1.15, необходимо задать следующую конфигурацию.

Файл etc/config.properties:

cedrusdata-catalog.mode=remote
cedrusdata-catalog.access-token=<постоянный_токен_доступа>
cedrusdata-catalog.remote.uri=http://192.168.1.15

Файл etc/catalog/my_iceberg.properties:

connector.name=iceberg
iceberg.catalog.type=cedrusdata_catalog
iceberg.cedrusdata-catalog.catalog-name=sales
iceberg.cedrusdata-catalog.impersonation-enabled=true

EMBEDDED режим#

В данном примере мы рассмотрим подключение к CedrusData Catalog в embedded режиме. Для этого мы зададим в файле etc/config.properties параметр cedrusdata-catalog.coordinator-mode=embedded. При этом мы оставим конфигурацию remote режима, которая будет использована воркерами CedrusData. Параметр cedrusdata-catalog.remote.uri будет указывать на координатора CedrusData, внутри которого запущен CedrusData Catalog.

Файл etc/config.properties:

cedrusdata-catalog.mode=remote
cedrusdata-catalog.coordinator-mode=embedded
cedrusdata-catalog.access-token=<постоянный_токен_доступа>
cedrusdata-catalog.remote.uri=http://192.168.1.15

Файл etc/catalog/my_iceberg.properties:

connector.name=iceberg
iceberg.catalog.type=cedrusdata_catalog
iceberg.cedrusdata-catalog.catalog-name=sales

EMBEDDED режим и локальная файловая система#

В данном примере мы настроим коннектор Iceberg на работу с локальной файловой системой. Это позволит нам начать работу с Apache Iceberg без внешних зависимостей и сервисов. Данный пример предполагает, что кластер CedrusData состоит из одного узла — координатора, которые совмещает роль воркера.

Файл etc/config.properties:

cedrusdata-catalog.mode=embedded

Файл etc/catalog/my_iceberg.properties:

connector.name=iceberg
iceberg.catalog.type=cedrusdata_catalog
iceberg.cedrusdata-catalog.catalog-name=local

Подключение через Iceberg REST Protocol#

Подключение к CedrusData Catalog через протокол Iceberg REST аналогично подключению к любому другому REST каталогу. Воспользуйтесь документацией REST Catalog.