Skip to main content

GitLab CI/CD Pipeline

Reference Azure

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
StageToolRunnerTrigger
validateTerraform validate, Ansible lint, config validationCloud (shared)Automatic
planTerraform planCloud (shared)Automatic
deploy-foundationTerraform apply, output exportCloud (shared)Manual approval
configure-onpremAnsible playbooks (AD, OS, Arc)Self-hostedManual approval
deploy-clusterAzure CLI (ARM)Cloud (shared)Manual approval
configure-operationsAnsible playbooks (monitoring, WAC, syslog)Self-hostedManual approval
validate-deploymentConnectivity tests, compliance checksSelf-hostedManual

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​

VariableTypeDescription
ARM_CLIENT_IDSecretService Principal Application ID
ARM_CLIENT_SECRETSecretService Principal Secret
ARM_TENANT_IDSecretAzure AD Tenant ID
ARM_SUBSCRIPTION_IDSecretTarget Azure Subscription ID
DOMAIN_ADMIN_PASSWORDSecretOn-premises domain admin password
CLUSTER_NAMEVariableAzure Local cluster name
CLUSTER_RESOURCE_GROUPVariableCluster resource group
CI_ENVIRONMENT_NAMEVariableTarget 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 -check
  • ansible:lint — ansible-lint playbooks/ roles/ and ansible-playbook --syntax-check
  • config:validate — Load and verify variables.yml via 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 gate
  • terraform:outputs — Exports outputs as JSON artifact for downstream stages

Configure On-Prem Stage (sequential with manual gates)​

  • ad:preparation — playbooks/01-ad-preparation.yml
  • os: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 CLI
  • cluster:deploy — Initiates cluster deployment (long-running, 45-90 minutes)

Configure Operations Stage​

  • monitoring:setup — playbooks/04-monitoring-setup.yml
  • management:vms — playbooks/05-management-vms.yml

Validate Deployment Stage​

  • validate:connectivity — Post-deployment connectivity tests
  • validate: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.

StageJob typeDescription
planAutomaticRead 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
applyManualSomeone 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.

JobStageDescription
arm-preconditionsarm-planRead only. Parameters and every precondition. Always runs
arm-validatearm-validateRuns when ARM_MODE is Validate or ValidateAndDeploy
arm-deployarm-deployManual 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/


PreviousUpNext
Part 2: CI/CD PipelinesPart 2: CI/CD PipelinesGitHub Actions