I want to use Amazon EC2 Systems Manager to join an EC2 instance to the AWS Directory Service domain. How can I do this?

You can use the EC2 Systems Manager (SSM) to automatically join an instance to the domain. The domain can be hosted on AWS Directory Service, Simple AD, or Microsoft AD. The instance can also be located over an on-premises network that is joined to an AD Connector.

You can join your instances to an AWS Directory Service domain using Systems Manager Documents, or you can use the EC2 launch wizard. The wizard looks for an existing document; if it is not available, the wizard creates one using the format awsconfig_Domain_<DIRECTORYID>_<DOMAIN>.

Note: If you are using the EC2 Launch Wizard, the directory must be present in the same VPC as the instance that is being launched.

Configure an AWS Identity and Access Management (IAM) instance profile role for Systems Manager, and then attach the AmazonEC2RoleforSSM role to an EC2 instance. This role enables the instance to communicate with the Systems Manager API. For more information, see Setting Up Systems Manager.

To join a running instance using SSM:

Open notepad or your favorite HTML editor and save the following JSON file.

{    
     "schemaVersion": "1.0",
     "description": "Sample configuration to join an instance to a domain",
     "runtimeConfig": {
        "aws:domainJoin": {
          "properties": {
            "directoryId": "<directory id>",
            "directoryName": "<domain name>",
            "dnsIpAddresses": [
               "<domain controller IP address>"
         ]
       }
    }
  }
}

This document lists the directory ID and DNS addresses. Add this document to SSM using the AWS CLI or PowerShell, so that SSM knowns which domain to associate it with.

CLI:

aws ssm create-document --content <config_file>.json --name "domain_join_config"

PowerShell:

$json_file = Get-Content <config_file>.json | Out-String
New-SSMDocument -Content $json_file  -Name "domain_join_config"

This document is available for use with SSM. Associate the document with the instances in order to join it to the domain.

CLI:

aws ssm create-association --instance-id <instance-id>  --name "domain_join_config"

PowerShell:

New-SSMAssociation -InstanceId <instance-id>  -Name "domain_join_config"

Restart the instance to ensure that the domain join is successful.

Note: If the instance fails to join the directory domain, check if the instance is able to communicate with AWS Directory Service using the DirectoryServicePortTest test application; for more information, see Connect Verification.


Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2017-07-07