Iceberg REST Catalog

Iceberg REST Catalog — это REST-каталог для таблиц Apache Iceberg™, совместимый с Iceberg REST Catalog API. Компонент позволяет управлять каталогами, пространствами имен таблиц и доступом к данным. Для этого используются кастомные ресурсы:

• RestCatalog — для создания каталога Iceberg REST;
• RestCatalogPrincipal — для создания учетных записей доступа к Iceberg REST Catalog API.

КаталогКаталог

Каталог описывается ресурсом RestCatalog и определяет, где хранятся данные таблиц и какая модель доступа применяется. Оператор приводит фактическое состояние каталога к указанному в спецификации ресурса.

Каталог привязан к бакету Object Storage: параметр spec.stacklandStorage.bucketRef ссылается на существующий ресурс Bucket. Все разрешенные пути хранения из spec.allowedLocations должны находиться внутри этого бакета.

Основные параметры спецификации:

• allowedLocations — список S3-путей, где разрешено хранить данные таблиц. Нужно указать хотя бы один путь.
• stacklandStorage.bucketRef — имя бакета, в котором хранятся данные каталога.
• defaultBaseLocation — базовый путь по умолчанию для данных таблиц. Должен входить в allowedLocations. Если не задан, используется первый элемент allowedLocations.
• defaultNamespace — пространство имен по умолчанию для таблиц (массив сегментов пути).
• properties — дополнительные параметры каталога в формате «ключ — значение».
• deletionProtection — опциональная защита каталога от удаления. По умолчанию false. Если значение true, каталог нельзя удалить, пока флаг не будет снят.

Имя каталога совпадает с metadata.name ресурса RestCatalog. На кластере допускается не более одного каталога с заданным именем.

Группы пользователей и роли каталогаГруппы пользователей и роли каталога

Модель доступа каталога состоит из двух частей: групп пользователей и ролей каталога.

Группы пользователей задаются в параметре spec.declaredPrincipalRoles. Каждая группа — это имя роли, которой управляет оператор. Группы используются в ролях каталога и при назначении доступа учетным записям.

Роли каталога задаются в параметре spec.catalogRoles. Каждая роль определяет область охвата и набор привилегий для нее. Поддерживаются четыре типа охвата:

• catalog — привилегии на уровне всего каталога;
• namespace — привилегии на уровне пространства имен;
• table — привилегии на уровне таблицы;
• view — привилегии на уровне представления.

Роль каталога привязывается к одной или нескольким группам пользователей через параметр principalRoles. Имена в нем должны совпадать с именами из declaredPrincipalRoles.

Пользователи каталогаПользователи каталога

Пользователь каталога описывается ресурсом RestCatalogPrincipal и представляет учетную запись (principal) для доступа к Iceberg REST Catalog API по OAuth2.

Основные параметры спецификации:

• catalog — имя каталога, к которому привязан пользователь. Значение должно совпадать с metadata.name ресурса RestCatalog в том же проекте.
• principalRoles — список групп пользователей из declaredPrincipalRoles каталога. Нужно указать хотя бы одну группу.
• credentialsSecretRef — опциональная ссылка на Kubernetes Secret с учетными данными OAuth2. Если параметр не указан, секрет создастся автоматически, а в status.credentialsSecretName будет указано имя созданного секрета.

Учетные данные хранятся в Kubernetes Secret в двух полях: clientId и clientSecret. Идентификатор клиента clientId совпадает с именем учетной записи. Секрет клиента clientSecret используется при получении OAuth2-токена для доступа к Iceberg REST Catalog API.

СтатусыСтатусы

Текущее состояние каталога отражает поле status.phase ресурса RestCatalog:

• pending — каталог создается или ожидает зависимостей;
• ready — каталог готов к работе;
• failed — ошибка, требуется исправление конфигурации или внешних условий;
• deleting — каталог удаляется;
• pendingResources — каталог доступен, но в Iceberg еще нет нужных пространств имен, таблиц или представлений, поэтому выдача привилегий ролям отложена.

Текущее состояние пользователя каталога отражает поле status.phase ресурса RestCatalogPrincipal:

• pending — учетная запись создается или ожидает зависимостей;
• ready — учетная запись синхронизирована с каталогом;
• failed — ошибка, требуется исправление конфигурации или внешних условий;
• deleting — учетная запись удаляется;
• pendingResources — учетная запись ожидает роль, которая не объявлена в каталоге.

Адреса подключенияАдреса подключения

В статусе ресурса RestCatalog устанавливаются адреса для подключения клиентов.

Внутренние адреса:

• endpoint — внутренний URI Iceberg REST Catalog API;
• oauth2TokenEndpoint — адрес для получения OAuth2-токена по внутреннему адресу.

Внешние адреса появляются, только если для компонента настроен публичный доступ:

• externalEndpoint — публичный URI каталога;
• externalOAuth2TokenEndpoint — адрес для получения OAuth2-токена по внешнему адресу.

Публичный доступ включается в ресурсе IcebergRestCatalogConfig параметром spec.settings.rest-catalog.ingress.enabled: true.