Merge pull request #241626 from bjqian/main

Add replica document for Azure SignalR and Azure Web PubSub

Author: v-ccolin

articles/azure-signalr/TOC.yml

@@ -99,14 +99,16 @@
       href: ./security-controls-policy.md
 - name: How-to guides
   items:
-  - name: Scale
+  - name: Scale and geo-replicate
     items:
     - name: Single instance
       href: signalr-howto-scale-signalr.md
     - name: Multiple instances
       href: signalr-howto-scale-multi-instances.md
     - name: Autoscale
       href: signalr-howto-scale-autoscale.md
+    - name: Geo-replication
+      href: howto-enable-geo-replication.md
   - name: Secure
     items:
     - name: Access key rotation

articles/azure-signalr/howto-enable-geo-replication.md

@@ -0,0 +1,100 @@
+---
+title: How to enable geo-replication
+description: How to enable geo-replication for Azure SignalR service
+author: biqian
+
+ms.author: biqian
+ms.date: 06/01/2023
+ms.service: signalr
+ms.topic: how-to
+---
+
+#  Geo-replication (Preview) in Azure SignalR
+
+Companies seeking local presence or requiring a robust failover system often choose to deploy services across multiple Azure regions. With the integration of geo-replication in Azure SignalR, managing multi-region scenarios has become significantly easier.
+
+## Benefits of using geo-replication
+* **More resilient to regional outage:** If a regional outage happens, the Azure SignalR DNS will be resolved to healthy replicas in other regions.
+* **Cross Region Communication**. Different replicas could communicate with each other as if they are the same instance.
+* **Enhanced network speed:** Geographically dispersed clients will connect to the nearest replica. These replicas communicate through [Azure global network backbone](https://azure.microsoft.com/explore/global-infrastructure/global-network), ensuring fast and stable networking.
+* **Shared configurations**. All replicas retain the primary Azure SignalR Service resource's configuration. 
+
+## Prerequisites
+
+* An Azure SignalR Service in [Premium tier](https://azure.microsoft.com/pricing/details/signalr-service/).
+* The user needs following permissions to operate on replicas:
+
+    | Permission                                        | Description                                       |
+    |---------------------------------------------------|---------------------------------------------------|
+    | Microsoft.SignalRService/signalr/replicas/write   | create, update or delete a replica. |
+    | Microsoft.SignalRService/signalr/replicas/read    | get meta data of a replica.|
+    | Microsoft.SignalRService/signalr/replicas/action  | perform actions on a replica, such as restarting. |
+
+
+## Example use case
+Contoso is a social media company with its customer base spread across the US and Canada. To serve those customers and let them communicate with each other, Contoso runs its services in Central US. Azure SignalR Service is used to handle user connections and facilitate communication among users. Contoso's end users are mostly phone users. Due to the long geographical distances, end-users in Canada might experience high latency and poor network quality.
+
+![Screenshot of using one Azure SignalR instance to handle traffic from two countries. ](./media/howto-enable-geo-replication/signalr-single.png  "Single SignalR Example")
+
+Before the advent of the geo-replication feature, Contoso could set up another Azure SignalR Service in Canada Central to serve its Canadian users. By setting up a geographically closer Azure SignalR Service, end users now have better network quality and lower latency. 
+
+However, managing multiple Azure SignalR Services brings some challenges:
+1. A cross-region communication mechanism would be required to enable conversation between Canada and US users.
+2. The development team would need to manage two separate Azure SignalR Services, each with distinct domain and connection string.
+3. If a regional outage happens, the traffic needs to be switched to another region.
+
+![Screenshot of using two Azure SignalR instances to handle traffic from two countries. ](./media/howto-enable-geo-replication/signalr-multiple.png  "Mutiple SignalR Example")
+
+## Harnessing geo-replication
+With the new geo-replication feature, Contoso can now establish a replica in Canada Central, effectively overcoming the above-mentioned hurdles.
+
+![Screenshot of using one Azure SignalR instance with replica to handle traffic from two countries.](./media/howto-enable-geo-replication/signalr-replica.png  "Replica Example")
+
+## Create a SignalR replica
+
+To create a replica, Navigate to the SignalR **Replicas** blade on the Azure portal and click **Add** to create a replica. It will be automatically enabled upon creation.
+
+![Screenshot of creating replica for Azure SignalR on Portal.](./media/howto-enable-geo-replication/signalr-replica-create.png  "Replica create")
+
+> [!NOTE]
+> * Geo-replication is a feature available in premium tier.
+> * A replica is considered a separate resource when it comes to billing. See [Pricing](#pricing) for more details. 
+
+After creation, you would be able to view/edit your replica on the portal by clicking the replica name.
+
+![Screenshot of overview blade of Azure SignalR replica resource. ](./media/howto-enable-geo-replication/signalr-replica-overview.png  "Replica Overview")
+
+## Pricing
+Replica is a feature of [Premium tier](https://azure.microsoft.com/pricing/details/signalr-service/) of Azure SignalR Service. Each replica is billed **separately** according to its own units and outbound traffic. Free message quota is also calculated separately.
+
+In the preceding example, Contoso added one replica in Canada Central. Contoso would pay for the replica in Canada Central according to its unit and message in Premium Price.
+
+## Delete a replica
+After you've created a replica for your Azure SignalR Service, you can delete it at any time if it's no longer needed. 
+
+To delete a replica in the Azure portal:
+
+1. Navigate to your Azure SignalR Service, and select **Replicas** blade. Click the replica you want to delete.
+2. Click Delete button on the replica overview blade.
+
+## Understanding how the SignalR replica works
+
+The diagram below provides a brief illustration of the SignalR Replicas' functionality:
+
+![Screenshot of the arch of Azure SignalR replica. ](./media/howto-enable-geo-replication/signalr-replica-arch.png  "Replica Arch")
+
+1. The client resolves the Fully Qualified Domain Name (FQDN) `contoso.service.signalr.net` of the SignalR service. This FQDN points to a Traffic Manager, which returns the  Canonical Name (CNAME) of the nearest regional SignalR instance.
+2. With this CNAME, the client establishes a connection to the regional instance.
+3. The two replicas will synchronize data with each other. Messages sent to one replica would be transferred to other replicas if necessary.
+4. In case a replica fails the health check conducted by the Traffic Manager (TM), the TM will exclude the failed instance's endpoint from its domain resolution process.
+
+> [!NOTE]
+> * In the data plane, a primary Azure SignalR resource functions identically to its replicas
+
+## Impact on performance after adding replicas
+
+Post replica addition, your clients will be distributed across different locations based on their geographical locations. SignalR must synchronize data across these replicas. The cost for synchronization is negligible if your use case primarily involves sending to large groups (size >100) or broadcasting. However, the cost becomes more apparent when sending to smaller groups (size < 10) or a single user.
+
+To ensure effective failover management, it is recommended to set each replica's unit size to handle all traffic. Alternatively, you could enable [autoscaling](signalr-howto-scale-autoscale.md) to manage this.
+
+For more performance evaluation, refer to [Performance](signalr-concept-performance.md).

articles/azure-signalr/media/howto-enable-geo-replication/signalr-multiple.png

@@ -69,6 +69,12 @@ For example, an application that uses 6.25 units per day has a daily free quota
 
 As a result, you'll be billed with 6.25 standard units and 8.75 additional message units for the day. 
 
+## How replica is billed
+
+Replica is a feature of Premium tier of Azure Web PubSub service. When you create a replica in desired regions, you incur Premium fees for each region.
+
+Each replica is billed separately according to its own units and outbound traffic. Free message quota is also calculated separately.
+
 ## Pricing 
 
 The Web PubSub service offers multiple tiers with different pricing. For more information about Web PubSub pricing, see [Azure Web PubSub service pricing](https://azure.microsoft.com/pricing/details/web-pubsub).

articles/azure-signalr/media/howto-enable-geo-replication/signalr-replica-arch.png

@@ -0,0 +1,89 @@
+---
+title: How to enable geo-replication for Azure Web PubSub
+description: How to enable geo-replication for Web PubSub service
+author: biqian
+
+ms.author: biqian
+ms.date: 06/01/2023
+ms.service: azure-web-pubsub
+ms.topic: how-to
+---
+
+# Geo-replication (Preview) in Azure Web PubSub 
+
+## What is geo-replication feature?
+Mission critical apps often need to have a robust failover system and serve users closer to where they are. Before the release of the geo-replication feature, developers needed to deploy multiple Web PubSub resources and write custom code to orchestrate communication across resources. Now, with quick configuration through Azure portal, you can easily enable this feature. 
+
+## Benefits of using geo-replication
+* **More resilient to regional outage:** If a regional outage happens, clients will be automatically routed to a healthy replica.
+* **Cross-region communication:** Developers use a geo-replication-enabled resource as usual, even though behind-the-scenes there are more than one resource. The communication across replicas is handled by the service. 
+* **Enhanced network speed:** Geographically dispersed clients will connect to the nearest replica. These replicas communicate through [Azure global network backbone](https://azure.microsoft.com/explore/global-infrastructure/global-network), ensuring fast and stable networking.
+* **Ease of management**. All replicas share the configuration of the primary Web PubSub resource.
+
+## Prerequisites
+* A Web PubSub resource in [premium tier](https://azure.microsoft.com/pricing/details/web-pubsub/).
+
+## Example use case
+### Contoso, a social media company
+Contoso is a social media company with its customer base spread across the US and Canada. Contoso provides a mobile and web app to its users so that they can connect with each other. Contoso application is deployed in Central US. As part of Contoso's architecture, Web PubSub is used to establish persistent WebSocket connections between client apps and the application server. Contoso **likes** that they can offload managing WebSocket connections to Web PubSub, but **doesn't** like reading reports of users in Canada experiencing higher latency. Furthermore, Contoso's development team wants to insure the app against regional outage so that the users can access the app with no interruptions.
+
+![Screenshot of using one Azure WebPubSub instance to handle traffic from two countries. ](./media/howto-enable-geo-replication/web-pubsub-single.png  "Single WebPubSub Example")
+
+Contoso **could** set up another Web PubSub resource in Canada Central which is geographically closer to its users in Canada. However, managing multiple Web PubSub resources brings some challenges:
+1. A cross-region communication mechanism would need to be implemented so that users in Canada and US can interact with each other.
+2. The development team would need to manage two separate Web PubSub resources, each with distinct domain and connection string.
+3. If a regional outage takes place, the traffic needs to be directed to an available resource.
+
+All of the above takes engineering resources away from focusing on product innovation.
+
+![Screenshot of using two Azure Web PubSub instances to handle traffic from two countries. ](./media/howto-enable-geo-replication/web-pubsub-multiple.png  "Mutiple Web PubSub Example")
+
+### Harnessing the geo-replication feature
+With the geo-replication feature, Contoso can now establish a replica in Canada Central, effectively overcoming the above-mentioned challenges. The developer team is glad to find out that they don't need to make any code changes. It's as easy as clicking a few buttons on Azure portal. The developer team is also happy to share with the stakeholders that as Contoso plans to enter the European market, they simply need to add another replica in Europe. 
+
+![Screenshot of using one Azure Web PubSub instance with replica to handle traffic from two countries.](./media/howto-enable-geo-replication/web-pubsub-replica.png  "Replica Example")
+
+## How to enable geo-replication in a Web PubSub resource
+To create a replica in an Azure region, go to your Web PubSub resource and find the **Replicas** blade on the Azure portal and click **Add** to create a replica. It will be automatically enabled upon creation.
+
+![Screenshot of creating replica for Azure Web PubSub on Portal.](./media/howto-enable-geo-replication/web-pubsub-replica-create.png  "Replica create")
+
+After creation, you would be able to view/edit your replica on the portal by clicking the replica name.
+
+![Screenshot of overview blade of Azure Web PubSub replica resource. ](./media/howto-enable-geo-replication/web-pubsub-replica-overview.svg  "Replica Overview")
+
+> [!NOTE]
+> * Geo-replication is a feature available in premium tier.
+> * A replica is considered a separate resource when it comes to billing. See [Pricing](concept-billing-model.md#how-replica-is-billed) for more details. 
+
+## Delete a replica
+After you've created a replica for a Web PubSub resource, you can delete it at any time if it's no longer needed. 
+
+To delete a replica in the Azure portal:
+
+1. Navigate to your Web PubSub resource, and select **Replicas** blade. Click the replica you want to delete.
+2. Click Delete button on the replica overview blade.
+
+## Impact on performance after enabling geo-replication feature
+After a replica is created, your clients will be distributed across selected Azure regions based on their geographical locations. Web PubSub service handles synchronizing data across these replicas automatically and this synchronization incurs a low level of cost. The cost is negligible if your use case primarily involves `sendToGroup()` where the group has more than 100 connections. However, the cost may become more apparent when sending to smaller groups (connection count < 10) or a single user. 
+
+For more performance evaluation, refer to [Performance](concept-performance.md).
+
+## Best practices
+To ensure effective failover management, it is recommended to enable [autoscaling](howto-scale-autoscale.md) for the resource and its replicas. If there are two replicas in a Web PubSub resource and one of the replicas is not available due to an outage, the available replica will receive all the traffic and handle all the WebSocket connections. Auto-scaling can scale up to meet the demand automatically.
+> [!NOTE]
+> * Autoscaling for replica is configured on its own resource level. Scaling primary resource won't change the unit size of the replica.
+
+## Understand how the geo-replication feature works
+
+![Screenshot of the arch of Azure Web PubSub replica. ](./media/howto-enable-geo-replication/web-pubsub-replica-arch.png  "Replica Arch")
+
+1. The client resolves the Fully Qualified Domain Name (FQDN) `contoso.webpubsub.azure.com` of the Web PubSub service. This FQDN points to a Traffic Manager, which returns the  Canonical Name (CNAME) of the nearest regional Web PubSub instance.
+2. With this CNAME, the client establishes a websocket connection to the regional instance.
+3. The two replicas will synchronize data with each other. Messages sent to one replica would be transferred to other replicas if necessary.
+4. In case a replica fails the health check conducted by the Traffic Manager (TM), the TM will exclude the failed instance's endpoint from its domain resolution results.
+
+> [!NOTE]
+> * In the data plane, a primary Azure Web PubSub resource functions identically to its replicas
+
+----