Registros de esquemas para Kafka ClickPipe

ClickPipes permite la integración con un registro de esquemas para decodificar valores de registros codificados con Avro y Protobuf y claves estructuradas de Kafka.

Registros compatibles con Kafka ClickPipes

Kafka ClickPipes admite dos familias de registros de esquemas:

Registros compatibles con Confluent: cualquier registro compatible con la API de Confluent Schema Registry, como el propio Confluent Schema Registry y Redpanda Schema Registry. Admite Avro y Protobuf.
AWS Glue Schema Registry: para datos Avro serializados con AWS Glue SerDe, normalmente procedentes de Amazon MSK.

ClickPipes aún no admite Azure Schema Registry. Si necesita compatibilidad con este servicio, póngase en contacto con nuestro equipo.

Registros compatibles con Confluent

Configuración

Para integrar ClickPipes con un registro de esquemas durante la configuración, debe usar una de las siguientes opciones:

Proporcione una ruta completa al subject del esquema (p. ej., https://registry.example.com/subjects/events)
- Opcionalmente, puede hacer referencia a una versión específica agregando /versions/[version] a la URL (de lo contrario, ClickPipes recuperará la versión más reciente).
Proporcione una ruta completa al ID del esquema (p. ej., https://registry.example.com/schemas/ids/1000)
Proporcione la URL raíz del registro de esquemas (p. ej., https://registry.example.com)

Conectividad de red

ClickPipes se conecta al registro de esquemas por HTTPS en la URL que proporciones. El registro de esquemas no necesita ser accesible públicamente. Si accedes a los brókeres de Kafka mediante un endpoint privado inverso (AWS PrivateLink o GCP Private Service Connect), el registro de esquemas puede usar la misma conectividad privada. ClickPipes resuelve el nombre de host del registro a través del DNS privado del endpoint privado inverso, por lo que un registro alojado de forma privada junto con tus brókeres será accesible siempre que su nombre de host se resuelva en las direcciones IP privadas del endpoint privado inverso (mediante el soporte de DNS privado del endpoint o una correspondencia de DNS privado personalizada). Ten en cuenta lo siguiente:

La URL del registro de esquemas debe usar https://.
Si el nombre de host del registro se resuelve en una dirección privada, debe ser accesible a través de un endpoint privado inverso seleccionado para el ClickPipe; de lo contrario, la comprobación de conectividad durante la configuración fallará.

Cómo funciona

ClickPipes recupera y aplica dinámicamente el esquema desde el registro de esquemas configurado.

Si el valor del registro incluye un ID de esquema, se usará para recuperar el esquema.
Si el valor del registro no incluye un ID de esquema, se usará el ID de esquema o el nombre del subject especificado en la configuración de ClickPipe para recuperar el esquema.
Si el valor del registro se escribe sin un ID de esquema incrustado y en la configuración de ClickPipe no se especifica ningún ID de esquema ni nombre de subject, el esquema no se recuperará y el mensaje se omitirá; se registrará un SOURCE_SCHEMA_ERROR en la tabla de errores de ClickPipes.
Si el valor del registro no se ajusta al esquema, se omitirá y se registrará un DATA_PARSING_ERROR en la tabla de errores de ClickPipes.
Solo para esquemas Protobuf: ClickPipes cargará todos los esquemas importados definidos como dependencias. Los esquemas Avro con referencias externas aún no son compatibles.

Cuando se configuran correspondencias para campos como _key.id, ClickPipes resuelve el ID de esquema incrustado en la clave de Kafka independientemente del valor del registro. La clave puede usar un ID de esquema diferente, pero debe usar la misma familia de registros de esquemas y formato de serialización que el valor. Los esquemas de clave resueltos se almacenan en caché y los cambios de esquema se detectan automáticamente.

AWS Glue Schema Registry

Si sus productores serializan datos Avro con AWS Glue SerDe (por ejemplo, AWSKafkaAvroSerializer en un topic de Amazon MSK), ClickPipes puede resolver esos esquemas directamente desde AWS Glue Schema Registry. Glue utiliza un formato wire y una API distintos de los registros compatibles con Confluent, por lo que se configura por separado. Actualmente, la configuración de AWS Glue Schema Registry solo está disponible a través de la consola de ClickHouse Cloud. No es compatible con la API de ClickPipes ni con el Terraform provider.

Solo Avro. Los registros de AWS Glue solo son compatibles con el formato Avro. Glue SerDe también puede encapsular JSON y Protobuf, pero ClickPipes no los admite y se rechazan al crear el pipe.

Configuración

En el asistente para crear un ClickPipe, habilite Registro de esquemas en el paso de conexión de Kafka y establezca Tipo de registro en AWS Glue:

Campo	Obligatorio	Descripción	Ejemplo
Tipo de registro	Sí	Seleccione AWS Glue	`AWS Glue`
Región de AWS	Sí	Región donde se encuentra el registro de Glue. Debe coincidir exactamente con la región del registro.	`us-east-1`
Nombre del registro	Sí	Nombre del registro de Glue. Se rechazan los esquemas que se resuelven en un registro diferente, por lo que cualquier error tipográfico se detectará cuando ClickPipes resuelva una versión de esquema.	`my-glue-registry`
ARN del rol de IAM	Condicional	Un rol dedicado para acceder al registro. Es opcional si su broker usa autenticación de IAM; de lo contrario, es obligatorio.	`arn:aws:iam::123456789012:role/ClickHouseAccessRole-glue`

No hay ninguna URL de registro que configurar. Cada registro generado por Glue SerDe incluye el ID de su propia versión de esquema, que ClickPipes resuelve mediante glue:GetSchemaVersion y almacena en caché, con una llamada a la API por cada versión de esquema distinta. La evolución del esquema se gestiona automáticamente: cuando los registros cambian a una nueva versión de esquema a mitad del flujo, esta se resuelve la primera vez que se encuentra.

Configuración de IAM

Use la opción que mejor se adapte a su configuración. La opción A es la más habitual para Amazon MSK.

Opción A: reutilizar la identidad de IAM del broker

Si tu Kafka ClickPipe ya se autentica en MSK mediante IAM, ClickPipes utiliza la misma identidad de IAM para leer el registro. Deja vacío el campo ARN del rol de IAM y añade la siguiente instrucción a los permisos de la identidad:

Rol de IAM: Añade la instrucción a la política de permisos del rol configurado para MSK.
Credenciales de IAM: Añade la instrucción a la política de permisos del principal de IAM asociado a la clave de acceso.

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

Para la autenticación basada en roles, no es necesario modificar la política de confianza; la relación de confianza configurada para MSK ya permite este acceso. Las credenciales de IAM no utilizan una política de confianza de roles.

Opción B: usar un rol dedicado para el registro

Use esta opción si su broker no se autentica con IAM (SASL/SCRAM, SASL/PLAIN, mTLS) o si el registro se encuentra en una cuenta de AWS distinta de la del broker.

Solo para implementaciones en AWS. Esta opción requiere un servicio de ClickHouse Cloud desplegado en AWS, ya que depende del rol de AWS IAM del servicio. Si su servicio se ejecuta en GCP o Azure y el broker no usa autenticación de IAM, no podrá configurar un rol dedicado para el registro.

Obtenga el ARN del rol de IAM del servicio de ClickHouse

Abra el servicio, seleccione la pestaña Settings, desplácese hasta la sección Network security information y copie el valor de Service role ID (IAM), un ARN con el formato arn:aws:iam::123456789012:role/CH-S3-example-service-Role. En adelante, se hará referencia a este valor como {ClickHouse_IAM_ARN}. Cada servicio de ClickHouse desplegado en AWS tiene su propio rol, por lo que este valor es distinto para cada servicio.

Cree el rol de IAM del registro

Cree un rol de IAM en su cuenta de AWS. El nombre del rol debe comenzar por ClickHouseAccessRole-.Configure la política de confianzaReemplace {ClickHouse_IAM_ARN} por el valor del paso anterior.

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

Configure la política de permisos

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

Configure el ClickPipe

Pegue el ARN del nuevo rol en el campo ARN del rol de IAM del asistente.

Ámbito de los recursos de IAM. Estos ejemplos siguen la política documentada por AWS para deserializadores y la política administrada AWSGlueSchemaRegistryReadonlyAccess, que otorgan glue:GetSchemaVersion sobre "*". ClickPipes comprueba de forma independiente cada esquema resuelto con el Nombre del registro configurado y rechaza las versiones de cualquier otro registro.

Solución de problemas

Error	Causa y solución
`access denied retrieving schema version …: check the IAM role grants glue:GetSchemaVersion`	A la identidad de IAM utilizada para acceder al registro le falta el permiso `glue:GetSchemaVersion`. En el acceso basado en roles, es posible que la política de confianza del rol tampoco incluya el ID de rol de su servicio. Vuelva a comprobar la configuración de IAM anterior.
`… is not authorized to perform: sts:AssumeRole on resource: …`	La política de confianza especifica el principal incorrecto. El error incluye el rol exacto que intentó asumir el rol. Use ese valor en la política de confianza.
`schema version … not found in Glue schema registry`	Los registros hacen referencia a una versión de esquema que no existe en la cuenta o región configurada. Confirme que la región de AWS coincida con la región del registro.
`schema version … belongs to Glue registry "X", but the pipe is configured for registry "Y"`	Sus productores registran esquemas en un registro distinto del indicado por el pipe. Corrija el nombre del registro o dirija los productores al registro correcto.
`the AWS Glue schema registry only supports the Avro format`	Los pipes de Glue solo admiten Avro. JSON y Protobuf mediante Glue SerDe no son compatibles.

Limitaciones

Solo se admite Avro. JSON Schema y Protobuf a través de Glue SerDe no son compatibles.
Solo fuentes de Kafka. Los ClickPipes de Kinesis no pueden usar un registro de Glue.

Mapeo de esquemas

Las siguientes reglas se aplican tanto a los registros compatibles con Confluent como a AWS Glue Schema Registry. Rigen el mapeo entre el esquema de valores obtenido y la tabla de destino de ClickHouse, y también se aplican a los campos de registros o mensajes mapeados desde claves estructuradas con el prefijo _key.:

Si el esquema contiene un campo que no está incluido en el mapeo de destino de ClickHouse, ese campo se ignora.
Si al esquema le falta un campo definido en el mapeo de destino de ClickHouse, la columna de ClickHouse se rellenará con un valor “cero”, como 0 o una cadena vacía. Tenga en cuenta que las expresiones DEFAULT no son compatibles.
Si el campo del esquema y la columna de ClickHouse son incompatibles, las inserciones de esa fila o mensaje fallarán, y el error se registrará en la tabla de errores de ClickPipes. Tenga en cuenta que se admiten varias conversiones implícitas (p. ej., entre tipos numéricos), pero no todas (p. ej., un campo de tipo registro de Avro no puede insertarse en una columna Int32 de ClickHouse).

ClickPipes para almacenamiento de objetos

ClickPipes para Postgres

ClickPipes para Kafka

ClickPipes para Kinesis

ClickPipes para GCP Pub/Sub

ClickPipes para MySQL

ClickPipes para MongoDB

ClickPipes para BigQuery

Acceso programático

Redes

Otros

Registros de esquemas para Kafka ClickPipe

Registros compatibles con Kafka ClickPipes

Registros compatibles con Confluent

Configuración

Conectividad de red

Cómo funciona

AWS Glue Schema Registry

Configuración

Configuración de IAM

Opción A: reutilizar la identidad de IAM del broker

Opción B: usar un rol dedicado para el registro

Solución de problemas

Limitaciones

Mapeo de esquemas

​Registros compatibles con Kafka ClickPipes

​Registros compatibles con Confluent

​Configuración

​Conectividad de red

​Cómo funciona

​AWS Glue Schema Registry

​Configuración

​Configuración de IAM

​Opción A: reutilizar la identidad de IAM del broker

​Opción B: usar un rol dedicado para el registro

​Solución de problemas

​Limitaciones

​Mapeo de esquemas

Registros compatibles con Kafka ClickPipes

Registros compatibles con Confluent

Configuración

Conectividad de red

Cómo funciona

AWS Glue Schema Registry

Configuración

Configuración de IAM

Opción A: reutilizar la identidad de IAM del broker

Opción B: usar un rol dedicado para el registro

Solución de problemas

Limitaciones

Mapeo de esquemas