How to Deploy an Active Directory Domain Controller in Azure Using Terraform and GitHub Actions (Step-by-Step Lab)

If you’re an Azure engineer, architect, or IT professional preparing for hybrid cloud environments, one essential skill is knowing how to deploy an Active Directory Domain Controller in Azure, not manually, but programmatically with Terraform and GitHub Actions.

In this post, I’ll walk you through a fully automated Azure AD DS lab setup, including networking, compute, disk configuration, and PowerShell automation, perfect for testing Group Policy, Azure AD Connect, or hybrid identity scenarios.

Table of Contents

Why Build an Active Directory Lab in Azure?

Setting up a domain controller manually is fine for quick tests, but if you want repeatability, version control, and scalability, Infrastructure as Code is the way forward.

This lab demonstrates:

Fully automated deployment using Terraform
Role installation via PowerShell VM extensions
Deployment orchestration using GitHub Actions CI/CD
Modular setup that can evolve with your environment

What This Lab Deploys

The Terraform configuration builds the following Azure components:

A Resource Group
A Virtual Network (10.0.0.0/16) with a Subnet (10.0.1.0/24)
A Network Security Group allowing RDP (3389)
A Public IP and NIC
A Windows Server 2022 VM
A 128 GB Managed Data Disk mounted as F:
A PowerShell script that installs the AD DS role

Prerequisite: Create a Service Principal with Contributor Access

To allow GitHub Actions to authenticate with Azure and deploy infrastructure via Terraform, you need to create a Service Principal and assign it Contributor permissions to your subscription.

az login

az ad sp create-for-rbac --name "terraform-sp" \
  --role Contributor \
  --scopes /subscriptions/<your-subscription-id> \
  --sdk-auth

This will output a JSON object. Copy it and save it as a GitHub secret called AZURE_CREDENTIALS.

In addition, you’ll need to add the following GitHub secrets:

ARM_CLIENT_ID
ARM_CLIENT_SECRET
ARM_SUBSCRIPTION_ID
ARM_TENANT_ID

These are parsed from the JSON above and used by both Terraform and GitHub Actions for authentication.

GitHub Actions for CI/CD Automation

Instead of running Terraform locally, this project uses GitHub Actions to:

Authenticate with Azure using the service principal
Run terraform init, plan, and apply
Trigger the PowerShell script via a VM extension to install AD DS
All secrets are managed via GitHub Secrets, ensuring a secure and portable CI/CD pipeline.

Domain Promotion (Manual by Design)

The deployment installs AD DS but does not auto-promote the machine to a Domain Controller. This is intentional to:

Avoid conflicts with hardcoded domains
Let you choose your own domain name and Safe Mode password
Make the lab flexible for different test scenarios

Once deployed, connect via RDP and run this PowerShell command:

Install-ADDSForest `
  -DomainName "yourdomain.local" `
  -DomainNetbiosName "YOURDOMAIN" `
  -InstallDNS `
  -DatabasePath "F:\Windows\NTDS" `
  -LogPath "F:\Windows\NTDS" `
  -SysvolPath "F:\Windows\SYSVOL" `
  -SafeModeAdministratorPassword (ConvertTo-SecureString "YourDSRMPassword123!" -AsPlainText -Force) `
  -Force:$true

Lessons Learned

Set static IP via the Azure NIC, not inside the OS. Misconfigured static IPs break RDP.
Don’t reboot inside VM extensions. Azure assumes failure if the script doesn’t return a success code.
Separate the install and promotion steps to simplify debugging and increase flexibility.

Security Tips for Lab Environments

While this is a non-production setup, you should still:

Lock down RDP to your own IP or use just-in-time access
Never commit passwords to code, use GitHub Secrets
Use strong admin passwords and rotate regularly

What You Can Do with This Lab

Test Group Policy Objects (GPOs)
Set up Azure AD Connect
Join other VMs to the domain
Explore DNS forwarding and trusts
Validate hybrid identity scenarios

Try It Now

You can get started in minutes by cloning the full repo:

rrichley/azure-ad-dc-lab