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: 指定主題和群組名稱的轉換方式

您可以指定轉換規則，讓您可以將資料鏡射到目標群集中不同名稱的主題中。 以下三種情況描述了可能的轉換，並解釋了每種轉換的用例。

啟用鏡射後，您可以隨時指定鏡射哪些主題或消費者群組，但是主題或群組轉換只能在啟用鏡射時進行。 如果已啟用鏡射，則需要先停用鏡射，然後再提出啟用請求，以指定主題或群組轉換。

情況 1：透過移除舊的前綴或後綴並新增前綴或後綴來轉換主題

配置以下四個附加參數。

ibmcloud resource service-instance-update 指令需要透過 -p 指令行參數指定。 指定這些選項時，只有具有符合前綴或後綴的主題才有資格進行鏡射。 例如，如果您的 remove_prefix 為 app1-，並指定主題選擇為 abc.*，則只有以 app1-abc 開頭的主題才會被鏡射。

如果您指定「重新命名」類型的轉換，但沒有指定 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"
      }
    }
  }
}

場景三：主題鏡像，名稱不變

在這種情況下，您也套用 topic_name_transform，類型設定為 none。 使用此設定，來源群集中名為 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

根據預設，Mirror Maker 在鏡射到目標群集時，不會修改消費者群組 ID。 不過，Event Streams 允許您修改群組 ID 的資料，如以下兩種情況所述。 與主題類似，群組 ID 模式會在移除任何來源前綴或後綴之後，並在新增任何前綴或後綴之前套用。 如果您指定「重新命名」類型的轉換，但沒有指定 add_prefix 或 add_suffix 的參數，則目標群集中的鏡像群組 ID 將移除這些參數。

ibmcloud resource service-instance-update 指令需要透過 -p 指令行參數指定。

情況 1：透過移除舊的前綴或後綴，並加入新的前綴或後綴來轉換群組 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"
    }
  }
}

場景二：消費者群組ID鏡像，名稱不變

在這種情況下，您也套用 topic_name_transform，類型設定為 none。 使用此設定，來源群集中名為 aaa-group-id 的主題將會鏡射到目標群集中名為 aaa-group-id 的主題。

請參閱以下 CLI 命令範例：

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

注意事項

使用鏡像同步化模式之前，請檢閱下列預防措施：

1. 在兩個註冊表之間大量匯出/匯入模式時，需要一個維護視窗 - 維護視窗的時間約為幾小時或更短。
2. 為了讓主題重新命名生效，模式必須使用 Confluent Avro Serdes，因此主題可以從主題名稱衍生出來。 Confluent Avro Serdes，因為與模式相關的主題可以從主題名稱衍生出來（例如，主題和主題/記錄主題命名策略）。
3. 鏡像 S2S 授權必須不間斷；停用 s2s 授權或鏡像將阻止模式登錄請求的轉發。
4. 如果需要轉換，則必須在進行任何遷移之前，使用主題重新命名規則配置目標實例模式登錄。
5. 重命名規則在遷移完成前無法變更。 在遷移過程中進行變更會導致註冊表之間的不一致。

指示

以下指示概述了如何使用模式註冊表鏡像在兩個實例之間移動模式。

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。 啟用時，來源實例只識別原始名稱，而目標實例只識別新的（轉換後的）主題名稱。 所有傳回的結果都會進行相應的轉換。

如果沒有提供轉換規則，則會使用 use_alias，這與 Event Streams 中現有的鏡像行為一致。 若要轉寄而不變更主題名稱，請使用 topic_name_transform 鍵入 none。 轉換使用 現有的 CLI 轉換欄位 設定。

遷移流量

在兩個 Event Streams 實體之間遷移時，建議使用下列流程。

1. 啟用兩個實體間的鏡射，指定 schemas: proxied。
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