> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Как интегрировать ClickPipes с реестром схем для управления схемами.
# Реестры схем для Kafka ClickPipe
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
ClickPipes поддерживает интеграцию с реестром схем для декодирования топиков в форматах Avro и Protobuf.
## Поддерживаемые реестры схем для Kafka ClickPipes
Kafka ClickPipes поддерживает два типа реестров схем:
* [Реестры, совместимые с Confluent](#confluent-compatible-registries): любые реестры, API которых совместим с Confluent Schema Registry, включая сам Confluent Schema Registry и Redpanda Schema Registry. Поддерживаются Avro и Protobuf.
* [AWS Glue Schema Registry](#aws-glue-schema-registry): для данных Avro, сериализованных с помощью AWS Glue SerDe, обычно поступающих из Amazon MSK.
ClickPipes пока не поддерживает Azure Schema Registry. Если вам нужна его поддержка, [свяжитесь с нашей командой](https://clickhouse.com/company/contact?loc=clickpipes).
## Реестры, совместимые с Confluent
### Конфигурация
Чтобы интегрироваться с реестром схем при настройке ClickPipes, необходимо использовать один из следующих способов:
1. Укажите полный путь к subject схемы (например, `https://registry.example.com/subjects/events`)
* При необходимости можно указать конкретную версию, добавив `/versions/[version]` к URL (в противном случае ClickPipes получит последнюю версию).
2. Укажите полный путь к ID схемы (например, `https://registry.example.com/schemas/ids/1000`)
3. Укажите корневой URL реестра схем (например, `https://registry.example.com`)
### Сетевое подключение
ClickPipes подключается к реестру схем по HTTPS, используя указанный вами URL. Реестр схем не обязательно должен быть общедоступным.
Если доступ к вашим брокерам Kafka осуществляется через [обратную частную конечную точку](/docs/ru/integrations/clickpipes/networking/aws-privatelink) (AWS PrivateLink или GCP Private Service Connect), реестр схем может использовать то же частное подключение. ClickPipes разрешает имя хоста реестра через private DNS обратной частной конечной точки, поэтому реестр, размещённый в частной сети рядом с вашими брокерами, будет доступен, если его имя хоста разрешается в частные IP-адреса обратной частной конечной точки (через поддержку private DNS этой конечной точки или через [пользовательское сопоставление private DNS](/docs/ru/integrations/clickpipes/networking/aws-privatelink#custom-private-dns)).
Имейте в виду следующее:
* URL реестра схем должен использовать `https://`.
* Если имя хоста реестра разрешается в частный адрес, он должен быть доступен через обратную частную конечную точку, выбранную для ClickPipe; в противном случае проверка подключения на этапе настройки завершится ошибкой.
### Как это работает
ClickPipes динамически получает и применяет схему из настроенного реестра схем.
* Если в сообщении есть встроенный ID схемы, он будет использован для получения схемы.
* Если в сообщении нет встроенного ID схемы, для получения схемы будет использован ID схемы или имя subject, указанные в конфигурации ClickPipe.
* Если сообщение записано без встроенного ID схемы и в конфигурации ClickPipe не указан ни ID схемы, ни имя subject, схема не будет получена, а сообщение будет пропущено; в таблицу ошибок ClickPipes будет записана ошибка `SOURCE_SCHEMA_ERROR`.
* Если сообщение не соответствует схеме, оно будет пропущено; в таблицу ошибок ClickPipes будет записана ошибка `DATA_PARSING_ERROR`.
* Только для схем Protobuf: ClickPipes загрузит все импортированные схемы, указанные как зависимости. Схемы Avro с внешними ссылками пока не поддерживаются.
## AWS Glue Schema Registry
Если ваши producer сериализуют Avro с помощью AWS Glue SerDe (например, `AWSKafkaAvroSerializer` для топика Amazon MSK), ClickPipes может получать эти схемы непосредственно из AWS Glue Schema Registry. Glue использует другой формат передачи данных и другой API, чем реестры, совместимые с Confluent, поэтому настраивается отдельно.
Настройка AWS Glue Schema Registry в настоящее время доступна только в консоли ClickHouse Cloud. Через API ClickPipes или Terraform-провайдер она не поддерживается.
**Только Avro.** Реестры AWS Glue поддерживаются только для формата Avro. Glue SerDe также может формировать JSON и Protobuf, но ClickPipes их не поддерживает и отклоняет при создании пайпа.
### Конфигурация
В мастере создания ClickPipe на шаге подключения Kafka включите **Реестр схем** и установите для параметра **Тип реестра** значение **AWS Glue**:
| Поле | Обязательно | Описание | Пример |
| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Тип реестра | Да | Выберите **AWS Glue** | `AWS Glue` |
| Регион AWS | Да | Регион, в котором расположен реестр Glue. Должен в точности совпадать с регионом реестра. | `us-east-1` |
| Имя реестра | Да | Имя реестра Glue. Схемы из другого реестра отклоняются, поэтому опечатка будет выявлена при разрешении ClickPipes версии схемы. | `my-glue-registry` |
| ARN роли IAM | Условно | Выделенная роль для доступа к реестру. Необязательна, если ваш брокер использует аутентификацию IAM; в противном случае обязательна. | `arn:aws:iam::123456789012:role/ClickHouseAccessRole-glue` |
URL реестра настраивать не требуется. Каждая запись, созданная Glue SerDe, содержит идентификатор своей версии схемы, который ClickPipes получает с помощью `glue:GetSchemaVersion` и кэширует; для каждой уникальной версии схемы выполняется один вызов API. Изменение схемы обрабатывается автоматически: если записи в потоке переключаются на новую версию схемы, она будет получена при первом обращении.
### Настройка IAM
Выберите один из двух вариантов в зависимости от вашей конфигурации. Вариант A обычно используется для Amazon MSK.
#### Вариант A: использовать IAM-идентичность брокера
Если ваш Kafka ClickPipe уже аутентифицируется в MSK с помощью IAM, ClickPipes использует ту же IAM-идентичность для чтения реестра. Оставьте поле **ARN роли IAM** пустым и добавьте следующий оператор в разрешения этой идентичности:
* **Роль IAM:** Добавьте оператор в политику разрешений роли, настроенной для MSK.
* **Учетные данные IAM:** Добавьте оператор в политику разрешений субъекта IAM, связанного с ключом доступа.
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ClickPipesGlueSchemaRegistryRead",
"Effect": "Allow",
"Action": ["glue:GetSchemaVersion"],
"Resource": "*"
}
]
}
```
Для аутентификации на основе ролей изменять политику доверия не требуется: отношение доверия, настроенное для MSK, уже предусматривает этот доступ. Учетные данные IAM не используют политику доверия.
#### Вариант B: использование отдельной роли для реестра
Используйте этот вариант, если ваш брокер не использует аутентификацию IAM (SASL/SCRAM, SASL/PLAIN, mTLS) или если реестр находится в другом аккаунте AWS, чем брокер.
**Только для развертываний в AWS.** Для этого варианта требуется сервис ClickHouse Cloud, развернутый в AWS, поскольку он использует роль AWS IAM сервиса. Если ваш сервис работает в GCP или Azure, а брокер не использует аутентификацию IAM, настроить отдельную роль для реестра не получится.
Откройте сервис, перейдите на вкладку **Settings**, прокрутите до раздела **Network security information** и скопируйте значение **Service role ID (IAM)** — ARN вида `arn:aws:iam::123456789012:role/CH-S3-example-service-Role`. Далее оно обозначается как `{ClickHouse_IAM_ARN}`. У каждого сервиса ClickHouse, развернутого в AWS, есть собственная роль, поэтому это значение отличается для каждого сервиса.
Создайте роль IAM в своем аккаунте AWS. Имя роли **должно начинаться с** `ClickHouseAccessRole-`.
**Настройте политику доверия**
Замените `{ClickHouse_IAM_ARN}` значением из предыдущего шага.
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "{ClickHouse_IAM_ARN}"
},
"Action": "sts:AssumeRole"
}
]
}
```
**Настройте политику разрешений**
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ClickPipesGlueSchemaRegistryRead",
"Effect": "Allow",
"Action": ["glue:GetSchemaVersion"],
"Resource": "*"
}
]
}
```
Вставьте ARN новой роли в поле **ARN роли IAM** мастера.
**Область действия IAM-ресурсов.** Эти примеры соответствуют [документированной AWS политике для десериализаторов](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-gs-serde.html) и ее [управляемой политике `AWSGlueSchemaRegistryReadonlyAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSGlueSchemaRegistryReadonlyAccess.html), обе из которых предоставляют разрешение `glue:GetSchemaVersion` для `"*"`. ClickPipes независимо проверяет каждую разрешенную схему на соответствие настроенному вами **Имя реестра** и отклоняет версии из любых других реестров.
### Устранение неполадок
| Ошибка | Причина и решение |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access denied retrieving schema version …: check the IAM role grants glue:GetSchemaVersion` | У идентификатора IAM, используемого для доступа к реестру, отсутствует привилегия `glue:GetSchemaVersion`. При ролевом доступе в политике доверия роли также может не быть указан идентификатор роли вашего сервиса. Ещё раз проверьте настройку IAM выше. |
| `… is not authorized to perform: sts:AssumeRole on resource: …` | В политике доверия указан неверный субъект. В ошибке указана точная роль, которая попыталась принять роль. Используйте это значение в политике доверия. |
| `schema version … not found in Glue schema registry` | Записи ссылаются на версию схемы, которой нет в настроенном аккаунте или регионе. Убедитесь, что **регион AWS** совпадает с регионом реестра. |
| `schema version … belongs to Glue registry "X", but the pipe is configured for registry "Y"` | Ваши producer регистрируют схемы в реестре, отличающемся от указанного для пайпа. Исправьте **Имя реестра** или настройте producer на правильный реестр. |
| `the AWS Glue schema registry only supports the Avro format` | Пайпы Glue поддерживают только формат Avro. JSON и Protobuf через Glue SerDe не поддерживаются. |
### Ограничения
* Поддерживается только Avro. JSON Schema и Protobuf через Glue SerDe не поддерживаются.
* Поддерживаются только источники Kafka. ClickPipes для Kinesis не могут использовать реестр Glue.
## Сопоставление схемы
Следующие правила применяются как к Confluent-совместимым реестрам, так и к AWS Glue Schema Registry. Они регулируют сопоставление между полученной схемой и целевой таблицей ClickHouse:
* Если схема содержит поле, которое отсутствует в сопоставлении с целевой таблицей ClickHouse, это поле игнорируется.
* Если в схеме отсутствует поле, определённое в сопоставлении с целевой таблицей ClickHouse, соответствующий столбец ClickHouse будет заполнен "нулевым" значением, например 0 или пустой строкой. Обратите внимание, что выражения `DEFAULT` не поддерживаются.
* Если поле схемы и столбец ClickHouse несовместимы, вставка этой строки/сообщения завершится ошибкой, и ошибка будет записана в таблицу ошибок ClickPipes. Обратите внимание, что поддерживаются некоторые неявные преобразования (например, между числовыми типами), но не все (например, поле записи Avro нельзя вставить в столбец ClickHouse типа `Int32`).