Реестры схем для Kafka ClickPipe

ClickPipes поддерживает интеграцию с реестром схем для декодирования значений записей, закодированных в Avro и Protobuf, а также структурированных ключей Kafka.

Поддерживаемые реестры схем для Kafka ClickPipes

Kafka ClickPipes поддерживает два типа реестров схем:

Реестры, совместимые с Confluent: любые реестры, API которых совместим с Confluent Schema Registry, включая сам Confluent Schema Registry и Redpanda Schema Registry. Поддерживаются Avro и Protobuf.
AWS Glue Schema Registry: для данных Avro, сериализованных с помощью AWS Glue SerDe, обычно поступающих из Amazon MSK.

ClickPipes пока не поддерживает Azure Schema Registry. Если вам нужна его поддержка, свяжитесь с нашей командой.

Реестры, совместимые с Confluent

Конфигурация

Чтобы интегрироваться с реестром схем при настройке ClickPipes, необходимо использовать один из следующих способов:

Укажите полный путь к subject схемы (например, https://registry.example.com/subjects/events)
- При необходимости можно указать конкретную версию, добавив /versions/[version] к URL (в противном случае ClickPipes получит последнюю версию).
Укажите полный путь к ID схемы (например, https://registry.example.com/schemas/ids/1000)
Укажите корневой URL реестра схем (например, https://registry.example.com)

Сетевое подключение

ClickPipes подключается к реестру схем по HTTPS, используя указанный вами URL. Реестр схем не обязательно должен быть общедоступным. Если доступ к вашим брокерам Kafka осуществляется через обратную частную конечную точку (AWS PrivateLink или GCP Private Service Connect), реестр схем может использовать то же частное подключение. ClickPipes разрешает имя хоста реестра через private DNS обратной частной конечной точки, поэтому реестр, размещённый в частной сети рядом с вашими брокерами, будет доступен, если его имя хоста разрешается в частные IP-адреса обратной частной конечной точки (через поддержку private DNS этой конечной точки или через пользовательское сопоставление private DNS). Имейте в виду следующее:

URL реестра схем должен использовать https://.
Если имя хоста реестра разрешается в частный адрес, он должен быть доступен через обратную частную конечную точку, выбранную для ClickPipe; в противном случае проверка подключения на этапе настройки завершится ошибкой.

Как это работает

ClickPipes динамически получает и применяет схему из настроенного реестра схем.

Если во value записи есть встроенный ID схемы, он будет использован для получения схемы.
Если во value записи нет встроенного ID схемы, для получения схемы будет использован ID схемы или имя subject, указанные в конфигурации ClickPipe.
Если value записи записано без встроенного ID схемы и в конфигурации ClickPipe не указан ни ID схемы, ни имя subject, схема не будет получена, а сообщение будет пропущено; в таблицу ошибок ClickPipes будет записана ошибка SOURCE_SCHEMA_ERROR.
Если value записи не соответствует схеме, оно будет пропущено; в таблицу ошибок ClickPipes будет записана ошибка DATA_PARSING_ERROR.
Только для схем Protobuf: ClickPipes загрузит все импортированные схемы, указанные как зависимости. Схемы Avro с внешними ссылками пока не поддерживаются.

Когда настроены сопоставления для таких полей, как _key.id, ClickPipes независимо от value записи определяет ID схемы, встроенный в ключ Kafka. Ключ может использовать другой ID схемы, но должен использовать то же семейство реестров и формат сериализации, что и value. Полученные схемы ключей кэшируются, а изменения схемы обнаруживаются автоматически.

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, связанного с ключом доступа.

{
  "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, настроить отдельную роль для реестра не получится.

Получите ARN роли IAM сервиса ClickHouse

Откройте сервис, перейдите на вкладку 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 для реестра

Создайте роль IAM в своем аккаунте AWS. Имя роли должно начинаться с ClickHouseAccessRole-.Настройте политику доверияЗамените {ClickHouse_IAM_ARN} значением из предыдущего шага.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "{ClickHouse_IAM_ARN}"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Настройте политику разрешений

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClickPipesGlueSchemaRegistryRead",
      "Effect": "Allow",
      "Action": ["glue:GetSchemaVersion"],
      "Resource": "*"
    }
  ]
}

Настройте ClickPipe

Вставьте ARN новой роли в поле ARN роли IAM мастера.

Область действия IAM-ресурсов. Эти примеры соответствуют документированной AWS политике для десериализаторов и ее управляемой политике AWSGlueSchemaRegistryReadonlyAccess, обе из которых предоставляют разрешение 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, а также применяются к полям записей или сообщений, сопоставленным из структурированных ключей с префиксом _key.:

Если схема содержит поле, которое отсутствует в сопоставлении с целевой таблицей ClickHouse, это поле игнорируется.
Если в схеме отсутствует поле, определённое в сопоставлении с целевой таблицей ClickHouse, соответствующий столбец ClickHouse будет заполнен “нулевым” значением, например 0 или пустой строкой. Обратите внимание, что выражения DEFAULT не поддерживаются.
Если поле схемы и столбец ClickHouse несовместимы, вставка этой строки/сообщения завершится ошибкой, и ошибка будет записана в таблицу ошибок ClickPipes. Обратите внимание, что поддерживаются некоторые неявные преобразования (например, между числовыми типами), но не все (например, поле записи Avro нельзя вставить в столбец ClickHouse типа Int32).

ClickPipes для объектного хранилища

ClickPipes для Postgres

ClickPipes для Kafka

ClickPipes для Kinesis

ClickPipes для GCP Pub/Sub

ClickPipes для MySQL

ClickPipes для MongoDB

ClickPipes для BigQuery

Программный доступ

Сеть

Другое

Реестры схем для Kafka ClickPipe

Поддерживаемые реестры схем для Kafka ClickPipes

Реестры, совместимые с Confluent

Конфигурация

Сетевое подключение

Как это работает

AWS Glue Schema Registry

Конфигурация

Настройка IAM

Вариант A: использовать IAM-идентичность брокера

Вариант B: использование отдельной роли для реестра

Устранение неполадок

Ограничения

Сопоставление схемы

​Поддерживаемые реестры схем для Kafka ClickPipes

​Реестры, совместимые с Confluent

​Конфигурация

​Сетевое подключение

​Как это работает

​AWS Glue Schema Registry

​Конфигурация

​Настройка IAM

​Вариант A: использовать IAM-идентичность брокера

​Вариант B: использование отдельной роли для реестра

​Устранение неполадок

​Ограничения

​Сопоставление схемы

Поддерживаемые реестры схем для Kafka ClickPipes

Реестры, совместимые с Confluent

Конфигурация

Сетевое подключение

Как это работает

AWS Glue Schema Registry

Конфигурация

Настройка IAM

Вариант A: использовать IAM-идентичность брокера

Вариант B: использование отдельной роли для реестра

Устранение неполадок

Ограничения

Сопоставление схемы