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>"}}'

ミラーリングするトピックを選択

サービスインスタンスの更新が完了したら、ソースからターゲットのクラスターにミラーリングするトピックを選択する必要があります。 これは、CLIで「ibmcloud es mirroring-topic-selection-set」コマンドを使用して実行します。 これらの選択されたトピックを消費する消費者グループは、ソースからターゲットのクラスタにミラーリングされます。 トピックの選択は、正規表現パターン、またはそのようなパターンのコンマ区切りリストの形式で行われます。

以下のコマンドは、ミラーリングするすべてのトピックを選択します。

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

以下のように、ミラーリングするトピックをリストすることにより、トピックを選択できます。

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

選択について詳しくは、 ミラーリング・ユーザー制御 を参照してください。

トピックの選択が完了すると、ターゲットクラスタには、ソースクラスタのエイリアスを接尾語として使用したミラーリングユーザーコントロールを使用して、ミラーリング用に選択されたトピックが表示されます。

ステップ 3.1: トピック名とグループ名の変換方法を指定します

変換ルールを指定することで、ターゲットクラスタ内の異なる名前のトピックにデータをミラーリングすることができます。 以下の3つのシナリオでは、考えられる変革について説明し、それぞれのユースケースを説明します。

ミラーリングが有効化された後は、いつでもどのトピックまたは消費者グループをミラーリングするかを指定できますが、トピックまたはグループの変換はミラーリングが有効化された時点でのみ可能です。 ミラーリングがすでに有効になっている場合は、トピックまたはグループ変換を指定する次の有効化リクエストを行う前に、まず無効にする必要があります。

シナリオ1：古い接頭辞または接尾辞を削除し、新しい接頭辞または接尾辞を追加することでトピックを変換する

以下の4つの追加パラメータを設定する。

| トピックの名前変更に必要なパラメータ｜説明｜トピックの名前変更に必要なパラメータ | -- | -- | | remove_prefix｜ 移動元クラスタのトピック名から削除するプレフィックス。| | remove_suffix | ソース・クラスタのトピック名から削除するサフィックス。| | add_prefix | 対象クラスターのトピック名に追加するプレフィックス。| | add_suffix | 対象クラスターでトピック名に追加するサフィックス。|

ibmcloud resource service-instance-update コマンドは、 -p コマンドライン引数で指定する必要があります。 これらのオプションが指定された場合、一致する接頭辞または接尾辞を持つトピックのみがミラーリングの対象となります。 例えば、 remove_prefix が app1- で、 abc.* をトピック選択として指定した場合、 app1-abc で始まるトピックのみがミラーリングされます。

「rename」タイプの変換を指定し、 add_prefix または add_suffix のパラメータを指定しない場合、ターゲットクラスタ内のミラーリングされたトピックからこれらのパラメータが削除されます。 トピックパターンは、ソースの接頭辞または接尾辞が削除された後、接頭辞または接尾辞が追加される前に、トピック名に適用されます。

以下のCLIコマンドの例を参照のこと：

{
  "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"
        }
      }
    }
  }
}

シナリオ 2 : ミラー化されたトピックにサフィックスとしてソースエイリアスを追加する

topic_name_transform型を use_alias に設定してトピック名の変換を適用する。 この構成では、ソース・クラスタの app1-topic というトピックは、ターゲット・クラスタの app1-topic.source というトピックにミラーリングされます。これは、構成で指定されたソース・エイリアスが source であるためです。

以下のCLIコマンドの例を参照のこと：

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

シナリオ3：トピックは名前を変更せずにミラーリングされる

このシナリオでは、タイプを none に設定した topic_name_transform も適用します。 この構成では、ソースクラスターの app1-topic というトピックが、ターゲットクラスターの app1-topic というトピックにミラーリングされます。

以下のCLIコマンドの例を参照のこと：

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

ステップ 3.2: 対応する消費者グループIDの変換

デフォルトでは、ミラーメーカーはターゲットクラスタにミラーリングする際に、コンシューマーグループIDを変更しません。 ただし、 Event Streams では、以下の2つのシナリオで概説されているように、グループIDのデータを修正することができます。 トピックと同様に、グループIDパターンは、ソースの接頭辞または接尾辞を削除した後、接頭辞または接尾辞を追加する前に適用されます。 「rename」タイプの変換を指定し、 add_prefix または add_suffix のパラメータを指定しない場合、ターゲットクラスタのミラーリングされたグループIDからこれらのパラメータが削除されます。

ibmcloud resource service-instance-update コマンドは、 -p コマンドライン引数で指定する必要があります。

シナリオ1：古い接頭辞または接尾辞を削除し、新しい接頭辞または接尾辞を追加することでグループIDを変換する

以下の4つの追加パラメータを設定する。

| グループIDの名前変更に必要なパラメーター｜説明｜グループIDの名前変更に必要なパラメーター | -- | -- | | remove_prefix｜ソースクラスタのグループIDから削除するプレフィックス。| | remove_suffix｜ソース・クラスターのグループIDから削除するサフィックス。| |add_prefix｜ターゲット・クラスターのグループIDに追加するプレフィックス。| | add_suffix｜ターゲット・クラスターのグループIDに追加するサフィックス。|

これらのオプションが指定された場合、一致する接頭辞または接尾辞を持つグループIDのみがミラーリングの対象となります。 例えば、 remove_prefix が aaa 、 add_prefix が bbb の場合、ソースクラスターで aaa-group-id で始まる消費者グループは、ターゲットクラスターの bbb-group-id にミラーリングされます。

以下のCLIコマンドの例を参照のこと：

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

シナリオ2：消費者グループIDは名前を変えずにミラーリングされる

このシナリオでは、タイプを none に設定した topic_name_transform も適用します。 この構成では、ソースクラスターの aaa-group-id というトピックが、ターゲットクラスターの aaa-group-id というトピックにミラーリングされます。

以下のCLIコマンドの例を参照のこと：

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

注意事項

ミラーリングを使用してスキーマを同期する前に、以下の注意事項を確認してください：

1. スキーマが2つのレジストリ間で一括エクスポート/インポートされる間、メンテナンスウィンドウが必要です。
2. トピックのリネームが機能するためには、スキーマが Confluent Avro Serdes を使用し、トピック名からサブジェクトを導出できるようにする必要があります。 Confluent Avro Serdesは、スキーマに関連付けられたサブジェクトをトピック名から派生させることができるからである（たとえば、トピックおよびトピック/レコードのサブジェクト命名ストラテジーの場合）。
3. S2S s2s の認可またはミラーリングを無効にすると、スキーマレジストリ要求が転送されなくなる。
4. 変換が必要な場合は、移行を実行する前に、ターゲット・インスタンスのスキーマ・レジストリをトピック名変更ルールで構成する必要があります。
5. マイグレーションが完了するまで、名前の変更ルールは変更できない。 移行中に変更を加えると、レジストリ間で不整合が生じる。

説明

以下の手順では、スキーマ・レジストリのミラーリングを使用して2つのインスタンス間でスキーマを移動する方法を説明します。

エクスポート・ユーティリティはまだCLIに追加されていない。

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

トピック名の変換

トピック名は転送中に変換できる。 例えば、適切なルールがあれば、old-my-topic 、 new-my-topic。 有効にすると、ソース・インスタンスは元の名前のみを認識し、ターゲット・インスタンスは新しい (変換された) トピック名のみを認識します。 返される結果はすべて、それに応じて変換される。

変換ルールが提供されない場合、 Event Streams の既存のミラーリングの動作に沿って、 use_alias が使用される。 トピック名を変更せずに転送するには、 topic_name_transform タイプ none を使用する。 変換は、 既存のCLI変換フィールドを 使用して設定される。

移住の流れ

2つの Event Streams インスタンス間で移行する場合、以下のフローを推奨する。

1. schemas: proxied を指定して、2つのインスタンス間のミラーリングを有効にする。
2. ターゲットスキーマ・レジストリを使用するようにアプリケーションを更新する。
3. schemas: read-only に切り替えることで、ターゲットレジストリへの書き込みをブロックする。 この変更を行う前に、ミラーリングを一時的に無効にしておく必要がある。
4. ソース・インスタンスからすべてのスキーマをエクスポートします。
5. ソース・インスタンスからエクスポートされたすべてのスキーマをターゲットにインポートします。 これは、 IBM Cloud® CLIを使用して行うことができます： ibmcloud [...]。
6. ミラーリングを無効にする。

スキーマのエクスポート

より詳細な情報については、 Confluent のドキュメントを 参照してください。

Event Streams CLIでは、スキーマのインポートに v1 exportVersion。

1. 最新の v2.x.x のソースコードをダウンロードする。例えば、 https://github.com/Apicurio/apicurio-registry/archive/refs/tags/2.6.13.Final.zip。

2. エクスポート・クライアントの構築： mvn -pl utils/exportConfluent -am -DskipTests -Pprod package.

3. エクスポーターを実行する（出力を 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
   

スキーマのインポート

スキーマは Event Streams CLI を使ってインポートできる。

1. event-streams[es] プラグインがインストールされていることを確認してください： ibmcloud plugin list.

2. IBM Cloud® にログイン : ibmcloud login [...].

3. インポートしたい Event Streams インスタンスを初期化する： ibmcloud es init.

4. スキーマをインポートする：

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