How do I use AWS Systems Manager to join a running EC2 Windows instance to my AWS Directory Service domain?

Last updated: 2020-12-18

I want to use AWS Systems Manager to join a running Amazon Elastic Compute Cloud (Amazon EC2) instance to my AWS Directory Service domain. How can I do this?

Short description

You can use AWS Systems Manager to automatically join a running instance to the domain. You can host the domain on AWS Directory Service using AWS Directory Service for Microsoft Active Directory or Simple AD. The domain can also be located over an on-premises network using the AD Connector directory gateway.


You can join a running Windows EC2 instance to an AWS Directory Service directory using Run Command with the AWS-provided document AWS-JoinDirectoryServiceDomain.


  • AWS Directory Service directory
  • Windows EC2 instance
  • Systems Manager prerequisites
  • AWS Identity and Access Management (IAM) instance profile role with the following permissions policies attached for Systems Manager and directory join access:

Note: If you use Amazon Virtual Private Cloud (Amazon VPC) endpoints for Systems Manager, then requests to join an EC2 instance to an AWS Directory Service domain fail. For more information, see VPC endpoint restrictions and limitations.

Join an Amazon EC2 Windows instance to an AWS Directory Service directory

Important: The target instance reboots automatically to finish joining your domain. Before you begin, be sure that rebooting your instance is safe for your infrastructure.

  1. Open the Amazon EC2 console, choose your Region, and then choose Instances from the navigation pane.
  2. Select your target instance. On the Description tab, for IAM role, confirm that a role is attached which is configured for Systems Manager and directory join access. For more details, see Create an IAM instance profile for Systems Manager.
    Note: To update the attached IAM role, choose Actions, Instance Settings, Attach/Replace IAM Role.
  3. Open the AWS Systems Manager console, choose your Region, and then choose Run Command from the navigation pane.
  4. Choose Run a Command.
  5. Search for the document AWS-JoinDirectoryServiceDomain. Then, select AWS-JoinDirectoryServiceDomain from the search results.
  6. For Command parameters, enter the following:
    For Directory Id, enter the ID of the AWS Directory Service directory.
    For Directory Name, enter the DNS name of the directory.
    (Optional) For Dns Ip Addresses, enter the IP addresses of the DNS servers in the directory, one per line. This step isn't required if domain DNS servers are configured in the DHCP options set.
    Note: To locate the values used in step 6 for your directory, open the AWS Directory Service console, and then choose Directories from the navigation pane. Choose the Directory ID link for your directory, and then find the values in the Directory details section.
  7. For Targets, select Choose instances manually, and then select the instance that you want to join to the domain.
  8. Choose Run.
  9. When the Command status reports Success, choose the Instance Id in the Targets and outputs section. You can view the command output and verify that the instance successfully joined the domain.


If the instance fails to join the directory domain, then verify that the instance is able to communicate with Directory Service using the DirectoryServicePortTest application.

For more information about working with the AWS Systems Manager agent and other troubleshooting steps, see AWS Systems Manager managed instances.

For more troubleshooting strategies, see How to troubleshoot errors that occur when you join Windows-based computers to a domain on the Microsoft website.