[APIM] Shared workspace gateway

Author: gitName

articles/api-management/how-to-create-workspace.md

@@ -5,7 +5,7 @@ author: dlepow
 ms.topic: how-to
 ms.service: azure-api-management
 ms.author: danlep
-ms.date: 11/12/2024
+ms.date: 12/05/2024
 ms.custom:
 ---
 
@@ -19,7 +19,7 @@ Set up a [workspace](workspaces-overview.md) to enable an API team to manage and
 
 Follow the steps in this article to:
 
-* Create an API Management workspace and a workspace gateway using the Azure portal
+* Create an API Management workspace and associate a workspace gateway using the Azure portal
 * Optionally, isolate the workspace gateway in an Azure virtual network
 * Assign permissions to the workspace
 
@@ -43,7 +43,7 @@ Follow the steps in this article to:
 
 1. On the **Gateway** tab, configure settings for the workspace gateway:
 
-    * In **Gateway details**, enter a gateway name and select the number of scale **Units**. The gateway costs are based on the number of units you select. For more information, see [API Management pricing](https://aka.ms/apimpricing).
+    * In **Gateway details**, select an existing gateway, or enter a new gateway name and select the number of scale **Units**. The gateway costs are based on the number of units. For more information, see [API Management pricing](https://aka.ms/apimpricing).
 
     * In **Network**, select a **Network configuration** for your workspace gateway. 
 
@@ -54,7 +54,7 @@ Follow the steps in this article to:
 
 1. Select **Next**. After validation completes, select **Create**.
 
-It can take from several minutes to up to several hours to create the workspace, workspace gateway, and related resources. To track the deployment progress in the Azure portal, go to the gateway's resource group. In the left menu, under **Settings**, select **Deployments**.
+It can take from several minutes to up to several hours to create the workspace, a new workspace gateway (if selected), and related resources. To track the deployment progress in the Azure portal, go to the gateway's resource group. In the left menu, under **Settings**, select **Deployments**.
 
 After the deployment completes, the new workspace appears in the list on the **Workspaces** page. Select the workspace to manage its settings and resources.
 

articles/api-management/workspaces-overview.md

@@ -60,19 +60,34 @@ While workspaces are managed independently from the API Management service and o
 
 ## Workspace gateway
 
-Each workspace can be associated with workspace gateways to enable runtime of APIs managed within the workspace. The workspace gateway is a standalone Azure resource with the same core functionality as the gateway built into your API Management service. 
-
-Workspace gateways are managed independently from the API Management service and from each other. They ensure isolation of runtime between workspaces, increasing API reliability, resiliency, and security and enabling attribution of runtime issues to workspaces. 
+Each workspace can be associated with workspace gateways to enable runtime of APIs managed within the workspace. A workspace gateway is a standalone Azure resource with the same core functionality as the gateway built into your API Management service. Workspace gateways are managed independently from the API Management service and from each other.  
 
 * For information on the cost of workspace gateways, see [API Management pricing](https://aka.ms/apimpricing).
 * For a detailed comparison of API Management gateways, see [API Management gateways overview](api-management-gateways-overview.md).
 
+### Dedicated versus shared workspace gateway
+
 > [!NOTE]
 > We're introducing the ability to associate multiple workspaces with a workspace gateway, helping organizations manage APIs with workspaces at a lower cost. This feature is being rolled out starting in December 2024 and it may not be available to all eligible services before January. [Learn more](https://aka.ms/apim/workspaces/sharedgateway)
 
+A workspace gateway can be either *dedicated* to a single workspace or *shared* among multiple workspaces:
+
+* **Dedicated** - Provides isolation of runtime between workspaces, increasing API reliability, resiliency, and security and enabling attribution of runtime issues to a workspace.
+
+* **Shared** - Gateway settings including scale, hostname, networking, and TLS configuration, and computing resources such as CPU and memory, are shared by multiple workspaces on a gateway.
+
+<!--- Can a workspace be associated with both a dedicated g/w and a shared g/w?-->
+
+Consider reliability, security, and cost when choosing a deployment model for workspaces.
+
+* **Use dedicated gateways for mission-critical workloads** - To maximize API reliability and security, assign each mission-critical workspace to its own dedicated gateway, avoiding shared use with other workspaces.
+* **Balance reliability, security, and cost** - Associate multiple workspaces with a gateway to balance reliability, security, and cost for non-critical workloads. Distributing workspaces across at least two gateways helps prevent issues, such as resource exhaustion or configuration errors, from impacting all APIs within the organization.
+* **Use distinct gateways for different use cases** - Group workspaces on a gateway based on a use case or network requirements. For instance, separate internal and external APIs by assigning them to different gateways.
+**Prepare to quarantine troubled workspaces** - Use a proxy, such as Azure Application Gateway or Azure Front Door, in front of shared workspace gateways to simplify moving a workspace that's causing resource exhaustion to a different gateway, preventing impact on other workspaces sharing the gateway.
+
 ### Gateway hostname
 
-Each association of a workspace to a workspace gateway creates a unique hostname for APIs managed in that workspace. Default hostnames follow the pattern `<workspace-name>-<hash>.gateway.<region>.azure-api.net`. Currently, custom hostnames aren't supported for workspace gateways.
+Each workspace gateway provides a unique hostname for APIs managed in that workspace. Default hostnames follow the pattern `<gateway-name>-<hash>.gateway.<region>.azure-api.net`. Currently, custom hostnames aren't supported for workspace gateways.
 
 
 ### Network isolation
@@ -94,7 +109,9 @@ For a current list of regions where workspace gateways are available, see [Avail
 ### Gateway constraints
 The following constraints currently apply to workspace gateways:
 
-* A workspace gateway needs to be in the same region as the API Management instance's primary Azure region and in the same subscription. 
+* A workspace gateway needs to be in the same region as the API Management instance's primary Azure region and in the same subscription
+* To associate a shared gateway, a workspace must be in the same API Management instance
+* A shared gateway can be associated with up to 30 workspaces (contact support to increase this limit)
 * A workspace can't be associated with a self-hosted gateway
 * Workspace gateways don't support inbound private endpoints
 * APIs in workspace gateways can't be assigned custom hostnames