GitLab CI/CD Pipeline
DOCUMENT CATEGORY: Reference SCOPE: GitLab CI/CD pipeline configuration PURPOSE: Document the primary GitLab delivery pipeline for Azure Local deployments MASTER REFERENCE: GitLab CI/CD Documentation
Status: Active
Overview
GitLab CI/CD is the primary pipeline platform for Azure Local deployments. The pipeline uses modular stage includes with reusable templates, manual approval gates between phases, and artifact passing between jobs.
Pipeline Architecture
validate → plan → deploy-foundation → configure-onprem → deploy-cluster → configure-operations → validate-deployment
| Stage | Tool | Runner | Trigger |
|---|---|---|---|
| validate | Terraform validate, Ansible lint, config validation | Cloud (shared) | Automatic |
| plan | Terraform plan | Cloud (shared) | Automatic |
| deploy-foundation | Terraform apply, output export | Cloud (shared) | Manual approval |
| configure-onprem | Ansible playbooks (AD, OS, Arc) | Self-hosted | Manual approval |
| deploy-cluster | Azure CLI (ARM) | Cloud (shared) | Manual approval |
| configure-operations | Ansible playbooks (monitoring, WAC, syslog) | Self-hosted | Manual approval |
| validate-deployment | Connectivity tests, compliance checks | Self-hosted | Manual |
Pipeline Structure
pipelines/gitlab/
├── .gitlab-ci.yml # Master pipeline definition
├── stages/
│ ├── validate.yml # Lint, schema validate, plan
│ ├── deploy-foundation.yml # Terraform apply
│ ├── configure-onprem.yml # AD prep, OS config, Arc registration
│ ├── deploy-cluster.yml # ARM cluster deployment
│ ├── configure-operations.yml # Monitoring, WAC, Syslog
│ └── validate-deployment.yml # Post-deployment tests
└── templates/
├── terraform-plan-apply.yml # Reusable TF plan/apply template
└── ansible-playbook.yml # Reusable Ansible run template
Configuration
Required CI/CD Variables
| Variable | Type | Description |
|---|---|---|
ARM_CLIENT_ID | Secret | Service Principal Application ID |
ARM_CLIENT_SECRET | Secret | Service Principal Secret |
ARM_TENANT_ID | Secret | Azure AD Tenant ID |
ARM_SUBSCRIPTION_ID | Secret | Target Azure Subscription ID |
DOMAIN_ADMIN_PASSWORD | Secret | On-premises domain admin password |
CLUSTER_NAME | Variable | Azure Local cluster name |
CLUSTER_RESOURCE_GROUP | Variable | Cluster resource group |
CI_ENVIRONMENT_NAME | Variable | Target environment (lab/staging/production) |
Runner Requirements
The configure-onprem and configure-operations stages require a self-hosted GitLab Runner with:
- Network access: WinRM (5986), LDAP (389), Kerberos (88) to on-premises infrastructure
- Software: Python 3.10+, Ansible >= 2.15, PowerShell >= 7.0, Azure CLI
- Tags:
azurelocal,self-hosted
Stage Details
Validate Stage
terraform:validate—terraform init -backend=false && terraform validate && terraform fmt -checkansible:lint—ansible-lint playbooks/ roles/andansible-playbook --syntax-checkconfig:validate— Load and verifyvariables.ymlvia PowerShell helper
Plan Stage
terraform:plan— Generates a plan artifact passed to the apply job
Deploy Foundation Stage
terraform:apply— Applies the plan with manual approval gateterraform:outputs— Exports outputs as JSON artifact for downstream stages
Configure On-Prem Stage (sequential with manual gates)
ad:preparation—playbooks/01-ad-preparation.ymlos:configuration—playbooks/02-os-configuration.yml(depends on AD prep)arc:registration—playbooks/03-arc-registration.yml(depends on OS config)
Deploy Cluster Stage
cluster:validate— Checks cluster readiness via Azure CLIcluster:deploy— Initiates cluster deployment (long-running, 45-90 minutes)
Configure Operations Stage
monitoring:setup—playbooks/04-monitoring-setup.ymlmanagement:vms—playbooks/05-management-vms.yml
Validate Deployment Stage
validate:connectivity— Post-deployment connectivity testsvalidate:compliance— Azure Policy and Defender compliance checks
Reusable Templates
terraform-plan-apply.yml
Extends .terraform:plan and .terraform:apply with backend configuration:
include:
- local: 'pipelines/gitlab/templates/terraform-plan-apply.yml'
my-plan:
extends: .terraform:plan
variables:
TF_ROOT: src/terraform/environments/azure-local
ansible-playbook.yml
Extends .ansible:playbook for consistent collection installation and execution:
include:
- local: 'pipelines/gitlab/templates/ansible-playbook.yml'
my-playbook:
extends: .ansible:playbook
variables:
PLAYBOOK: playbooks/01-ad-preparation.yml
OS Configuration Pipeline
File: pipelines/gitlab/os-configuration.gitlab-ci.yml (include it from .gitlab-ci.yml, or copy it). It runs Invoke-AzureLocalOsConfiguration.ps1 and nothing else.
| Stage | Job type | Description |
|---|---|---|
plan | Automatic | Read only. Publishes the plan report and the wipe list (the disks that would be wiped on each node when os_configuration.clear_storage is true) as artifacts |
apply | Manual | Someone allowed to run protected jobs reads the plan job's log and artifacts, then plays it. resource_group keeps two runs from working on the cluster at once |
Sign-in is AZURE_AUTH = oidc (a federated app registration, through id_tokens) or managed-identity. No secret is stored: the nodes' local administrator password is read from the Key Vault named by identity.local_admin.password. The runner needs a route to the nodes' management network for PowerShell remoting (WinRM), or -Transport ArcRunCommand for a site with no route. See Automated OS configuration.
ARM Validate and Deploy Pipeline
File: pipelines/gitlab/stages/arm-deployment.yml. It declares its own stages (arm-plan, arm-validate, arm-deploy), so include it from a pipeline file of its own, not from .gitlab-ci.yml, whose stage list belongs to the Terraform and Ansible pipeline above.
| Job | Stage | Description |
|---|---|---|
arm-preconditions | arm-plan | Read only. Parameters and every precondition. Always runs |
arm-validate | arm-validate | Runs when ARM_MODE is Validate or ValidateAndDeploy |
arm-deploy | arm-deploy | Manual job in the protected environment azure-local-deploy. It re-checks every precondition and that these parameters validated. ARM_RESUME=true resubmits a failed Deploy |
CI/CD variables: ARM_MODE, AZURE_AUTH, AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, INFRASTRUCTURE_FILE, OS_CONFIGURATION_REPORT, HANDOFF_FILE, ARM_ACKNOWLEDGE. Details: ARM Validate and Deploy automation.
Repository
Source: azurelocal-toolkit/pipelines/gitlab/
Navigation
| Previous | Up | Next |
|---|---|---|
| Part 2: CI/CD Pipelines | Part 2: CI/CD Pipelines | GitHub Actions |