Gestion du cycle de vie des schémas

Preview

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

À mesure que vos applications et leurs exigences en termes de données évoluent, la structure de vos messages Kafka doit également s'adapter. Une gestion efficace du cycle de vie des schémas est essentielle pour gérer ces modifications en douceur et préserver l'intégrité des données. Ce processus implique non seulement de modifier les schémas, mais aussi de contrôler systématiquement les types de modifications qui sont sûrs ou suffisamment compatibles pour les applications qui en dépendent.

Le registre de schémas Managed Service pour Apache Kafka prend en charge l'intégralité du cycle de vie de la gestion des schémas et inclut les fonctionnalités suivantes :

• Définissez et appliquez des règles de compatibilité (type de compatibilité) pour gérer l'évolution des schémas lorsque de nouvelles versions sont introduites. Ces règles permettent de s'assurer que les producteurs et les consommateurs continuent de fonctionner correctement.

• Configurez des contrôles opérationnels (modes de schéma) pour gérer la mutabilité des schémas à différents niveaux, en protégeant vos pipelines de traitement des données.

• Gérez les références de schéma pour favoriser la réutilisation et la cohérence de vos schémas.

Fonctionnement de l'évolution du schéma

1. Vous modifiez la définition de votre schéma. Par exemple, ajoutez un champ facultatif à votre fichier .proto ou .avsc.

2. Un producteur configuré avec auto.register.schemas=true envoie un message à l'aide du nouveau schéma, ou vous tentez explicitement d'enregistrer le nouveau schéma à l'aide de l'API ou des bibliothèques clientes.

3. Lorsqu'une demande d'enregistrement pour une nouvelle version atteint le registre de schémas, elle récupère la règle de compatibilité configurée pour le sujet cible. Il compare le nouveau schéma proposé aux versions précédentes requises, conformément à cette règle.

4. Si la version du schéma est compatible, le nouveau schéma est enregistré en tant que prochaine version sous le sujet, et un nouveau numéro de version lui est attribué, ainsi qu'un nouvel schema_id si la définition est unique.

5. Le producteur (le cas échéant) reçoit le schema_id à inclure dans les messages.

6. Si la version du schéma est incompatible, la tentative d'enregistrement échoue et une erreur est renvoyée.

À propos du type de compatibilité

La compatibilité des schémas vous permet de définir la façon dont le registre de schémas gère les vérifications de compatibilité entre différentes versions de schémas. Vous pouvez appliquer ces configurations à différents niveaux de la hiérarchie du registre de schémas, comme indiqué par les options de modèle de ressource suivantes :

• Au niveau du registre : définit la configuration par défaut pour l'ensemble du registre de schémas.

  • Chemin d'accès : projects/project/locations/location/schemaRegistries/schema_registry/config

• Au niveau du sujet dans le contexte par défaut : définit une configuration spécifique pour un sujet dans le contexte par défaut du registre.

  • Chemin d'accès : projects/project/locations/location/schemaRegistries/schema_registry/config/subject

• Au niveau du sujet dans un contexte spécifique : définit une configuration spécifique pour un sujet dans un contexte nommé.

  • Chemin d'accès : projects/project/locations/location/schemaRegistries/schema_registry/contexts/context/config/subject

Les configurations définies au niveau du sujet remplacent celles définies au niveau du registre. Si un paramètre n'est pas spécifié au niveau du sujet, il hérite de la valeur du niveau du registre. Si elle n'est pas définie explicitement au niveau du registre, la valeur par défaut est Backward.

Les types disponibles suivants déterminent la façon dont le registre de schémas compare une nouvelle version de schéma aux précédentes :

• None : aucune vérification de compatibilité n'est effectuée. Autorise toute modification, mais présente un risque élevé de casser les clients.

• Backward (par défaut) : les applications grand public utilisant le nouveau schéma peuvent décoder les données produites avec uniquement le schéma précédemment enregistré. Cela permet d'ajouter des champs facultatifs et de supprimer des champs. Les consommateurs doivent être mis à niveau avant les producteurs.

• Backward_transitive : les applications grand public utilisant le nouveau schéma peuvent décoder les données produites avec toutes les versions précédentes du schéma dans ce sujet. Ce paramètre est plus strict que Backward.

• Forward : les données produites à l'aide du nouveau schéma doivent être lisibles par les clients utilisant le schéma enregistré précédent. Les producteurs doivent être mis à niveau en premier, mais il est possible que les consommateurs utilisant le nouveau schéma ne puissent pas lire les données produites avec des schémas encore plus anciens. Ce paramètre permet de supprimer des champs facultatifs et d'en ajouter.

• Forward_transitive : les données produites à l'aide du nouveau schéma doivent être lisibles à l'aide de toutes les versions précédentes du schéma. Ce paramètre est plus strict que Forward.

• Full : le nouveau schéma est rétrocompatible et compatible avec les versions ultérieures du schéma enregistré précédemment. Les clients peuvent être mis à niveau dans n'importe quel ordre par rapport au producteur à l'aide du nouveau schéma. Permet d'ajouter ou de supprimer des champs facultatifs.

• Full_transitive : le nouveau schéma est rétrocompatible et compatible avec toutes les versions précédentes du schéma dans ce sujet. Ce paramètre est plus strict que Full.

Exemple de type de compatibilité

Supposons que vous disposiez d'un registre de schémas avec un type de compatibilité Backward. Vous créez également plusieurs sujets dans ce registre, qui héritent de la compatibilité Backward du registre.

Pour un sujet spécifique nommé user-events, vous avez besoin de règles de compatibilité plus strictes. Vous mettez à jour le niveau de compatibilité du schéma pour le sujet user-events sur Full.

Dans ce cas, les règles suivantes s'appliquent :

• Toute nouvelle version de schéma enregistrée sous le sujet user-events doit être à la fois rétrocompatible et compatible avec la version de schéma précédemment enregistrée pour ce sujet.

• Les autres sujets du registre de schémas respectent toujours le paramètre de compatibilité Backward au niveau du registre, sauf si leur compatibilité a été explicitement configurée.

Si vous deviez modifier ultérieurement le niveau de compatibilité du registre de schémas sur Forward, cette modification affecterait la compatibilité par défaut de tous les nouveaux sujets créés dans le registre. Toutefois, le sujet user-events conserverait sa compatibilité Full définie explicitement, car les configurations au niveau du sujet remplacent celles au niveau du registre.

Cela montre comment vous pouvez avoir un niveau de compatibilité par défaut pour l'ensemble du registre tout en ayant la possibilité de définir des exigences de compatibilité spécifiques pour des sujets individuels en fonction des besoins de votre application.

Pour en savoir plus, consultez Mettre à jour le type de compatibilité.

Bonnes pratiques concernant le mode Compatibilité

• N'utilisez pas None comme stratégie de type de compatibilité, car vous risquez de casser les clients avec des modifications de schéma.

• Choisissez une stratégie basée sur l'avant, comme Forward ou Forward-transitive, si vous souhaitez mettre à jour les producteurs en premier. Choisissez une stratégie basée sur la compatibilité ascendante, comme Backward ou Backward-transitive, si vous souhaitez d'abord mettre à jour les consommateurs.

• Choisissez une stratégie transitive si vous souhaitez maintenir la compatibilité avec plusieurs versions précédentes du schéma. Si vous souhaitez maximiser la compatibilité et minimiser le risque de rupture des clients lors de la mise à jour des versions de schéma, utilisez la stratégie Full-transitive.

À propos des références de schéma

Les références de schéma vous permettent de définir des structures communes une seule fois et de les référencer à partir de plusieurs schémas. Par exemple, un schéma Address peut être utilisé dans un schéma Customer et un schéma Supplier.

Cette approche favorise la réutilisation et la cohérence de vos schémas. De plus, l'utilisation de références de schéma crée des dépendances claires, en suivant explicitement les schémas qui en dépendent d'autres. Cela améliore la facilité de maintenance de l'architecture de votre schéma.

Lorsqu'un schéma doit utiliser un autre schéma commun, il inclut une référence à ce schéma commun. Cette relation est formellement définie par une structure SchemaReference.

Un SchemaReference comporte les composants suivants :

• name (chaîne) : nom complet du schéma référencé pour les formats Avro ou nom de fichier d'un type importé pour les formats Protobuf, tel qu'il est utilisé dans la définition du schéma lui-même.

• subject (chaîne) : nom du sujet sous lequel le schéma référencé est enregistré dans le registre de schémas.

• version (int32) : numéro de version spécifique du schéma référencé.

Un schéma qui utilise d'autres schémas déclare ces dépendances dans un champ references. Ce champ contient une liste d'objets SchemaReference.

Exemple de références de schéma

Supposons que vous deviez définir des schémas pour les données Customer et Supplier, et que les deux doivent inclure une adresse. Les références de schéma vous permettent de définir la structure d'adresse une seule fois et de la réutiliser.

Pour suivre cet exemple, consultez Créer un sujet.

1. Créez un sujet nommé address_schema et enregistrez la définition d'une adresse standard. Lorsque vous créez un sujet pour la première fois, vous créez également la version 1 du schéma pour ce sujet.

   Avro

   Créez et stockez-le en tant que version 1 du sujet address_schema_avro.

   {
     "type": "record",
     "name": "Address",
     "namespace": "com.example.common",
     "fields": [
       {"name": "street", "type": "string"},
       {"name": "city", "type": "string"},
       {"name": "zipCode", "type": "string"},
       {"name": "country", "type": "string", "default": "USA"}
     ]
   }
   

   Protobuf

   Créez et stockez-le en tant que version 1 du sujet address_schema_proto.

   syntax = "proto3";
   
   package com.example.common;
   
   message Address {
     string street = 1;
     string city = 2;
     string zip_code = 3;
     string country = 4;
   }
   

2. Créez le schéma customer_schema. Au lieu de répéter les champs d'adresse, vous faites référence au schéma address_schema.

   Avro

   Le type com.example.common.Address du champ billingAddress fait référence au schéma Address défini à l'étape précédente.

   {
     "type": "record",
     "name": "Customer",
     "namespace": "com.example.crm",
     "fields": [
       {"name": "customerId", "type": "long"},
       {"name": "customerName", "type": "string"},
       // This field's type refers to the Address schema
       {"name": "billingAddress", "type": "com.example.common.Address"}
     ]
   }
   

   Lors de l'enregistrement de customer_schema_avro, ses métadonnées incluraient une référence de schéma :

   // Conceptual metadata for customer_schema_avro
   "references": [
     {
       "name": "com.example.common.Address",
       "subject": "address_schema_avro",
       "version": 1
     }
   ]
   

   Protobuf

   Le fichier customer.proto importe address.proto et utilise com.example.common.Address pour le champ billing_address.

   syntax = "proto3";
   package com.example.crm;
   import "address.proto";
   
   message Customer {
     int64 customer_id = 1;
     string customer_name = 2;
     // This field's type refers to the imported Address message
     com.example.common.Address billing_address = 3;
   }
   

   Lors de l'enregistrement de customer_schema_proto, ses métadonnées incluraient une référence de schéma :

   // Conceptual metadata for customer_schema_proto
   "references": [
     {
       "name": "address.proto",
       "subject": "address_schema_proto",
       "version": 1
     }
   ]
   

3. De même, pour votre schéma Supplier, vous ajouteriez une référence de schéma pointant vers le même schéma Address commun.

À propos du mode Schéma

Le mode schéma définit l'état opérationnel d'un registre de schémas ou d'un sujet spécifique, et contrôle les types de modifications autorisées. Le mode de schéma peut être appliqué à un registre ou à un sujet spécifique dans un registre de schémas. Voici les chemins d'accès aux ressources du mode Schéma :

• Mode au niveau du registre : s'applique à l'ensemble du registre de schémas.

  • Chemin d'accès : projects/project/locations/location/schemaRegistry/schema_registry/mode

• Mode Sujet au niveau du registre : s'applique à un sujet spécifique dans l'ensemble du registre de schéma.

  • Chemin d'accès : projects/project/locations/location/schemaRegistries/schema_registry/mode/subject

Les modes suivants sont disponibles :

• Readonly : dans ce mode, le registre de schémas ou le ou les sujets spécifiés ne peuvent pas être mis à jour. Les modifications, telles que la mise à jour des configurations ou l'ajout de nouvelles versions de schéma, sont empêchées.

• Readwrite : ce mode autorise des opérations d'écriture limitées sur le registre de schémas ou sur le ou les sujets spécifiés. Il permet d'effectuer des modifications, comme mettre à jour des configurations et ajouter de nouvelles versions de schéma. Il s'agit du mode par défaut pour les nouveaux registres de schémas et les nouveaux sujets.

Pour déterminer si une modification est autorisée pour un sujet spécifique, le mode défini au niveau du sujet est prioritaire sur le mode défini au niveau du registre de schémas.

Par exemple, si un registre de schémas est en mode Readonly, mais qu'un sujet spécifique est en mode Readwrite, les modifications apportées à ce sujet spécifique sont autorisées. Toutefois, la création de sujets est limitée par le mode Readonly au niveau du registre.

Exemple pour le mode Schéma

Prenons l'exemple d'un registre de schémas dont le mode est défini sur Readwrite. Cette configuration vous permet d'ajouter de nouveaux sujets au registre et de nouvelles versions de schéma aux sujets existants.

Supposons que vous ayez un sujet nommé production-config que vous souhaitez protéger contre les modifications accidentelles. Vous définissez le mode pour le sujet production-config sur Readonly. Par conséquent, les conditions suivantes s'appliquent à l'objet production-config :

• Vous ne pouvez pas ajouter de nouvelles versions de schéma au sujet.

• Vous ne pouvez pas mettre à jour la configuration (comme le type de compatibilité) de l'objet.

• Les autres sujets du registre dont le mode n'est pas explicitement défini restent en mode Readwrite. Vous pouvez donc toujours les modifier.

• Vous pouvez continuer à créer des sujets dans le registre, car le registre lui-même est toujours en mode Readwrite.

Vous pourrez ensuite décider de mettre l'ensemble du registre de schémas en état de maintenance en définissant le mode au niveau du registre sur Readonly. Toutefois, vous avez un autre sujet, staging-config, qui doit rester modifiable pour les tests en cours. Vous définissez explicitement le mode pour le staging-config soumis à Readwrite. Par conséquent, les conditions suivantes s'appliquent à l'objet staging-config :

• Le registre de schémas est désormais Readonly. Vous ne pouvez pas créer de sujets.

• La plupart des sujets existants, tels que ceux sans remplacement de mode spécifique, deviennent également Readonly par héritage. Vous ne pouvez pas leur ajouter de nouvelles versions de schéma ni mettre à jour leurs configurations.

• L'objet production-config reste Readonly, comme défini explicitement.

• L'objet staging-config reste en mode Readwrite, car son paramètre au niveau de l'objet remplace le mode Readonly au niveau du registre. Vous pouvez continuer à ajouter des versions de schéma et à mettre à jour les configurations pour staging-config.

Cette approche hiérarchique offre une flexibilité dans la gestion des modifications de schéma à différents niveaux de précision.

Pour savoir comment mettre à jour le mode de schéma, consultez Mettre à jour le mode de schéma.

Configuration recommandée pour utiliser le registre de schémas en production

Pour sécuriser vos schémas dans un environnement de production, appliquez les configurations suivantes :

• Empêchez l'enregistrement de nouveaux schémas en définissant mode=READONLY pour l'ensemble du registre de schémas ou pour les sujets de production spécifiques.

• Empêchez les clients Kafka de créer des versions de schéma en vous assurant qu'ils ne disposent pas de l'autorisation create version.

• Dans vos sérialiseurs de client Kafka, définissez auto.register.schemas=false. Pour Kafka Connect, configurez ce paramètre pour les sérialiseurs de clé et de valeur selon vos besoins :

  • key.serializer.auto.register.schemas=false
  • value.serializer.auto.register.schemas=false

• (Facultatif) Pour forcer les clients à utiliser le schéma le plus récent pour un sujet, définissez use.latest.version=true dans le sérialiseur ou le désérialiseur. Ce paramètre indique au client d'utiliser la dernière version du schéma enregistrée pour le sujet, plutôt que la version correspondant au message spécifique.

Étapes suivantes

• Créer un registre de schémas

• Créer un sujet

Apache Kafka® est une marque déposée d'Apache Software Foundation ou de ses filiales aux États-Unis et/ou dans d'autres pays.