Skip to main content

Automation Guide

Runbook Azure

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​

StepPurposeLink
1Understand the guide's boundaries and intended readerPurpose and Scope
2Learn how to navigate between automation and implementation docsHow to Use This Guide
3Build the CI/CD foundationPart 1: CI/CD Infrastructure
4Choose a delivery platformPart 2: CI/CD Pipelines
5Use the tool-specific guidesPart 3: Automation Guides
6Automate the cluster ARM Validate and Deploy stepARM Validate and Deploy automation

Deployment Paths​

PathAzure ResourcesOn-Premises / Guest ConfigurationBest For
Terraform + PowerShellTerraformPowerShell scriptsTeams with existing PowerShell operational workflows
Terraform + AnsibleTerraformAnsible playbooksTeams preferring declarative configuration management
Ansible Onlyazure.azcollectionAnsible playbooksTeams standardizing on Ansible across cloud and on-premises
PowerShell scripts from one infrastructure.ymlARM Validate and Deploy scriptOS configuration scriptTeams 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​

One input model

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​

SectionWhat You Get
Purpose and ScopeReader expectations, deployment paths, scope boundaries
How to Use This GuideReading order and how to combine this guide with the implementation guide
Part 1: CI/CD InfrastructureRunner deployment, project setup, environments, and variables
Part 2: CI/CD PipelinesPlatform-specific delivery pipeline models
Part 3: Automation GuidesTool-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:

DirectoryContents
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