Creating an SSM IAM Role and Configuring an EC2 Instance with AWS Systems Manager via the CLI

45 minutes
  • 6 Learning Objectives

About this Hands-on Lab

In this hands-on lab, we’ll be dissecting the IAM role required by an EC2 instance to be able to communicate with Systems Manager service. We’ll first locate the managed AWS policy required for this role and create an EC2 instance via the command line, assigning it the instance profile (container for role assigned). Finally, we’ll verify that Systems Manager (SSM) can detect the instance and communicate with it. (**Note:** This lab is focused on the AWS command line and all technical steps will be shown via the CLI.)

Learning Objectives

Successfully complete this lab by achieving the following learning objectives:

Get the ARN of SSM Policy for IAM Role `AmazonEC2RoleforSSM`
  1. Note down the ARN of the policy from the following command:

    aws iam list-policies --scope AWS --query "Policies[?PolicyName == 'AmazonEC2RoleforSSM']"
  2. Optionally, you may also use the following command in addition to the value of DefaultVersionId from the above command to look at the JSON document of the policy in question via the CLI:

    aws iam get-policy-version --policy-arn <ARN-OF-POLICY> --version-id <VERSION-ID-STRING-FROM-PREV-COMMAND>
Create IAM Role for EC2 and Assign SSM Policy to It
  1. Copy the following JSON and create a new JSON file in your current directory. Name it EC2Trust.json:

      "Version": "2012-10-17",
      "Statement": {
        "Effect": "Allow",
        "Principal": {"Service": ""},
        "Action": "sts:AssumeRole"
  2. Create the role and attach the trust policy JSON file you created above to it. Make sure you execute the following command in the same directory where you created the EC2Trust.json file:

    aws iam create-role --role-name MyEC2SSMRole --assume-role-policy-document file://EC2Trust.json
  3. Assign policy from previous step to the newly created role:

    aws iam attach-role-policy --role-name MyEC2SSMRole --policy-arn <SSM-POLICY-ARN>
Create and Attach an Instance Profile to the IAM EC2 Service Role
  1. Create instance profile using the command below and note down the name you assign to the instance profile (in the case of the command below, it is MyEC2InstanceProfile). Note down the ARN of the instance profile returned to you from executing the command below. We’ll be using it in the next step when we create an EC2 instance.

    aws iam create-instance-profile --instance-profile-name MyEC2InstanceProfile
  2. Add the role created in second task to the instance profile created above:

    aws iam add-role-to-instance-profile --instance-profile-name MyEC2InstanceProfile --role-name MyEC2SSMRole
Gather Necessary Data for Plugging into EC2 Instance Creation Command
  1. Get subnet ID:

    aws ec2 describe-subnets --query "Subnets[?Tags[?Value == 'SubnetA'] ].SubnetId | [0]"
  2. Get security group ID:

    aws ec2 describe-security-groups --filters Name=group-name,Values=SG --query "SecurityGroups[?GroupName == 'SG'].GroupId | [0]"
  3. Get AMI ID (with SSM installed):

    aws ec2 describe-images --filters "Name=architecture,Values=x86_64" "Name=description,Values=*Amazon Linux 2 AMI 2.0.2019*gp2" "Name=owner-id,Values=137112412989" "Name=image-type,Values=machine" --query "sort_by(Images, &CreationDate)[::-1].ImageId | [0]"
Create an EC2 Instance Using Subnet, Security Group, and AMI ID

Plug in the subnet ID, security group ID, AMI ID, and instance profile ARN in the following command:

aws ec2 run-instances --associate-public-ip-address --security-group-ids <SECURITY-GROUP-ID> --iam-instance-profile Arn=<INSTANCE-PROFILE-ARN> --instance-type t2.micro --image-id <AMI-ID> --subnet-id <SUBNET-ID> --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=MyEC2}]"

Notice that we are giving our EC2 instance the name MyEC2 (basically we’re tagging it with this name) so we can get its instance ID and later confirm that SSM sees it.<br/>
If you gave your IAM instance profile the same name as given in the lab task(i.e. MyEC2InstanceProfile ) , you can fetch the Instance Profile ARN(required by command above), by using the following command:<br/>

aws iam get-instance-profile --instance-profile-name MyEC2InstanceProfile
Confirm via SSM CLI API (or GUI) that the Newly Created EC2 Instance Is Visible to It
  1. Get the instance ID of the newly created instance (remember we named it MyEC2, so we’ll use this name in the command to get its instance ID — if you tagged/named it differently, be sure to use that name):

    aws ec2 describe-instances --filters Name=tag:Name,Values=MyEC2 --query "Reservations[].Instances[].InstanceId"
  2. Run the following SSM instance information API command to see if the same instance ID from the command above is showing up in SSM API’s output (plug the instance ID you noted in the previous command into this command in place of the placeholder <INSTANCE-ID>):

    aws ssm describe-instance-information --query "InstanceInformationList[?InstanceId == '<INSTANCE-ID>']"

    The command should return an object with information about the newly configured EC2 instance with Systems Manager.

Note: It can take up to five minutes for the instance to show up in the SSM GUI or API command output.

You can also choose to skip this last step, log in to the AWS Management Console, and compare the EC2 instance value in the EC2 console with the instance ID value under AWS Systems Manager > Managed Instances.

Additional Resources

You work as a DevOps Engineer for a SaaS company, where the development team has been growing recently. New developers are allowed to spin up EC2 instances, but since their OS administration skills are minimal, they face hurdles with software installation and its administration.

Management has tasked you with coming up with a proof of concept for managing EC2 instances in a consolidated way, and you've found AWS Systems Manager is the best possible solution.

Your first task is to figure out how to configure an EC2 instance with SSM before you can proceed.

Log in to the AWS Management Console using the credentials provided, and make sure you're in the us-east-1 (N. Virginia) region.

Helpful Documentation

What are Hands-on Labs

Hands-on Labs are real environments created by industry experts to help you learn. These environments help you gain knowledge and experience, practice without compromising your system, test without risk, destroy without fear, and let you learn from your mistakes. Hands-on Labs: practice your skills before delivering in the real world.

Get Started
Who’s going to be learning?

How many seats do you need?

  • $499 USD per seat per year
  • Billed Annually
  • Renews in 12 months

Ready to accelerate learning?

For over 25 licenses, a member of our sales team will walk you through a custom tailored solution for your business.


Sign In
Welcome Back!
Thanks for reaching out!

You’ll hear from us shortly. In the meantime, why not check out what our customers have to say about ACG?