With OIDC, Stage Gates & Reusable Templates
Table of Contents
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: falseIf 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:
- Runs the shared template
- Runs Terraform Validate
- 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
- Click Run Pipeline
- Select environment & location
- Review Validate & Plan output
- Wait for the approval request
- Approver reviews the plan
- Approver clicks “Approve”
- 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.