AWS Management Tools Blog

Centralized Management of Multiple Accounts and Cross-Platform EC2 Instances Using AWS Systems Manager

Introduction

Many AWS customers, particularly in the public sector, are implementing a central IT agency model. These organizations have an AWS account for central IT that is designated for the management of security and compliance activities such as patch management, use of golden Amazon Machine Images (AMIs), and federates user access for other agencies’ AWS accounts.

In this blog post, I present a solution that will allow the AWS account for central IT to use AWS Systems Manager (SSM) to execute commands using Run Command and manage patches in the AWS accounts of other agencies. I’ll walk you through the steps for deploying this solution using AWS CloudFormation templates. We will create a Systems Manager Activation in the central account for registering Amazon EC2 instances as managed instances from the other agencies’ AWS accounts. We’ll also deploy AWS Lambda functions to propagate the EC2 tags into the Central IT account and attach them to the managed instances as Systems Manager tags. This way the tags can be used as targets for executing SSM Documents through Run Commands and for other Systems Manager features such as State Manager, Maintenance Windows, and Patch Management.

These are the minimum requirements for implementing this solution:
• Central IT account (or a parent account)
• Agency account (or child accounts)
• EC2 instance profile in the agency account
• SSM agents and Boto3 library on EC2 instances

The following diagram shows the system architecture:

 

Implementation

Step one
First, we’ll create a managed instance activation in the central IT AWS account. This activation will be used to register both Windows and Linux EC2 instances from individual agency accounts. On activation creation, an activation ID along with activation code is returned. You need to store these in a text file, we’ll use them in later steps.

For this blog post I’m providing a Python script for registering Amazon Linux-based EC2 instances from the agency account. You can easily write your own script for Windows or other operating system (OS) platforms.

Step two
Next, we’ll deploy SSM Agent on EC2 instances in all of the agency/child accounts that will be centrally managed through the activation created in the first step. Note that by default the EC2 instance registers to its own account’s Systems Manager after the agent is installed and started. The EC2 instance appears in the Systems Manager Shared Resources section in the appropriate AWS Region, in the Managed Instances tab.

Step three
Now we’ll create two parameters, ActivationID and ActivationCode, in the agency’s Systems Manager Parameter Store for the values we already have copied in a text file in step one. Our Python script that registers the EC2 instance to activation uses the values of these parameters for registration. You can use either the AWS Management Console, the API, or AWS CLI for creating the parameters. For the AWS CLI, use the following commands, which are documented in the CLI Command Reference.

aws ssm put-parameter --name "ActivationID" --type "String" --value "xxxxxxxxxx" --region <AWS_region>

aws ssm put-parameter --name "ActivationCode" --type "String" --value "xxxxxxxxx" --region <AWS_region>

 

Step four
After the SSM Agent is installed, the EC2 instances need to be registered to the activation that we created in the first step. When the registration to an activation is complete, a managed instance ID is returned in the form mi-xxxxxxxxxxxxxxxx. This ID is attached to the instance since neither EC2 instance ID nor the EC2 tags are propagated to the Central IT account from the agency account through activation. We’ll use Lambda functions later to propagate all of the EC2 tags to the Central IT account from each agency account.

The Python code that follows registers an Amazon Linux-based EC2 instance to an unexpired activation. The code requires the Boto 3 library to be pre-installed on the instance and an EC2 instance profile that has permissions to access Systems Manager Parameter Store and create EC2 tags.

#!/usr/bin/python

import os
import urllib2
import json
import commands
import re
import boto3
from boto3 import session

instance_details = json.loads(urllib2.urlopen('http://169.254.169.254/2016-06-30/dynamic/instance-identity/document/').read())

instanceid=instance_details['instanceId']
REGION=instance_details['region']

# Getting the AWS credentials from the IAM role

session = session.Session()
credentials = session.get_credentials()

def Activation(InstanceID):

	#Getting Activation ID and Code from parameter store
	ssm = boto3.client('ssm',region_name=REGION)

	activation_id = ssm.get_parameter(Name='ActivationID')
	ActivationID=activation_id['Parameter']['Value']
	activation_code = ssm.get_parameter(Name='ActivationCode')
	ActivationCode=activation_code['Parameter']['Value']

	# Registering Instance to Activation and storing ManagedInstanceID for tagging

	status_stop_service, Output_stop_service =commands.getstatusoutput("sudo stop amazon-ssm-agent")

	cmd="sudo amazon-ssm-agent -register -y -code %s -id %s -region %s"%(ActivationCode,ActivationID,REGION)

	status, output = commands.getstatusoutput(cmd)
	m = re.search('(mi-)\w{17}',output.splitlines()[-1])

	ManagedInstanceID=m.group(0)

	if status==0:

		status_start_service, Output_start_service =commands.getstatusoutput("sudo start amazon-ssm-agent")

	print ManagedInstanceID

	# Creating Tag for ManagedInstanceID tag
	create_tags = ec2.create_tags(Resources=[str(InstanceID)],Tags=[{'Key':'managedinstanceid','Value':ManagedInstanceID}])

# Checking if Instance already has ManagedInstanceID Tag

ec2=boto3.client('ec2',region_name=REGION)

ec2_attached_tags = ec2.describe_instances(Filters=[{'Name': 'tag-key','Values': ['managedinstanceid']}],InstanceIds=[instanceid])

if not ec2_attached_tags['Reservations']:
	Activation(instanceid)
else:
	print "Instance is already registered to an Activation/Account"

 

 

IAM policy for the EC2 instance profile:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "ec2:CreateTags",
                "ec2:DescribeInstances"
            ],
            "Effect": "Allow",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetParameter"
            ],
            "Resource": "*"
        }
    ]
}
 
       

 

Learn more about activation for different operating systems:

Note that there is a limit of 1,000 instances per activation and activation expires after a maximum of 30 days. After activation expiry, new instances can’t be registered to it, but registered instances can continue to be managed.

Step five
After they are registered, the EC2 Instances in other accounts will appear in the EC2 console, in the Central IT account, Managed Instances section. They are identified by the same managed ID that was returned during activation process. This returned Managed ID is attached as an EC2 tag in the earlier Python code. A Lambda function, called Automation-EC2-Tags-Collector, copies the EC2 tags in the agency account to the Central IT account by invoking a second Lambda function, called Automation-SSM-Tag-Manager. The following CloudFormation template will deploy this Lambda function in agency accounts:

The Automation-SSM-Tag-Manager Lambda function is deployed in the Central IT account so that it can accept the EC2 tags passed as an event by each agency’s Lambda function. Since each of the EC2 tags has the managed instance ID tag as well, it can used to map all the relevant EC2 tags propagated from agency accounts to the managed instances in in the central account. A maximum of 10 tags can be attached to a managed instance. Tags are critical to Systems Manager operation because they group resources together for applying and deploying Systems Manager functionalities such as Run Command, State Manager, Patch Manager, and Maintenance Windows.

Use the following CloudFormation template to deploy Automation-SSM-Tag-Manager Central IT account:

The Automation-EC2-Tags-Collector Lambda function should have permissions to invoke Automation-SSM-Tag-Manager. We’ll ensure this by deploying the following CloudFormation template. For parameters for adding permissions, you need to provide the agency account ID and the AWS Region into which the Automation-EC2-Tags-Collector is deployed.

Step six
After these CloudFormation templates are successfully deployed, you need to validate the instances appearing as managed instances in the central IT account along with the EC2 tags. Execute following AWS CLI command for the central IT account:

aws ssm list-tags-for-resource --resource-type “ManagedInstance” --resource-id "<managedinstanceID>" --region <Activation_region>

You can now use the propagated tags to execute Systems Manager documents or create Maintenance Windows. As an example you can execute the following Run Command on EC2 tag of “OS=Linux” as under:

aws ssm send-command --document-name "AWS-RunShellScript" –parameters commands=["ifconfig"] --targets Key=tag:OS,Values=Linux --region <your_SSM_region>

Conclusion

In this blog post I presented a Central IT solution for cross-account and cross-platform EC2 management using AWS Systems Manager and AWS Lambda. We created an Activation in the central IT account for registering agencies’ EC2 instances, we then deployed Lambda functions to import EC2 tags into the Central IT account for using them in implementing various EC2 SSM features. Using Systems Manager in Central IT provides you a variety of out-of-the-box features such as Patch Management, Maintenance Windows, Automation, and State Manager. These features can be used to enforce compliance and governance. Deploying this solution not only allows you to manage instances centrally but also to keep managing various OS platforms independently using the exported EC2 tags.

 

About the Author

Sohaib Tahir is a Solutions Architect for State and Local Government Public Sector Team. Sohaib has a focus in Networking and Automation, and loves to help customers in building architectures with automation services like AWS Systems Manager, AWS Lambda and Cloud-formation and Networking services including Amazon VPC and Direct Connect.