Enabling mirroring

Step 1: Setup

Mirroring is not supported for a Satellite cluster, therefore neither can be a source nor a target cluster.

Ensure that you provision two Enterprise plan clusters. Both clusters must have the same throughput and storage capacity and have service-to-service bindings (see Step 2 for more information).

Because mirroring is unidirectional, decide which direction of mirroring you want. One cluster is the source and the other cluster is the target.

Decide which topics from your source cluster that you want to mirror. By default no topics are mirrored and you can enable mirroring by using the user controls after mirroring is enabled as shown in step 4. You must specify the selection as one or more patterns.

Consider your bandwidth requirements; is there enough bandwidth available in the source cluster? Your source cluster needs to have some headroom to run mirroring. See Choosing your plan for cluster bandwidth limits and use Event Streams metrics to determine how busy your source cluster is and whether it has the headroom for mirroring.

Although mirroring from a Enterprise multi-zone-region cluster to a Enterprise single-zone-region cluster and vice versa is allowed. We do not recommend this configuration unless you have specific residency requirements and are aware of the implications. The Service Level Agreement (SLA) policy of a Enterprise multi-zone-region cluster to a Enterprise single-zone-region cluster might be lower or vice versa.

Step 2: Enable service-to-service bindings

You must configure a service-to-service binding between both instances to allow both instances to communicate. To configure, complete the following steps:

1. Navigate to the Authorizations panel in IAM and click Create.
2. From the point of view of IAM, the source and target services are the opposite of mirroring. Select both clusters, assign the Reader role, and click Authorize.

If your requirement is to fail back, you also need the service-to-service binding in the opposite direction.

The following example shows how to use the command line to configure service-to-service binding.

In this command we are using IAM source and target definitions, which are the opposite to that of mirroring. That is, IAM Source cluster is the mirroring target cluster.

ibmcloud iam authorization-policy-create messagehub messagehub Reader --source-service-instance-id <instance id of the mirroring target cluster> [--source-service-account <account id>] --target-service-instance-id <instance id of the mirroring source cluster>

For more information about service-to-service bindings, see Manage authorizations panel and Using authorizations to grant access between services.

Step 3: Enable mirroring

To enable mirroring, you need to run a service-instance-update command against your target cluster by using the CLI with the following required parameters:

• The source_crn is in this format: "crn:v1:bluemix:public:messagehub:us-south:a/aaa:aaaa::"
• The source_alias and the target_alias are the aliases that you want to configure for each of the two service instances when you enable mirroring. The aliases appear in topic names. Choose short and descriptive names. For example, "us-south" and "us-east".

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

Step 4: Validation

You can get the current service instance information by running the following command:

ibmcloud resource service-instance "Event Streams resource instance name" --output=json

Review the last operation section of the output. The information is continuously updated as the update proceeds. When the mirroring enablement process has completed, the last operation information indicates whether the update succeeded or the sync succeeded.

"last_operation": {
  "type": "update",
  "state": "in progress",
  "description": "Update in progress.",
  "updated_at": null,
  "cancelable": false
}

Run the command again until success is indicated as follows:

"last_operation": {
  "type": "update",
  "state": "succeeded",
  "description": "Update succeeded.",
  "updated_at": null,
  "cancelable": false
}

The IBM Cloud Monitoring dashboard Event Streams Mirroring shows the state of mirroring.

Step 5: Select topics

When the service instance update has completed, we want to select some topics from the source cluster to mirror. This is done with the CLI by using the ibmcloud es mirroring-topic-selection-set command.

Topic selection is in the form of a regex pattern, or comma-separated list of such patterns.

The following command selects all topics to be mirrored:

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

You can select topics by listing the topics you want to mirror as follows:

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

For more information about making the selection, see Mirroring user controls.

After the topic selection is completed, the target cluster shows the topics that are selected for mirroring using the Mirroring user controls suffixed with the source cluster's alias.