Merge pull request #291606 from dlepow/wkspcgw

[APIM] Shared workspace gateway

Author: Stacyrch140

articles/api-management/api-management-key-concepts.md

@@ -231,4 +231,4 @@ Complete the following quickstart and start using Azure API Management:
 [How to create or invite developers]: api-management-howto-create-or-invite-developers.md
 [Policy reference]: ./api-management-policies.md
 [API Management policies]: api-management-howto-policies.md
-[Create an API Management service instance]: get-started-create-service-instance.md
+[Create an API Management service instance]: get-started-create-service-instance.md

articles/api-management/breaking-changes/workspaces-breaking-changes-march-2025.md

@@ -5,7 +5,7 @@ services: api-management
 author: dlepow
 ms.service: azure-api-management
 ms.topic: concept-article
-ms.date: 07/10/2024
+ms.date: 04/16/2025
 ms.author: danlep
 ---
 
@@ -71,8 +71,8 @@ The following are abbreviated steps to add a workspace gateway to a workspace. F
 1. In the left menu, under **APIs**, select **Workspaces**.
 1. Select a workspace.
 1. In the left menu, under **Deployment + infrastructure**, select **Gateways** > **+ Add**.
-1. Complete the wizard to create a gateway. Currently, provisioning of the gateway can take from several minutes to up to 3 hours or longer.
-1. After your gateway is provisioned, go to the gateway's **Overview** page. Note the value of **Runtime hostname**. Use this value to update your client apps that call your workspace's APIs.
+1. Complete the wizard to create a new gateway or associate an existing gateway. Currently, provisioning a new gateway can take from several minutes to up to 3 hours or longer.
+1. After adding a gateway, go to the gateway's **Overview** page. Note the value of **Runtime hostname**. Use this value to update your client apps that call your workspace's APIs.
 1. Repeat the preceding steps for your remaining workspaces.
 
 ### Update client apps to use the new gateway hostname

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: 04/16/2025
 ms.custom:
 ---
 
@@ -19,19 +19,19 @@ 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
 
 > [!NOTE]
 > * Currently, creating a workspace gateway is a long-running operation that can take up to 3 hours or more to complete. 
-> * 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)
+> * Associating multiple workspaces with a workspace gateway is available only for workspace gateways created after April 15, 2025. [Learn more about shared workspace gateways](workspaces-overview.md#workspace-gateway).
 
 ## Prerequisites
 
 * An API Management instance. If you need to, [create one](get-started-create-service-instance.md) in a supported tier.
 * **Owner** or **Contributor** role on the resource group where the API Management instance is deployed, or equivalent permissions to create resources in the resource group.
-* (Optional) An existing or new Azure virtual network and subnet to isolate the workspace gateway's inbound and outbound traffic. For configuration options and requirements, see [Network resource requirements for workspace gateways](virtual-network-workspaces-resources.md).
+* (Optional) A subnet in a new or existing Azure virtual network to isolate the workspace gateway's inbound and outbound traffic. For configuration options and requirements, see [Network resource requirements for workspace gateways](virtual-network-workspaces-resources.md).
 
 ## Create a workspace - portal
 
@@ -41,20 +41,26 @@ Follow the steps in this article to:
 
 1. On the **Basics** tab, enter a descriptive **Display name**, resource **Name**, and optional **Description** for the workspace. Select **Next**.
 
-1. On the **Gateway** tab, configure settings for the workspace gateway:
+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).
+    :::image type="content" source="media/how-to-create-workspace/create-workspace-gateway.png" alt-text="Screenshot of creating a workspace gateway in the portal.":::
 
-    * In **Network**, select a **Network configuration** for your workspace gateway. 
+    * Select **Create new** to create a new workspace gateway, or select **Use existing** to associate the workspace with an existing gateway that has other workspaces deployed on it.
 
-        > [!IMPORTANT]
-        > Plan your workspace's network configuration carefully. You can't change the network configuration after you create the workspace.
-
-    * If you select a network configuration that includes private inbound or private outbound network access, select a **Virtual network** and **Subnet** to isolate the workspace gateway, or create a new one. For network requirements, see [Network resource requirements for workspace gateways](virtual-network-workspaces-resources.md).
+    * If you choose to create a new gateway:
+        * In **Gateway details**, 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. 
+    
+          > [!IMPORTANT]
+          > Plan your workspace's network configuration carefully. You can't change the network configuration after you create the workspace.
+    
+        * If you select a network configuration that includes private inbound or private outbound network access, select a **Virtual network** and **Subnet** to isolate the workspace gateway, or create a new one. For network requirements, see [Network resource requirements for workspace gateways](virtual-network-workspaces-resources.md).
+    
 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**.
+    > [!NOTE]
+    > Creation of a new workspace gateway, if selected, can take up to several hours to complete. 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/media/how-to-create-workspace/create-workspace-gateway.png

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: concept-article
-ms.date: 01/27/2025
+ms.date: 04/16/2025
 ms.author: danlep
 #customer intent: As administrator of an API Management instance, I want to learn about using workspaces to manage APIs in a decentralized way, so that I can enable my development teams to manage and productize their own APIs.
 
@@ -40,6 +40,7 @@ In Azure API Management, use *workspaces* to implement federated API management.
 * Each workspace is associated with one or more [workspace gateways](#workspace-gateway) for routing API traffic to the backend services of APIs in the workspace.
 * The platform team can apply API policies spanning APIs in workspaces, monitor the platform by viewing the logs for all workspaces, and implement a centralized API discovery experience with a developer portal.
 
+
 :::image type="content" source="media/workspaces-overview/workspace-concept.png" alt-text="Conceptual diagram of API Management service with workspaces.":::
 
 [!INCLUDE [api-management-workspace-intro-note](../../includes/api-management-workspace-intro-note.md)]
@@ -62,20 +63,41 @@ The following is a sample workflow for creating and using a workspace.
 
 ## Workspace gateway
 
-Each workspace is associated with one or more 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. 
+Each workspace is configured with one or more *workspace gateways* to enable runtime of APIs managed within the workspace. A workspace gateway is a standalone Azure resource (*workspace gateway premium*) 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 allow for isolation of runtime between workspaces or use cases, increasing API reliability, resiliency, and security and enabling attribution of runtime issues to workspaces. 
 
 * 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).
 
+### Associate workspaces with a workspace gateway
+
+ Depending on your organization's needs, you can associate one workspace or multiple workspaces with a workspace gateway. 
+
+> [!NOTE]
+> Associating multiple workspaces with a workspace gateway is available only for workspace gateways created after April 15, 2025. 
+
+* A workspace gateway has certain configuration (such as virtual network, scale, hostname) and allocated computing resources (CPU, memory, networking resources).
+* Configuration and computing resources are shared by all workspaces deployed on a gateway.
+* Bugs in an API or anomalous traffic may cause exhaustion of these resources, affecting all workspaces on that gateway. In other words, the more workspaces are deployed on a gateway, the higher the risk that an API from a workspace will experience reliability issues caused by an API from another workspace.
+
+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 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, you can distinguish between internal and external APIS by assigning them to separate gateways, each with its own network configuration.
+* **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.
+
 > [!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 needs to be in the same region as the API Management instance's primary Azure region and in the same subscription
+> * All workspaces associated with a workspace gateway must be in the same API Management instance
+> * A workspace gateway can be associated with up to 30 workspaces (contact support to increase this limit)
 
 ### 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 an associated workspace. Default hostnames follow the pattern `<gateway-name>-<hash>.gateway.<region>.azure-api.net`. Use the gateway hostname to route API requests to your workspace's APIs.
 
+Currently, custom hostnames aren't supported for workspace gateways. You can configure Azure Application Gateway or Azure Front Door with a custom hostname in front of a workspace gateway.
 
 ### Network isolation
 
@@ -96,7 +118,6 @@ 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 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

articles/api-management/workspaces-overview.md

@@ -49,6 +49,8 @@ To request a limit increase, create a support request from the Azure portal. For
 | Maximum number of access policies per connection | 100 | 100 | 100 | 100 | 100 |
 | Maximum number of authorization requests per minute per connection | 250 | 250 | 250 | 250 | 250 |
 | Maximum number of [workspaces](../articles/api-management/workspaces-overview.md) per service instance | N/A | N/A | N/A | N/A | 100 |
+| Maximum number of APIs per [workspace](../articles/api-management/workspaces-overview.md#workspace-gateway) | N/A | N/A | N/A | N/A | 50 |
+| Maximum number of workspaces per [workspace gateway premium](../articles/api-management/workspaces-overview.md#workspace-gateway) | N/A | N/A | N/A | N/A | 30 |
 
 <sup>1</sup> Connections are pooled and reused unless explicitly closed by the backend.<br/>
 <sup>2</sup> Includes an up to 2048-bytes long query string.<br/>