Orchestrating Azure Infrastructure via GitHub Actions and Terraform

The intersection of Infrastructure as Code (IaC) and Continuous Integration/Continuous Deployment (CI/CD) represents the modern standard for cloud governance. By integrating Terraform—a powerful, provider-agnostic orchestration tool—with GitHub Actions, organizations can transition from manual resource provisioning to a fully automated, version-controlled lifecycle. This architectural approach ensures that every change to the Azure environment is documented, tested, and validated before it is ever applied to production. The synergy between GitHub's event-driven automation and Terraform's state management allows for a rigorous "GitOps" workflow, where the repository serves as the single source of truth for the entire cloud footprint, including complex deployments such as Azure Kubernetes Service (AKS) clusters.

The Automated Infrastructure Lifecycle

The operational flow for managing Azure infrastructure via GitHub Actions is designed around a series of triggers that ensure code quality and environment stability. This lifecycle typically begins when a developer creates a new branch and commits Terraform code modifications. This initial step ensures that changes are isolated from the stable environment, allowing for iterative development without risking production uptime.

Once the modifications are ready, a Pull Request (PR) is initiated in GitHub. This action triggers a specific GitHub Actions workflow designed for validation. The primary objective of this workflow is to ensure the code is well-formatted, internally consistent, and secure. The validation process consists of several critical layers:

• Linting: The workflow executes terraform fmt to verify that the code adheres to the standard Terraform formatting guidelines. This ensures readability and maintainability across the engineering team.
• Syntactic Validation: The terraform validate command is run to check that the code is syntactically correct and internally consistent. This prevents deployment failures caused by simple typos or invalid resource references.
• Static Analysis: The workflow integrates Checkov, an open-source static code analysis tool for IaC. Checkov scans the configuration to detect security vulnerabilities and compliance issues, ensuring that the infrastructure is secure by design before it is provisioned.
• Change Preview: A Terraform plan is executed to generate a detailed preview of the changes. This plan allows reviewers to see exactly which resources will be added, modified, or destroyed in the Azure environment.

After a thorough peer review of the PR and the associated Terraform plan, the PR is merged into the main branch. This merge triggers a secondary GitHub Actions workflow that executes the terraform apply command, translating the approved configuration into actual Azure resources.

Secure Authentication via OpenID Connect (OIDC)

A critical component of a secure CI/CD pipeline is the elimination of long-lived secrets. Traditionally, GitHub Actions required the storage of Azure Service Principal client secrets as GitHub Secrets. However, the modern standard is to use OpenID Connect (OIDC).

OIDC is an identity authentication protocol that extends OAuth 2.0 to standardize how users and applications authenticate. In the context of GitHub Actions, OIDC allows the workflow to request a short-lived access token directly from Azure. This mechanism is significantly more secure than using static credentials because it removes the need to create and duplicate secrets within GitHub. Because these tokens are only valid for the duration of a single job, the system effectively implements automatic credential rotation.

To implement OIDC, a federated credential must be established between Microsoft Entra ID (formerly Azure Active Directory) and GitHub. This setup tells both platforms to trust one another. The trust relationship is defined using subjects that grant specific permissions based on the GitHub context. For example:

• Environment-based access: A subject such as repo:${var.github_organization_target}/${var.github_repository}:environment:${var.environment} grants the workflow permission to authenticate when deploying to a specific environment, such as "dev".
• PR-based access: A subject like repo:${var.github_organization_target}/${var.github_repository}:pull_request enables authentication specifically for workflows triggered by pull requests.
• Branch-based access: The subject can also be tied to a specific branch, such as repo:my-github-user/my-repo:ref:refs/heads/main.

Terraform State Management in Azure

Terraform relies on a state file to map real-world resources to the configuration files. This state file contains metadata that allows Terraform to determine which changes need to be made to reach the desired state described in the code. By default, this is stored in a local terraform.tfstate file.

Under no circumstances should the terraform.tfstate file be committed to source control. Committing state files leads to security risks, as they often contain sensitive data, and creates concurrency issues when multiple developers are working on the same infrastructure.

The professional solution is to use a remote backend. For Azure deployments, the state is stored inside an Azure Storage Account. This provides a centralized, locked, and secure location for the state file, enabling team collaboration and preventing state corruption during simultaneous runs.

Provider Configuration and OIDC Integration

To enable OIDC authentication within Terraform, the provider configuration must be explicitly told to use OIDC. This is achieved in the providers.tf file. The configuration involves defining the required providers and the backend settings.

The following configuration demonstrates the integration of the AzureRM and AzAPI providers:

```hcl
terraform {
requiredversion = ">=1.0"
requiredproviders {
azurerm = {
source = "hashicorp/azurerm"
version = "~>3.0"
}
azapi = {
source = "azure/azapi"
version = "~>1.5"
}
random = {
source = "hashicorp/random"
version = "~>3.0"
}
azuread = {
source = "hashicorp/azuread"
version = "2.30.0"
}
}
backend "azurerm" {
key = "terraform.tfstate"
use_oidc = true
}
}

provider "azurerm" {
features {}
use_oidc = true
}

provider "azapi" {
use_oidc = true
}
```

In this setup, the use_oidc = true flag is critical. It instructs the AzureRM and AzAPI providers to utilize the OIDC token provided by the GitHub Actions environment rather than searching for traditional client secrets.

Utilizing Data Sources for Dynamic Configuration

To maintain a flexible and DRY (Don't Repeat Yourself) codebase, Terraform uses data blocks. A data block allows Terraform to read information from an existing Azure resource without managing that resource's lifecycle.

For example, to retrieve the Subscription ID of the current Azure subscription, the azurerm_subscription data source is used. This is exported under a local name, such as sub.

hcl data "azurerm_subscription" "sub" {}

Once this data is retrieved, it can be referenced elsewhere in the Terraform configuration. For instance, in a role assignment module where the Subscription ID is required, it can be called using the syntax data.azurerm_subscription.sub.id. This prevents the need to hardcode subscription IDs across multiple files, reducing the risk of errors during environment migrations.

Implementation of GitHub Environments and Approvals

To ensure that deployments to production are controlled and audited, GitHub Environments should be utilized. An environment named production can be created to store Azure identity information and implement a manual approval process.

By configuring a protection rule on the production environment, administrators can require specific approvers to sign off on a deployment before the GitHub Actions workflow proceeds to the apply stage. Furthermore, the environment can be restricted so that only workflows triggered from the main branch are permitted to deploy to it.

The prerequisites for this setup include:

• An Azure Active Directory application with read/write permissions to the target subscription.
• Federated credentials configured for OIDC.
• A defined GitHub environment with associated secrets and protection rules.

Managing Configuration Drift

One of the most advanced aspects of this automation strategy is the detection of configuration drift. Drift occurs when the actual state of the Azure infrastructure deviates from the state defined in the Terraform configuration, often due to manual changes made via the Azure Portal.

To combat this, a regularly scheduled GitHub Action workflow is implemented. This workflow runs periodically to compare the current state of the environment against the configuration. If any drift is detected, the workflow is configured to automatically create a new GitHub issue. This alerts the engineering team that the environment has been modified outside of the IaC pipeline, allowing them to either revert the manual changes or update the Terraform code to reflect the new reality.

Deployment Architecture for Complex Services (AKS)

When deploying complex services like an Azure Kubernetes Service (AKS) cluster, the GitHub Actions workflow can be split into distinct jobs to separate the "Plan" and "Apply" stages. This separation provides a critical safety buffer. The "Plan" job generates the execution plan and uploads it as an artifact. The "Apply" job then downloads this specific plan and executes it, ensuring that exactly what was previewed is what gets deployed.

The use of multiple providers, such as the AzureRM provider for standard resources and the AzAPI provider for newer or preview Azure features, allows for a comprehensive deployment strategy. This is particularly useful when building out a personal development cluster where monitoring, resiliency, and automated tests are added incrementally over time.

Technical Specifications Summary

The following table details the core components and their roles within the GitHub Actions and Terraform ecosystem.

Analysis of the Integrated Workflow

The integration of GitHub Actions and Terraform on Azure transforms infrastructure management from a manual task into a software engineering discipline. The reliance on OIDC significantly hardens the security posture by eliminating the "secret sprawl" typically associated with CI/CD pipelines. By leveraging federated identities, the trust is placed in the identity of the workflow itself, anchored to a specific repository and environment.

The use of the Azure Storage Account for state management solves the primary challenge of Terraform in a team environment: state locking and consistency. When combined with the "Deep Drilling" approach to validation—incorporating linting, syntactic checks, and security scanning via Checkov—the risk of deploying broken or insecure infrastructure is drastically reduced.

Furthermore, the implementation of drift detection closes the loop on the deployment cycle. Most IaC implementations stop at the apply phase; however, by scheduling a recurring check for drift, the system ensures that the "source of truth" in GitHub remains synchronized with the actual state of the cloud. This creates a self-healing or at least a self-reporting infrastructure that resists "manual creep," where engineers make "quick fixes" in the portal that are never documented in code.

The architectural decision to separate the Plan and Apply stages via GitHub Jobs, and to gate the Apply stage behind environment approvals, provides a robust framework for enterprise-grade deployments. This ensures that no change reaches production without an audit trail and a human-in-the-loop verification process, which is essential for maintaining the stability of critical services like AKS.

Sources

1. terraform-github-actions GitHub Repository
2. Deploying to Azure with Terraform and GitHub Actions - dev.to
3. GitHub Actions Terraform Azure - willvelida.com
4. Infrastructure as Code with GitHub Actions - Microsoft Learn