AWS Cloud Operations Blog

Enable management of your Amazon EC2 instances in AWS Systems Manager using Default Host Management Configuration

Update 01/2024: In October 2023, AWS Systems Manager announced the ability to enable AWS Systems Manager by default for all EC2 instances in an organization using Systems Manager Quick Setup. You can begin utilizing the benefits of DHMC in just a few clicks from the Quick Setup console. For more information, see Default Host Management for an organization.

Additionally, the CloudFormation template referenced in this post has been updated to create IAM roles in each target Region and the instructions have been modified to reflect this change. The previous version of the template created a single IAM role in the MainRegion.

Previously, customers were required to attach an AWS Identity and Access Management (IAM) instance profile to Amazon Elastic Compute Cloud (EC2) instances in order to register with AWS Systems Manager. To accomplish this, customers may have been required to manually attach an IAM instance profile on a per-instance basis or use automated methods, such as Systems Manager Quick Setup, to attach the IAM instance profile. If an instance did not have an appropriate IAM instance profile attached, the instance would remain unmanaged by Systems Manager which may lead to the instance becoming insecure, inaccessible, or falling out of security and compliance.

Today, we are excited to announce the release of Systems Manager Default Host Management Configuration which enables you to ensure that all EC2 instances are automatically managed by Systems Manager. By enabling Default Host Management Configuration, you no longer are required to attach an IAM instance profile to the EC2 instance in order to register the node with Systems Manager.

Thus, you can easily track and manage your instances without any additional configuration, providing you a better security and compliance posture for your entire EC2 fleet. To get started, you need to perform a one-time configuration in your AWS account and Region which we describe below.

Prerequisites

EC2 instances must have the AWS Systems Manager Agent (SSM Agent) version 3.2.532.0 or later installed. Additionally, EC2 instances must have network connectivity to the public Systems Manager service endpoints or to AWS PrivateLink VPC endpoints for Systems Manager.

Walkthrough

To enable Default Host Management Configuration in a single AWS account and Region, we recommend to use one of the approaches either the AWS Systems Manager Fleet Manager console, or the AWS Command Line Interface (AWS CLI), or one of the AWS SDKs.

To enable Default Host Management Configuration across multiple AWS accounts and Regions within an AWS Organization, we recommend to use AWS CloudFormation StackSets and the sample template provided below or alternatively use the Systems Manager Quick Setup configuration, Default Host Management for an organization.

Follow the steps in the walkthroughs below for your preferred approach.

Default Host Management Configuration in a single AWS account and Region

Using the Fleet Manager Console

  1. Open the AWS Systems Manager console and in the navigation pane, choose Fleet Manager.
  2. Choose Default Host Management Configuration under the Account management dropdown.
  3. Turn on Enable Default Host Management Configuration.
  4. Choose the IAM role used to enable Systems Manager capabilities for your instances. We recommend using the default role provided by Default Host Management Configuration. It contains the minimum set of permissions necessary to manage your Amazon EC2 instances using Systems Manager.
  5. Choose Configure to complete setup.

Using the AWS CLI

  1. Install and configure the AWS Command Line Interface (AWS CLI), if you haven’t already.
    For information, see Installing or updating the latest version of the AWS CLI.
  2. Create a few environment variables in your shell to work through the rest of the commands. Substitute your AWS account ID and the AWS Region you are working in for the commands below.
export AWS_ACCOUNT_ID=12345689012
export AWS_DEFAULT_REGION=us-west-2
export DEFAULT_ROLE_NAME=AWSSystemsManagerDefaultEC2InstanceManagementRole
  1. Create a local JSON file named trust-policy.json on your local machine with the following content for the IAM role trust relationship policy.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Service": "ssm.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
  1. Run the following command to create an IAM service role in your account. The name of the IAM service role is AWSSystemsManagerDefaultEC2InstanceManagementRole.
aws iam create-role \
--role-name ${DEFAULT_ROLE_NAME} \
--assume-role-policy-document file://trust-policy.json
  1. Run the following command to attach the AmazonSSMManagedEC2InstanceDefaultPolicy managed policy to your newly created role.
aws iam attach-role-policy \
    --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedEC2InstanceDefaultPolicy \
    --role-name ${DEFAULT_ROLE_NAME}
  1. Run the following command to update the service setting for Default Host Management. There is no output if the command succeeds. Note that you need to repeat this step in every Region where you want to turn on Default Host Management Configuration.
aws ssm update-service-setting \
    --setting-id arn:aws:ssm:${AWS_DEFAULT_REGION}:${AWS_ACCOUNT_ID}:servicesetting/ssm/managed-instance/default-ec2-instance-management-role \
    --setting-value ${DEFAULT_ROLE_NAME}
  1. Run the following command to view the current service settings for Default Host Management Configuration in the current AWS account and AWS Region.
aws ssm get-service-setting \
    --setting-id arn:aws:ssm:${AWS_DEFAULT_REGION}:${AWS_ACCOUNT_ID}:servicesetting/ssm/managed-instance/default-ec2-instance-management-role

The command returns information similar the following:

{
    "ServiceSetting": {
        "SettingId": "/ssm/managed-instance/default-ec2-instance-management-role",
        "SettingValue": "AWSSystemsManagerDefaultEC2InstanceManagementRole",
        "LastModifiedDate": 1670501489.527,
        "LastModifiedUser": "System",
        "ARN": "arn:aws:ssm:us-west-2:123456789012:servicesetting/ssm/managed-instance/default-ec2-instance-management-role",
        "Status": "Customized"
    }
}

After you run the commands above, you can describe EC2 instances registered with Systems Manager using the CLI command describe-instance-information. For example:

aws ssm describe-instance-information --output table --query 'InstanceInformationList[*].[InstanceId,IamRole]'
------------------------------------------------------------------------------
|                         DescribeInstanceInformation                        |
+----------------------+-----------------------------------------------------+
|  i-0123456789EXAMPLE |  AWSSystemsManagerDefaultEC2InstanceManagementRole  |
|  i-9876543210EXAMPLE |  AWSSystemsManagerDefaultEC2InstanceManagementRole  |
+----------------------+-----------------------------------------------------+

Use CloudFormation StackSets to enable Default Host Management Configuration across AWS accounts and Regions

The above processes detail how to enable Default Host Management within a given AWS account and Region. If you manage multiple AWS accounts or have EC2 instances in other AWS Regions, then you can use AWS CloudFormation StackSets to enable Default Host Management in those target locations or alternatively, use the Systems Manager Quick Setup configuration, Default Host Management for an organization.

Make sure that your management and target accounts are set up with the permissions required for these stacks to run. For more information, check the prerequisites for stack set operations in the AWS CloudFormation documentation. If you don’t have this setup or want to avoid using StackSets, then you can use individual CloudFormation stacks in each target account.

Open the following GitHub page and download the enableDefaultHostManagement.yml file.

https://github.com/aws-samples/aws-systems-manager-default-host-management-configuration/blob/main/enableDefaultHostManagement.yml

This template creates the following resources:

  1. The AWSSystemsManagerDefaultEC2InstanceManagementRole-${AWS::Region} IAM role for instances with the policy AmazonSSMManagedEC2InstanceDefaultPolicy attached.
  2. An Automation IAM service role scoped to:
    • ssm:UpdateServiceSetting
    • ssm:GetServiceSetting
    • iam:PassRole for the Default Host Management IAM role.
  1. An Automation runbook to then:
    • Check the existing setting value for Default Host Management Configuration.
    • Branch to the update step if the value does not equal AWSSystemsManagerDefaultEC2InstanceManagementRole-${AWS::Region}.
    • Update the service setting value to AWSSystemsManagerDefaultEC2InstanceManagementRole-${AWS::Region}.
    • Describe the service setting for confirmation.
  1. A State Manager association for the Automation runbook to run once.
Figure 1. Architecture diagram of resources created by the AWS CloudFormation StackSet in the designated target AWS accounts and Regions.

Figure 1. Architecture diagram of resources created by the AWS CloudFormation StackSet in the designated target AWS accounts and Regions.

To get started, proceed through the following steps:

  1. In the AWS Organizations management account or in the delegated administrator account for CloudFormation, open the AWS CloudFormation console.
  2. In the navigation pane, choose StackSets and then choose Create StackSet.
  3. On the Choose a template page, perform the following steps:
    1. The content of the Permissions section varies, depending on whether you have AWS Organizations enabled:
      1. If you do not have AWS Organizations enabled, choose Self service permissions, and then choose Next.
      2. If you have AWS Organizations enabled, you can choose Service managed permissions to apply the StackSets to an organization or OU. For more manual control, you can also choose Self service permissions.
    2. For Prerequisite – Prepare template, leave the default Template is ready.
    3. For Specify template, select Upload a template file, select Choose file, choose the enableDefaultHostManagement.yml file, and then choose Next.
  4. On the Specify StackSet details page perform the following steps:
    1. Provide a StackSet name, such as default-ssm.
    2. Optionally, provide a description.
    3. Choose Next.
  1. On the Configure StackSet options page, optionally add tags and choose Next.
  2. On the Set deployment options page, perform the following steps:
    1. For Deployment targets, choose to deploy to the entire AWS organization or choose to deploy to specific AWS organizational units (OUs).
    2. For Specify regions, select the regions were you have Systems Manager managed nodes.
    3. Choose Next.
  1. On the Review page, review the options and parameters selected, choose I acknowledge that AWS CloudFormation might create IAM resources with custom names, and then choose Submit.

After the page is refreshed, you will be able to see your StackSet. The status will change to SUCCEEDED after it’s been created.

Testing

After you’ve turned on Default Host Management Configuration, instances with SSM Agent version 3.2.532.0 or later installed will automatically become managed instances.

Let’s test by launching a t2.medium instance without any attached IAM roles, connect via SSH to install the latest version of SSM agent, and verify that the instance is able to register with Systems Manager. Note: You must create a key pair prior to launching the EC2 instance. For more information see, Create key pairs.

Launch a test Amazon Linux 2 instance

  1. Retrieve the latest Amazon Linux 2 image ID and store it as an environment variable.
IMAGE_ID=$(aws ssm get-parameter --name "/aws/service/ami-amazon-
linux-latest/amzn2-ami-hvm-x86_64-gp2" --query
 'Parameter.[Value][0]' --output text)
  1. Launch an instance using the image ID retrieved using the previous step and replace the key-name with your own. Note the instance ID of the launched instance, e.g. i-0xxxx0536ae9d1234.
aws ec2 run-instances \
    --image-id $IMAGE_ID \
    --instance-type t2.medium \
    --key-name blog-keypair
  1. Connect to the newly launched Amazon Linux 2 instance using SSH. Note: You must replace the key-pair name with your own and the public DNS name with the public DNS entry of your EC2 instance.
ssh -i /blog-keypair.pem ec2-user@ec2-11-22-33-44.compute-1.amazonaws.com
  1. Install the latest version of SSM agent:
sudo yum install -y https://s3.amazonaws.com/ec2-downloads-
windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm
  1. Verify SSM agent is running:
sudo systemctl status amazon-ssm-agent
● amazon-ssm-agent.service - amazon-ssm-agent
   Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2023-02-10 14:23:00 UTC; 37s ago
 Main PID: 6432 (amazon-ssm-agen)
   CGroup: /system.slice/amazon-ssm-agent.service
           ├─6432 /usr/bin/amazon-ssm-agent
           └─6489 /usr/bin/ssm-agent-worker

Verify the instance is registered with Systems Manager

Now that we have launch an Amazon Linux 2 instance with the latest version of SSM Agent, our instance will register with Systems Manager. Verify that you are able to see the instance using the describe-instance-information CLI command:

aws ssm describe-instance-information --filters "Key=InstanceIds,Values= i-0xxxx0536ae9d1234"
{
    "InstanceInformationList": [
        {
            "InstanceId": "i-0xxxx0536ae9d1234",
            "PingStatus": "Online",
            "LastPingDateTime": "2023-02-10T14:26:05.639000+00:00",
            "AgentVersion": "3.2.582.0",
            "IamRole": "AWSSystemsManagerDefaultEC2InstanceManagementRole-us-east-1"
	…
        }, 
        …
}

Optionally, connect to the instance using Session Manager. Note: To connect using the AWS CLI, you must first install the Session Manager plugin for the AWS CLI.

aws ssm start-session --target i-0xxxx0536ae9d1234
Starting session with SessionId: Admin-0fb5a3f5a5054372e
sh-4.2$ yum info amazon-ssm-agent
Loaded plugins: extras_suggestions, langpacks, priorities, update-motd
Installed Packages
Name        : amazon-ssm-agent
Arch        : x86_64
Version     : 3.2.582.0
…

Clean up

To terminate the test instance, you can use the Amazon EC2 console or the following AWS CLI command:

aws ec2 terminate-instances --instance-id i-0xxxx0536ae9d1234

To disable Default Host Management Configuration, use the API ResetServiceSetting such as in the following AWS CLI command (Note: You must replace <AWS-REGION> and <ACCOUNT-ID> with your respective values):

aws ssm reset-service-setting --setting-id arn:aws:ssm:<AWS-
REGION>:<ACCOUNT-ID>:servicesetting/ssm/managed-instance/default-ec2-
instance-management-role

To delete the CloudFormation StackSet, go to the AWS CloudFormation console in the management account or delegated administrator account. From the left navigation pane, choose StackSets, and then choose the StackSet that you created. From Actions, choose Delete stacks from StackSet, enter the AWS OU ID, choose Add all regions, choose Next, and choose Submit. Once all of the Stack instances have been deleted, choose Actions and choose Delete StackSet to remove the StackSet.

Conclusion

In this post, we showed you how to enable Default Host Management Configuration in a single AWS account and Region using the Fleet Manager console or the AWS CLI. We also showed you how to enable this feature across your AWS Accounts and Regions within an AWS Organization using CloudFormation StackSets.

This provides a simple way of automatically registering Amazon EC2 instances in an account with AWS Systems Manager. By registering EC2 instances with Systems Manager, you can improve your security and compliance posture as you don’t have to worry about instances that maybe untracked due to misconfiguration.

To verify EC2 instances are registered across your AWS accounts and Regions, you can use Systems Manager Explorer. Systems Manager Explorer is a customizable operations dashboard that reports information about your AWS resources. Explorer displays an aggregated view of operations data (OpsData) for your AWS accounts and across AWS Regions. One widget in Explorer highlights EC2 instances that are managed by Systems Manager and instances that are unmanaged. For more information, see Getting started with Systems Manager Explorer and OpsCenter.

About the authors:

Erik Weber

Erik Weber is a Sr. World-wide Specialist Solutions Architect for AWS Cloud Operations services. He specializes in AWS Systems Manager, AWS Config, AWS CloudTrail, and AWS Audit Manager. Outside of work, Erik has a passion for hiking, cooking, and biking.

Deban Prabu

Deban Prabu is a Technical Account Manager at Amazon Web Services. He helps Enterprise Support customers achieve outcomes and find success in the cloud by providing advocacy and guidance to plan and build solutions using best practices. He drives customers adoption and use of AWS services, and helps them achieve the greatest value from AWS.

Vinod Shukla

Vinod Shukla is a Principal Solutions Architect at Amazon Web Services. As part of the AWS Integration and Automation team, he enjoys working with partners providing technical guidance and assistance in building AWS Partner Solutions, which are automated reference deployments of popular technologies.