Deploy Azure landing zone for Nonprofits with the Azure CLI

Use the Azure CLI deployment option when you're an experienced Azure operator, automation owner, or delivery partner who needs repeatable command-line deployment. For most users, the Azure portal flow is the recommended deployment experience. For more information, see Deploy and configure Azure landing zone for Nonprofits.

The CLI installer uses a JSON install configuration file and runs Azure deployment actions for one of the supported deployment paths: foundation or expanded platform. The installer supports three actions:

Action Use when
validate Check the configuration, selected scenario, deployment scope, tooling, and common authorization prerequisites before previewing or creating resources.
what-if Preview the Azure changes that the deployment makes. The installer runs validation before the what-if operation.
create Deploy the selected landing zone. The installer runs validation and what-if before it asks for create approval.

You can use an AI assistant to help review prerequisites, prepare configuration files, and check commands before running them. The operator is still responsible for validating inputs, permissions, cost choices, and deployment results.

Get the CLI installer files

Download or clone the contents of the AzureLandingZoneforNonprofits folder from the Nonprofits GitHub repository. Copy the files to a local folder before you run the installer.

Prerequisites

Before you deploy by using the Azure CLI, complete the planning steps in Plan and prepare to deploy Azure landing zone for Nonprofits.

You also need:

  • The Azure landing zone for Nonprofits CLI installer files from the Nonprofits GitHub repository, copied to a local folder.
  • PowerShell 7 or later.
  • Azure CLI 2.76.0 or later.
  • Azure CLI Bicep support. Run az bicep version to verify it.
  • An Azure CLI session signed in to the correct Microsoft Entra tenant.
  • Required permissions for the selected deployment path.

Verify your tools and sign in before you run the installer.

az version
az bicep version
az login --tenant <tenant-id>
az account show

Important

Use the least privilege required for deployment and remove temporary elevated access after deployment. Foundation requires subscription-level access that can create deployments, policy assignments, and Azure RBAC role assignments. Expanded platform requires tenant-scope deployment access, required access on the selected platform subscriptions, and management group permissions when an existing platform management group ID is supplied.

Prepare the CLI files

Open PowerShell in the root of the local AzureLandingZoneforNonprofits folder. Keep the folder structure intact.

The folder includes:

Item Purpose
Install-AzureLandingZone.ps1 Runs the supported deployment actions.
examples/commands/ Starter install configuration files for foundation and expanded platforms.
examples/parameters/ Example deployment parameter files referenced by the starter configs.
scenarios.json Supported scenario catalog used by the installer.

Copy the starter configuration file for your deployment path and edit the copy. If you keep the copy in examples/commands/, the default relative parametersFile value continues to work. If you move the configuration file to another folder, update parametersFile so it points to the selected parameter file.

Configure foundation

Use foundation when you need a compact landing-zone baseline in one existing subscription.

Start from examples/commands/foundation.install-config.json. The configuration must identify the foundation scenario, the target subscription, the deployment location, the parameter file, and any parameter overrides.

{
  "scenario": "foundation",
  "deploymentName": "alz-foundation",
  "deploymentLocation": "eastus",
  "parametersFile": "../parameters/foundation/foundation.subscription-only.parameters.json",
  "scope": {
    "subscription": "<foundation-subscription-id-or-name>"
  },
  "validationLevel": "Provider",
  "outputFolder": "outputs/foundation",
  "nonInteractive": false,
  "autoApprove": false,
  "parameterOverrides": {
    "deploymentPrefix": "npalz",
    "primaryLocation": "eastus",
    "serviceOwner": "platform@example.org",
    "monitoringNotificationEmails": [
      "ops@example.org"
    ],
    "monthlyBudgetAmount": 0,
    "enableSimpleNetwork": false,
    "enablePrivateDnsAndEndpoints": false
  }
}

Review these Foundation values before running the deployment.

Value Required Guidance
scenario Yes Use foundation. The alias foundation-subscription is also supported.
scope.subscription Yes Existing subscription that receives the foundation baseline.
deploymentPrefix Yes Use 3-12 lowercase letters, numbers, or hyphens. Keep the prefix stable for the environment.
primaryLocation Yes Approved Azure region for platform resources.
serviceOwner Yes Shared mailbox or team email used for platform ownership tags.
monitoringNotificationEmails Recommended Use shared operational recipients before relying on alert response.
monthlyBudgetAmount Optional Use 0 to skip automatic budget creation. Use a positive amount only when budget permissions and billing readiness are confirmed.
enableSimpleNetwork Optional Deploys the simple foundation network baseline.
enablePrivateDnsAndEndpoints Optional Requires the simple network baseline in foundation and can require DNS follow-up.

Run validation, preview, and create from the local folder root.

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/foundation.install-config.json `
  -Action validate

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/foundation.install-config.json `
  -Action what-if

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/foundation.install-config.json `
  -Action create

When create runs interactively, type CREATE when the preview and preflight checks are acceptable.

Configure expanded platform

Use the expanded platform when your organization has existing management and connectivity subscriptions and needs a dedicated platform model with shared management services and hub networking.

Start from examples/commands/expanded-platform.install-config.json.

{
  "scenario": "expanded-platform",
  "deploymentName": "alz-expanded-platform",
  "deploymentLocation": "eastus",
  "parametersFile": "../parameters/expanded-platform/expanded-platform.parameters.json",
  "validationLevel": "Provider",
  "outputFolder": "outputs/expanded-platform",
  "nonInteractive": false,
  "autoApprove": false,
  "parameterOverrides": {
    "deploymentPrefix": "npalz",
    "primaryLocation": "eastus",
    "managementSubscriptionId": "<management-subscription-id>",
    "connectivitySubscriptionId": "<connectivity-subscription-id>",
    "serviceOwner": "platform@example.org",
    "allowedLocations": [
      "eastus"
    ],
    "monitoringNotificationEmails": [
      "ops@example.org"
    ],
    "monthlyBudgetAmount": 0,
    "platformManagementGroupId": "",
    "reserveGatewaySubnet": false,
    "enablePrivateDnsAndEndpoints": false,
    "enableKeyVaultPurgeProtection": true
  }
}

Review these expanded platform values before running the deployment.

Value Required Guidance
scenario Yes Use expanded-platform. The aliases expanded, extended-platform, and extended are also supported.
managementSubscriptionId Yes Existing subscription that hosts shared management services, governance, monitoring, security baseline resources, access assignments, and the optional budget.
connectivitySubscriptionId Yes Existing subscription that hosts the dedicated hub network and connectivity governance baseline.
deploymentPrefix Yes Use 3-12 lowercase letters, numbers, or hyphens. Keep the prefix stable for the environment.
primaryLocation Yes Approved Azure region for shared platform resources.
allowedLocations Yes Include the primary region and any other approved regions required for operations, compliance, disaster recovery, or service availability.
serviceOwner Yes Shared mailbox or team email used for platform ownership tags.
platformManagementGroupId Optional Existing Platform management group ID that should receive an additional governance assignment. Expanded platform doesn't create the management group hierarchy.
reserveGatewaySubnet Optional Reserves the subnet only. The deployment doesn't create a VPN gateway, ExpressRoute gateway, Azure Virtual WAN, public IP address, or connection object.
enablePrivateDnsAndEndpoints Optional Enables private Key Vault connectivity and can require DNS and network follow-up.

Run validation, preview, and create from the local folder root.

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/expanded-platform.install-config.json `
  -Action validate

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/expanded-platform.install-config.json `
  -Action what-if

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/expanded-platform.install-config.json `
  -Action create

Use non-interactive deployment

Use non-interactive deployment only after you review the configuration file, validation successes, and the what-if result is acceptable.

Set nonInteractive and autoApprove to true in the install configuration file, or pass both switches on the command line.

pwsh ./Install-AzureLandingZone.ps1 `
  -ConfigFile ./examples/commands/foundation.install-config.json `
  -Action create `
  -NonInteractive `
  -AutoApprove

AutoApprove removes the interactive CREATE prompt. It doesn't remove the operator's responsibility to review the what-if result, costs, permissions, and follow-up actions.

Review output

The installer writes logs, resolved configuration, effective parameters, command results, and a summary to the configured outputFolder. The starter configuration files use outputs/... paths, which resolve under the root of the extracted CLI package.

Review the summary after every run. For create, confirm:

  • The selected scenario and deployment scope are correct.
  • Validation and authorization preflight checks don't report unresolved blockers.
  • The what-if result matches the intended change.
  • Budget creation is created or intentionally skipped.
  • Handover readiness and alert-response readiness are complete, or the summary lists the follow-up actions.
  • Security, governance, networking, and private connectivity choices match the approved plan.

Unsupported CLI scenarios

The CLI deployment option doesn't support every landing-zone activity. Don't use it to:

  • Create or modify a management group hierarchy for foundation.
  • Deploy foundation at management-group scope.
  • Create the platform management group for expanded platform.
  • Deploy application workloads, workload spokes, Azure Firewall, DDoS Network Protection, VPN gateways, ExpressRoute gateways, Azure Virtual WAN, public IP addresses, or connection objects.
  • Skip prerequisite review, what-if review, budget approval, or handover follow-up.
  • Use individual user object IDs where Microsoft Entra group object IDs are expected.

Next steps

  • Last updated on