Merge pull request #5 from kenieva/service-groups-update

kenieva · web-flow · commit 1286c5e42db8 · 2026-03-10T14:30:02.000-07:00
Improve service groups documentation: critical fixes and clarity
diff --git a/articles/governance/service-groups/create-service-group-member-portal.md b/articles/governance/service-groups/create-service-group-member-portal.md
@@ -9,9 +9,9 @@ ms.date: 11/3/2025
 ---
 
 
-# Quickstart: Add resources or resource containers to service groups with Service Group Member Relationships in Portal 
+# Quickstart: Add resources or resource containers to service groups in the Azure portal
  
-To add resources, resource groups, or subscriptions to a Service Group (preview), you need to create a new Service Group Member Relationship. For more information on service groups, see [Getting started with Service Groups](overview.md).
+To add resources, resource groups, or subscriptions to a Service Group (preview), you create a Service Group Member Relationship. This relationship links the resource to the service group without moving it from its current location. For more information on service groups, see [What are Azure Service Groups?](overview.md).
 
 > [!IMPORTANT]
 > Azure Service Groups is currently in PREVIEW. 
@@ -22,7 +22,11 @@ To add resources, resource groups, or subscriptions to a Service Group (preview)
 - If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/)
   account before you begin.
 
-- To be able to deploy a service group member relationship, you must have Microsoft.Relationship/ServiceGroupMember/write permissions on member resource and [Service Group Contributor](../../role-based-access-control/built-in-roles/management-and-governance.md) at the target service group. 
+- An existing service group. If you haven't created one yet, see [Create a service group in the portal](create-service-group-portal.md).
+
+- To add a member, you need both:
+  - **Microsoft.Relationship/ServiceGroupMember/write** permission on the resource you're adding (the member).
+  - [**Service Group Contributor**](../../role-based-access-control/built-in-roles/management-and-governance.md) role on the target service group.
 
 ## Add members during service group creation 
 
@@ -32,7 +36,7 @@ To add resources, resource groups, or subscriptions to a Service Group (preview)
 
 2. Select to add individual resources, resource groups, or subscriptions. 
 
-3. Once selected, you can use filters to narrow the list as needed. 
+3. Once selected, use filters to narrow the list. You can filter by resource type, subscription, resource group, or location.
 
 4. Once all members are chosen, press **Select**
 
@@ -45,42 +49,50 @@ To add resources, resource groups, or subscriptions to a Service Group (preview)
 
 ## Add members to existing service group 
 
-1. Log into the [Azure portal](https://aka.ms/portalfx/service-groups-internal).
+1. Log into the [Azure portal](https://portal.azure.com/).
 
-2. Select **All services** > **Management + governance**.
+2. Search for **Service Groups** using the top portal search bar.
 
-3. Select **Service Groups**.
+3. Select **Service Groups** from the results.
 
 4. Select the desired Service Group. 
 
-5. In the left hand side service menu, select **members** under relationship management. 
+5. In the left hand side service menu, select **Members** under **Relationship management**. 
 
 :::image type="content" source="./media/members-service-menu.png" alt-text="Screenshot of the relationship management drop down within the left hand context pane on the service group page." Lightbox="./media/members-service-menu.png":::
 
 6. To add members, select the **+Add** button on the top action bar. Select to add individual resources, resource groups, or subscriptions. On the **Add members** pane, select and filter to the desired resources. Once all members are chosen, select **Add**. 
 
 
-## Remove members to existing service group
+## Remove members from an existing service group
 
-1. Log into the [Azure portal](https://aka.ms/portalfx/service-groups-internal).
+1. Log into the [Azure portal](https://portal.azure.com/).
 
-2. Select **All services** > **Management + governance**.
+2. Search for **Service Groups** using the top portal search bar.
 
-3. Select **Service Groups**.
+3. Select **Service Groups** from the results.
 
 4. Select the desired Service Group. 
 
-5. In the left hand side service menu, select **members** under relationship management. 
+5. In the left hand side service menu, select **Members** under **Relationship management**. 
+
+6. Select the members from the list by clicking the check box and press **Delete** from the top action bar. This removes the resource as a member, but doesn't delete the resource itself. 
 
-6. Select the members from the list of members by clicking the check box and press **Delete** from the top action bar. This removes the resource as a member, but won't delete the resource. 
+> [!NOTE]
+> Removing a member only breaks the connection between the resource and the service group. The underlying resource, resource group, or subscription isn't affected.
 
 :::image type="content" source="./media/delete-members.png" alt-text="Screenshot of the delete button within the  service group members page." Lightbox="./media/delete-members.png":::
 
 ## Next step
 
 In this quickstart, you added members to service groups.
 
-To learn more about service groups and how to manage your service group hierarchy, continue to:
+To learn more about managing membership at scale using Bicep, Azure Policy, or PowerShell scripts, see:
 
 > [!div class="nextstepaction"]
-> [Manage your resources with service groups](manage-service-groups.md)
+> [Manage membership at scale](manage-membership.md)
+
+## Related content
+* [What are Azure Service Groups?](overview.md)
+* [How to: Manage Service Groups](manage-service-groups.md)
+* [Add members using REST API](create-service-group-member-rest-api.md)
diff --git a/articles/governance/service-groups/create-service-group-member-rest-api.md b/articles/governance/service-groups/create-service-group-member-rest-api.md
@@ -31,8 +31,16 @@ To add resources, resource groups, or subscriptions to a Service Group (preview)
 
 ## Create in REST API
 
+The `[scope]` in the URLs below refers to the full Azure Resource Manager path of the resource you want to add as a member. The scope varies depending on the type of resource:
+
+| Resource type | Scope format |
+|---|---|
+| Subscription | `subscriptions/{subscriptionId}` |
+| Resource group | `subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}` |
+| Resource | `subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProvider}/{resourceType}/{resourceName}` |
+
 For REST API, use the
-[Service Groups Member- Create or Update]() endpoint to create a new service group member.
+[Service Groups Member - Create or Update](/rest/api/resources/service-group-member/create-or-update) endpoint to create a new service group member.
 
 In this example, we're adding a Virtual Machine [VM1] to a service group [Contoso].
 
@@ -71,7 +79,7 @@ specify the service group as the parent, use the **TargetID** property.
 ## Clean up resources
 
 To remove the service group created in this document, use the
-[Service Group Member Delete]() endpoint:
+[Service Group Member - Delete](/rest/api/resources/service-group-member/delete) endpoint:
 
 - REST API URI
 
@@ -81,6 +89,22 @@ To remove the service group created in this document, use the
 
 - No Request Body
 
+## Verify your service group member
+
+The Create Service Group Member API is an asynchronous call. A successful response means the request was accepted, but the operation may still be processing. To check the operation status:
+
+1. Look for the **Azure-AsyncOperation** header in the response from the PUT request.
+2. Make a GET request to the URL in that header to check the operation status.
+
+```json
+{
+    "status": "Succeeded"
+}
+```
+
+Possible status values include `Succeeded`, `Failed`, and `InProgress`. Wait for the operation to complete before relying on the membership relationship.
+
+For more information on checking operation status, see [Checking for Service Group Operation Status](manage-service-groups.md#checking-for-service-group-operation-status).
 
 ## Next step
 
diff --git a/articles/governance/service-groups/create-service-group-portal.md b/articles/governance/service-groups/create-service-group-portal.md
@@ -13,7 +13,7 @@ ms.custom:
 
 # Quickstart: Create a service group (preview) in the portal
  
-Azure Service Groups offer a flexible way to organize and manage resources across subscriptions and resource groups, parallel to any existing Azure resource hierarchy. They're ideal for scenarios requiring cross-boundary grouping, minimal permissions, and aggregations of data across resources. These features empower teams to create tailored resource collections that align with operational, organizational, or persona-based needs. This article helps give you an overview of what service groups are, the scenarios to use them for, and provide guidance on how to get started. For more information on service groups, see [Getting started with Service Groups](overview.md).
+Azure Service Groups let you create flexible, custom groupings of your Azure resources across subscriptions and resource groups, without changing your existing resource hierarchy. For a full overview of capabilities and scenarios, see [What are Azure Service Groups?](overview.md).
 
 > [!IMPORTANT]
 > Azure Service Groups is currently in public preview. 
@@ -23,53 +23,56 @@ Azure Service Groups offer a flexible way to organize and manage resources acros
 
 - If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn)
   account before you begin.
+- You need **Service Group Contributor** or **Service Group Administrator** role on the parent service group where you want to create the new group. If creating under the root service group, see [Root Service Group access](./overview.md#the-root-service-group).
 
 ## Create in Azure portal
 
 1. Log into the [Azure portal](https://portal.azure.com/).
-3. Search **Service Groups**.
-4. Select **+ Create Service Group**.
+
+2. In the top search bar, search for **Service Groups** and select **Service Groups** from the results.
+
+3. Select **+ Create Service Group**.
     
 :::image type="content" source="./media/create-service-group.png" alt-text="Screenshot of new Service Group screen." Lightbox = "./media/create-service-group.png" :::
-5. Fill in the service group ID field
-
-   * The **Service Group ID** is the directory unique identifier that is used to submit commands
-         on this service group. This identifier isn't editable after creation as it's used throughout
-         the Azure system to identify this group. The
-         [root service group](./overview.md#the-root-service-group) is
-         automatically created with an ID that is the Microsoft Entra ID. For all other
-         service groups, assign a unique ID.
-   * The display name field is the name that is displayed within the Azure portal. A separate
-         display name is an optional field when creating the service group and can be changed at any time.
-6. Select the **Parent Service Group**. 
+
+4. Fill in the **Service Group ID** field.
+
+   * The **Service Group ID** is a unique identifier used to reference this service group in API calls, scripts, and policies. This ID **can't be changed** after creation, so choose a meaningful and descriptive name (for example, `platform-networking` or `project-contoso-prod`).
+   * The ID must be globally unique across all Microsoft Entra tenants. Two tenants can't have a Service Group with the same ID.
+   * The **Display name** field is optional and can be changed at any time. It controls how the service group appears in the Azure portal.
+
+5. Select the **Parent Service Group**. 
     
-   * If you don't have a parent service group, or don't know what to pick, select the Root Service Group which has same ID as the tenant's ID. _"Microsoft.Management/serviceGroups[tenantId]"_
+   * If you don't have a parent service group, or don't know what to pick, select the Root Service Group which has the same ID as your tenant's ID: `Microsoft.Management/serviceGroups/[tenantId]`
+
+6. Select **Next** to proceed.
 
-7. Select "Next" 
-8. The review page shows
+7. The review page shows a summary of your choices.
 
 :::image type="content" source="./media/create-review-service-group.png" alt-text="Screenshot of the review page for creating a new service group" Lightbox="./media/create-review-service-group.png":::
 
-9. If all information is correct, select **Create**
+8. If all information is correct, select **Create**.
+
+> [!TIP]
+> After creating your service group, the next step is to add members. See [Add members to a service group in the portal](create-service-group-member-portal.md) or [Add members using REST API](create-service-group-member-rest-api.md).
 
 ## Clean up resources
 
-1. Search **Service Groups**.
+1. In the top search bar, search for **Service Groups** and select **Service Groups** from the results.
 
-1. Find the service group created that you want to delete, select it, then select the box. 
+1. Find the service group you want to delete, select the checkbox next to it.
 
-1. Select the **delete** button at the top of the page.  
+1. Select the **Delete** button at the top of the page.  
 
 ## Next steps
 
-In this quickstart, you created a service group. The service group can hold subscriptions, resource groups, or resources.
-
-To learn more about service groups and how to manage your hierarchy, continue to:
+In this quickstart, you created a service group. The next step is to add resources, resource groups, or subscriptions as members.
 
 > [!div class="nextstepaction"]
-> [How to: Manage Service Groups](manage-service-groups.md)
+> [Add members to a service group in the portal](create-service-group-member-portal.md)
 
 ## Related content
 * [What are Azure Service Groups?](overview.md)
 * [How to: Manage Service Groups](manage-service-groups.md)
-* [Connect service group members with REST API](create-service-group-member-rest-api.md)
+* [Add members using REST API](create-service-group-member-rest-api.md)
+* [Manage membership at scale](manage-membership.md)
diff --git a/articles/governance/service-groups/index.yml b/articles/governance/service-groups/index.yml
@@ -1,11 +1,11 @@
 ### YamlMime:Landing
 
 title: Azure Service Groups documentation
-summary: Azure Service Groups.
+summary: Organize and manage resources across subscriptions with flexible, custom groupings using Azure Service Groups.
 
 metadata:
   title: Azure Service Groups documentation
-  description: Azure Service Groups documentation.
+  description: Learn how to create flexible resource groupings across subscriptions using Azure Service Groups. Build custom views for teams, projects, and workloads with minimal permissions.
   ms.service: azure-policy
   ms.topic: landing-page
   author: kenieva
@@ -20,13 +20,19 @@ landingContent:
         links:
           - text: What are Azure Service Groups?
             url: ./overview.md
-      - linkListType: how-to-guide 
+      - linkListType: quickstart
         links:
+          - text: Create a service group in the Azure portal
+            url: ./create-service-group-portal.md
           - text: Create a service group with REST API
             url: ./create-service-group-rest-api.md
-          - text: Create a service group in Azure portal
-            url: ./create-service-group-portal.md
-          - text: Connect Service Group members using the REST API
+          - text: Add members in the Azure portal
+            url: ./create-service-group-member-portal.md
+          - text: Add members with REST API
             url: ./create-service-group-member-rest-api.md
-          - text: How to use Service Groups to manage resources
+      - linkListType: how-to-guide
+        links:
+          - text: Manage Service Groups and members
             url: ./manage-service-groups.md
+          - text: Manage membership at scale
+            url: ./manage-membership.md
diff --git a/articles/governance/service-groups/manage-service-groups.md b/articles/governance/service-groups/manage-service-groups.md
@@ -29,8 +29,8 @@ This section shows you how to manage service group's actions create, read, updat
 
 - HTTP method: **PUT** 
 - Resource Provider: **Microsoft.Management**
-- API Version: **2024-04-01-preview**
-- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-04-01-preview
+- API Version: **2024-02-01-preview**
+- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-02-01-preview
 
 Request Body:
 ```json
@@ -61,7 +61,7 @@ API Response:
 }
 ```
 
-* **GroupID**:  Required field in the URL that uniquely identifies the Service Group. This ID is immutable once created
+* **GroupID**:Required field in the URL that uniquely identifies the Service Group. This ID is immutable once created
   * Service groups must have a Global Unique Name. This means it isn't specific to Tenant it's being created in, but all tenants in that cloud. Ex. Public Cloud across all tenants.  
 * **Kind**: Optional string property that is used by Resource Providers for scenarios. Kind value is immutable after creation.  
 * **Display Name**: Optional String Property to display a different name rather than the Group ID
@@ -75,8 +75,8 @@ To update a service group, a PUT or PATCH API method can be used which have the
 
 - HTTP method: **PUT** or **PATCH**
 - Resource Provider: **Microsoft.Management**
-- API Version: **2024-04-01-preview**
-- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-04-01-preview
+- API Version: **2024-02-01-preview**
+- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-02-01-preview
 
 
 Request Body: 
@@ -113,8 +113,8 @@ For descriptions of the properties see [Create Service Group](#create-service-gr
 
 - HTTP method: **DELETE** 
 - Resource Provider: **Microsoft.Management**
-- API Version: **2024-04-01-preview**
-- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-04-01-preview
+- API Version: **2024-02-01-preview**
+- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-02-01-preview
 - No Request Body
 
 API Response: 
@@ -124,8 +124,8 @@ The DELETE response returns an HTTP Status Code. The HTTP DELETE Action is an As
 
 - HTTP method: **GET** 
 - Resource Provider: **Microsoft.Management**
-- API Version: **2024-04-01-preview**
-- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-04-01-preview
+- API Version: **2024-02-01-preview**
+- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]?api-version=2024-02-01-preview
 - No Request Body
 
 API Response: 
@@ -151,8 +151,8 @@ Service Groups has an API that allows you to get all the Service Group Parents a
 
 - HTTP method: **POST** 
 - Resource Provider: **Microsoft.Management**
-- API Version: **2024-04-01-preview**
-- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]/listAncestors?api-version=2024-04-01-preview
+- API Version: **2024-02-01-preview**
+- URL: https://management.azure.com/providers/Microsoft.Management/serviceGroups/[groupID]/listAncestors?api-version=2024-02-01-preview
 
 - No Request Body
 
@@ -206,6 +206,14 @@ Service group members are resources, resource groups, or subscriptions that are
 ### Create a Service Group Member
 Resources, resource groups, and subscriptions can all be made members of a service group. The Service Group Member relationship is created as an extension off the member that is being connected to the group.  
 
+The `[scope]` in the URLs below refers to the full Azure Resource Manager path of the resource being added as a member:
+
+| Resource type | Scope format |
+|---|---|
+| Subscription | `subscriptions/{subscriptionId}` |
+| Resource group | `subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}` |
+| Resource | `subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProvider}/{resourceType}/{resourceName}` |
+
 - HTTP method: **PUT** 
 - Resource Provider: **Microsoft.Relationships**
 - API Version: **2023-09-01-preview**
diff --git a/articles/governance/service-groups/overview.md b/articles/governance/service-groups/overview.md
diff --git a/articles/governance/service-groups/toc.yml b/articles/governance/service-groups/toc.yml
