Exemple de commande CLI

ibmcloud resource service-instance-update "Event Streams resource instance name" -p '{"mirroring":{"source_crn":"<source_crn>", "source_alias":"<source_alias>", "target_alias":"<target_alias>"}}'

Sélectionner les sujets à refléter

Lorsque la mise à jour de l'instance de service est terminée, vous devez sélectionner les rubriques qui seront mises en miroir de la source vers le cluster cible. Cette opération s'effectue à l'aide de la commande 'ibmcloud es mirroring-topic-selection-set'. Tous les groupes de consommateurs utilisés pour consommer à partir de ces sujets sélectionnés seront mis en miroir de la source vers le cluster cible. La sélection de rubrique se présente sous la forme d'un modèle d'expression régulière ou d'une liste séparée par des virgules de ces modèles.

La commande suivante sélectionne toutes les rubriques à mettre en miroir:

ibmcloud es mirroring-topic-selection-set --select '.*'

Vous pouvez sélectionner des rubriques en répertoriant les rubriques que vous souhaitez mettre en miroir comme suit:

ibmcloud es mirroring-topic-selection-set --select topic1,topic2,topic3

Pour plus d'informations sur la sélection, voir Mise en miroir des contrôles utilisateur.

Une fois la sélection des rubriques terminée, le cluster cible affiche les rubriques sélectionnées pour la mise en miroir à l'aide des contrôles utilisateur de mise en miroir, précédés de l'alias du cluster source.

Étape 3.1: Spécifier comment les noms de rubriques et de groupes sont transformés

Vous pouvez spécifier des règles de transformation qui vous permettent de mettre en miroir des données dans des rubriques portant des noms différents dans le cluster cible. Les trois scénarios suivants décrivent les transformations possibles et expliquent les cas d'utilisation pour chacun d'entre eux.

Vous pouvez spécifier quels sujets ou groupes de consommateurs sont mis en miroir à tout moment une fois que la mise en miroir a été activée, mais la transformation des sujets ou des groupes n'est possible qu'au moment où la mise en miroir est activée. Si la mise en miroir est déjà activée, elle devra d'abord être désactivée avant qu'une nouvelle demande d'activation ne soit faite pour spécifier la transformation d'un sujet ou d'un groupe.

Scénario 1 : transformation des sujets par la suppression de l'ancien préfixe ou suffixe et l'ajout d'un nouveau préfixe ou suffixe

Configurez les quatre paramètres supplémentaires suivants.

La commande ibmcloud resource service-instance-update doit être spécifiée via l'argument de la ligne de commande -p. Lorsque ces options sont spécifiées, seuls les sujets dont les préfixes ou suffixes correspondent seront éligibles à la mise en miroir. Par exemple, si vous avez un remove_prefix de app1- et que vous spécifiez une sélection de sujets de abc.*, seuls les sujets commençant par app1-abc seront mis en miroir.

Si vous spécifiez le type de transformation "rename" et que vous ne spécifiez pas les paramètres pour add_prefix ou add_suffix, ces paramètres seront supprimés du sujet mis en miroir dans le cluster cible. Les modèles de sujet sont appliqués au nom du sujet après la suppression de tout préfixe ou suffixe source et avant l'ajout de tout préfixe ou suffixe.

Voir l'exemple de commande CLI suivant :

{
  "mirroring": {
    "source_crn": "crn:v1:...",
    "source_alias": "source",
    "target_alias": "target",
    "options": {
      "topic_name_transform": {
        "type": "rename",
        "rename": {
          "add_prefix": "newprefix-",
          "remove_prefix": "oldprefix-",
          "add_suffix": "-newsuffix",
          "remove_suffix": "-oldsuffix"
        }
      }
    }
  }
}

Scénario 2 : Ajout de l'alias de la source comme suffixe aux rubriques en miroir

Appliquer une transformation de nom de sujet avec le type topic_name_transform fixé à use_alias Avec cette configuration, un sujet appelé app1-topic dans le cluster source sera mis en miroir avec un sujet appelé app1-topic.source dans le cluster cible, car l'alias source spécifié dans la configuration est source

Voir l'exemple de commande CLI suivant :

{
  "mirroring": {
    "source_crn": "crn:v1:...",
    "source_alias": "source",
    "target_alias": "target",
    "options": {
        "topic_name_transform": {
            "type": "use_alias"
      }
    }
  }
}

Scénario 3 : les sujets sont mis en miroir sans que leur nom soit modifié

Dans ce scénario, vous appliquez également l'article topic_name_transform avec le type none. Avec cette configuration, un sujet appelé app1-topic dans le cluster source sera mis en miroir avec un sujet appelé app1-topic dans le cluster cible.

Voir l'exemple de commande CLI suivant :

{
  "mirroring": {
    "source_crn": "crn:v1:...",
    "source_alias": "source",
    "target_alias": "target",
    "options": {
        "topic_name_transform": {
            "type": "none"
      }
    }
  }
}

Étape 3.2: Transformation des identifiants des groupes de consommateurs correspondants

Par défaut, Mirror Maker ne modifie pas les identifiants des groupes de consommateurs lors de la mise en miroir vers le cluster cible. Cependant, Event Streams vous permet de modifier les données des identifiants de groupe, comme indiqué dans les deux scénarios suivants. Comme pour les sujets, les modèles d'ID de groupe sont appliqués après la suppression de tout préfixe ou suffixe source et avant l'ajout de tout préfixe ou suffixe. Si vous spécifiez le type de transformation "rename" et que vous ne spécifiez pas les paramètres pour add_prefix ou add_suffix, l'ID du groupe en miroir dans le cluster cible aura ces paramètres supprimés.

La commande ibmcloud resource service-instance-update doit être spécifiée via l'argument de la ligne de commande -p.

Scénario 1 : Transformer l'identifiant du groupe en supprimant l'ancien préfixe ou suffixe et en ajoutant un nouveau préfixe ou suffixe

Configurez les quatre paramètres supplémentaires suivants.

Lorsque ces options sont spécifiées, seuls les ID de groupe avec les préfixes ou suffixes correspondants seront éligibles pour la mise en miroir. Par exemple, si vous avez un remove_prefix de aaa et un add_prefix de bbb, les groupes de consommateurs qui commencent par aaa-group-id dans le cluster source seront mis en miroir vers bbb-group-id dans le cluster cible.

Voir l'exemple de commande CLI suivant :

{
  "group_id_transform": {
    "type": "rename",
    "rename": {
       "add_prefix": "newprefix-",
       "remove_prefix": "oldprefix-",
       "add_suffix": "-newsuffix",
       "remove_suffix": "-oldsuffix"
    }
  }
}

Scénario 2 : les identifiants des groupes de consommateurs sont dupliqués sans que leur nom soit modifié

Dans ce scénario, vous appliquez également l'article topic_name_transform avec le type none. Avec cette configuration, un sujet appelé aaa-group-id dans le cluster source sera mis en miroir avec un sujet appelé aaa-group-id dans le cluster cible.

Voir l'exemple de commande CLI suivant :

"group_id_transform": {
  "type": "none"
}

Précautions

Avant de synchroniser des schémas à l'aide d'un miroir, prenez connaissance des précautions suivantes :

1. Une fenêtre de maintenance est nécessaire pendant que les schémas sont exportés/importés en masse entre les deux registres - cela devrait être de l'ordre de quelques heures ou moins.
2. Pour que le renommage des sujets fonctionne, les schémas doivent utiliser Confluent Avro Serdes, afin que le sujet puisse être dérivé du nom du sujet. Confluent Avro Serdes parce que le sujet associé à un schéma peut être dérivé du nom du sujet (par exemple, pour les stratégies de dénomination du sujet et du sujet/enregistrement).
3. La mise en miroir de l'autorisation S2S doit être ininterrompue; la désactivation de l'autorisation s2s ou de la mise en miroir empêchera la transmission des demandes de registre des schémas.
4. Si une transformation est nécessaire, le registre des schémas de l'instance cible doit être configuré avec des règles de renommage des rubriques avant toute migration.
5. Les règles de renommage ne peuvent pas être modifiées tant que la migration n'est pas terminée. Les modifications apportées au cours de la migration entraîneront des incohérences entre les registres.

Instructions

Les instructions suivantes expliquent comment utiliser la mise en miroir du registre des schémas pour déplacer des schémas entre deux instances.

Un utilitaire d'exportation n'a pas encore été ajouté à la CLI.

ibmcloud resource service-instance-update \
"trgt-instance-name" \
-p '{
"mirroring": {
"source_crn": "<src instance crn>",
"source_alias": "source",
"target_alias": "target",
"schemas": "proxied"
}
}'

Transformation du nom du sujet

Les noms des sujets peuvent être transformés pendant le transfert. Par exemple, avec les bonnes règles,old-my-topic pourrait devenir new-my-topic. Lorsqu'elle est activée, l'instance source ne reconnaît que le nom original, tandis que l'instance cible ne reconnaît que le nouveau nom du sujet (transformé). Tous les résultats renvoyés sont transformés en conséquence.

Si aucune règle de transformation n'est fournie, c'est use_alias qui est utilisé, conformément au comportement de miroir existant dans Event Streams. Pour faire suivre sans changer les noms des sujets, utilisez topic_name_transform type none. La transformation est configurée à l'aide des champs de transformation CLI existants.

Flux migratoires

Lors de la migration entre deux instances Event Streams, la procédure suivante est suggérée.

1. Activer la mise en miroir entre deux instances, en spécifiant schemas: proxied.
2. Mettez à jour vos applications pour utiliser le registre des schémas cibles.
3. Bloquer toute écriture dans le registre cible en passant à schemas: read-only. Avant d'effectuer cette modification, il faut désactiver momentanément la mise en miroir.
4. Exporter tous les schémas de l'instance source.
5. Importer tous les schémas exportés de l'instance source dans l'instance cible. Cette opération peut être effectuée à l'aide du CLI IBM Cloud®: ibmcloud [...].
6. Désactiver la mise en miroir.

Exportation de schémas

Pour plus d'informations, voir la documentation de Confluent.

L'interface de programmation Event Streams exige que les importations de schémas aient une valeur v1 exportVersion.

1. Téléchargez la dernière version du code source de v2.x.x, par exemple, https://github.com/Apicurio/apicurio-registry/archive/refs/tags/2.6.13.Final.zip.

2. Construire le client d'exportation : mvn -pl utils/exportConfluent -am -DskipTests -Pprod package.

3. Exécutez l'exportateur (enregistre la sortie sur confluent-schema-registry-export.zip ):

   java -jar utils/exportConfluent/target/apicurio-registry-utils-exportConfluent-2.6.13.Final.jar \
   "https://token:<password>@<my-event-streams-instance.com>/confluent" \
   --client-props basic.auth.credentials.source=URL
   

Importation de schémas

Les schémas peuvent être importés à l'aide du CLI Event Streams.

1. Assurez-vous que le plugin event-streams[es] est installé : ibmcloud plugin list.

2. Connectez-vous à IBM Cloud®: ibmcloud login [...].

3. Initialiser l'instance Event Streams dans laquelle vous souhaitez importer : ibmcloud es init.

4. Importer le schéma :

   ibmcloud es schema-import \
   -f confluent-schema-registry-export.zip