review comments

Author: gitName

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

@@ -186,6 +186,14 @@ API Management service owners can also create custom groups or use external grou
 * [How to create and use groups][How to create and use groups]
 * [How to manage user accounts](api-management-howto-create-or-invite-developers.md)
 
+### Workspaces
+
+Workspaces support a federated API management model by allowing decentralized API development teams to manage and productize their own APIs, while a central API platform team maintains the API Management infrastructure. Each workspace contains APIs, products, subscriptions, and related entities that are accessible only to the workspace collaborators. Access is controlled through Azure role-based access control (RBAC). Each workspace is associated with one or more workspace gateways that route API traffic to its backend services.
+
+**More information**:
+
+* [Workspaces in API Management](workspaces-overview.md)
+
 ### Policies
 
 With [policies][API Management policies], an API provider can change the behavior of an API through configuration. Policies are a collection of statements that are executed sequentially on the request or response of an API. Popular statements include format conversion from XML to JSON and call-rate limiting to restrict the number of incoming calls from a developer. For a complete list, see [API Management policies][Policy reference].
@@ -222,4 +230,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/how-to-create-workspace.md

@@ -25,7 +25,7 @@ Follow the steps in this article to:
 
 > [!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 shared workspace gateway, helping organizations manage APIs with workspaces at a lower cost. This feature is being rolled out starting in December 2024. Shared gateways will only be available in workspaces created after the service update. [Learn more](https://aka.ms/apim/workspaces/sharedgateway)
+> * Associating multiple workspaces to a workspace gateway is available only for workspace gateways created after March 1, 2025. [Learn more about shared workspace gateways](workspaces-overview.md#workspace-gateway).
 
 ## Prerequisites
 
@@ -45,7 +45,7 @@ Follow the steps in this article to:
 
     :::image type="content" source="media/how-to-create-workspace/create-workspace-gateway.png" alt-text="Screenshot of creating a workspace gateway in the portal.":::
 
-    * Select **Create new** to create a new workspace gateway, or select **Use existing** to share an existing 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.
 
     * 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).

articles/api-management/workspaces-overview.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: concept-article
-ms.date: 01/27/2025
+ms.date: 02/25/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.
 
@@ -70,16 +70,16 @@ Workspace gateways are managed independently from the API Management service and
 * 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
+### Dedicated versus shared workspace gateways
 
 > [!NOTE]
-> We're introducing the ability to associate multiple workspaces with a shared workspace gateway, helping organizations manage APIs with workspaces at a lower cost. This feature is being rolled out starting in December 2024. Shared gateways will only be available in workspaces created after the service update. [Learn more](https://aka.ms/apim/workspaces/sharedgateway)
+> Associating multiple workspaces to a workspace gateway is available only for workspace gateways created after March 1, 2025. 
 
-A workspace gateway can be either *dedicated* to a single workspace or *shared* among multiple workspaces:
+Each workspace gateway can be associated with one or 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** - Shares gateway settings including scale, hostname, networking, and TLS configuration, and computing resources such as CPU and memory by multiple workspaces.
+* 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.
 
@@ -90,12 +90,14 @@ Consider reliability, security, and cost when choosing a deployment model for wo
 
 > [!NOTE]
 > * 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 that share a workspace gateway 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)
+> * 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 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`. Currently, custom hostnames aren't supported for workspace gateways. Use the gateway hostname to route API requests to your workspace's APIs.
+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 a proxy, such as Azure Application Gateway or Azure Front Door, with a custom hostname.
 
 ### Network isolation
 
@@ -161,7 +163,7 @@ Workspaces are designed to be self-contained to maximize segregation of administ
 
 ## Migrate from preview workspaces
 
-If you created preview workspaces in Azure API Management and want to continue using them, migrate your workspaces to the generally available version by associating a dedicated or shared workspace gateway with each workspace.
+If you created preview workspaces in Azure API Management and want to continue using them, migrate your workspaces to the generally available version by associating a workspace gateway with each workspace.
 
 For details and to learn about other changes that could affect your preview workspaces, see [Workspaces breaking changes (March 2025)](breaking-changes/workspaces-breaking-changes-march-2025.md).
 

includes/api-management-service-limits.md

@@ -49,8 +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) per service instance | N/A | N/A | N/A | N/A | 50 |
-| Maximum number of workspaces per [shared workspace gateway premium](../articles/api-management/workspaces-overview.md#workspace-gateway) per service instance | N/A | N/A | N/A | N/A | 30 |
+| 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/>