This content is part of the Conference Coverage: Your guide to AWS re:Invent 2017 news and analysis

Organize hybrid compute resources with Amazon SSM agent

It's difficult to manage a cloud deployment and even more difficult to get a handle on hybrid cloud. EC2 Systems Manager works across AWS and on-premises servers to lessen the burden.

A move to cloud opens doors for many businesses, but it also introduces several challenges. IT teams need updated...

skills to manage these new technologies.

It's not easy for an enterprise to completely shift their infrastructure to a new platform; a hybrid cloud approach is a natural first step. Typically, some infrastructure remains on premises while they launch new applications in the cloud. In these hybrid scenarios, IT teams need additional tools and management strategies, depending on where infrastructure lives. This can be especially complex when distributing servers across data centers -- on premises and in the cloud.

To address these hybrid cloud challenges, AWS provides Elastic Compute Cloud (EC2) Simple Systems Manager (SSM), a service that collects software inventory, applies patches, performs configuration management across both Windows and Linux and maintains software compliance. The Amazon SSM agent not only targets EC2 instances, it also supports on-premises servers, making it a handy tool for hybrid cloud.

SSM includes Run Command, a component that enables teams to remotely execute commands on servers. Developers can run those commands on EC2 instances in the cloud, as well as VMs or physical servers in a data center. This centralizes management across cloud and local servers.

Create an IAM service role

On-premises servers need permissions to call the SSM service. Create a role in the AWS Identity and Access Management (IAM) console or AWS Command Line Interface (CLI) to enable those systems to communicate with SSM. CLI is quicker and requires fewer steps, so let's take that approach.

Create a text file called ssm.json with the following code:


  "Version": "2012-10-17",

  "Statement": {

    "Effect": "Allow",

    "Principal": {"Service": ""},

    "Action": "sts:AssumeRole"



Next, use the create-role subcommand to create the service role. For example, this command could create a role called SSMRole, and it assumes that the ssm.json file from the previous step is located in the current directory.

aws iam create-role --role-name SSMRole --assume-role-policy-document file://ssm.json

After creating the role, attach the AmazonEC2RoleforSSM policy, which allows any system that assumes the role to execute SSM commands. This is a long one-liner, so watch out for line-wrapping issues here:

aws iam attach-role-policy --role-name SSMRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEC2RoleforSSM

At this point, your IAM setup is ready to go. The next step is to integrate an on-premises server.

Activate an instance prior to installation

Create a managed instance activation in the EC2 console before installing the SSM agent on local servers. This process provides an activation code and ID to use when installing the agent on data center servers.

In the EC2 console, expand Systems Manager Shared Resources, and select Activations. Select the Create an activation button, and fill out the details, as shown below.

Configure a managed instance activation before installing the Amazon SSM agent.
Figure 1. Name and configure the activation.

I've given the activation a description. The instance limit is set to one, but the value can increase to accommodate multiple servers. In this case, I'm only setting up an on-premises server; this activation connects with the IAM role we created via CLI. Finally, I've set an expiration date for the activation. The server's default name is Web1.

After filling in the configuration information and clicking Activate, you'll see a screen like that in Figure 2.

Note the activation code and activation ID after creating an activation.
Figure 2. Create a managed instance activation in the EC2 console.

Note the activation code and the activation ID; you'll need these when installing the Amazon SSM agent on the on-premises server.

Install the Amazon SSM Agent

There are agents for a variety of Linux distributions, as well as Windows Server. In this example, I'll use a Windows Server agent. Consult AWS documentation for steps to install the Amazon SSM agent on Linux.

You'll need to script the installation of the agent. Take a look at the following code snippet:

Use code to install SSM with a Windows Server agent.
Figure 3. Install the SSM agent with this code.

This may seem complex, but keep in mind it's fully covered in the AWS documentation. Here's a rundown of what the script includes:

  • On lines 1 and 2, we declare the location of the SSM agent and download it to the local server.
  • On lines 4 and 5, we create variables that reference the activation code and activation ID from the EC2 console when creating the activation.
  • On line 7, we kick off the installer with a few special arguments. We pass in values for the activation code, the activation ID and the region in which we created the managed instance activation. This ties the server to the created activation from the previous step.

After running this script, navigate to Systems Manager Shared Resources in the EC2 console, and select Managed Instances to view the managed instance.

Once you have a managed instance, target the on-premises server with the Run Command utility. You can also use other features that SSM supports, including system, patching and software inventory. This approach makes it easier to visualize and manage all servers in the cloud and on premises.

Next Steps

Blow past hybrid setup barriers with these tools

Questions remain about AWS and VMware's partnership

Hybrid cloud fits into AWS' future plans

Dig Deeper on Amazon EC2 (Elastic Compute Cloud) management