Microsoft Workloads on AWS

Event-driven Active Directory domain join with HAQM EventBridge

In this blog post, I will show you how HAQM EventBridge can automate Microsoft Active Directory (AD) domain join and unjoin for your HAQM Elastic Compute Cloud (HAQM EC2) instances. In a previous blog post, I showed you how AWS Systems Manager Automation can dynamically domain join and unjoin EC2 instances manually. I have worked with customers who wanted to add automation to execute the AWS Systems Manager Automation runbook. I will show you two examples of AD domain join and unjoin automation that are event driven, HAQM EC2 tag triggering AWS Lambda and HAQM EC2 Auto Scaling.

Solution Overview

EventBridge is a serverless service that lets you connect applications using events. It listens for specific events in your AWS environment based on rules and subsequently triggers actions in response (Figure 1). This blog post presents two solutions for domain join and unjoin using EventBridge. The first solution allows you to domain join or unjoin with HAQM EC2 tags. The second solution allows you to domain join or unjoin with HAQM EC2 Auto Scaling. Visit AWS documentation to learn What is HAQM EventBridge, Rules in HAQM EventBridge, and HAQM EventBridge event patterns.

Figure 1 - Example HAQM EventBridge workflow which routes events to an AWS Lambda function and then AWS Systems Manager Automation.

Figure 1 – Example HAQM EventBridge workflow which routes events to an AWS Lambda function and then AWS Systems Manager Automation.

Prerequisites

Both solutions are available as AWS CloudFormation templates. To start, deploy the Automation runbook from the previous blog post.

Note: This guide assumes DNS has been configured already for your AD environment running in AWS. Configuring DNS at scale is beyond the scope of this blog. You can review existing guides to configure such an environment with either HAQM Route 53 Resolver endpoints or DHCP option sets in HAQM VPC.

The components of the EC2 tag solution include:

The components of the HAQM EC2 Auto Scaling solution include:

  • An Auto Scaling group.
  • Two lifecycle hooks.
    • One lifecycle hook for instance launching.
    • One lifecycle hook for instance termination.
  • An HAQM EC2 launch template associated with the Auto Scaling group.
  • HAQM Simple Notification Service topic.
  • Two EventBridge rules.
    • One rule to join HAQM EC2 instances to your AD domain.
    • One rule to unjoin HAQM EC2 instances from your AD domain.
  • IAM roles and policies.

Walkthroughs

I will start with the HAQM EC2 tag walkthrough. Tagging your HAQM EC2 instances with StartEvent will activate the EventBridge rule, triggering your Lambda function to execute the Automation runbook. The Lambda function evaluates the domain activity based on the HAQM EC2 tag value, either Join or Unjoin. In addition, the Lambda function will start HAQM EC2 instances if they are not in a running state before executing the Automation runbook.

Note: Additional tag compliances can be configured in your AWS account with services such as AWS Config. Visit the AWS documentation, Implementing and enforcing tagging.

HAQM EC2 tag walkthrough

New or existing HAQM EC2 tags are matched with the Tag Change on Resource event.

{
  "detail-type": ["Tag Change on Resource"],
  "source": ["aws.tag"],
  "detail": {
    "changed-tag-keys": ["StartEvent"],
    "service": ["ec2"],
    "resource-type": ["instance"]
  }
}

Now I will walk through AWS Tools for PowerShell examples to join multiple HAQM EC2 instances from an AD domain using EC2 tags.

  1. Open the console, search for AWS CloudShell, and select CloudShell (Figure 2).
Figure 2 - Opening CloudShell from the AWS Management Console.

Figure 2 – Opening CloudShell from the AWS Management Console.

  1. At the CloudShell prompt, type pwsh, and press Enter.
  2. At the PowerShell prompt, paste and run the following PowerShell statement to launch Windows HAQM EC2 instances.
    1. Replace SubnetId, SecurityGroupId, and IamInstanceProfile_Arn parameters with values within your AWS account.
    2. This walkthrough launches 4 HAQM EC2 instances of m6i.2xlarge instance type.
Import-Module AWS.Tools.EC2
$imageId = Get-SSMLatestEC2Image -Path ami-windows-latest -ImageName "Windows_Server-2019-English-Core-Base"
$nameTag = @{Key="Name";Value="AD-PowerShell-Join-Demo"}
$adJoinTag = @{Key="StartEvent";Value="Join"}
$tagSpecAdJoin = New-Object -TypeName HAQM.EC2.Model.TagSpecification
$tagSpecAdJoin.ResourceType = "instance"
$tagSpecAdJoin.Tags.Add($nameTag)
$tagSpecAdJoin.Tags.Add($adJoinTag)
New-EC2Instance -ImageId $imageId -MaxCount 4 -InstanceType "YOURINSTANCETYPE" -SubnetId "YOURSUBNETID" -SecurityGroupId "YOURSECURITYGROUPID" -TagSpecification $tagSpecAdJoin -IamInstanceProfile_Arn "YOURINSTANCEPROFILEARN"
  1. If successful, a ReservationID will be displayed in CloudShell (Figure 3).
Figure 3 - Running New-EC2Instance cmdlet in AWS CloudShell.

Figure 3 – Running New-EC2Instance cmdlet in AWS CloudShell.

  1. Confirm the EC2 instances are launching in the HAQM EC2 console (Figure 4).
  2. In the navigation pane, choose Instances, and the running HAQM EC2 instances will be listed in the console.
  3. After all status checks have passed, navigate to the Systems Manager console.
Figure 4 - Four new EC2 instances launched from AWS CloudShell.

Figure 4 – Four new EC2 instances launched from AWS CloudShell.

  1. In the navigation pane, select Automation. If successful, 4 executions will be listed (Figure 5).
Figure 5 - Four Automation runbook executions with a status code of Success which means the AD domain join was completed.

Figure 5 – Four Automation runbook executions with a status code of Success which means the AD domain join was completed.

Now I will show you how easy it is to remove these HAQM EC2 instances from the same AD domain using PowerShell.

  1. Follow Step 1 to launch CloudShell if it was closed.
  2. At the PowerShell prompt, paste and run the following PowerShell statement, making note of the HAQM EC2 tag’s value changing to Unjoin.
Import-Module AWS.Tools.EC2
$adUnjoinTag = New-Object -TypeName HAQM.EC2.Model.Tag
$adUnjoinTag.Key = "StartEvent"
$adUnjoinTag.Value = "Unjoin"
$instanceIds = (Get-EC2Instance -Filter @{Name="tag:Name";Values="AD-PowerShell-Join-Demo"}).Instances.InstanceId

foreach ($instanceid in $instanceIds) {
    New-EC2Tag -Resource $instanceid -Tag $adUnjoinTag
}
  1. If successful, validate the tags are changed in the HAQM EC2 console (Figure 6).
Figure 6 - Tag value changed to Unjoin after running the PowerShell script.

Figure 6 – Tag value changed to Unjoin after running the PowerShell script.

  1. Navigate to the Systems Manager console.
  2. In the navigation pane, select Automation. A new set of executions will have started, attempting to remove the HAQM EC2 instances from the AD domain.

HAQM EC2 Auto Scaling walkthrough

New HAQM EC2 instances that are launched by an Auto Scaling group are matched with the EC2 Instance-launch Lifecycle Action event.

{
  "detail-type": ["EC2 Instance-launch Lifecycle Action"],
  "source": ["aws.autoscaling"],
  "detail": {
    "AutoScalingGroupName": ["YOURASGNAME"]
  }
}

Terminating HAQM EC2 instances from an Auto Scaling group is matched with the EC2 Instance-terminate Lifecycle Action event. The event pattern differs slightly with the detail-type of the EC2 Instance-terminate Lifecycle Action.

Another scalable method to perform AD domain join or unjoin is with HAQM EC2 Auto Scaling. Windows workloads that are AD-aware scale with an Auto Scaling group and ensure that each HAQM EC2 instance are added to an AD domain at launch or removed from the same AD domain before termination. EventBridge rules monitor Auto Scale group events through their lifecycle policies.

Now I will walk through an example of scaling up and down with an AD domain.

  1. Navigate to the HAQM EC2 console.
  2. In the navigation pane, choose Auto Scaling Groups, and then select the Auto Scaling group created by the CloudFormation template (Figure 7).
Figure 7 - Auto Scaling group created by the CloudFormation template.

Figure 7 – Auto Scaling group created by the CloudFormation template.

  1. In Details tab, select Edit in the Group Details panel (Figure 8).
Figure 8 - The Details tab showing the Auto Scaling group details.

Figure 8 – The Details tab showing the Auto Scaling group details.

  1. Change the Desired capacity type from 0 to 1 and select Update. This will add one new HAQM EC2 instance to the Auto Scaling group (Figure 9).
Figure 9 - Manually changing the Desired Capacity from 0 to 1, manually adding a new HAQM EC2 instance to the Auto Scaling group.

Figure 9 – Manually changing the Desired Capacity from 0 to 1, manually adding a new HAQM EC2 instance to the Auto Scaling group.

  1. In the Instance management tab, the Lifecycle of the HAQM EC2 instance will change from Pending:Wait to InService (Figure 10).
Figure 10 - New HAQM EC2 instance in Pending:Wait lifecycle, which will trigger the EventBridge rule to call Systems Manager Automation.

Figure 10 – New HAQM EC2 instance in Pending:Wait lifecycle, which will trigger the EventBridge rule to call Systems Manager Automation.

  1. Navigate to the Systems Manager console.
  2. In the navigation pane, select Automation.

Just like the HAQM EC2 tag example, Systems Manager will execute the AD domain Automation runbook to show that the Auto Scaling launched HAQM EC2 instance has joined the AD domain (Figure 11).

Note: If the AD domain join fails, HAQM EC2 instances are stopped and tagged appropriately. If the failure is not remediated, continual scaling activities will occur within an Auto Scaling group. Test your AD join and unjoin with a smaller set of HAQM EC2 instances.

Figure 11 - The Automation runbook execution with a status code of Success which means the AD domain join was completed.

Figure 11 – The Automation runbook execution with a status code of Success which means the AD domain join was completed.

Repeating steps 14 – 18 and changing Desired capacity type to 0 will start the removal of HAQM EC2 instances launched by the Auto Scaling group. The event pattern will see the termination lifecycle hook and attempt to remove the HAQM EC2 instance from your AD domain. To confirm, go to the Instance management tab and confirm that the Lifecycle changes from InService to Terminating:Wait (Figure 12).

Figure 12 - Example of an HAQM EC2 instance in a Terminating:Wait lifecycle. EventBridge will initiate the Systems Manager Automation runbook to perform an AD domain unjoin activity.

Figure 12 – Example of an HAQM EC2 instance in a Terminating:Wait lifecycle. EventBridge will initiate the Systems Manager Automation runbook to perform an AD domain unjoin activity.

Cleanup

To delete the resources created by the CloudFormation template, go to the AWS CloudFormation console in the management account. Choose the stack you created, and then choose Delete. To avoid incurring charges, clean up the resources that you created as part of this post. This will delete the instances, make sure to keep snapshots as part of recovery if required by your business.

Summary

Using EventBridge, you can automate and scale the domain join and unjoin processes for your Windows EC2 instances. Whether you choose to perform these tasks with HAQM EC2 tags or HAQM EC2 Auto Scaling, EventBridge will domain join and unjoin and scale to meet your application needs!

AWS has significantly more services, and more features within those services, than any other cloud provider, making it faster, easier, and more cost effective to move your existing applications to the cloud and build nearly anything you can imagine. Give your Microsoft applications the infrastructure they need to drive the business outcomes you want. Visit our .NET on AWS and AWS Database blogs for additional guidance and options for your Microsoft workloads. Contact us to start your migration and modernization journey today.

TAGS: ,
Syed Ahmad

Syed Ahmad

Syed Ahmad is a Principal Specialist Solutions Architect for Microsoft workloads in AWS. He specializes in Active Directory, AWS Identity services, and AWS Management & Governance. Outside of work, Syed spends time with his family, enjoys playing on his Xbox, mimics great chef recipes at an amateur level, and waiting for another 49ers Super Bowl victory.