Automation Guide
DOCUMENT CATEGORY: Runbook SCOPE: Infrastructure-as-Code, CI/CD platform setup, and automation tooling PURPOSE: Organize Azure Local automation guidance into a reader-friendly structure aligned to the implementation guide MASTER REFERENCE: Microsoft Learn - Azure Local
Status: Active
This guide centralizes the automation assets used to deliver Azure Local in a repeatable way. It is structured to mirror the implementation guide: start with orientation, move into CI/CD platform setup, then choose the pipeline platform and tooling that match your operating model.
Start Here
| Step | Purpose | Link |
|---|---|---|
| 1 | Understand the guide's boundaries and intended reader | Purpose and Scope |
| 2 | Learn how to navigate between automation and implementation docs | How to Use This Guide |
| 3 | Build the CI/CD foundation | Part 1: CI/CD Infrastructure |
| 4 | Choose a delivery platform | Part 2: CI/CD Pipelines |
| 5 | Use the tool-specific guides | Part 3: Automation Guides |
| 6 | Automate the cluster ARM Validate and Deploy step | ARM Validate and Deploy automation |
Deployment Paths
| Path | Azure Resources | On-Premises / Guest Configuration | Best For |
|---|---|---|---|
| Terraform + PowerShell | Terraform | PowerShell scripts | Teams with existing PowerShell operational workflows |
| Terraform + Ansible | Terraform | Ansible playbooks | Teams preferring declarative configuration management |
| Ansible Only | azure.azcollection | Ansible playbooks | Teams standardizing on Ansible across cloud and on-premises |
PowerShell scripts from one infrastructure.yml | ARM Validate and Deploy script | OS configuration script | Teams that provision with azurelocal-ztp (or an ISO), then configure and deploy from a jump server or a pipeline: OS configuration, then ARM Validate and Deploy |
Why the Guide Is Split into Sections
- CI/CD Infrastructure covers the platform you must build first: source control project, environments, variables, and runners.
- CI/CD Pipelines covers the delivery engine you choose to run on that platform: GitLab, GitHub Actions, or Azure DevOps.
- Automation Guides covers the technical assets those pipelines call: Terraform, Ansible, Bicep, and PowerShell.
This separation keeps platform setup, delivery orchestration, and tool implementation from being mixed together on the same level of the sidebar.
Architecture
Every tool reads the master infrastructure.yml (schema 5, current version 5.6.26): the toolkit scripts, azurelocal-ztp, azurelocal-sonar, OS configuration, ARM Validate and Deploy, Terraform and Ansible. The file, its schema, its templates and its variables reference are generated from the toolkit's master registry (config/variables/schema/master-registry.yaml), and a new variable is added to the registry first. Secrets are never in the file: a secret key holds only a reference (keyvault://<vault>/<secret>, env://<VARIABLE>, file://<name> or command://<name>).
┌─────────────────────────────────────────────────────────────────────┐
│ infrastructure.yml │
│ (one file per environment, defined by the registry) │
└────────────┬───────────────────┬──────────────────┬─────────────────┘
│ │ │
New-IacVariableFiles.ps1 (same script) Import-AzlInfrastructure
│ │ │
▼ ▼ ▼
terraform.tfvars.json inventory/hosts.yml, PowerShell scripts,
and backend.hcl group_vars, host_vars ZTP, Sonar, ARM
│ │
▼ ▼
┌─────────────┐ ┌─────────────────────────────┐
│ Terraform │ │ Ansible roles (src/ansible)│
│ Modules │ │ │
├─────────────┤ ├─────────────────────────────┤
│ landing-zone│ │ ad-preparation │
│ networking │ │ azurelocal_os_configuration │
│ identity │ │ arc-registration │
│ monitoring │ │ monitoring-agents │
│ security │ │ domain-controller │
│ compute │ │ cicd_runner │
│ cicd-runner │ └──────────────┬──────────────┘
└──────┬──────┘ │
▼ ▼
Azure Resources On-Prem Config
Section Overview
| Section | What You Get |
|---|---|
| Purpose and Scope | Reader expectations, deployment paths, scope boundaries |
| How to Use This Guide | Reading order and how to combine this guide with the implementation guide |
| Part 1: CI/CD Infrastructure | Runner deployment, project setup, environments, and variables |
| Part 2: CI/CD Pipelines | Platform-specific delivery pipeline models |
| Part 3: Automation Guides | Tool-specific guidance for Terraform, Ansible, Bicep, and PowerShell, and the ARM Validate and Deploy automation |
Variable System
One master file feeds every tool. The Terraform and Ansible variable files are written from it:
./config/variables/scripts/New-IacVariableFiles.ps1 -InfrastructureFile ./infrastructure.yml -OutputDirectory D:\work\iac -WhatIf
New-IacVariableFiles.ps1 writes terraform.tfvars.json and backend.hcl for each Terraform environment and inventory/hosts.yml, group_vars/all.yml and host_vars/<node>.yml for Ansible (none of them is committed; every pipeline writes them before it runs). Every variable of the code says in the registry which key it comes from. A secret is never written to a file. See Variable Management.
Repository
All automation code lives in the azurelocal-toolkit repository:
| Directory | Contents |
|---|---|
src/terraform/ | Terraform modules and root environment |
src/ansible/ | Ansible roles, playbooks, and inventory. The only Ansible tree: the OS configuration role is src/ansible/roles/azurelocal_os_configuration, run by src/ansible/playbooks/02-os-configuration.yml |
pipelines/ | CI/CD pipeline definitions: Terraform and Ansible deploy, CI/CD infrastructure, discovery, OS configuration, pre-cluster verification, and ARM Validate and Deploy. The only home of the deployment pipelines (the toolkit's .github/workflows folder holds only its own deploy-docs.yml). See the route table |
scripts/deploy/ | PowerShell deployment scripts |
config/variables/ | Central variable system: the master registry, the infrastructure.yml schema, templates and the generated variables reference |
docs/ | Operator guides for OS configuration and ARM Validate and Deploy, with their design and audit |