Skip to main content

Key Inputs and Variables

Runbook Azure

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:

  1. The master registry: config/variables/schema/master-registry.yaml defines every variable. It is the only master.
  2. 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.
  3. The generated schema and templates: config/variables/schema/infrastructure.schema.json validates the file. config/variables/templates/infrastructure.master.yml has every key, and config/variables/templates/tools/<tool>.yml has one template per tool.

Every tool reads the same file: the toolkit scripts, azurelocal-ztp, azurelocal-sonar, Trailwright, the ARM deployment, Terraform and Ansible.

Complete Documentation

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:

Planning Workflow:

  1. Complete the discovery checklist to gather all required values.
  2. Apply the naming standards to generate resource names.
  3. Choose the landing zone deployment model (Full CAF or Simplified).
  4. Start infrastructure.yml from a template, set scenario first, then fill in the values.
  5. 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 DocumentWhere it goes in infrastructure.ymlDescription
Discovery Checklistazure.tenant_id, azure.subscription_id, site, identityAzure identity and tenant information gathered
Naming StandardsThe name of each item: cluster.name, landing_zone.resource_groups[].name, landing_zone.networks[].name, key_vaults[].nameResource naming patterns following CAF standards
Landing Zone Strategylanding_zone.management_groups[], landing_zone.subscriptions[], landing_zone.resource_groups[]Management group and subscription structure (Full CAF or Simplified)
Site Assessmentsite.code, networking, nodes[], scenarioSite-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.

SectionWhat it holds
scenarioThe design choices: identity, storage, topology, connectivity and the install method. Set this first
site, environment, tagsThe site code and name, the environment class and the Azure resource tags
azureThe 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
identityThe local administrator, Active Directory (domain, OU, LCM user, security groups), local identity and Microsoft Entra groups
landing_zoneManagement groups, subscriptions, resource groups, networks, network security groups, the VPN gateway, Bastion, NAT gateway, management VMs and the Log Analytics workspace
networkingThe 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
hardwareDrives, network cards, BIOS settings and the Solution Builder Extension (SBE) package, with the partner properties and credentials the vendor's SBE asks for
storageThe pool, the volumes, the storage paths, the VM images and the SAN
clusterThe cluster name, deployment mode, witness, cluster Key Vault and diagnostics
security, operationsThe security baseline, Defender for Cloud (free level), monitoring (Azure Local Insights and the Log Analytics workspace), updates and licensing
sdnSDN enabled by Azure Arc
devopsThe CI/CD platform, project, repository, environments, runners, Terraform state, and the runner label and approval environments of the toolkit's pipelines
secretsThe settings of the secret providers (file and command)
extensionsYour 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-platform
  • kv-azlc-clus01

Rules:

  • Must start with letter
  • No consecutive hyphens
  • 3-24 characters
  • Globally unique

Cluster Names​

Pattern: {site}-clus{number}

Examples:

  • iic-clus01
  • demo-clus01
  • lab-clus02

Rules:

  • Maximum 15 characters (NetBIOS requirement)
  • Lowercase alphanumeric + hyphens only
Naming Standards

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​

ErrorWhat it meansFix
A key is missingThe scenario you chose makes the key requiredAdd the key. The message names it and the rule
A value has the wrong type or is not allowedThe value does not match the schemaRead the key in the variables reference for the type and allowed values
A password is not acceptedA secret key holds a value, not a referenceReplace it with keyvault://<vault>/<secret> (or another reference form)
A vault is not foundThe reference names a vault that is not under key_vaultsAdd the vault to key_vaults
An unknown keyThe schema does not define itFix the spelling, or move your own key under extensions