W-16256706 MQ Custom Fallback Region Beta Doc

modules/ROOT/pages/_partials/mq-failover.adoc

@@ -6,10 +6,21 @@ For example, if the primary queue name is `myDemoQueue`, the fallback queue name
 
 // Fallback queues aren't configurable by end users
 // tag::fallbackQnotConfig[]
-The Anypoint MQ server manages fallback queues and regions;
-end users can't configure them.
+The Anypoint MQ server manages fallback queues; end users can't configure them.
 // end::fallbackQnotConfig[]
 
+// Specify custom fallback region
+// tag::fallbackRegionCustom[]
+With Anypoint MQ Connector version 4.0.10, you can specify a custom fallback region for a queue.
+// end::fallbackRegionCustom[]
+
+// Change fallback region
+// tag::changeFallbackRegion[]
+After Anypoint MQ assigns a fallback queue to a primary queue, you can't change the fallback region for the fallback queue.
+To specify a different region for the fallback queue, delete the primary queue.
+Then, create a new primary queue and choose a new fallback region.
+// end::changeFallbackRegion[]
+
 // Fallback queues inherit settings from primary queue
 // tag::fallbackQsync[]
 When you update the configuration of the primary queue, 
@@ -22,4 +33,6 @@ syncing the queue configuration.
 // tag::fallbackDLQ[]
 If the primary queue has an assigned dead-letter queue (DLQ),
 you must enable failover for the DLQ before enabling failover for the primary queue.
-// end::fallbackDLQ[]
+// end::fallbackDLQ[]
+
+

modules/ROOT/pages/mq-failover.adoc

@@ -1,9 +1,13 @@
 = Configuring Cross-Region Failover for Standard Queues
 include::partial$mq-on-hyperforce.adoc[tag=mqFeaturesNoHF]
 
-Anypoint Connector for Anypoint MQ (Anypoint MQ Connector) for Mule 4 version 4.0.7 provides failover capability for standard queues.
+You can configure failover by specifying a fallback region for standard queues using Anypoint Connector for Anypoint MQ (Anypoint MQ Connector) for Mule 4 version 4.0.10 and later.
 
-When you enable failover for a queue, Anypoint MQ automatically creates a fallback queue in a <<primary-fallback-regions,fallback region>>.
+* To use the failover feature with the default region, use connector version 4.0.7 or later.
+* To configure a specific failover region, use connector version 4.0.10 or later.
+
+
+When you enable failover for a queue, Anypoint MQ automatically creates a fallback queue in a default or custom <<primary-fallback-regions,fallback region>>.
 If a Mule app can't reach an Anypoint MQ server in a region,
 it switches to the fallback queue to publish and consume messages.
 For information about situations that can cause a region to be considered unavailable, see <<region-unavailability>>.
@@ -37,6 +41,10 @@ When you disable failover for a queue, apps can still consume any messages that
 For information about enabling this feature in your app, see 
 xref:anypoint-mq-connector::anypoint-mq-failover.adoc#enable-failover-feature[Enable Failover in Your App].
 ** Failover support requires Anypoint MQ Connector 4.0.7 or later.
+** Custom fallback region support requires Anypoint MQ Connector 4.0.10 or later.
++
+// Can't change fallback region
+include::partial$mq-failover.adoc[tag=changeFallbackRegion]
 // +
 // xref to upgrade steps?
 ** Failover is supported for standard queues only.
@@ -49,9 +57,11 @@ xref:anypoint-mq-connector::anypoint-mq-failover.adoc#enable-failover-feature[En
 +
 If failover is enabled for queues in those regions and the primary region goes down,
 data resides in a region outside the country until the primary region is available.
++
+To specify a custom fallback region when enabling failover, upgrade to Anypoint MQ Connector 4.0.10 or later.
 --
 +
-For the list of fallback regions, see <<primary-fallback-regions>>.
+For the list of default fallback regions, see <<primary-fallback-regions>>.
 * Authentication
 +
 If access management is unavailable when the connector switches to the fallback region,
@@ -78,7 +88,7 @@ You can configure how frequently the connector checks the fallback queue. See xr
 
 To use failover, you must first:
 
-* Upgrade Anypoint MQ Connector to 4.0.7 or later.
+* Upgrade Anypoint MQ Connector to 4.0.7 or later (default fallback region) or 4.0.10 or later (custom fallback region).
 +
 For information, see xref:anypoint-mq-connector::anypoint-mq-connector-upgrade-migrate.adoc[].
 * Enable the failover feature in your app.
@@ -119,14 +129,21 @@ For information about queue settings, see xref:mq-queues.adoc#create-a-queue[Cre
 +
 image::mq-create-queues-failover.png["Create Queue dialog box showing the failover option selected"]
 // added screenshot
+// .. Select the fallback region.
+// +
+// If you are using an Anypoint MQ Connector version earlier 4.0.10, 
+// leave the fallback region set at the default.
+// +
+// [NOTE]
+// include::partial$mq-failover.adoc[tag=changeFallbackRegion]
 .. Click *Create Queue*.
 + 
 Anypoint MQ creates the queue and also creates a fallback queue in the fallback region.
 // Fallback queue naming
 include::partial$mq-failover.adoc[tag=fallbackQname]
-+
-// Fallback queue/region not configurable
-include::partial$mq-failover.adoc[tag=fallbackQnotConfig]
+// +
+// Fallback queues aren't configurable by end users
+// include::partial$mq-failover.adoc[tag=fallbackQnotConfig]
 Modify an existing queue::
 +
 --
@@ -137,16 +154,23 @@ Anypoint MQ supports failover for standard queues only.
 .. In the *Queue Settings* page, select *Enable Cross-Region Failover*:
 +
 image::mq-queue-settings-failover.png["Queue Settings page showing the failover option selected"]
-// added screenshot
++
+[NOTE]
+include::partial$mq-failover.adoc[tag=changeFallbackRegion]
+
 
 .. Click *Save Changes*.
 +
 Anypoint MQ updates the queue settings and creates a fallback queue in the fallback region.
 // Fallback queue naming
 include::partial$mq-failover.adoc[tag=fallbackQname]
-+
-// Fallback queue/region not configurable
-include::partial$mq-failover.adoc[tag=fallbackQnotConfig]
+// +
+// Fallback queues aren't configurable by end users
+// include::partial$mq-failover.adoc[tag=fallbackQnotConfig]
+// Specify custom fallback region
+// include::partial$mq-failover.adoc[tag=fallbackRegionCustom]
+// Can't change fallback region
+// include::partial$mq-failover.adoc[tag=changeFallbackRegion]
 +
 If you previously enabled failover for the queue, the fallback queue already exists and is reinstated.
 .. Restart all applications consuming from or publishing to the queue.
@@ -209,9 +233,57 @@ The primary queue details shows that failover is disabled:
 image::mq-queue-details-primary-queue-fallback-disabled.png["Details pane for the primary queue showing the fallback queue and failover status"]
 . Restart all applications consuming from or publishing to the queue.
 
+[[assign-custom-fb-region-api]]
+== Assign a Custom Fallback Region Using the API
+
+With version 4.0.10 and later of the connector, 
+you can specify the fallback region when you enable failover, for example, to prevent data from residing in a different country for compliance reasons.
+
+Use the `fallbackRegion` property in the Anypoint MQ Admin API to specify one of the following custom fallback regions for the `us-west-2` region: `us-east-1`, `us-east-2`, or `ca-central-1` (default).
+
+To specify the custom fallback region when enabling failover,
+use a `curl` command like the following:
+
+[source,bash]
+----
+curl --location --request PUT 'https://anypoint.mulesoft.com/mq/admin/api/v1/organizations/\
+{organization-id}/environments/{environment-id}/regions/{region-id}/destinations/queues/\
+{destination-id}/fallback' \
+--header 'Authorization: Bearer {auth-token}' \
+--header 'Content-Type: application/json' \
+--data '{
+    "fallbackEnabled": true,
+    "fallbackRegion": "us-east-1"
+}'
+----
+
+* The value of `fallbackRegion` can be the default region or a custom region.
+* The `fallbackRegion` property is available for the `us-west-2` region only.
+* You can set `fallbackRegion` to any of the following values:
+** `us-east-1`
+** `us-east-2`
+** `ca-central-1` (default)
+
+For more information, see https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/anypoint-mq-admin/minor/1.0/console/method/%23599/[Anypoint MQ Admin API].
+
+=== Custom Fallback Regions and Fallback Queue Names
+
+When using custom fallback regions, keep in mind the following:
+
+* If the fallback region is not specified or set to the default, the name of the fallback queue is the primary queue name with the `_fb` suffix.
++
+For example, if the primary queue name is `myDemoQueue` in `us-west-2` and the fallback region is set to the default, the fallback queue name is `myDemoQueue_fb`.
+* If the fallback region is set to a region other than the default, the fallback queue name includes an additional identifier to indicate the primary region (`us-west-2`): `uw2`.
++
+For example, if the primary queue name is `myDemoQueue` in `us-west-2` and the fallback region is set to `us-east-1`, the fallback queue name is `myDemoQueue_uw2_fb` to indicate that the primary queue is in `us-west-2`.
+
 
 [[primary-fallback-regions]]
-== Primary-Fallback Regions
+== Default Primary-Fallback Regions
+
+By default, Anypoint MQ Connector uses the default primary-fallback region pairings.
+
+IMPORTANT: To minimize latency, use the default fallback region.
 
 [%header,cols="8,12,12,12,12"]
 |===
@@ -234,11 +306,11 @@ image::mq-queue-details-primary-queue-fallback-disabled.png["Details pane for th
 [[region-note-unavailable]]
 ^***^ {empty}
 Because Anypoint MQ is available in only one region in this country, 
-the fallback region is not in the same country as the primary region.
+the default fallback region is not in the same country as the primary region.
 
 [[region-note]]
 ^****^ {empty}
-The fallback region for this region is not in the same country as the primary region.
+The default fallback region for this region is not in the same country as the primary region.
 
 [[region-unavailability]]
 == Region Unavailability

modules/ROOT/pages/mq-glossary.adoc

@@ -85,6 +85,11 @@ A queue that Anypoint MQ automatically creates in a fallback region when failove
 // Fallback queues aren't configurable by end users
 include::partial$mq-failover.adoc[tag=fallbackQnotConfig]
 +
+// Specify custom fallback region
+include::partial$mq-failover.adoc[tag=fallbackRegionCustom]
+// Can't change fallback region
+include::partial$mq-failover.adoc[tag=changeFallbackRegion]
++
 For information, see xref:mq-failover.adoc[].
 
 [[fallback-region]]
@@ -93,6 +98,11 @@ A region that Anypoint MQ automatically assigns to a fallback queue when failove
 // Fallback queues aren't configurable by end users
 include::partial$mq-failover.adoc[tag=fallbackQnotConfig]
 +
+// Specify custom fallback region
+include::partial$mq-failover.adoc[tag=fallbackRegionCustom]
+// Can't change fallback region
+include::partial$mq-failover.adoc[tag=changeFallbackRegion]
++
 For information, see xref:mq-failover.adoc[].
 
 [[fifo-queues]]