Merge pull request #81 from Azure/policymg

feat: add management group scope support for Policy and Role constructs

Author: archit017

API.md

@@ -4,7 +4,7 @@ This module provides a unified, version-aware implementation for managing Azure
 
 ## Overview
 
-Azure Policy Assignments apply policy definitions to specific scopes (subscription, resource group, or resource) and provide parameter values for policy enforcement. Policy assignments can configure enforcement modes, managed identities for remediation, and custom non-compliance messages.
+Azure Policy Assignments apply policy definitions to specific scopes (management group, subscription, resource group, or resource) and provide parameter values for policy enforcement. Policy assignments can configure enforcement modes, managed identities for remediation, and custom non-compliance messages.
 
 ## Key Features
 
@@ -13,7 +13,7 @@ Azure Policy Assignments apply policy definitions to specific scopes (subscripti
 - **Schema-Driven Validation**: Built-in validation based on Azure API schemas
 - **Type-Safe**: Full TypeScript support with comprehensive interfaces
 - **JSII Compatible**: Can be used from multiple programming languages
-- **Flexible Scoping**: Support for subscription, resource group, and resource-level assignments
+- **Flexible Scoping**: Support for management group, subscription, resource group, and resource-level assignments
 - **Enforcement Modes**: Control whether policies are enforced or audited
 - **Managed Identity Support**: Enable remediation for deployIfNotExists and modify policies
 - **Scope Exclusions**: Exclude specific scopes from policy evaluation
@@ -285,6 +285,14 @@ console.log("Enforcement Mode:", assignment.enforcementMode);
 
 Policy assignments can be applied at different organizational levels:
 
+#### Management Group Scope
+
+```typescript
+scope: "/providers/Microsoft.Management/managementGroups/my-mg";
+```
+
+Applies to all subscriptions and resources within the management group hierarchy. This is the highest level scope and is ideal for organization-wide policies.
+
 #### Subscription Scope
 
 ```typescript
@@ -390,6 +398,40 @@ Policy Assignment constructs expose the following outputs:
 
 ## Examples
 
+### Assign Policy at Management Group Level
+
+```typescript
+// Apply an organization-wide policy at management group scope
+const mgPolicyDefinition = new PolicyDefinition(this, "org-policy", {
+  name: "require-resource-tags",
+  parentId: "/providers/Microsoft.Management/managementGroups/my-mg",
+  displayName: "Require Resource Tags",
+  policyRule: {
+    if: {
+      field: "tags['CostCenter']",
+      exists: "false",
+    },
+    then: {
+      effect: "deny",
+    },
+  },
+});
+
+const mgAssignment = new PolicyAssignment(this, "mg-tag-assignment", {
+  name: "require-tags-org-wide",
+  displayName: "Require Tags Across Organization",
+  description: "Enforces required tags across all subscriptions in the management group",
+  policyDefinitionId: mgPolicyDefinition.id,
+  scope: "/providers/Microsoft.Management/managementGroups/my-mg",
+  nonComplianceMessages: [
+    {
+      message:
+        "All resources must have a CostCenter tag for billing and cost allocation purposes.",
+    },
+  ],
+});
+```
+
 ### Assign Tag Policy at Subscription Level
 
 ```typescript

LICENSE

@@ -63,7 +63,7 @@ const COMMON_PROPERTIES: { [key: string]: PropertyDefinition } = {
     dataType: PropertyType.STRING,
     required: true,
     description:
-      "The scope at which the policy assignment is applied (subscription, resource group, or resource)",
+      "The scope at which the policy assignment is applied (management group, subscription, resource group, or resource)",
     validation: [
       {
         ruleType: ValidationRuleType.REQUIRED,

src/azure-policyassignment/README.md

@@ -3,8 +3,8 @@
  *
  * This class provides a version-aware implementation for managing Azure Policy Assignments
  * using the AZAPI provider. Policy assignments apply policy definitions to specific scopes
- * (subscription, resource group, or resource) and can provide parameter values and
- * enforcement settings.
+ * (management group, subscription, resource group, or resource) and can provide parameter
+ * values and enforcement settings.
  *
  * Supported API Versions:
  * - 2022-06-01 (Active, Latest)
@@ -89,9 +89,10 @@ export interface PolicyAssignmentProps extends AzapiResourceProps {
 
   /**
    * The scope at which the policy assignment is applied
-   * Can be a subscription, resource group, or resource
+   * Can be a management group, subscription, resource group, or resource
    * Required property
    *
+   * @example "/providers/Microsoft.Management/managementGroups/my-mg"
    * @example "/subscriptions/00000000-0000-0000-0000-000000000000"
    * @example "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-name"
    */
@@ -262,8 +263,9 @@ export interface PolicyAssignmentBody {
  * Policy Assignments. It automatically handles version resolution, schema validation,
  * and property transformation.
  *
- * Note: Policy assignments can be deployed at subscription, resource group, or resource scope.
- * Like policy definitions, they do not have a location property as they are not region-specific.
+ * Note: Policy assignments can be deployed at management group, subscription, resource group,
+ * or resource scope. Like policy definitions, they do not have a location property as they
+ * are not region-specific.
  *
  * @example
  * // Basic policy assignment:
@@ -302,6 +304,16 @@ export interface PolicyAssignmentBody {
  *   }
  * });
  *
+ * @example
+ * // Policy assignment at management group scope:
+ * const mgAssignment = new PolicyAssignment(this, "mgAssignment", {
+ *   name: "mg-policy-assignment",
+ *   policyDefinitionId: "/providers/Microsoft.Authorization/policyDefinitions/policy-id",
+ *   scope: "/providers/Microsoft.Management/managementGroups/my-mg",
+ *   displayName: "Management Group Policy",
+ *   description: "Applies policy across the entire management group hierarchy"
+ * });
+ *
  * @stability stable
  */
 export class PolicyAssignment extends AzapiResource {

src/azure-policyassignment/lib/policy-assignment-schemas.ts

@@ -793,6 +793,19 @@ describe("PolicyAssignment - Unified Implementation", () => {
   });
 
   describe("Scope Configurations", () => {
+    it("should support management group scope", () => {
+      const assignment = new PolicyAssignment(stack, "ManagementGroupScope", {
+        name: "mg-assignment",
+        policyDefinitionId:
+          "/providers/Microsoft.Authorization/policyDefinitions/test-policy",
+        scope: "/providers/Microsoft.Management/managementGroups/my-mg",
+      });
+
+      expect(assignment.assignmentScope).toContain(
+        "/providers/Microsoft.Management/managementGroups/",
+      );
+    });
+
     it("should support subscription scope", () => {
       const assignment = new PolicyAssignment(stack, "SubscriptionScope", {
         name: "subscription-assignment",

src/azure-policyassignment/lib/policy-assignment.ts

@@ -344,6 +344,32 @@ Policy Definition constructs expose the following outputs:
 
 ## Examples
 
+### Policy Definition at Management Group Scope
+
+```typescript
+// Create a policy definition at management group scope
+// This makes the policy available to all subscriptions under the management group
+new PolicyDefinition(this, "mg-policy", {
+  name: "org-wide-tag-policy",
+  parentId: "/providers/Microsoft.Management/managementGroups/my-mg",
+  displayName: "Organization-Wide Tag Policy",
+  description: "Enforces required tags across all subscriptions in the organization",
+  policyRule: {
+    if: {
+      field: "tags['CostCenter']",
+      exists: "false",
+    },
+    then: {
+      effect: "deny",
+    },
+  },
+  metadata: {
+    category: "Tags",
+    version: "1.0.0",
+  },
+});
+```
+
 ### Require Specific Resource Locations
 
 ```typescript

src/azure-policyassignment/test/policy-assignment.spec.ts

@@ -112,6 +112,17 @@ export interface PolicyDefinitionProps extends AzapiResourceProps {
    */
   readonly metadata?: any;
 
+  /**
+   * The parent scope where the policy definition should be created
+   * Can be a management group or subscription scope
+   * If not specified, defaults to subscription scope
+   *
+   * @example "/providers/Microsoft.Management/managementGroups/my-mg"
+   * @example "/subscriptions/00000000-0000-0000-0000-000000000000"
+   * @defaultValue Subscription scope (auto-detected from client config)
+   */
+  readonly parentId?: string;
+
   /**
    * The lifecycle rules to ignore changes
    * @example ["metadata"]
@@ -223,6 +234,24 @@ export interface PolicyDefinitionBody {
  *   }
  * });
  *
+ * @example
+ * // Policy definition at management group scope:
+ * const mgPolicyDefinition = new PolicyDefinition(this, "mgPolicy", {
+ *   name: "mg-require-tag-policy",
+ *   parentId: "/providers/Microsoft.Management/managementGroups/my-mg",
+ *   displayName: "Management Group Tag Policy",
+ *   description: "Enforces tags across the management group hierarchy",
+ *   policyRule: {
+ *     if: {
+ *       field: "tags['CostCenter']",
+ *       exists: "false"
+ *     },
+ *     then: {
+ *       effect: "deny"
+ *     }
+ *   }
+ * });
+ *
  * @stability stable
  */
 export class PolicyDefinition extends AzapiResource {
@@ -368,6 +397,22 @@ export class PolicyDefinition extends AzapiResource {
     };
   }
 
+  /**
+   * Overrides parent ID resolution to use parentId from props if provided
+   * Policy definitions can be deployed at subscription or management group scope
+   */
+  protected resolveParentId(props: any): string {
+    const typedProps = props as PolicyDefinitionProps;
+
+    // If explicit parentId is provided, use it (management group or subscription)
+    if (typedProps.parentId) {
+      return typedProps.parentId;
+    }
+
+    // Otherwise, fall back to default subscription scope
+    return super.resolveParentId(props);
+  }
+
   // =============================================================================
   // PUBLIC METHODS FOR POLICY DEFINITION OPERATIONS
   // =============================================================================

src/azure-policydefinition/README.md

@@ -1062,4 +1062,106 @@ describe("PolicyDefinition - Unified Implementation", () => {
       expect(resourceProviderPolicy.policyMode).toBe("Microsoft.KeyVault.Data");
     });
   });
+
+  describe("Management Group Scope Support", () => {
+    it("should support management group scope via parentId property", () => {
+      const mgPolicyDefinition = new PolicyDefinition(
+        stack,
+        "MgPolicyDefinition",
+        {
+          name: "mg-policy",
+          parentId: "/providers/Microsoft.Management/managementGroups/my-mg",
+          displayName: "Management Group Policy",
+          description: "Policy deployed at management group scope",
+          policyRule: {
+            if: {
+              field: "tags['CostCenter']",
+              exists: "false",
+            },
+            then: {
+              effect: "deny",
+            },
+          },
+        },
+      );
+
+      expect(mgPolicyDefinition).toBeDefined();
+      expect(mgPolicyDefinition.props.parentId).toBe(
+        "/providers/Microsoft.Management/managementGroups/my-mg",
+      );
+
+      // Verify the policy was created successfully
+      const synthesized = Testing.synth(stack);
+      expect(synthesized).toBeDefined();
+
+      const stackConfig = JSON.parse(synthesized);
+      const azapiResource = Object.values(
+        stackConfig.resource.azapi_resource,
+      )[0] as any;
+
+      expect(azapiResource.parent_id).toBe(
+        "/providers/Microsoft.Management/managementGroups/my-mg",
+      );
+    });
+
+    it("should default to subscription scope when parentId is not provided", () => {
+      new PolicyDefinition(stack, "SubPolicyDefinition", {
+        name: "sub-policy",
+        displayName: "Subscription Policy",
+        policyRule: {
+          if: {
+            field: "type",
+            equals: "Microsoft.Compute/virtualMachines",
+          },
+          then: {
+            effect: "audit",
+          },
+        },
+      });
+
+      const synthesized = Testing.synth(stack);
+      const stackConfig = JSON.parse(synthesized);
+      const azapiResource = Object.values(
+        stackConfig.resource.azapi_resource,
+      )[0] as any;
+
+      // Should default to subscription scope
+      expect(azapiResource.parent_id).toContain("/subscriptions/");
+    });
+
+    it("should support explicit subscription scope via parentId", () => {
+      const subPolicyDefinition = new PolicyDefinition(
+        stack,
+        "ExplicitSubPolicy",
+        {
+          name: "explicit-sub-policy",
+          parentId: "/subscriptions/00000000-0000-0000-0000-000000000000",
+          displayName: "Explicit Subscription Policy",
+          policyRule: {
+            if: {
+              field: "location",
+              equals: "eastus",
+            },
+            then: {
+              effect: "deny",
+            },
+          },
+        },
+      );
+
+      expect(subPolicyDefinition.props.parentId).toBe(
+        "/subscriptions/00000000-0000-0000-0000-000000000000",
+      );
+
+      const synthesized = Testing.synth(stack);
+      const stackConfig = JSON.parse(synthesized);
+      const azapiResource = Object.values(
+        stackConfig.resource.azapi_resource,
+      )[0] as any;
+
+      expect(azapiResource.parent_id).toBe(
+        "/subscriptions/00000000-0000-0000-0000-000000000000",
+      );
+    });
+  });
 });