Prerequisites and Landing Zone Requirements¶

Everything on this page must exist, or be requested from the customer, before the deployment engineer starts the preparation. A missing prerequisite is the most common reason an implementation stalls, so check each item early.

Azure¶

Subscriptions¶

The hub uses one platform subscription per function, and the platform has two platform environments: canary and prod (Glossary). Each platform environment needs its own set.

Subscription	Role in the hub	Required
Management	Log Analytics, Key Vault, Automation, storage. Often also holds the Terraform state storage account and the job runners (both are set in `mcp.json`).	Yes
Connectivity	Virtual WAN, hub, Azure Firewall, gateways, DNS, Application Gateway	Yes
Identity	Identity virtual network	Optional, depending on whether the customer needs an identity subscription

That is a minimum of four subscriptions (management and connectivity, for canary and for prod), or six with the optional identity subscriptions. In addition, every spoke needs a subscription. The pipelines can only create a subscription with a CSP billing account, so create spoke subscriptions through your own EA, MCA or CSP process first (New spoke).

The subscription IDs go in scaffold_subscriptions in <env-folder>/global.auto.tfvars (Hub config).

Management group¶

Create a top-level management group for the platform directly under the Tenant Root Group. Its ID is the value of management_group_organization_id. The ID cannot be changed after creation and cannot contain spaces.
Place the platform subscriptions under it. Every subscription that the deployment identity must manage must sit under this management group, because the identity gets its rights by inheritance.
If the customer asks the platform team to create the management group, the deploying identity needs permission on the Tenant Root Group: see Elevated access at tenant level.

The platform builds the rest of the hierarchy itself (Management group structure).

Permissions the platform team needs¶

Where	What	Why
Platform management group	Owner, with the condition that allows assigning all roles	The deployment creates role assignments
Microsoft Entra ID	A directory role that can create app registrations, for example Application Developer	To create the deployment service principals
Entra ID administrative unit	Groups Administrator and User Administrator on the unit	To let the platform manage the groups it creates for spokes
Tenant Root Group (only if the platform team creates the management group)	Management Group Contributor	To create a management group under the root

Grant these to a group, not to individual users, and make that group's membership available through PIM. See Prepare identity for the steps.

Lower the rights after installation where you can

The installation needs high privileges. Review them at hand-over and keep only what the day-to-day pipelines need. The deployment service principals keep their rights, because every pipeline run depends on them.

Elevated access at tenant level¶

To assign roles on the Tenant Root Group, a Global Administrator must first enable Access management for Azure resources for their account (Microsoft Entra ID, Properties). Switch it off again when the assignment is done. If the Tenant Root Group does not appear as a clickable management group in the portal, this is the reason.

Partner association¶

If an implementation partner or managed-service provider works in the tenant, link its partner ID to the tenant so Azure usage is attributed to the partner (Partner Admin Link, PAL). In PowerShell, with the Az and Az.ManagementPartner modules installed:

Connect-AzAccount -TenantId <tenant-id>
New-AzManagementPartner -PartnerId <partner-id>
Get-AzManagementPartner

Get-AzManagementPartner must show the partner ID. Skip this step in a self-managed implementation without a partner.

Azure DevOps (when the customer uses Azure DevOps)¶

Item	Detail
Organization	The customer's Azure DevOps organization, backed by the customer's Entra ID tenant
Project	A private project for the platform, with Git repositories. Add the platform team's group as project administrators for the duration of the implementation.
Users	Every platform team member has an account in the organization with the Basic access level
Parallelism	Enough parallel jobs purchased for the pipelines and the pool

If the platform team works in the customer's own organization, the customer must arrange users and the project. If you use a separate organization of the platform team, you do not need these items, but you need a way to run the pipelines against the customer's tenant.

GitHub (when the customer uses GitHub)¶

Item	Detail
Organization	The customer's GitHub organization (GitHub.com or GitHub Enterprise)
Roles for the platform team	The predefined organization roles CI/CD admin (manage Actions policies, runners, runner groups, secrets and variables) and App Manager (create and edit GitHub Apps)
Repositories	The platform team can create repositories
Hosted compute networking	Visible in the organization settings if you plan to use GitHub-hosted runners with private networking (older approach). If not, the customer's enterprise owner must enable it.
Runner	At least one standard runner on a current Ubuntu image in the default runner group, for the first deployments

See GitHub variant.

Network and planning¶

IP plan. Address ranges for the hub (per region), the identity and management networks, the job runner network (virtual network, agent subnet, private endpoint subnet, Container Apps environment subnet, DNS resolver subnet) and the first spokes. The platform does not check for overlap, so review the plan.
Connectivity inputs. If the design includes VPN, ExpressRoute or BGP: peer addresses, ASNs and the on-premises routes, and who configures the other side.
Name choices. The customer short name (maximum six characters, see the naming reference) and the workload naming rules.
Azure resource providers. The providers the platform uses must be registered in every platform subscription. The older runbooks run a script from the code repository for this (scripts/register-az-providers.ps1; check that it exists in the version you pin). The infrastructure run registers the providers that the job runners need. Registering a provider requires at least Contributor on the subscription.
Quota. Check that the subscription has quota for the job runner VM size in the chosen region. A quota shortfall fails the first infrastructure run.

The information you need from the customer¶

Collect this in the plan phase, so the deployment engineer can work without asking questions:

Item	Example form
Entra ID tenant ID	GUID
Platform management group ID	`<customer>-platform`
Subscription IDs	Management, connectivity (and identity) for canary and prod
Customer short name	Maximum six characters
Members of the platform team group	List of users (guests, or internal users)
Azure DevOps organization and project, or GitHub organization	Names
Primary region and extra regions	Short and long names
IP plan	Ranges per purpose
Alert receivers and the security contact	E-mail addresses or webhook

Check the prerequisites¶

When the customer says the prerequisites are in place, the platform team verifies them before the work starts. If a check fails, go back to the customer: the preparation is not the place to fix someone else's prerequisites.

Azure checks¶

Sign in to the customer's Azure portal. If PIM is used, open Privileged Identity Management, My roles, Groups, check that an eligible assignment exists, and activate it.
After activation, check your Entra ID directory role. It must include the role from the permissions table above (for example Application Developer).
In Entra ID, check that all platform team members exist as users, and that the requested groups exist with the right members. You may lack permission to see all users; ask the customer to confirm.
In Management groups, check that the platform management group exists.
In its Access control (IAM), check that the platform team group has Owner.
Check that the platform subscriptions are placed under that management group.

Azure DevOps checks¶

Sign in to the customer's organization. In Organization settings, Users, check that every platform team member is present with the Basic access level.
Check that the project exists, that the platform team are project administrators, and that you see Repos and Pipelines.

GitHub checks¶

In the organization, People, check that every team member is a member and holds the roles listed above.
In Settings, check that you can create GitHub Apps and, if needed, see Hosted compute networking.
Check that you can create repositories.
In Settings, Actions, Runner groups, open the default group and check that it has at least one runner on a current Ubuntu image. Create one if there is none.

Next step¶

Continue with Discovery output to deployment input, then Prepare identity.