Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

Joining a Windows Instance to an AWS Directory Service Domain

You can join an Amazon EC2 Windows instance to an active AWS Directory Service directory or AD Connector directory using Amazon EC2 Systems Manager (SSM) Config. To perform this task with SSM Config, you use the AWS CLI or AWS Tools for Windows PowerShell to create an Systems Manager document that specifies the domain join details, and then associate the document with a running instance. Alternatively, you can use launch an instance using the Amazon EC2 console and specify the domain that you want to join. The wizard searches for Systems Manager documents for the domain in your account to associate with the instance; if it can't locate one, it creates a Systems Manager document for you and associates it with your running instance.

Note

In regions that don't support SSM Config, you can manually join an instance to a domain. For more information, see Add an Instance to Your Directory in the AWS Directory Service Administration Guide.

After you've associated a Systems Manager document with your instance, you can connect to the instance using domain credentials you've defined in your AWS Directory Service directory.

There's no additional charge for using SSM Config or joining your instance to a domain. Standard charges for instance usage and AWS Directory Service usage apply.

Limits

  • SSM Config is supported only for Windows instances.

  • SSM Config is available in the following regions.

  • The Windows Server 2016 Nano server installation option (Nano Server) does not support online domain joining. You must perform an offline domain join instead. For more information, see Offline Domain Join (Djoin.exe) Step-by-Step Guide on Microsoft TechNet.

For more information, see Managing Windows Instance Configuration.

Prerequisites

Before you begin, complete the following prerequisites.

  • Create an AWS Directory Service directory. For more information, see Getting Started with AWS Directory Service in the AWS Directory Service Administration Guide.

  • Configure a Windows instance that meets the requirements described in Setting Up Systems Manager in the Amazon EC2 Systems Manager User Guide.

  • When you use the AWS CLI or the AWS Tools for Windows PowerShell, you must create a JSON file that specifies the contents for the Systems Manager document. You must include the name and ID of the directory and the IP addresses of the DNS servers in the directory. To find these addresses, open the AWS Directory Service console, choose Directories, and select the directory. For more information about the structure of a Systems Manager document, see Systems Manager Documents in the Amazon EC2 Systems Manager User Guide.

Example Configuration

The following is an example of the content for a document that joins instances to a domain. Save this content in a file with a .json extension.

Copy
{ "schemaVersion": "1.0", "description": "Sample configuration to join an instance to a domain", "runtimeConfig": { "aws:domainJoin": { "properties": { "directoryId": "d-1234567890", "directoryName": "test.example.com", "dnsIpAddresses": [ "198.51.100.1", "198.51.100.2" ] } } } }

Note that if a valid organizational unit (OU) exists, you could add the OU in directoryOU as follows.

Copy
{ "schemaVersion": "1.0", "description": "Sample configuration to join an instance to a domain", "runtimeConfig": { "aws:domainJoin": { "properties": { "directoryId": "d-1234567890", "directoryName": "test.example.com", "directoryOU": "\"OU=Computers,OU=example,DC=test,DC=example,DC=com\"", "dnsIpAddresses": [ "198.51.100.1", "198.51.100.2" ] } } } }

Joining a Domain Using the Console

When you launch an instance using the Amazon EC2 console, you can join the instance to a domain. If you don't already have a Systems Manager document, the wizard creates one for you and associates it with the instance. Note that you can't use the console to associate a Systems Manager document with an existing instance.

To join an instance to a domain at launch

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the dashboard, choose Launch Instance.

  3. On the first page of the wizard, select a Windows AMI. On the next page, select an instance type, and then choose Next: Configure Instance Details.

  4. For Network, select the VPC for your directory. For Subnet, select a subnet. For Auto-assign Public IP, select Enable, unless you're launching your instance into a private subnet and using a NAT instance for Internet connectivity.

  5. For Domain join directory, select your directory. For IAM role, select an IAM role.

  6. Complete the rest of the configuration steps and launch your instance. Be sure to select or create a security group with a rule that allows RDP access from your IP address, or from a range of IP addresses within your network. For more information, see Authorizing Inbound Traffic for Your Windows Instances.

  7. Check the status of the domain join. For more information, see Getting the Domain Join Status.

Joining a Domain Using the AWS Tools for Windows PowerShell

To use the Tools for Windows PowerShell to join a domain, you must associate a Systems Manager document with an already running instance.

To join a domain using the AWS CLI or AWS Tools for Windows PowerShell

  1. Create a Systems Manager document using the New-SSMDocument command. The name of the file must be between 1 and 64 characters in length.

    Copy
    PS C:\> $contents = Get-Content -Raw my-custom-config.json | Out-String PS C:\> New-SSMDocument -Content $contents -Name "my-custom-config" -DocumentType "Command"
  2. Launch an EC2 instance using the New-EC2Instance command. You must specify the same VPC that you used for your domain. You must assign an IAM role to the instance. You must also ensure that the instance has a public IP address, unless you're using a NAT gateway for Internet connectivity.

    Copy
    PS C:\> New-EC2Instance -ImageId ami-1a2b3c4d -SubnetId subnet-33cc44dd -KeyName my-key-pair -InstanceType m1.large -InstanceProfile_Id MyInstanceProfile -associatePublicIp $true
  3. Associate the document with the running instance using the New-SSMAssociation command.

    Copy
    PS C:\> New-SSMAssociation -InstanceId i-1234567890abcdef0 -Name "My_Custom_Config_File"
  4. Check the status of the domain join. For more information, see Getting the Domain Join Status.

Joining a Domain Using the AWS CLI

To use the AWS CLI to join a domain, you must associate a Systems Manager document with an already running instance.

To join a domain using the AWS CLI

  1. Create a Systems Manager document using the create-document command. The name of the file must be between 1 and 64 characters in length.

    Copy
    aws ssm create-document --content file://path/to/myconfigfile.json --name "My_Custom_Config_File"
  2. Launch an EC2 instance using the run-instances command. You must specify the same VPC that you used for your domain. You must assign an IAM role to the instance. You must also ensure that the instance has a public IP address, unless you're using a NAT gateway for Internet connectivity.

    Copy
    aws ec2 run-instances --image-id ami-1a2b3c4d --subnet-id subnet-33cc44dd --key-name my-key-pair --instance-type m1.large --iam-instance-profile MyInstanceProfile --associate-public-ip-address
  3. Associate the document with the running instance using the create-association command.

    Copy
    aws ssm create-association --instance-id i-1234567890abcdef0 --name "My_Custom_Config_File"
  4. Check the status of the domain join. For more information, see Getting the Domain Join Status.

Getting the Domain Join Status

After you associate a configuration file with an instance, it can take several minutes before the instance is joined to a domain. You can check the status of a domain join by viewing the system log for the instance or by checking the status of the association.

Check the System Log

In the system log, the following is example output when the domain join is successful:

2015/02/02 10:59:36Z: Info: EC2Config configuration status:2;region:us-east-1;iam:1;authz:1
2015/02/02 10:59:42Z: Info: EC2Config: Downloading config awsconfig_Domain_d-1234567890_corp.example.com
2015/02/02 10:59:45Z: Info: EC2Config: The instance is joining domain with id:d-1234567890, name:corp.example.com ...
2015/02/02 10:59:48Z: Info: EC2Config: The instance successfully joined the domain. 
2015/02/02 10:59:48Z: Info: EC2Config: The instance will reboot shortly for domain join to take effect.

To check the system log using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select the instance.

  4. Choose Actions, Instance Settings, Get System Log.

To check the system log using the Tools for Windows PowerShell

Use the Get-EC2ConsoleOutput command as follows.

Copy
Get-EC2ConsoleOutput -instanceId i-1234567890abcdef0

To check the system log using the AWS CLI

Use the get-console-output command as follows.

Copy
aws ec2 get-console-output --instance-id i-1234567890abcdef0

Check the Association Status

You can check the status of the association between the configuration document and the instance.

To check the status of the association using the Tools for Windows PowerShell

Use the Get-SSMAssociation command as follows.

Copy
Get-SSMAssociation -Name "my-custom-config" -instanceId i-1234567890abcdef0

To check the status of the association using the AWS CLI

Use the describe-association command as follows.

Copy
aws ssm describe-association --name "my-custom-config" --instance-id i-1234567890abcdef0

Connecting To Your Instance Using Domain Credentials

After you've joined your instance to a domain, you can connect to your instance using domain credentials that you've defined in AWS Directory Service.

After you've verified that you can connect to your instance as an administrator, domain users can connect to the instance using the same procedure, replacing the administrator credentials with their own user names and passwords.

To connect to an instance as an administrator using your directory credentials

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances, select your instance, and then choose Connect.

  3. In the dialog box, choose Download Remote Desktop File, and open the file using an RDP client.

  4. On the login screen, instead of using the local computer name and the generated password, use the fully-qualified user name for the administrator (for example, corp.example.com\Admin) and the password for this account.

Troubleshooting

If you are having trouble joining your instance to a domain, or if you are having trouble connecting to your instance using domain credentials, first verify the status of the domain join by checking instance's system log, or by checking the status of the association: Getting the Domain Join Status.

Cannot Connect to Instance

If the domain join was successful, but you are having trouble logging into to your instance, try the following:

  • If you can connect to your instance, but you cannot log in, check that you are using the correct user name and password. The user name must include the fully qualified name of your domain (for example, corp.example.com), and the password must be the password configured in the domain, not the password generated by a key pair file.

  • If you cannot connect to your instance, check your security group settings. You must have a rule that allows RDP access from your IP address or network.

The Domain Join was Unsuccessful

In the system log, the following output indicates the EC2Config service was unable to connect and download the associated SSM document, and therefore the domain join was unsuccessful:

Info: EC2Config configuration status:3;region:us-east-1;iam:0;authz:0

The output can help you troubleshoot the cause of the failure:

  • configuration status:3: The calls to SSM Config failed. Ensure that you have granted the required IAM permissions to IAM users. SSM Config also requires an Internet connection from your instance - your instance must have a public IP address, and must be launched into a public subnet. For more information about public subnets, see Your VPC With Subnets in the Amazon VPC User Guide.

  • iam:0: The instance does not have an associated IAM role. You cannot join your instance to a domain if there is no IAM role associated with the instance. To associate an IAM role, see Attaching an IAM Role to an Instance.

  • authz:0: The instance is not authorized to access SSM Config. This happens if you launched the instance without an IAM role, or if the role associated with your instance does not have the necessary permissions to access the service.

You can also troubleshoot specific reasons for a domain join failure by checking the status of the association using the describe-association (AWS CLI) command or the Get-SSMAssociation (Tools for Windows PowerShell) command. For example, the following output indicates that the IAM role associated with the instance does not have permission to use the ds:CreateComputer action:

Name                  : My_Config_Doc
InstanceId            : i-1234567890abcdef0
Date                  : 2/10/2015 1:31:45 AM
Status.Name           : Failed
Status.Date           : 2/10/2015 1:38:38 AM
Status.Message        : RunId=631148a7-894f-4684-8718-ee4cexample, status:Failed, code:0,
                        message:RuntimeStatusCounts=[Failed=1], RuntimeStatus=[aws:domainJoin={Failed,User:
                        arn:aws:sts::123456789101:assumed-role/NoDomainJoinPermission/i-1234567890abcdef0 is not authorized to
                        perform: ds:CreateComputer}]
Status.AdditionalInfo : {agent=EC2Config,ver=x.x.xx,osver=6.2.9200,os=Windows Server 2012 Standard,lang=en-US}

Viewing Your Associations

You can use the AWS CLI or the AWS Tools for Windows PowerShell to view information about your associations and your Systems Manager documents.

Action AWS Tools for Windows PowerShell AWS CLI
To view information about an association. Get-SSMAssociation describe-association
To view information about a document. Get-SSMDocumentDescription describe-document
To view the contents of a document. Get-SSMDocument get-document
To list the associations for a document or instance. Get-SSMAssociationList list-associations
To list your documents. Get-SSMDocumentList list-documents

Changing an Association

You can't update an Systems Manager document after you create it. If you want to join your instance to a new domain, you must first delete the association, and then create a new association using a new SSM document. It can take up to 15 minutes for the configuration changes to take effect.

Deleting an association does not change the configuration on the instance. Your instance is still joined to a domain until you manually remove it from the domain by modifying the network connection configuration information and system properties of the instance.

Tools for Windows PowerShell

Use the following Remove-SSMAssociation command to disassociate a document from your Windows instance.

Copy
PS C:\> Remove-SSMAssociation -InstanceId i-1a2b3c4d -Name "my-custom-config"

AWS CLI

Use the following delete-association command to disassociate a document from your Windows instance.

Copy
aws ssm delete-association --instance-id i-1a2b3c4d --name "my-custom-config"

Deleting a Document

When you are finished with a Systems Manager document, you can delete it. You must disassociate a document from any instances it is associated with before you can delete it.

Tools for Windows PowerShell

Use the following Remove-SSMDocument command to delete your document.

Copy
PS C:\> Remove-SSMDocument -Name "my-custom-config"

AWS CLI

Use the following delete-document command to delete your document.

Copy
aws ssm delete-document --name "my-custom-config"