[Документация Yandex Cloud](../../../index.md) > [Yandex Cloud Stackland](../../index.md) > Концепции > [Компоненты](overview.md) > Iceberg REST Catalog

# Iceberg REST Catalog {#rest-catalog}

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

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

## Каталог {#catalog}

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

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

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

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

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

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

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

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

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

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

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

## Пользователи каталога {#principals}

Пользователь каталога описывается ресурсом `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}

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

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

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

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

## Адреса подключения {#endpoints}

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

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

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

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

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

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