Management and Governance ARM deployments

Tenant deployment

A tenant deployment is a Resource Manager deployment executed at Microsoft Entra tenant scope.

Source: Microsoft Learn - Deploy resources to tenant with ARM templates Reviewed 2026-05-27

Exam trap: Assuming Global Administrator automatically has tenant-scope Azure RBAC rights for deployment and role assignment work.
Production check: Check az account show and az account tenant list before any tenant-scope deployment command.

Practice this topic Microsoft Learn

Article details and learning context

Aliases: Tenant deployment, tenant deployment, Azure Tenant deployment, tenant scope deployment, az deployment tenant, ARM tenant deployment
Difficulty: intermediate
CLI mappings: 5
Last verified: 2026-05-27
Review level: field-manual-complete
Article depth: field-manual-complete

Related context No curated learning path mapped yet; use the category trail.

Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

A tenant deployment is an infrastructure deployment that starts at the top Azure scope for an organization’s Microsoft Entra tenant. Instead of deploying only into one resource group or subscription, the template can define tenant-level changes and route modules toward management groups, subscriptions, or resource groups. It is used for platform foundations, not ordinary app releases. Think of it as a controlled way to automate decisions that affect the whole Azure estate, such as management group structure, role assignments, or shared governance entry points.

Why it matters

Tenant deployment matters because some Azure decisions cannot be safely owned by one application team or one subscription. Landing-zone hierarchy, tenant-wide role assignment patterns, management group creation, and cross-subscription modules need a repeatable control-plane path. If these changes are made manually, organizations end up with inconsistent scopes, missing audit trails, and emergency permissions that never get removed. A tenant deployment gives platform engineers a versioned, reviewable, and automatable method for top-level infrastructure. It also forces the right conversation about who can change tenant-wide boundaries, what approval is required, and how to prove the deployment did only what was intended. That clarity prevents broad Azure changes from becoming hidden operational debt.

Official wording and source

A tenant deployment is an Azure Resource Manager deployment run at Microsoft Entra tenant scope. It can create or configure tenant-level resources and target management groups, subscriptions, or resource groups when the deploying principal has the required scope permissions. for Tenant deployment operations.

Open Microsoft Learn

Technical context

Tenant deployments use Azure Resource Manager at the tenant scope, often with ARM templates or Bicep files that declare targetScope tenant. The deployment record needs a location for metadata, even when the resources themselves are global or placed elsewhere. The deploying identity must have Microsoft.Resources/deployments permissions and permissions for every resource being created. Tenant deployments commonly interact with management groups, policy assignments, role assignments, template specs, subscription modules, and governance baselines. They are control-plane operations with broad blast-radius potential.

Exam context

Compare with

ARM template Bicep

Where it is used

Where you see it

Azure CLI uses az deployment tenant create, validate, what-if, show, export, and list when the deployment target is the Microsoft Entra tenant rather than a subscription or resource group.
A Bicep file with targetScope set to tenant and modules scoped to managementGroup, subscription, or resourceGroup signals that the release starts at tenant scope. during Tenant deployment operational review.
Deployment history shows a tenant-scope record with a metadata location, deployment name, provisioning state, correlation ID, parameters, and operations for tenant-level troubleshooting. during Tenant deployment operational review.

Common situations

Create or update the initial management group hierarchy for an enterprise landing-zone rollout.
Deploy tenant-level role assignments or governance resources with reviewable infrastructure-as-code evidence.
Orchestrate modules into multiple subscriptions from one approved platform foundation template.
Validate tenant-scope changes with what-if before a change window that affects inherited governance.
Export tenant deployment records after an audit requests proof of who changed top-level Azure structure.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Manufacturer automates landing-zone hierarchy Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A global manufacturer had 47 Azure subscriptions spread across regional IT teams. Manual management group changes made policy inheritance unpredictable and slowed a new factory data platform rollout.

Goals

Create a standardized management group hierarchy across corporate, factory, and sandbox subscriptions.
Apply baseline role assignments through reviewed infrastructure-as-code.
Reduce landing-zone setup time for new regional subscriptions below two hours.
Preserve deployment evidence for internal audit and cyber insurance review.

Approach using Tenant deployment

The platform team authored a Bicep template with targetScope tenant and modules for management group creation, baseline role assignments, and subscription placement. Before execution, the release pipeline ran az deployment tenant validate and what-if with the same managed identity used for creation. The deployment used a stable metadata location and deployment name tied to the change record. After the run, operators exported the tenant deployment and listed operations to confirm each management group and assignment. Regional teams received read-only evidence and a subscription onboarding checklist.

Potential outcomes

New subscription onboarding fell from 3.5 days to 54 minutes for the next six factories.
Policy inheritance mismatches dropped from 19 known exceptions to two approved exceptions.
Audit evidence collection time fell from two weeks to one afternoon.
No personal administrator account was used for the tenant-scope rollout.

What to learn

Tenant deployment is valuable when top-level Azure structure needs the same rigor, review, and evidence as application infrastructure.

Scenario 02 Media group deploys governance without weekend chaos Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A streaming media company needed to roll out data-residency policy assignments before launching in two new markets. Previous manual policy changes caused broken deployments and blame between platform and product teams.

Goals

Deploy region-governance assignments at tenant and management group boundaries.
Preview all policy changes before the market-launch freeze.
Keep subscription-specific product deployments out of the tenant foundation release.
Provide a rollback plan if legitimate workloads were blocked.

Approach using Tenant deployment

Engineers separated the tenant deployment into a governance template and subscription-level workload modules. The tenant template created management-group scoped policy assignments and outputs that listed affected scopes. The pipeline required az deployment tenant what-if approval, then ran create only after product leads confirmed the allowed regions. A follow-up script queried policy compliance for the targeted management groups. When one analytics sandbox was blocked, the team used a documented exemption workflow instead of weakening the tenant template.

Potential outcomes

The governance rollout completed 36 hours before the launch freeze with no emergency policy removals.
Blocked workload tickets fell by 68% compared with the prior market launch.
What-if review caught three incorrect management group targets before deployment.
Compliance reporting for the new markets was ready on launch day.

What to learn

Tenant deployments help platform teams introduce broad governance in small, reviewable releases instead of risky portal sessions.

Scenario 03 Nonprofit replaces emergency tenant changes Scenario, objectives, solution, measured impact, and takeaway.

Scenario

A humanitarian nonprofit grew quickly after a disaster-response program and gave several engineers emergency access across Azure. Six months later, nobody could prove which tenant-level assignments were still required.

Goals

Move tenant-level role assignment changes into a controlled deployment pipeline.
Remove undocumented emergency access without disrupting active response systems.
Create an evidence trail for donor security questionnaires.
Shorten future access reviews to less than one day.

Approach using Tenant deployment

The cloud lead wrote a tenant-scope template that declared approved platform group assignments and removed unmanaged manual steps from the access process. The first pipeline run used tenant validation and what-if only, producing a diff between approved assignments and existing emergency grants. Security reviewed the diff, converted two break-glass accounts to privileged access workflow, and then approved the create step. Deployment operations and outputs were stored with the access review. Subscription teams were notified before inherited role changes took effect.

Potential outcomes

Undocumented tenant-level assignments fell from 28 to four approved break-glass paths.
Quarterly access review effort dropped from nine staff-days to six hours.
No response-system outage occurred during the cleanup release.
Donor questionnaire evidence was delivered three weeks earlier than the previous cycle.

What to learn

Tenant deployment gives security teams a safer way to repair broad access drift without relying on memory or portal screenshots.

Azure CLI

With tenant deployments, I strongly prefer Azure CLI because portal clicks do not make broad governance changes safer. CLI lets an engineer validate, what-if, create, show, export, and list tenant-scope deployments with a repeatable command line and a named deployment record. After ten years of Azure work, I want the template file, parameter source, location, identity, validation level, and what-if output preserved in pipeline logs. CLI also makes tenant deployment practical for GitOps-style platform engineering. You can block a pull request on validation, require approval on what-if results, and export deployment evidence after the run. This keeps automation reviewable when ownership changes or incidents happen.

Useful for

Run az deployment tenant validate to catch template, parameter, permission, and provider issues before approval.
Run az deployment tenant what-if to review management group, policy, or role-assignment changes before execution.
Create a tenant deployment from a Bicep file or template spec with a named deployment and metadata location.
List or export tenant-scope deployment records when auditors ask what changed at the top Azure scope.

Before you run a command

Confirm you are logged into the intended Microsoft Entra tenant and that your default subscription context is not misleading for tenant-scope work.
Verify the deployment identity has tenant-scope deployment permissions and the specific rights needed for management groups, role assignments, policies, or downstream modules.
Choose the deployment metadata location deliberately and use stable deployment names so evidence can be found after incidents or audits.
Run validation and what-if first, classify the change as security-impacting, and confirm rollback or compensating steps before running create.

What the output tells you

ProvisioningState shows whether Resource Manager accepted, executed, failed, or is still running the tenant deployment.
The correlation ID, deployment name, and location identify the tenant-scope operation when searching activity logs or support evidence.
Output values and operation details show which management groups, role assignments, policies, or downstream scopes were touched.
What-if output shows planned creates, modifies, deletes, ignores, or unsupported changes before the tenant-wide operation starts.

Mapped commands

Tenant-scope deployment commands

direct

az deployment tenant validate --location <region> --template-file main.bicep --parameters @main.bicepparam --validation-level Provider

az deployment tenantdiscoverManagement and Governance

az deployment tenant what-if --location <region> --template-file main.bicep --parameters @main.bicepparam --result-format ResourceIdOnly

az deployment tenantdiscoverManagement and Governance

az deployment tenant create --name <deployment-name> --location <region> --template-file main.bicep --parameters @main.bicepparam

az deployment tenantsecureManagement and Governance

az deployment tenant show --name <deployment-name> --output json

az deployment tenantdiscoverManagement and Governance

az deployment tenant export --name <deployment-name>

az deployment tenantsecureManagement and Governance

Architecture context

Architecturally, a tenant deployment belongs to the platform layer, above subscriptions and most workload teams. It should be part of a landing-zone or governance pipeline, not an ad hoc administrator session. I use it when the desired scope is genuinely tenant-level or when one template must orchestrate modules into management groups, subscriptions, and resource groups. The design should separate foundation changes from application releases, define who owns the tenant template, and include a rollback or compensating-change plan. A good diagram shows the tenant scope, target management groups, delegated subscriptions, deployment identity, policy controls, and evidence storage. That ownership line should be visible in every platform review.

Security: Security impact is direct and high. A tenant deployment can create management groups, assign roles, configure governance resources, or target scopes that affect many subscriptions. The deploying principal should use least privilege, just-in-time approval, and strong identity controls. Global Administrator status alone is not the same as Azure RBAC permission at tenant scope, so access must be explicit and auditable. Review templates for role assignments, policy exemptions, public endpoints in downstream modules, and secrets in parameters or outputs. Store deployment logs carefully because they reveal tenant structure, resource IDs, principals, and governance design. Record the approval path and verify the boundary after the change.
Cost: Tenant deployments do not create cost by themselves, but they can automate decisions that create large downstream spend. A tenant-scope template might place subscriptions under a management group with required diagnostics, deploy policy initiatives that enforce premium SKUs, or create shared monitoring resources. Cost risk also appears when a failed foundation deployment leaves partially created resources that teams ignore. FinOps should review tenant templates for tag requirements, SKU defaults, logging retention, regional placement, and optional modules. The deployment evidence should show what changed, so cost owners can trace a new spend pattern back to the governance release that introduced it.
Reliability: Reliability risk comes from blast radius. A mistaken tenant deployment can break inheritance, route modules to the wrong subscription, create conflicting policy assignments, or remove assumptions that workload teams rely on. Reliable teams run validate and what-if at tenant scope, deploy in small foundation releases, and avoid combining unrelated hierarchy, RBAC, and workload changes. They use stable deployment names, pinned template versions, and clear rollback notes. Because tenant deployments may touch multiple lower scopes, post-change checks must confirm not only deployment success but also inherited policy, role assignment, and target-scope behavior. Post-change verification should prove inherited behavior still works as intended.
Performance: Tenant deployment performance is mostly operational rather than runtime. The deployment engine must validate and execute broad control-plane operations, and large templates with many nested modules can take time. Slow or failed tenant deployments delay platform releases, policy rollout, and subscription vending. More importantly, the deployment can configure downstream performance choices such as regions, SKUs, diagnostics, or networking. Use what-if to reduce surprise, split very broad changes into manageable modules, and avoid running multiple tenant-scope changes that contend for the same management group or role assignment targets. Reliable deployment speed comes from narrow scope and clear dependencies. Measure before and after so tuning claims stay testable.
Operations: Operations work for tenant deployments includes reviewing templates, validating parameters, running what-if, watching deployment state, exporting the template used, and listing deployment operations for failures. Operators need to know the active tenant, deployment location, identity, scope transitions, and affected management groups or subscriptions. Runbooks should include approval gates, evidence retention, emergency cancel steps, and ownership for every downstream module. After a tenant deployment, teams should verify hierarchy placement, role assignments, policy compliance, and any subscription or resource-group module outputs. Treat every tenant deployment as a change-management item, not a convenience script. Keep this evidence attached to the incident, release, or audit ticket.

Common mistakes

Assuming Global Administrator automatically has tenant-scope Azure RBAC rights for deployment and role assignment work.
Running a tenant deployment with a personal administrator account instead of an auditable pipeline identity and approval gate.
Combining management group restructuring, policy rollout, and role changes in one oversized release with no rollback path.
Ignoring the deployment metadata location and name, then struggling to find tenant-scope evidence during an audit.