Merge pull request #1395 from hashicorp/docs/group-administrative-units

docs: add note on using `ignore_changes` on `administrative_unit_ids` for `azuread_group`

docs/resources/administrative_unit.md

@@ -32,6 +32,8 @@ The following arguments are supported:
 * `display_name` - (Required) The display name of the administrative unit.
 * `members` - (Optional) A set of object IDs of members who should be present in this administrative unit. Supported object types are Users or Groups.
 
+~> **Caution** When using the `members` property of the [azuread_administrative_unit](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit#members) resource, to manage Administrative Unit membership for a group, you will need to use an `ignore_changes = [administrative_unit_ids]` lifecycle meta argument for the `azuread_group` resource, in order to avoid a persistent diff.
+
 !> **Warning** Do not use the `members` property at the same time as the [azuread_administrative_unit_member](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit_member) resource for the same administrative unit. Doing so will cause a conflict and administrative unit members will be removed.
 
 * `hidden_membership_enabled` - (Optional) Whether the administrative unit and its members are hidden or publicly viewable in the directory.

docs/resources/administrative_unit_member.md

@@ -41,6 +41,8 @@ The following arguments are supported:
 * `administrative_unit_object_id` - (Required) The object ID of the administrative unit you want to add the member to. Changing this forces a new resource to be created.
 * `member_object_id` - (Required) The object ID of the user or group you want to add as a member of the administrative unit. Changing this forces a new resource to be created.
 
+~> **Caution** When using the [azuread_administrative_unit_member](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit_member) resource to manage Administrative Unit membership for a group, you will need to use an `ignore_changes = [administrative_unit_ids]` lifecycle meta argument for the `azuread_group` resource, in order to avoid a persistent diff.
+
 ## Attributes Reference
 
 In addition to all arguments above, the following attributes are exported:

docs/resources/group.md

@@ -112,7 +112,7 @@ The following arguments are supported:
 
 * `administrative_unit_ids` - (Optional) The object IDs of administrative units in which the group is a member. If specified, new groups will be created in the scope of the first administrative unit and added to the others. If empty, new groups will be created at the tenant level.
 
-!> **Warning** Do not use the `administrative_unit_ids` property at the same time as the [azuread_administrative_unit_member](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit_member) resource, or the `members` property of the [azuread_administrative_unit](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit#members) resource, _for the same group_. Doing so will cause a conflict and administrative unit members will be removed.
+~> **Caution** When using the [azuread_administrative_unit_member](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit_member) resource, or the `members` property of the [azuread_administrative_unit](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit#members) resource, to manage Administrative Unit membership for a group, you will need to use an `ignore_changes = [administrative_unit_ids]` lifecycle meta argument for the `azuread_group` resource, in order to avoid a persistent diff.
 
 * `assignable_to_role` - (Optional) Indicates whether this group can be assigned to an Azure Active Directory role. Defaults to `false`. Can only be set to `true` for security-enabled groups. Changing this forces a new resource to be created.
 * `auto_subscribe_new_members` - (Optional) Indicates whether new members added to the group will be auto-subscribed to receive email notifications. Can only be set for Unified groups.

internal/services/administrativeunits/administrative_unit_member_resource_test.go

@@ -162,6 +162,9 @@ func (r AdministrativeUnitMemberResource) group(data acceptance.TestData) string
 resource "azuread_group" "member" {
   display_name     = "acctest-AdministrativeUnitMember-%[2]d"
   security_enabled = true
+  lifecycle {
+    ignore_changes = [administrative_unit_ids]
+  }
 }
 
 resource "azuread_administrative_unit_member" "test" {

internal/services/administrativeunits/administrative_unit_resource_test.go

@@ -140,6 +140,9 @@ data "azuread_domains" "test" {
 resource "azuread_group" "member" {
   display_name     = "acctest-AdministrativeUnitMember-%[1]d"
   security_enabled = true
+  lifecycle {
+    ignore_changes = [administrative_unit_ids]
+  }
 }
 
 resource "azuread_user" "memberA" {