Merge pull request #264228 from dlepow/wkspc

[APIM] Workspaces breaking changes

Author: Stacyrch140

articles/api-management/TOC.yml

@@ -639,6 +639,8 @@
       href: breaking-changes/self-hosted-gateway-v0-v1-retirement-oct-2023.md
     - name: Deprecated (legacy) developer portal (October 2023)
       href: breaking-changes/legacy-portal-retirement-oct-2023.md
+    - name: Workspaces breaking changes (June 2024)
+      href: breaking-changes/workspaces-breaking-changes-june-2024.md
     - name: stv1 compute platform retirement (August 2024)
       href: breaking-changes/stv1-platform-retirement-august-2024.md
     - name: ADAL-based identity provider retirement (September 2025)

articles/api-management/breaking-changes/overview.md

@@ -2,12 +2,12 @@
 title: Upcoming Breaking Changes in Azure API Management | Microsoft Docs
 description: A list of all the upcoming breaking changes for Azure API Management
 services: api-management
-author: adrianhall
+author: dlepow
 
 ms.service: api-management
 ms.topic: reference
-ms.date: 03/15/2023
-ms.author: adhal
+ms.date: 01/25/2024
+ms.author: danlep
 ---
 
 # Upcoming breaking changes
@@ -22,6 +22,7 @@ The following table lists all the upcoming breaking changes and feature retireme
 | [API version retirements][api2023] | September 30, 2023 |
 | [Deprecated (legacy) portal retirement][devportal2023] | October 31, 2023 |
 | [Self-hosted gateway v0/v1 retirement][shgwv0v1] | October 1, 2023 |
+| [Workspaces breaking changes][workspaces2024] | June 14, 2024 |
 | [stv1 platform retirement][stv12024] | August 31, 2024 |
 | [ADAL-based Microsoft Entra ID or Azure AD B2C identity provider retirement][msal2025] | September 30, 2025 |
 | [CAPTCHA endpoint update][captcha2025] | September 30, 2025 |
@@ -36,3 +37,4 @@ The following table lists all the upcoming breaking changes and feature retireme
 [msal2025]: ./identity-provider-adal-retirement-sep-2025.md
 [captcha2025]: ./captcha-endpoint-change-sep-2025.md
 [metrics2023]: ./metrics-retirement-aug-2023.md
+[workspaces2024]: ./workspaces-breaking-changes-june-2024.md

articles/api-management/breaking-changes/workspaces-breaking-changes-june-2024.md

@@ -0,0 +1,71 @@
+---
+title: Azure API Management workspaces - breaking changes (June 2024) | Microsoft Docs
+description: Azure API Management is updating the workspaces (preview) with breaking changes. If your service uses workspaces, you may need to update workspace configurations.
+services: api-management 
+author: dlepow
+ms.service: api-management
+ms.topic: reference
+ms.date: 03/07/2024
+ms.author: danlep
+---
+
+# Workspaces - breaking changes (June 2024)
+
+On 14 June 2024, as part of our development of [workspaces](../workspaces-overview.md) (preview) in Azure API Management, we're introducing several breaking changes. 
+
+These changes will have no effect on the availability of your API Management service. However, you may have to take action to continue using full workspaces functionality beyond 14 June 2024.
+
+## Is my service affected by these changes?
+
+Your service may be affected by these changes if you configured workspaces (preview) in your API Management instance. This feature was introduced in the **Premium**, **Standard**, and **Developer** tiers.
+
+## Breaking changes
+
+Review the following breaking changes to determine if you need to take action:
+
+### Change to supported service tiers
+
+The following service tiers will no longer support workspaces: **Standard** and **Developer**. Workspaces will be available in the **Premium** tier. 
+
+For availability in the v2 tiers, see [Azure API Management v2 tiers](../v2-service-tiers-overview.md).
+
+### Changes to support for assigning service-level entities in workspaces
+
+The following assignments of workspace entities to service-level entities will no longer be supported:
+
+* Assign workspace APIs to service-level products
+* Assign workspace APIs to service-level tags
+* Assign workspace products to service-level tags
+* Assign service-level groups to workspace products for visibility controls
+
+    > [!NOTE]
+    > The built-in Guests and Developer groups will continue to be available in workspaces.
+
+### Changes to supported context objects
+
+The following `context` objects will no longer be supported in workspace policies or in the all-APIs policy on the service level:
+
+* `context.Api.Workspace`
+* `context.Product.Workspace`
+
+The `context.Workspace` object can be used instead.
+
+
+> [!NOTE]
+> You can continue to reference users from the service level in the `context` object in workspace-level policies.
+
+## What is the deadline for the change?
+
+The breaking changes are effective 14 June 2024. We strongly recommend that you make all required changes to the configuration of workspaces before then.
+
+## Help and support
+
+If you have questions, get answers from community experts in [Microsoft Q&A](https://aka.ms/apim/azureqa/change/captcha-2022). If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview).
+
+## More information
+
+* [Workspaces overview](../workspaces-overview.md)
+
+## Related content
+
+See all [upcoming breaking changes and feature retirements](overview.md).

articles/api-management/v2-service-tiers-overview.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: conceptual
-ms.date: 10/02/2023
+ms.date: 01/31/2024
 ms.author: danlep
 ms.custom: references_regions
 ---
@@ -85,7 +85,7 @@ Currently, the following API Management capabilities are unavailable in the v2 t
 * Built-in analytics
 * Inbound connection using a private endpoint
 * Upgrade to v2 tiers from v1 tiers 
-* Workspaces
+* Workspaces (*Standard v2*)
 
 **Developer portal**
 * Delegation of user registration and product subscription

articles/api-management/workspaces-overview.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: conceptual
-ms.date: 03/10/2023
+ms.date: 01/25/2024
 ms.author: danlep
 ms.custom:
 ---
@@ -15,14 +15,14 @@ ms.custom:
 
 In API Management, *workspaces* allow 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). 
 
-[!INCLUDE [api-management-availability-premium-dev-standard](../../includes/api-management-availability-premium-dev-standard.md)]
+[!INCLUDE [api-management-availability-premium](../../includes/api-management-availability-premium.md)]
 
 
 > [!NOTE]
 > * Workspaces are a preview feature of API Management and subject to certain [limitations](#preview-limitations).
 > * Workspaces are supported in API Management REST API version 2022-09-01-preview or later.
 > * For pricing considerations, see [API Management pricing](https://azure.microsoft.com/pricing/details/api-management/).
-
+> * See [upcoming breaking changes](./breaking-changes/workspaces-breaking-changes-june-2024.md) for workspaces.
 
 ## Example scenario overview
 
@@ -48,9 +48,7 @@ The following resources can be managed in the workspaces preview.
 
 * Apply a policy for all APIs in a workspace. 
 
-* Use `context.Api.Workspace` and `context.Product.Workspace` objects in workspace-scoped policies and in the all-APIs policy on the service level. 
-
-* Describe APIs with tags from the workspace level or from the service level. 
+* Describe APIs with tags from the workspace level. 
 
 * Define named values, policy fragments, and schemas for request and response validation for use in workspace-scoped policies. 
 
@@ -64,11 +62,7 @@ The following resources can be managed in the workspaces preview.
 
 ### Products and subscriptions
 
-* Publish APIs with products. APIs in a workspace can be part of a service-level product or a workspace-level product. 
-
-    * Workspace-level product -  Visibility can be configured based on user membership in a workspace-level or a service-level group. 
-
-    * Service-level product - Visibility can be configured only for service-level groups. 
+* Publish APIs with products. APIs in a workspace can only be part of a workspace-level product. Visibility can be configured based on user membership in a workspace-level or a service-level group. 
 
 * Manage access to APIs with subscriptions. Subscriptions requested to an API or product within a workspace are created in that workspace. 
 
@@ -80,7 +74,7 @@ The following resources can be managed in the workspaces preview.
 
 Azure RBAC is used to configure workspace collaborators' permissions to read and edit entities in the workspace. For a list of roles, see [How to use role-based access control in API Management](api-management-role-based-access-control.md).
 
-Workspace members must be assigned both a service-scoped role and a workspace-scoped role, or granted equivalent permissions using custom roles. The service-scoped role enables referencing service-level resources from workspace-level resources. For example, publish an API from a workspace with a service-level product, assign a service-level tag to an API, or organize a user into a workspace-level group to control API and product visibility.  
+Workspace members must be assigned both a service-scoped role and a workspace-scoped role, or granted equivalent permissions using custom roles. The service-scoped role enables referencing certain service-level resources from workspace-level resources. For example, organize a user into a workspace-level group to control API and product visibility.  
 
 > [!NOTE]
 > For easier management, set up Microsoft Entra groups to assign workspace permissions to multiple users.
@@ -95,7 +89,7 @@ Workspace members must be assigned both a service-scoped role and a workspace-sc
     * API gateways, including scaling, locations, and self-hosted gateways
 
 
-* **Resource references** - Resources in a workspace can reference other resources in the workspace and the following resources from the service level: products, tags, and users. They can't reference resources from another workspace. 
+* **Resource references** - Resources in a workspace can reference other resources in the workspace and users from the service level. They can't reference resources from another workspace. 
 
     For security reasons, it's not possible to reference service-level resources from workspace-level policies (for example, named values) or by resource names, such as `backend-id` in the [set-backend-service](set-backend-service-policy.md) policy.
 
@@ -137,10 +131,13 @@ Therefore, the following sample scenarios aren't currently supported in workspac
 
 * Specifying API authorization server information (for example, for the developer portal)
 
-Workspace APIs can't be published to self-hosted gateways.
+* Publishing workspace APIs to self-hosted gateways
 
-All resources in an API Management service need to have unique names, even if they are located in different workspaces.
+> [!IMPORTANT]
+> All resources in an API Management service need to have unique names, even if they are located in different workspaces.
+> 
 
-## Next steps
+## Related content
 
 * [Create a workspace](how-to-create-workspace.md)
+* [Workspaces breaking changes - June 2024](breaking-changes/workspaces-breaking-changes-june-2024.md)