Skip to content

Domain Join Overview

The domain join feature allows EC2 instances to automatically join Active Directory domains during provisioning. This is accomplished using AWS Systems Manager (SSM) documents that execute domain join operations on Windows instances.

Supported Domain Types

This Terraform module supports two types of Active Directory integration:

  1. AWS Managed Microsoft AD - Fully managed Microsoft Active Directory hosted by AWS Directory Service
  2. Self-Managed AD - Customer-owned Active Directory running on-premises or in a shared services VPC

How It Works

Domain join is implemented as an SSM document that is associated with EC2 instances through SSM associations. When an instance is launched and the SSM agent is running, the association automatically triggers the domain join process.

Workflow

  1. SSM Document Creation - Terraform creates an SSM document containing the domain join logic
  2. SSM Association - EC2 instances reference the domain join document in their configuration
  3. Automatic Execution - When the instance starts, SSM agent executes the document
  4. Domain Join - The instance joins the specified domain and reboots

Key Features

  • Automated Domain Join - No manual intervention required after deployment
  • Credential Security - Domain credentials stored in AWS Secrets Manager
  • OU Placement - Optionally specify target Organizational Unit for computer accounts
  • DNS Configuration - Automatically configures DNS to point to domain controllers
  • Idempotent - Safe to re-run if domain join fails

Module Structure

The domain join functionality is organized into:

  • Module: src/modules/domain_join/ - Core module implementing SSM documents
  • Variables: src/variables.domainjoin.tf - Input variable definitions
  • Main: src/main.domainjoin.tf - Module instantiation

Next Steps