Remotely Run Commands on an EC2 Instance with AWS Systems Manager
TUTORIAL
Overview
In this hands-on tutorial, you will learn how to use AWS Systems Manager to remotely run commands on your Amazon EC2 instances. Systems Manager is a management tool that enables you to gain operational insights and take action on AWS resources safely and at scale. Using the run command, one of the automation features of Systems Manager, you can simplify management tasks by eliminating the need to use bastion hosts, SSH, or remote PowerShell.
In our example scenario, as a System Administrator, you need to update the packages on your EC2 instances. To complicate this normally simple admin task, your security team does not allow you to direct access production servers via SSH or allow you to use bastion hosts. Fortunately, you can use Systems Manager to remotely run commands, like update packages, on your EC2 instances.
To solve this challenging scenario, you will create an Identity and Access Management (IAM) role, enable an agent on your instance that communicates with Systems Manager, then follow best practices by running the AWS-UpdateSSMAgent document to upgrade your Systems Manager Agent, and finally use Systems Manager to run a command on your instance.
AWS Systems Manager is an always free tier product. The EC2 instance you create in this tutorial is free tier eligible.
Open the AWS Management Console, so you can keep this step-by-step guide open. When the screen loads, enter your user name and password to get started.
AWS experience
Beginner
Time to complete
10 minutes
Cost to complete
Free Tier eligible
Requires
- AWS Account
- Recommended browser: The latest version of Chrome or Firefox
[**]Accounts created within the past 24 hours might not yet have access to the services required for this tutorial.
Last updated
July 14, 2022
Implementation
Step 1: Create an Identity and Access Management (IAM) role
In this step, you will create an IAM role that will be used to give Systems Manager permission to perform actions on your instances.
a. Open the IAM console at https://console.aws.amazon.com/iam/.
b. In the left navigation pane, choose Roles, and then choose Create role.
c. On the Select trusted entity page, under AWS Service, choose EC2, and then choose Next.
d. On the Add permissions page, in the search bar type AmazonEC2RoleforSSM. From the policy list select AmazonEC2RoleforSSM and then choose Next.
e. On the Name, review, and create page, in the Role name box, type in EnablesEC2ToAccessSystemsManagerRole. In the Description box, type in Enables an EC2 instance to access Systems Manager. Choose Create role.
Step 2: Create an EC2 instance
In this step, you will create an EC2 instance using the EnablesEC2ToAccessSystemsManagerRole role. This will allow the EC2 instance to be managed by Systems Manager.
a. Open the Amazon EC2 console. From the EC2 console, select your preferred Region. Systems Manager is supported in all AWS Regions. Now choose Launch instance.
b. In the Name field, enter MyEC2Tutorial. Select the Amazon Linux AMI. Retain the default selection that appears in the dropdown. You can also install the Systems Manager Agent on your own Windows or Linux system.
d. You will not need a keypair to use Systems Manager to remotely run commands. Scroll down to Key pair and under the Key pair name dropdown, choose Proceed without a key pair.
e. Retain default settings under Network settings and Configure storage.
Step 3: Update the Systems Manager Agent
Now that you have an EC2 instance running the Systems Manager agent, you can automate administration tasks and manage the instance. In this step, you run a pre-packaged command, called a document, that will upgrade the agent. It is best practice to update the Systems Manager Agent when you create a new instance.
a. In the top navigation bar, search for Systems Manager and open the Systems Manager console.
b. Under the Node Management section on the left navigation bar, choose Fleet Manager.
c. Select the node ID created in step 2, MyEC2Tutorial, to open the node detail page.
d. On the node detail page, in the Node actions dropdown, select Execute run command.
e. On the Run a command page, click in the search bar and select, Document name prefix, then click on Equals, then type in AWS-UpdateSSMAgent.
Now select the radio button on the left of AWS-UpdateSSMAgent. This document will upgrade the Systems Management agent on the instance.
f. Scroll down to the Targets panel and select the check box next to your managed EC2 instance.
Finally, scroll down and select Run.
g. Next you will see a page documenting your running command, and then overall success in green. Congrats, you have just run your first remote command using Systems Manager.
Step 4: Run a remote shell script
Now that your EC2 instance has the latest Systems Manager Agent, you can upgrade the packages on the EC2 instance. In this step, you will run a shell script through Run Command.
a. Under the Node Management section on the left navigation bar, choose Fleet Manager.
b. Select the node ID created in step 2, MyEC2Tutorial, to open the node detail page.
c. On the node detail page, in the Node actions dropdown, select Execute run command.
d. On the Run a command page, click in the search bar and select, Document name prefix, then click on Equals, then type in AWS-RunShellScript.
Now select the radio button on the left of AWS-RunShellScript.
e. Scroll down to the Command Parameters panel and insert the following command in the Commands text box:
sudo yum update –y
f. Scroll down to the Targets panel and select the check box next to your managed EC2 instance.
Finally, scroll down and select Run.
g. While your script is running remotely on the managed EC2 instance, the Overall status will be In Progress. Soon the Overall status will turn to Success. When it does, scroll down to the Targets and outputs panel and select the Instance ID of your instance. Your Instance ID will be different than the one pictured.
h. From the Output on: i-XX page, select the header of the Output panel to view the output of the update command from the instance.
Step 5: Terminate your resources
In this step, you will terminate your Systems Manager and EC2 related resources. Important: Terminating resources that are not actively being used reduces costs and is a best practice. Not terminating your resources can result in a charge.
a. Open the Amazon EC2 console and from the left navigation under the Instances heading, select Instances.
b. Select your instance's checkbox and choose Instance state, then select Terminate instance. This will terminate your instance completely.
Congratulations
Congratulations, you have successfully created a managed instance and remotely run a command using AWS Systems Manager. You first set up the correct permissions through IAM. Next you launched an Amazon Linux instance that was preinstalled with the Systems Manager agent. Finally, you used Run Command to update the agent and remotely perform a yum update.
Systems Manager is a good choice when you need to view operation data for groups of resources, automate operational actions, understand and control the current state of your resources, manage hybrid environments, and maintain security and compliance.