Iceberg REST Catalog#

CedrusData Catalog реализует протокол Iceberg REST Catalog и позволяет управлять таблицами Iceberg.

В запущенном экземпляре CedrusData Catalog работа по протоколу Iceberg REST Catalog осуществляется по адресу http(s)://host[:port]/catalog/iceberg.

Совместимость#

CedrusData Catalog поддерживает весь функционал прокола Iceberg REST Catalog за исключением нескольких функций, описанных ниже. Вы можете работать со следующими объектами Iceberg: namespace, table и view.

CedrusData Catalog не поддерживает:

  1. Делегирование доступа через механизм vended-credentials

  2. Делегирование доступа через механизм remote-signing

  3. Сбор метрик (metrics reporting)

Начало работы#

Экземпляр CedrusData Catalog может иметь один или несколько зарегистрированных каталогов Iceberg. Используйте команду iceberg catalog create для создания каталога Iceberg.

После того как вы создали каталог, подключите один или несколько движков согласно инструкциям: CedrusData, Trino, Apache Spark. Инструкции для подключения других движков вы можете найти в их документации.

Объекты Iceberg#

CedrusData Catalog работает со следующими объектами Iceberg:

  1. Catalog — логическое хранилище объектов namespace. В зависимости от целевого движка, данный объект может называться catalog, warehouse, и т.д. Созданием и изменением каталогов обычно занимаются администраторы системы.

  2. Namespace — логическое хранилище объектов table и view. В различных движках namespace обычно соответствует логической схеме (schema). Например, с помощью команды CREATE SCHEMA в CedrusData или Apache Spark.

  3. Table — таблица Iceberg, принадлежащая namespace. Состоит из системной записи в CedrusData Catalog, метаданных Iceberg в файловой системе, и данных в файловой системе.

  4. View — виртуальное представление Iceberg, принадлежащее namespace. Состоит из системной записи в CedrusData Catalog и метаданных Iceberg в файловой системе.

В типичном сценарии, пользователи работают с объектами namespace, table и view через протокол Iceberg REST Catalog посредством вычислительного движка (CedrusData, Apache Spark, и т.д.), а администраторы каталога создают и изменяют объекты catalog через утилиту командной строки.

Аутентификация#

CedrusData поддерживает аутентификацию через OAuth2 client credentials flow (свойство credential) и Bearer-токен (свойство token).

OAuth2 аутентификация#

Аутентификация в каталоге возможна через OAuth2 client credentials flow. Для этого в клиента Iceberg REST Catalog необходимо передать параметр credential. Данный параметр представляет собой пару значений client_id:client_secret. В CedrusData Catalog роль этой пары значений выполняет постоянный токен доступа, который вы можете получить с помощью команды access-token create.

Используйте аутентификацию через OAuth2 client credentials flow, если у вас есть системный пользователь, которому необходимо аутентифицировать других пользователей. Например, этот вариант подходит для работы с каталогом из CedrusData или Trino, в конфигурации которых задан credential системного пользователя, а операции над каталогом совершают другие пользователи.

Последовательность событий:

  1. Движок отправляет в CedrusData Catalog значение credential и имя пользователя, которого необходимо аутентифицировать. Пользователь, который владеет постоянным токеном, называется actor. Пользователь, которого необходимо аутентифицировать, называется subject. Actor и subject могут быть одним и тем же пользователем.

  2. Каталог проверяет, что credential (то есть постоянный токен доступа) зарегистрирован в системе, и его владелец (actor) активен. Если постоянный токен доступа не найден или его владелец деактивирован, каталог вернет ошибку.

  3. Каталог проверяет, что пользователь, для которого запрошена аутентификация (subject) активен. Каталог вернет ошибку, если actor не имеет привилегии на создание временных токенов (access-token.create-temporary), или если subject деактивирован.

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

  5. Движок может запросить создание нового временного токена доступа для пользователя, если время жизни временного токен подходит к концу. Для этого движок отправляет в CedrusData Catalog текущий временный токен, а движок возвращает новый временный токен. Продление возможно, только если пользователь (subject) имеет привилегию на создание временных токенов (access-token.create-temporary).

Разные движки предлагают различные способы передачи параметра credential:

  • CedrusData: параметр каталога Iceberg iceberg.rest-catalog.oauth2.credential

  • Trino: параметр каталога Iceberg iceberg.rest-catalog.oauth2.credential

  • Apache Spark: параметр сессии spark.sql.catalog.<имя_каталога>.credential

  • Apache Flink: параметр каталога credential

Bearer аутентификация#

Аутентификация в каталоге возможна через Bearer токен. Для этого в клиента Iceberg REST Catalog необходимо передать параметр token. В CedrusData роль токена может выполнять постоянный или временный токены доступа, которые вы можете получить с помощью команд access-token create и access-token create-temporary.

Используйте аутентификацию через Bearer токен, если вам не нужно осуществлять имперсонацию других пользователей. Например, этот вариант аутентификации хорошо подойдет, для пользователей, запускающих задачи Apache Spark.

Разные движки предлагают различные способы передачи параметра token:

  • CedrusData: параметр каталога Iceberg iceberg.rest-catalog.oauth2.token

  • Trino: параметр каталога Iceberg iceberg.rest-catalog.oauth2.token

  • Apache Spark: параметр сессии spark.sql.catalog.<имя_каталога>.token

  • Apache Flink: параметр каталога token

Авторизация#

Каждый объект Iceberg имеет собственный набор привилегий. Для выполнения той или иной операции над объектом пользователь должен иметь соответствующую привилегию, назначенную ему посредством роли.

Интеграция с движками#