Key Inputs and Variables
DOCUMENT CATEGORY: Runbook
SCOPE: Configuration management system
PURPOSE: Define variable registry and infrastructure configuration
MASTER REFERENCE: Variable Registry Process
Status: Active
Overview
Azure Local deployments use one configuration system:
- The master registry:
config/variables/schema/master-registry.yamldefines every variable. It is the only master. infrastructure.yml: one file per environment (schema 5, current version 5.6.28). It holds your values. It is never committed to a public repository, and it never holds a secret value.- The generated schema and templates:
config/variables/schema/infrastructure.schema.jsonvalidates the file.config/variables/templates/infrastructure.master.ymlhas every key, andconfig/variables/templates/tools/<tool>.ymlhas one template per tool.
Every tool reads the same file: the toolkit scripts, azurelocal-ztp, azurelocal-sonar, Trailwright, the ARM deployment, Terraform and Ansible.
See Variable Management for the full standard, and infrastructure-file.md in the toolkit for how to fill in the file.
Planning Phase Integration
The infrastructure.yml file is filled in during the planning and discovery phase. Key planning documents provide the source values:
- Naming Standards - Defines resource naming patterns and conventions
- Discovery Checklist - Comprehensive checklist for gathering all required configuration values
- Site Assessment - Site readiness and infrastructure requirements
- Landing Zone Strategy - Determines management group and subscription structure
Planning Workflow:
- Complete the discovery checklist to gather all required values.
- Apply the naming standards to generate resource names.
- Choose the landing zone deployment model (Full CAF or Simplified).
- Start
infrastructure.ymlfrom a template, setscenariofirst, then fill in the values. - Validate it with
Test-InfrastructureFile.ps1.
Configuration Architecture
master-registry.yaml the only master (edit this)
| generated by New-InfrastructureArtifacts.ps1
v
infrastructure.schema.json templates/infrastructure.master.yml templates/tools/<tool>.yml
infrastructure.yml your values, one file per environment
|
+--> every script: Import-AzlInfrastructure -Path ./infrastructure.yml
+--> one tool: New-InfrastructureArtifacts.ps1 -Cut <tool>
How Scripts Use infrastructure.yml
Every deployment script reads its values from infrastructure.yml through one module. A script carries no value of its own: a test fails the build when a script has a hard-coded address, name, ID or region.
Script Execution Pattern
# The file is a parameter. Run with -WhatIf first.
./Deploy-VirtualNetworks.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Inside a script:
Import-Module ./scripts/common/infrastructure/AzlInfrastructure.psm1
$infra = Import-AzlInfrastructure -Path $InfrastructureFile # stops if the file has errors
$tenantId = $infra.azure.tenant_id
$gateway = $infra.networking.management.gateway
The script help lists the keys the script reads. The same script runs for every environment. Only the values in infrastructure.yml differ.
-InfrastructureFile is mandatory. No script takes -ConfigPath or -ConfigFile, and no script prompts. A credential comes from a -Credential parameter or from a secret reference in the file. Without one, the script stops with exit code 2.
Secrets
A key that needs a secret holds a reference: keyvault://<vault>/<secret> (the default), env://<VARIABLE>, file://<name> or command://<name>. One resolver reads every reference. No script names a vault.
The Files
1. infrastructure.yml
Start from config/variables/templates/infrastructure.master.yml, a scenario template under config/variables/templates/scenarios/, or the nearest worked example in config/variables/examples/. The values in the examples are example-company values.
_metadata:
schema_version: 5.6.28
scenario:
identity: active_directory
azure:
tenant_id: 00000000-0000-0000-0000-000000000000
subscription_id: 00000000-0000-0000-0000-000000000000
resource_group: rg-iic-azl-01
location: eastus
key_vaults:
- name: kv-iic-mgmt-01
subscription_id: 00000000-0000-0000-0000-000000000000
resource_group: rg-iic-mgmt-01
identity:
local_admin:
username: iic-admin
password: keyvault://kv-iic-mgmt-01/local-admin-password
The all-zero GUID is a placeholder. Use your own IDs in your own file.
2. The schema and the templates
infrastructure.schema.json is generated from the registry. It validates the structure of the file. A test regenerates it and fails when it is stale. Each tool also has its own schema in config/variables/schema/tools/.
Key Planning Inputs
The following table shows how planning phase outputs map to the file:
| Planning Document | Where it goes in infrastructure.yml | Description |
|---|---|---|
| Discovery Checklist | azure.tenant_id, azure.subscription_id, site, identity | Azure identity and tenant information gathered |
| Naming Standards | The name of each item: cluster.name, landing_zone.resource_groups[].name, landing_zone.networks[].name, key_vaults[].name | Resource naming patterns following CAF standards |
| Landing Zone Strategy | landing_zone.management_groups[], landing_zone.subscriptions[], landing_zone.resource_groups[] | Management group and subscription structure (Full CAF or Simplified) |
| Site Assessment | site.code, networking, nodes[], scenario | Site-specific infrastructure and network requirements |
Landing Zone Impact:
- Full CAF Deployment: Requires multiple subscriptions and a management group hierarchy
- Simplified Deployment: Uses a single subscription with resource group organization
Key Input Categories
Each top-level section of infrastructure.yml holds one kind of input. Every key, with its type, default and example, is in the variables reference.
| Section | What it holds |
|---|---|
scenario | The design choices: identity, storage, topology, connectivity and the install method. Set this first |
site, environment, tags | The site code and name, the environment class and the Azure resource tags |
azure | The tenant, the subscription, the resource group, the location, the resource provider object ID and the automation identity |
key_vaults[] | Every vault a secret reference may name, with its subscription and resource group |
identity | The local administrator, Active Directory (domain, OU, LCM user, security groups), local identity and Microsoft Entra groups |
landing_zone | Management groups, subscriptions, resource groups, networks, network security groups, the VPN gateway, Bastion, NAT gateway, management VMs and the Log Analytics workspace |
networking | The management network, intents, storage networks, VLANs, logical networks, outbound path (proxy, Arc gateway) and NTP |
nodes[] | Each machine: name, serial number, BMC, network adapters with MAC addresses, SAN host bus adapters |
hardware | Drives, network cards, BIOS settings and the Solution Builder Extension (SBE) package, with the partner properties and credentials the vendor's SBE asks for |
storage | The pool, the volumes, the storage paths, the VM images and the SAN |
cluster | The cluster name, deployment mode, witness, cluster Key Vault and diagnostics |
security, operations | The security baseline, Defender for Cloud (free level), monitoring (Azure Local Insights and the Log Analytics workspace), updates and licensing |
sdn | SDN enabled by Azure Arc |
devops | The CI/CD platform, project, repository, environments, runners, Terraform state, and the runner label and approval environments of the toolkit's pipelines |
secrets | The settings of the secret providers (file and command) |
extensions | Your own keys. Tools ignore what they do not own |
Naming Conventions
All naming follows Microsoft Cloud Adoption Framework (CAF) standards:
Resource Groups
Pattern: rg-<workload>-<environment>-<region>-<instance>
Examples:
rg-azlocal-prod-eus-001(Primary cluster resources)rg-azlocal-prod-eus-arc(Arc-connected resources)rg-azlocal-prod-eus-network(Networking resources)rg-azlocal-prod-eus-security(Security resources)
Storage Accounts
Pattern: st<workload><environment><region><instance>
Examples:
stazlprdeus001(Azure Local production storage)stazldevwus001(Azure Local dev storage)stazltestcus001(Azure Local test storage)
Rules:
- No hyphens allowed
- Lowercase only
- 3-24 characters
- Globally unique
Key Vaults
Pattern: kv-{env_abbr}-{purpose}
Examples:
kv-iic-platformkv-azlc-clus01
Rules:
- Must start with letter
- No consecutive hyphens
- 3-24 characters
- Globally unique
Cluster Names
Pattern: {site}-clus{number}
Examples:
iic-clus01demo-clus01lab-clus02
Rules:
- Maximum 15 characters (NetBIOS requirement)
- Lowercase alphanumeric + hyphens only
See complete naming standards in Naming Standards
Variable Validation
Pre-Deployment Validation
Always validate infrastructure.yml before a deployment:
./scripts/common/infrastructure/Test-InfrastructureFile.ps1 -Path ./infrastructure.yml
It checks the file against the schema and the rules (for example, identity: active_directory needs identity.active_directory). It lists every problem at once and exits with code 1 when there are errors. Warnings do not fail it.
What To Do With An Error
| Error | What it means | Fix |
|---|---|---|
| A key is missing | The scenario you chose makes the key required | Add the key. The message names it and the rule |
| A value has the wrong type or is not allowed | The value does not match the schema | Read the key in the variables reference for the type and allowed values |
| A password is not accepted | A secret key holds a value, not a reference | Replace it with keyvault://<vault>/<secret> (or another reference form) |
| A vault is not found | The reference names a vault that is not under key_vaults | Add the vault to key_vaults |
| An unknown key | The schema does not define it | Fix the spelling, or move your own key under extensions |
Related Documentation
- Variable Management: the full standard
- Variable Management Standard: the short version
- Naming Standards: Azure resource naming conventions