Skip to content

docs: clarify parent management group choice in Decision 6 - #4240

Open
Git-PrinceNagar wants to merge 1 commit into
mainfrom
git-princenagar-shiny-carnival
Open

docs: clarify parent management group choice in Decision 6#4240
Git-PrinceNagar wants to merge 1 commit into
mainfrom
git-princenagar-shiny-carnival

Conversation

@Git-PrinceNagar

@Git-PrinceNagar Git-PrinceNagar commented Aug 14, 2026

Copy link
Copy Markdown

Overview

Fixes #4198

Decision 6 asks you to choose a parent management group, but does not say that this can be the Tenant Root Group or an existing management group underneath it, and gives no criterion for choosing between the two. The issue asks why you would pick either option, and why using an existing management group appears to add a level compared with the published Azure landing zone architecture diagrams.

This also corrects a statement in the same section that has been stale since v7.0.0.

Changes

docs/content/accelerator/0_planning.md, Decision 6 only.

  • State both options for the parent management group, and when to choose each.
  • Explain that the bootstrap creates an intermediate root management group under the parent you choose, and builds the Platform landing zone hierarchy underneath that.
  • Document the Owner requirement on the chosen parent, linking to the phase 1 prerequisites and the Permissions FAQ.
  • Note that adding a management group above the intermediate root management group is not required in order to use your own naming, linking to the Terraform customization page.

Correction

The current text says the hierarchy is built underneath the parent "with only permission applied at that scope". This has not been accurate since v7.0.0:

The role assignments are now just applied at the intermediate root management group, they are no longer applied at the parent management group.

The "no policies are applied at that scope" half is still correct and is retained.

Testing

Documentation-only change.

  • hugo builds successfully (358 pages, no errors). All three {{< relref >}} links resolve.
  • Link text matches the target page titles (Platform Subscriptions and Permissions, Permissions FAQ, Customize Management Group Names and IDs).
  • The described behaviour was checked against the bootstrap modules: the intermediate root management group is created under root_parent_management_group_id, and for Terraform its ID and display name are taken from the management group with no parent_id in the architecture definition. The renaming guidance matches the existing contoso-alz / Contoso worked example in the Terraform options documentation.
  • The naming note is scoped to Terraform because there is no equivalent management group customization page under starter-bicep.

Decision 6 did not explain that the parent may be the Tenant Root Group or
an existing management group underneath it, nor give a criterion for choosing
between them. Issue #4198 asked why one would pick either option.

- State both options and when to choose each
- Note the Owner requirement on the chosen parent, linking to the phase 1
  prerequisites and the Permissions FAQ
- Note that adding a management group above the intermediate root management
  group is not required in order to use your own naming, linking to the
  Terraform customization page

Also corrects a statement that has been stale since v7.0.0: role assignments
are applied at the intermediate root management group and are no longer
applied at the parent management group.

Closes #4198

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@Git-PrinceNagar
Git-PrinceNagar force-pushed the git-princenagar-shiny-carnival branch from 577e9c7 to 651cf88 Compare August 14, 2026 04:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Intermediate Management Group Query

1 participant