Registres de schémas pour Kafka ClickPipe

ClickPipes prend en charge l’intégration à un registre de schémas afin de décoder des valeurs d’enregistrement encodées en Avro et en Protobuf ainsi que des clés Kafka structurées.

Kafka ClickPipes prend en charge deux types de registres de schémas :

• Registres compatibles avec Confluent : tout registre compatible avec l’API de Confluent Schema Registry, notamment Confluent Schema Registry lui-même et Redpanda Schema Registry. Prend en charge Avro et Protobuf.
• AWS Glue Schema Registry : pour les données Avro sérialisées avec AWS Glue SerDe, généralement à partir d’Amazon MSK.

ClickPipes ne prend pas encore en charge Azure Schema Registry. Si vous souhaitez sa prise en charge, contactez notre équipe.

Pour intégrer un registre de schémas lors de la configuration de ClickPipes, vous devez utiliser l'une des approches suivantes :

1. Fournir un chemin complet vers le sujet du schéma (par ex. https://registry.example.com/subjects/events)
   • Vous pouvez également faire référence à une version spécifique en ajoutant /versions/[version] à l'URL (sinon, ClickPipes récupérera la version la plus récente).
2. Fournir un chemin complet vers l'ID de schéma (par ex. https://registry.example.com/schemas/ids/1000)
3. Fournir l'URL racine du registre de schémas (par ex. https://registry.example.com)

ClickPipes se connecte au registre de schémas en HTTPS à l’URL que vous fournissez. Le registre de schémas n’a pas besoin d’être accessible publiquement.

Si vos brokers Kafka sont accessibles via un reverse private endpoint (AWS PrivateLink ou GCP Private Service Connect), le registre de schémas peut utiliser la même connectivité privée. ClickPipes résout le hostname du registry via le private DNS du reverse private endpoint ; ainsi, un registry hébergé en privé aux côtés de vos brokers reste accessible tant que son hostname se résout vers les adresses IP privées du reverse private endpoint (via la prise en charge du private DNS de l’endpoint ou un DNS privé personnalisé).

Gardez les points suivants à l’esprit :

• L’URL du registre de schémas doit utiliser https://.
• Si le hostname du registry se résout vers une adresse privée, il doit être accessible via un reverse private endpoint sélectionné pour le ClickPipe ; sinon, la vérification de connectivité lors de la configuration échouera.

ClickPipes récupère et applique dynamiquement le schéma à partir du registre de schémas configuré.

• Si un ID de schéma est inclus dans la valeur de l’enregistrement, il sera utilisé pour récupérer le schéma.
• Si aucun ID de schéma n'est inclus dans la valeur de l’enregistrement, l'ID de schéma ou le nom du sujet spécifié dans la configuration du ClickPipe sera utilisé pour récupérer le schéma.
• Si la valeur de l’enregistrement est écrite sans ID de schéma inclus et qu'aucun ID de schéma ni nom du sujet n'est spécifié dans la configuration du ClickPipe, le schéma ne sera pas récupéré et le message sera ignoré, avec une SOURCE_SCHEMA_ERROR consignée dans la table d’erreurs de ClickPipes.
• Si la valeur de l’enregistrement n'est pas conforme au schéma, il sera ignoré, avec une DATA_PARSING_ERROR consignée dans la table d’erreurs de ClickPipes.
• Pour les schémas Protobuf uniquement : ClickPipes chargera tous les schémas importés définis comme dépendances. Les schémas Avro avec des références externes ne sont pas encore pris en charge.

Lorsque des correspondances pour des champs tels que _key.id sont configurées, ClickPipes résout l’ID de schéma inclus dans la clé Kafka indépendamment de la valeur de l’enregistrement. La clé peut utiliser un ID de schéma différent, mais elle doit utiliser la même famille de registres et le même format de sérialisation que la valeur. Les schémas de clé résolus sont mis en cache et les changements de schéma sont détectés automatiquement.

Si vos producteurs sérialisent des données Avro avec AWS SerDe Glue (par exemple, AWSKafkaAvroSerializer pour un topic Amazon MSK), ClickPipes peut résoudre ces schémas directement depuis AWS Glue Schema Registry. Glue utilise un format de sérialisation et une API différents de ceux des registres compatibles avec Confluent ; sa configuration est donc distincte.

La configuration d’AWS Glue Schema Registry est actuellement disponible uniquement via la console ClickHouse Cloud. Elle n’est pas prise en charge par l’API ClickPipes ni par le Terraform provider.

Dans l’assistant de création de ClickPipe, activez Registre de schémas à l’étape de connexion Kafka et définissez Type de registre sur AWS Glue :

Aucune URL de registre n’est à configurer. Chaque enregistrement produit par le SerDe Glue contient l’ID de sa propre version de schéma, que ClickPipes résout à l’aide de glue:GetSchemaVersion et met en cache, à raison d’un appel d’API par version de schéma distincte. L’évolution du schéma est gérée automatiquement : lorsque les enregistrements basculent vers une nouvelle version de schéma en cours de flux, celle-ci est résolue dès sa première occurrence.

Choisissez l'une des deux options en fonction de votre configuration. L'option A est la plus courante pour Amazon MSK.

Si votre Kafka ClickPipe s’authentifie déjà auprès de MSK via IAM, ClickPipes utilise la même identité IAM pour lire le registre. Laissez le champ ARN du rôle IAM vide et ajoutez l’instruction suivante aux autorisations de l’identité :

• Rôle IAM : ajoutez l’instruction à la stratégie d’autorisations du rôle configuré pour MSK.
• Identifiants IAM : ajoutez l’instruction à la stratégie d’autorisations du principal IAM associé à la clé d’accès.

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

Pour l’authentification basée sur les rôles, aucune modification de la stratégie d’approbation n’est nécessaire : la relation d’approbation configurée pour MSK couvre déjà cet accès. Les identifiants IAM n’utilisent pas de stratégie d’approbation de rôle.

Utilisez cette option lorsque votre broker ne s’authentifie pas via IAM (SASL/SCRAM, SASL/PLAIN, mTLS) ou lorsque le registre se trouve dans un compte AWS différent de celui du broker.

Obtenir l’ARN du rôle IAM du service ClickHouse

Ouvrez le service, sélectionnez l’onglet Paramètres, faites défiler jusqu’à la section Informations de sécurité réseau, puis copiez la valeur ID du rôle de service (IAM), un ARN au format arn:aws:iam::123456789012:role/CH-S3-example-service-Role. Cette valeur est désignée ci-dessous par {ClickHouse_IAM_ARN}. Chaque service ClickHouse déployé sur AWS possède son propre rôle ; cette valeur est donc différente pour chaque service.

Créer le rôle IAM du registre

Créez un rôle IAM dans votre compte AWS. Le nom du rôle doit commencer par ClickHouseAccessRole-.

Configurez la stratégie d’approbation

Remplacez {ClickHouse_IAM_ARN} par la valeur de l’étape précédente.

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

Configurez la stratégie d’autorisation

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

Configurer le ClickPipe

Collez l’ARN du nouveau rôle dans le champ ARN du rôle IAM de l’assistant.

• Avro uniquement. JSON Schema et Protobuf via le SerDe Glue ne sont pas pris en charge.
• Sources Kafka uniquement. Les ClickPipes Kinesis ne peuvent pas utiliser de registry Glue.

Les règles suivantes s'appliquent aux registres compatibles avec Confluent ainsi qu'à AWS Glue Schema Registry. Elles régissent le mappage entre le schéma de valeur récupéré et la table de destination ClickHouse, et s'appliquent également aux champs d'enregistrement ou de message mappés à partir de clés structurées portant le préfixe _key. :

• Si le schéma contient un champ qui n'est pas inclus dans le mappage de destination ClickHouse, ce champ est ignoré.
• S'il manque au schéma un champ défini dans le mappage de destination ClickHouse, la colonne ClickHouse sera renseignée avec une valeur « zéro », telle que 0 ou une chaîne vide. Notez que les expressions DEFAULT ne sont pas prises en charge.
• Si le champ du schéma et la colonne ClickHouse sont incompatibles, l'insertion de cette ligne/de ce message échouera, et l'échec sera enregistré dans la table d’erreurs de ClickPipes. Notez que plusieurs conversions implicites sont prises en charge (par exemple, entre types numériques), mais pas toutes (par exemple, un champ d'enregistrement Avro ne peut pas être inséré dans une colonne ClickHouse Int32).