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.

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.

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

1. 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).
2. Proporcione una ruta completa al ID del esquema (p. ej., https://registry.example.com/schemas/ids/1000)
3. Proporcione la URL raíz del registro de esquemas (p. ej., https://registry.example.com)

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á.

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.

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.

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:

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.

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

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.

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.

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 confianza

Reemplace {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.

• 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.

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).