Building a Production-Ready Azure DevOps Pipeline for Terraform

With OIDC, Stage Gates & Reusable Templates

When you’re deploying infrastructure at scale, Azure DevOps Terraform pipelines need to be more than just a “plan and apply” script. They need to be safe, reusable, secure, and structured enough to support multiple teams and multiple environments.

In this post, I’ll walk through a production-grade Azure DevOps YAML pipeline that I use to deploy Terraform – complete with OIDC authentication, reusable templates, gated approvals, private module access and dynamic state file naming.

This is part of my broader series on deploying Infrastructure as Code with DevOps.

Why This Pipeline Pattern Matters

Most teams start with a basic Terraform workflow:

  • install Terraform
  • run init
  • run plan
  • run apply

But in real-world environments, we also need:

  • Guardrails to prevent accidental deployments
  • Parameter enforcement
  • No secrets or client credentials
  • A plan stage that requires human approval
  • A structure that works across multiple projects
  • Reusable templates to avoid copy/pasting YAML everywhere
  • Support for private module repos

This pipeline covers all of that.

Pipeline Overview

The pipeline is built around three core stages:

1. Parameter Validation

Ensures environment and region are explicitly selected.

2. Validate & Plan

Runs Terraform validate and plan using OIDC authentication.

3. Apply With Approval

Uses an Azure DevOps Environment to pause execution until approved.

This gives you a clean workflow:

validate → plan → review → approve → apply

Parameters

I avoid CI-style “auto-deploy on push” pipelines for Terraform. Instead, I prefer intentional deployments: the user must select an environment and region.

parameters:
  - name: environment
    type: string
    default: notspecified
    values: [notspecified, dev, uat, prod]

  - name: location
    type: string
    default: notspecified
    values: [notspecified, westeurope, centralus, australiaeast]

  - name: debugMode
    type: boolean
    default: false
If either value is left as  notspecified, the pipeline will fail early.

Variables (Terraform Backend)

I use Azure Blob Storage as my Terraform remote backend:

Treat the Terraform state backend as a protected production data store. If the backend is private, choose an agent pattern that can reach its private endpoint.

variables:
  management-subscription-id: "<subscription-id>"
  TFSTATE_RESOURCE_GROUP: "rg-terraform"
  TFSTATE_STORAGE_ACCOUNT: "tfstatestorage"
  TFSTATE_CONTAINER_NAME: "tfstate"

These point to the shared management subscription where I keep my Terraform state.

Reusable Template: terraform-setup.yml

This is one of the most useful parts of the design.

Any time the pipeline needs to initialise Terraform, I call the following template:

  • Installs SSH key
  • Installs Terraform
  • Runs Terraform Init with backend config
- template: templates/terraform-setup.yml
  parameters:
    tfstateKey: $(TFSTATE_KEY)

I avoid repeating Terraform installation, backend configuration, etc.

Instead, the template handles it all.

This keeps pipelines clean and makes refactoring easy.

Dynamic State File Naming

Instead of hardcoding a .tfstate file name, I generate it dynamically

based on:

  • DevOps project
  • Environment
  • Region

Example:

myproject_dev_westeurope.tfstate

This allows reuse of the same pipeline across multiple deployments without clashing state files.

Terraform Validate & Plan Stage

After generating the state key, the pipeline:

  1. Runs the shared template
  2. Runs Terraform Validate
  3. Runs Terraform Plan using environment-specific .tfvars

Example folder structure:

/environments
  /westeurope
     dev.tfvars
     uat.tfvars
     prod.tfvars
  /centralus
     dev.tfvars
     uat.tfvars
     prod.tfvars

This pattern scales easily across regions and environments.

Approval-Gated Deployment

I use an Azure DevOps Environment (terraform-approval) for the apply stage.

This allows:

  • Approvals
  • Checks
  • Deployment history
  • Auditing

Before apply executes, an approver must sign off on the Terraform plan. This is extremely useful for catching unintended changes.

Debug Mode

If debugMode: true, Terraform logging is set to DEBUG:

export TF_LOG=DEBUG

This is helpful when investigating drift, module issues, or state conflicts.

The complete pipeline

The main pipeline

trigger: none

parameters:
  - name: environment
    displayName: "Deployment Environment"
    type: string
    default: notspecified
    values: [notspecified, dev, uat, prod]

  - name: location
    displayName: "Azure Location"
    type: string
    default: notspecified
    values: [notspecified, australiaeast, centralus, westeurope]

  - name: debugMode
    displayName: "Enable Debug Mode"
    type: boolean
    default: false

pool:
  vmImage: "ubuntu-latest"

variables:
  management-subscription-id: "xxxxx-xxxxx-xxxx"
  TFSTATE_RESOURCE_GROUP: "rg-gen-terraform-prod-cus-01"
  TFSTATE_STORAGE_ACCOUNT: "sttfmgmtprodcus01"
  TFSTATE_CONTAINER_NAME: "tfstate"

stages:
  # Parameter Validation Stage - ensure valid selections for environment and location
  - stage: ValidateParameters
    displayName: "Validate Parameters"
    jobs:
      - job: CheckParameters
        displayName: "Check Required Parameters"
        steps:
          - script: |
              if [ "${{ parameters.environment }}" == "notspecified" ] || [ "${{ parameters.location }}" == "notspecified" ]; then
                echo "##vso[task.logissue type=error]ERROR: You must select a valid environment and location."
                echo "##vso[task.logissue type=error]Current values: environment=${{ parameters.environment }}, location=${{ parameters.location }}"
                exit 1
              fi
              echo "Parameters validated successfully: environment=${{ parameters.environment }}, location=${{ parameters.location }}"
            displayName: "Validate Parameter Selection"

  #Terraform Validate and Plan Stage
  - stage: ValidateAndPlan
    displayName: "Terraform Validate and Plan"
    dependsOn: ValidateParameters
    jobs:
      - job: TerraformValidateAndPlan
        displayName: "Terraform Validate and Plan Job"
        steps:
          # Set dynamic TFSTATE_KEY variable
          - script: |
              key="$(echo "${SYSTEM_TEAMPROJECT}${{ parameters.environment }}_${{ parameters.location }}.tfstate" | tr '[:upper:]' '[:lower:]' | tr -d ' ')"
              echo "Generated TFSTATE_KEY: $key"
              echo "##vso[task.setvariable variable=TFSTATE_KEY]$key"
              echo "##vso[task.setvariable variable=TFSTATE_KEY;isOutput=true]$key"
            name: SetTfstateKey
            displayName: "Set dynamic, lowercase, space-free TFSTATE_KEY"

          # Use template for setup and init
          - template: templates/terraform-setup.yml
            parameters:
              tfstateKey: $(TFSTATE_KEY)

          # Terraform Validate
          - task: AzureCLI@2
            displayName: "Terraform Validate (OIDC)"
            inputs:
              azureSubscription: "Federated-Azure-Connection-$(System.TeamProject)"
              scriptType: bash
              scriptLocation: inlineScript
              inlineScript: |
                terraform validate

          # Terraform Plan
          - task: AzureCLI@2
            displayName: "Terraform Plan (OIDC)"
            inputs:
              azureSubscription: "Federated-Azure-Connection-$(System.TeamProject)"
              scriptType: bash
              scriptLocation: inlineScript
              inlineScript: |
                terraform plan \
                  -var="environment=${{ parameters.environment }}" \
                  -var="location=${{ parameters.location }}" \
                  -var-file=environments/${{ parameters.location }}/${{ parameters.environment }}.tfvars

  - stage: Deploy
    displayName: "Terraform Apply with Approval"
    dependsOn: ValidateAndPlan
    variables:
      TFSTATE_KEY: $[ stageDependencies.ValidateAndPlan.TerraformValidateAndPlan.outputs['SetTfstateKey.TFSTATE_KEY'] ]
    jobs:
      - deployment: TerraformApply
        displayName: "Terraform Apply with Approval"
        environment: terraform-approval
        strategy:
          runOnce:
            deploy:
              steps:
                # Checkout the repository to access tfvars files
                - checkout: self

                # Use template for setup and init
                - template: templates/terraform-setup.yml
                  parameters:
                    tfstateKey: $(TFSTATE_KEY)

                # Terraform Apply
                - task: AzureCLI@2
                  displayName: "Terraform Apply (OIDC)"
                  inputs:
                    azureSubscription: "Federated-Azure-Connection-$(System.TeamProject)"
                    scriptType: bash
                    scriptLocation: inlineScript
                    inlineScript: |
                      if [ "${{ parameters.debugMode }}" == "True" ]; then
                        export TF_LOG=DEBUG
                        echo "Debug mode enabled - logging to terraform-debug-apply.log"
                      fi

                      terraform apply \
                        -auto-approve \
                        -var="environment=${{ parameters.environment }}" \
                        -var="location=${{ parameters.location }}" \
                        -var-file=environments/${{ parameters.location }}/${{ parameters.environment }}.tfvars

The re-usable template

# Template for common Terraform setup steps
parameters:
  - name: tfstateKey
    type: string

steps:
  # Install the SSH key from the ADO library for Terraform Module access
  - task: InstallSSHKey@0
    displayName: "Install SSH Key for Terraform Modules"
    inputs:
      knownHostsEntry: "ssh.dev.azure.com"
      sshKeySecureFile: "terraform-id_rsa"

  # Install Terraform
  - task: TerraformInstaller@1
    displayName: "Install Terraform"
    inputs:
      terraformVersion: "latest"

  # Terraform Init
  - task: AzureCLI@2
    displayName: "Terraform Init (OIDC)"
    inputs:
      azureSubscription: "Federated-Azure-Connection-$(System.TeamProject)"
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        cd ./landingzones/rpsi-cloudsolutions-01
        terraform init \
          -backend-config="subscription_id=$(management-subscription-id)" \
          -backend-config="resource_group_name=$(TFSTATE_RESOURCE_GROUP)" \
          -backend-config="storage_account_name=$(TFSTATE_STORAGE_ACCOUNT)" \
          -backend-config="container_name=$(TFSTATE_CONTAINER_NAME)" \
          -backend-config="key=${{ parameters.tfstateKey }}"

Setting Up Azure DevOps

These tasks need to be carried out inside the Azure DevOps project where your terraform code is and the pipelines will run from.

1. Federated (OIDC) Service Connection

This gives Azure DevOps access to Azure without client secrets.

I standardise naming as:

Federated-Azure-Connection-<ProjectName>

This makes pipelines portable. Federation removes stored secrets but not the need to govern workload identity privileges.

When creating the service connection select to use the identity type of App Registration and the credential of Workload identity federation.

2. Azure DevOps Environment

If you recall in our Deploy stage within the pipeline we created an environment called ‘terraform-approval’. We need to create this environment within the DevOps project.

Create:

terraform-approval

Add approvers and set how many approvals are required.

3. Secure Files

We use an SSH Key to connect to allow our pipeline to reference terraform modules from a different Azure DevOps project. Follow the Microsoft guide to create the SSH Key to access the Terraform Modules Project.

Upload the SSH private key for module access into:

Library → Secure Files

How to Run the Pipeline

  1. Click Run Pipeline
  2. Select environment & location
  3. Review Validate & Plan output
  4. Wait for the approval request
  5. Approver reviews the plan
  6. Approver clicks “Approve”
  7. Terraform Apply runs

This pattern brings structure and safety to Terraform deployments.

Final Thoughts

A Terraform pipeline doesn’t need to be complicated – it just needs to be dependable.

By combining OIDC authentication, reusable templates, dynamic state management and gated approvals, this design keeps deployments clean, auditable and scalable across teams.

If you’re building out your IaC platform in Azure DevOps, this pattern is a great foundation.

In the upcoming articles in this series I’ll cover how to setup the terraform code to use the federated OIDC service connection and accept parameters from your pipeline. I will also cover how to protect your GIT repository and main branch as well as a guide on how to run automatic plans and drift analysis.

Further Reading

Check out my previous post on Infrastructure as Code here.

Your subscription could not be saved. Please try again.
Your subscription to deniscooper.co.uk has been successful.

Join Cloud Engineers Who Build Smarter on Azure

Free checklists, practical guides and the latest posts — built for cloud engineers working with Azure and Terraform.

Leave a Comment