Comando CLI de Exemplo

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

Selecione os tópicos a serem espelhados

Quando a atualização da instância de serviço for concluída, você deverá selecionar quais tópicos serão espelhados do cluster de origem para o cluster de destino. Isso é feito com a CLI usando o comando "ibmcloud es mirroring-topic-selection-set". Todos os grupos de consumidores usados para consumir desses tópicos selecionados serão espelhados da origem para o cluster de destino. A seleção de tópico está na forma de um padrão de expressão regular ou de uma lista separada por vírgula de tais padrões.

O comando a seguir seleciona todos os tópicos a serem espelhadas:

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

É possível selecionar tópicos listando os tópicos que você deseja espelhar da seguinte forma:

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

Para obter mais informações sobre como fazer a seleção, consulte Espelhamento de controles do usuário

Após a conclusão da seleção de tópicos, o cluster de destino mostra os tópicos selecionados para espelhamento usando os controles de usuário de espelhamento com o sufixo do alias do cluster de origem.

Etapa 3.1: Especifique como os nomes de tópicos e grupos são transformados

Você pode especificar regras de transformação que permitem espelhar dados em tópicos com nomes diferentes no cluster de destino. Os três cenários a seguir descrevem as possíveis transformações e explicam os casos de uso de cada uma delas.

Você pode especificar quais tópicos ou grupos de consumidores serão espelhados a qualquer momento após a ativação do espelhamento; no entanto, a transformação de tópicos ou grupos só é possível no momento em que o espelhamento é ativado. Se o espelhamento já estiver ativado, ele precisará ser desativado antes que uma solicitação de ativação subsequente seja feita para especificar a transformação de tópico ou grupo.

Cenário 1: transformação de tópicos removendo o prefixo ou sufixo antigo e adicionando um novo prefixo ou sufixo

Configure os quatro parâmetros adicionais a seguir.

| Parâmetros necessários para renomear tópicos Descrição | -- | -- | | Remove_prefix O prefixo a ser removido dos nomes de tópicos no cluster de origem. | | Remove_suffix O sufixo a ser removido dos nomes de tópicos no cluster de origem. | | Add_prefix O prefixo a ser adicionado aos nomes de tópicos no cluster de destino. | | O sufixo a ser adicionado aos nomes dos tópicos no cluster de destino. |

O comando ibmcloud resource service-instance-update precisa ser especificado por meio do argumento de linha de comando -p. Quando essas opções forem especificadas, somente os tópicos com os prefixos ou sufixos correspondentes estarão qualificados para espelhamento. Por exemplo, se você tiver um remove_prefix de app1- e especificar uma seleção de tópico de abc.*, somente os tópicos que começarem com app1-abc serão espelhados.

Se você especificar o tipo de transformação "renomear" e não especificar os parâmetros para add_prefix ou add_suffix, o tópico espelhado no cluster de destino terá esses parâmetros removidos. Os padrões de tópico são aplicados ao nome do tópico depois que qualquer prefixo ou sufixo de origem é removido e antes que qualquer prefixo ou sufixo seja adicionado.

Veja o exemplo de comando da CLI a seguir:

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

Cenário 2: adicionar o alias de origem como um sufixo aos tópicos espelhados

Aplicar uma transformação de nome de tópico com o tipo topic_name_transform definido como use_alias. Com essa configuração, um tópico chamado app1-topic no cluster de origem será espelhado em um tópico chamado app1-topic.source no cluster de destino, porque o alias de origem especificado na configuração é source.

Veja o exemplo de comando da CLI a seguir:

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

Cenário 3: Os tópicos são espelhados com seus nomes inalterados

Nesse cenário, você também aplica o topic_name_transform com o tipo definido como none. Com essa configuração, um tópico chamado app1-topic no cluster de origem será espelhado em um tópico chamado app1-topic no cluster de destino.

Veja o exemplo de comando da CLI a seguir:

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

Etapa 3.2: Transformação de IDs de grupos de consumidores correspondentes

Por padrão, o Mirror Maker não modificará os IDs do grupo de consumidores ao espelhar para o cluster de destino. No entanto, o site Event Streams permite que você modifique os dados dos IDs de grupo, conforme descrito nos dois cenários a seguir. Semelhante aos tópicos, os padrões de ID de grupo são aplicados após a remoção de qualquer prefixo ou sufixo de origem e antes da adição de qualquer prefixo ou sufixo. Se você especificar o tipo de transformação "renomear" e não especificar os parâmetros para add_prefix ou add_suffix, o ID do grupo espelhado no cluster de destino terá esses parâmetros removidos.

O comando ibmcloud resource service-instance-update precisa ser especificado por meio do argumento de linha de comando -p.

Cenário 1: Transforme a ID do grupo removendo o prefixo ou sufixo antigo e adicionando um novo prefixo ou sufixo

Configure os quatro parâmetros adicionais a seguir.

| Parâmetros necessários para renomear o ID do grupo Descrição | -- | -- | | Remove_prefix O prefixo a ser removido do ID do grupo no cluster de origem. | | Remove_suffix O sufixo a ser removido do ID do grupo no cluster de origem. | | Add_prefix O prefixo a ser adicionado ao ID do grupo no cluster de destino. | | O sufixo a ser adicionado ao ID do grupo no cluster de destino. |

Quando essas opções forem especificadas, somente os IDs de grupo com os prefixos ou sufixos correspondentes estarão qualificados para o espelhamento. Por exemplo, se você tiver um remove_prefix de aaa e um add_prefix de bbb, os grupos de consumidores que começam com aaa-group-id no cluster de origem serão espelhados para bbb-group-id no cluster de destino.

Veja o exemplo de comando da CLI a seguir:

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

Cenário 2: Os IDs de grupos de consumidores são espelhados com seus nomes inalterados

Nesse cenário, você também aplica o topic_name_transform com o tipo definido como none. Com essa configuração, um tópico chamado aaa-group-id no cluster de origem será espelhado em um tópico chamado aaa-group-id no cluster de destino.

Veja o exemplo de comando da CLI a seguir:

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

Precauções

Antes de sincronizar esquemas usando o espelhamento, examine as seguintes precauções:

1. Uma janela de manutenção é necessária enquanto os esquemas são exportados/importados em massa entre os dois registros - isso seria da ordem de algumas horas ou menos.
2. Para que a renomeação de tópicos funcione, os esquemas devem usar Confluent Avro Serdes, para que o assunto possa ser derivado do nome do tópico. Confluent Avro Serdes porque o assunto associado a um esquema pode ser derivado do nome do tópico (por exemplo, para estratégias de nomeação de tópicos e tópicos/registros).
3. O espelhamento da autorização S2S deve ser ininterrupto; a desativação da autorização s2s ou do espelhamento impedirá que as solicitações de registro de esquema sejam encaminhadas.
4. Se a transformação for necessária, o registro do esquema da instância de destino deverá ser configurado com regras de renomeação de tópicos antes de qualquer migração.
5. As regras de renomeação não podem ser alteradas até que a migração seja concluída. Fazer alterações durante a migração resultará em inconsistências entre os registros.

Instruções

As instruções a seguir descrevem como usar o espelhamento de registro de esquema para mover esquemas entre duas instâncias.

Um utilitário de exportação ainda não foi adicionado à CLI.

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

Transformação do nome do tópico

Os nomes de tópicos podem ser transformados durante o encaminhamento. Por exemplo, com as regras corretas,old-my-topic poderia se tornar new-my-topic. Quando ativado, a instância de origem reconhece apenas o nome original, enquanto a instância de destino reconhece apenas o novo nome de tópico (transformado). Todos os resultados retornados são transformados de acordo.

Se nenhuma regra de transformação for fornecida, o site use_alias será usado, de acordo com o comportamento de espelhamento existente em Event Streams. Para encaminhar sem alterar os nomes dos tópicos, use topic_name_transform e digite none. A transformação é configurada usando os campos de transformação existentes na CLI.

Fluxo de migração

Ao migrar entre duas instâncias do Event Streams, sugere-se o seguinte fluxo.

1. Habilite o espelhamento entre duas instâncias, especificando schemas: proxied.
2. Atualize seus aplicativos para usar o registro do esquema de destino.
3. Bloqueie todas as gravações no registro de destino mudando para schemas: read-only. Antes de fazer essa alteração, o espelhamento deve ser desativado momentaneamente.
4. Exportar todos os esquemas da instância de origem.
5. Importar todos os esquemas exportados da instância de origem para o destino. Isso pode ser feito usando a CLI do IBM Cloud®: ibmcloud [...].
6. Desativar o espelhamento.

Exportação de esquemas

Para obter informações mais detalhadas, consulte a documentação do site Confluent.

A CLI do Event Streams exige que as importações de esquemas tenham um valor v1 exportVersion.

1. Faça o download do código-fonte mais recente do v2.x.x, por exemplo, https://github.com/Apicurio/apicurio-registry/archive/refs/tags/2.6.13.Final.zip.

2. Crie o cliente de exportação: mvn -pl utils/exportConfluent -am -DskipTests -Pprod package.

3. Execute o exportador (salva a saída em 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
   

Importação de esquemas

Os esquemas podem ser importados usando a CLI do Event Streams.

1. Verifique se você tem o plug-in event-streams[es] instalado: ibmcloud plugin list.

2. Faça login em IBM Cloud®: ibmcloud login [...].

3. Inicialize a instância do Event Streams para a qual você gostaria de importar: ibmcloud es init.

4. Importar o esquema:

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