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

4 minute read

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

Short description

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


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


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

Note: If you launch an Amazon EC2 instance in a private subnet, then you must allow traffic from your instance to the public AWS Directory Service endpoints. 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 automatically reboots 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 AWS Region, and then choose Instances from the navigation pane.
  2. Select your target instance. On the Details tab, for IAM role, confirm that a role is attached that's configured for Systems Manager and directory join access. For more details, see Configure instance permissions for Systems Manager.
    Note: To update the attached IAM role, choose Actions, Security, Modify 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 for each line. If you configured the domain DNS servers in the DHCP options set, then this step isn't required.
    Note: To locate the values that you entered in step 6 for your directory, open the AWS Directory Service console. 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 Target selection, choose 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. Review the command output, and verify that the instance successfully joined the domain.


If the instance fails to join the directory domain, then complete the following steps:

  1. Use the DirectoryServicePortTest application to verify that the instance is can communicate with Directory Service. For a list of port numbers that are required for joining a domain, see Active Directory and Active Directory Domain Services Port Requirements on the Microsoft website.
  2. Verify that instances on the same subnet can manually join the domain. If the manual join attempt fails, then check if the Domain Controllers are accessible from the target subnet.
  3. If you use AD Connector to connect to AWS Managed Microsoft AD, then verify that the directory organizational unit (OU) parameter is specified. If you don't specify the directory OU parameter, then the domain join fails. AWS Managed Microsoft AD doesn't allow you to create computer objects in the default OU.

For more information about working with the AWS Systems Manager Agent and other troubleshooting steps, see Working with managed nodes.

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

Related information

What is AWS Directory Service?

How can I manage an AWS Managed Microsoft AD or Simple AD directory from an Amazon EC2 Windows instance?

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

AWS OFFICIALUpdated a year ago