AWS Cloud Operations Blog

Automate installing AWS Systems Manager agent on unmanaged Amazon EC2 nodes

Managing a fleet of AWS resources at scale can be challenging. Organizations rely on multiple solutions to automate tasks, collect inventory, patch instances, and maintain security compliance. Organizations need to access instances without opening inbound ports or managing SSH keys. AWS Systems Manager (SSM) simplifies this by serving as a centralized management solution that supports all these needs at scale. AWS Systems Manager is designed to simplify this complexity by serving as a centralized management solution that supports all these needs at scale.

To use Systems Manager’s capabilities, three main requirements must be met:

  1. Systems Manager agent (SSM agent) installed on the instance.
  2. Configure instance permissions required for Systems Manager.
  3. Network connectivity to AWS Systems Manager endpoints.

Systems Manager’s unified console allows you to configure and grant instance permissions across all nodes in your organization. The diagnose and remediate feature helps identify unmanaged AWS nodes and resolve network-related issues. These issues include security group misconfigurations or disabled Amazon Virtual Private Cloud (Amazon VPC) DNS.
While many AWS-provided Amazon Machine Images (AMIs) include the Systems Manager agent pre-installed, you might need to install the agent on a custom or older AMI. For organizations managing large fleets of nodes, manually installing the SSM agent across multiple servers and accounts can create operational overhead.

This post demonstrates an automated solution for the installation of the SSM agent on existing Amazon EC2 instances. The solution is designed to streamline SSM agent installation across your fleet of nodes that are spread across multiple accounts and Regions. This enables quick adoption of Systems Manager’s management capabilities across your AWS Organization.

Prerequisites

Your nodes must have the following prerequisites:

  1. Supported Operating System:
    • Windows Server 2016-2025.
    • Amazon Linux 2/2023.
    • RHEL/CentOS 7.x-10. x.
    • Ubuntu 18.04-24.04.
    • SUSE Linux Enterprise 15.x.
  2. EC2Launch v2 agent for Windows nodes.
  3. Cloud-init for Linux nodes.
  4. Network connectivity to Amazon S3 (s3.amazonaws.com) is required for downloading SSM agent installation files and uploading execution logs after the installation. You can establish a connectivity through an Internet Gateway, NAT Gateway, or S3 Gateway endpoint for private subnets.
  5. For Linux-based nodes, the automation requires unzip, curl, and awscli packages to download the SSM agent software and upload logs. If these packages aren’t present, the automation will attempt to install them from the system’s package repositories, which requires internet access during the installation process.
  6. If you’re onboarded to unified console, use the Delegated Administrator for Systems Manager used for onboarding.

Important considerations

This solution installs SSM agent using user data and requires stopping and starting your nodes during the process. Be aware that this will clear any ephemeral storage and change non-Elastic IP addresses.

Any applications running on these nodes are interrupted. We recommend running this remediation during a scheduled maintenance period to avoid unexpected interruptions.

During execution, the automation temporarily attaches an instance profile to enable log uploads to S3 from the instance. When completed, this temporary profile is removed, and the instance is restored to its original state.

Overview of solution

This solution provides automated deployment using AWS CloudFormation to provision all necessary resources. These resources include S3 buckets, Systems Manager Automation runbooks, IAM roles, permission policies, and instance profiles. After deployment, you can run the Systems Manager Automation runbook on-demand to install the SSM agent. The installation can target your entire EC2 fleet or specific nodes using tags.

Architecture diagram showing automated SSM Agent installation workflow across an AWS Organization. The flow starts with CloudFormation deployment creating automation runbooks, which then orchestrate SSM Agent installation across multiple accounts and regions through three runbooks: Orchestrator, Primary, and Secondary.

Figure 1 – Architecture diagram for deployment workflow for SSM agent installation

The automation workflow consists of three interconnected Systems Manager Automation runbooks working in harmony. The process begins when you run the SSMAgentInstall-Orchestrator runbook, which acts as the central coordinator. This orchestrator first validates all input parameters and then invokes the SSMAgentInstall-Primary runbook in each target account specified.

The Primary runbook runs against the nodes specified in the input (either through tags or using diagnose and remediate output) in the targeted Regions. For each target node, it invokes the SSMAgentInstall-Secondary runbook, which first verifies if the node is already SSM-managed.

If the nodes is unmanaged, the secondary runbook proceeds with the installation process through a carefully sequenced procedure: it validates nodes eligibility (checking for ASG membership, root volume type, and node state), then runs a stop-and-start cycle where it injects the SSM agent installation scripts via user data, temporarily attaches necessary IAM permissions, and verifies successful agent installation.

Throughout this process, execution logs are collected and stored in a central S3 bucket. Finally, the Orchestrator aggregates all results into a comprehensive CSV report, providing visibility into the success or failure of each installation attempt across your organization.

Permissions:

After installation, the SSM agent registers the nodes with AWS Systems Manager. For this, ensure nodes have network connectivity to Systems Manager endpoints and required IAM Permissions. Note: If you’re using unified console, the required permissions are automatically configured.

Walkthrough

To deploy the solution, use the Delegated Administrator for CloudFormation StackSets.

Step 1: Deploy the resources using the CloudFormation template.

  1. Download the CloudFormation template.
  2. Login to your appropriate AWS account. If enabled, switch to the home region of Unified console.
  3. On the Stacks page, choose Create stack at top right, and then choose With new resources (standard).
  4. For Prerequisite – Prepare template, choose Choose an existing template.
  5. For Template source, choose Upload a template file and select Choose file and choose the template you downloaded in step 1.
  6. Choose Next.
  7. Provide a stack name, for example, SSMAgentMultiAccountInstallation.

Stack Parameters:

  1. In the Parameters section, specify the values for the parameters:
  2. For DeploymentTargetsOUs, specify the Organizational Unit IDs (OU IDs) where target instances are in your organizations. CloudFormation attempts to create resources to these accounts and regions using Stacksets.
  3. For OrganizationId, enter the Organization ID of your Organizations.
  4. For TargetRegions, enter the regions where the where target instances are located in your organizations.
  5. On the Configure Stack Options page, apply tags if needed, otherwise choose Next.
  6. On the Review and create page, Select I acknowledge that AWS CloudFormation might create IAM resources with custom names, then choose Submit.
CloudFormation stack parameters configuration in the console console showing three input fields:  1. DeploymentTargetsOUs: For specifying Organizational Unit IDs where target instances are located. 2. OrganizationId: For entering the Organization ID. 3. TargetRegions: For entering the regions where target instances are located.

Figure 2 – AWS CloudFormation Console – Stacks page

Step 2: Run the Automation runbook.

  1. After the CloudFormation template deployment completes, open the Systems Manager console in the same Region.
  2. In the navigation pane, choose Automation, and then choose Execute automation.
  3. On the Owned by me tab, choose SSMAgentInstall-Orchestrator and choose Next.
  4. In the Input parameters section, specify the required inputs:
    • For AutomationAssumeRole, choose SSMAgentInstall-MAMR-AutomationAdministrationRole
    • For UploadLogsToS3Bucket, choose the log S3 bucket ssm-agent-install-automation-logs-<account-id>
  5. To target the instances via Tags, specify the required inputs:
    • TargetAccounts – Enter Account IDs or OUs where unmanaged instances are running.
    • TargetRegions – Enter Regions containing the unmanaged instances.
    • TargetTagKey – Enter target’s tag key as tag:<tagname> (Use InstanceIds to target all instances).
    • TargetTagValue – Enter the target’s tag value (Use * with InstanceIds to target all instances).
  6. Alternatively, Use Diagnose and Remediate output If you previously ran a diagnosis using Systems Manager unified console. The automation will fetch the unmanaged Instances from the csv:
    • In the navigation pane, choose Diagnose and remediate.
    • Choose View executions.
    • Choose the execution and expand the Output section.
    • Copy the S3 path from AggregateOutput.ExportObjectUri.
  7. Choose Execute.
  8. When complete, the automation creates an aggregated report CSV file in the S3 bucket and displays the file path in the output summary.
The image shows an example of the final output at the end of the Automation execution.

Figure 3 – AWS Systems Manager – Automation Output

The report csv file provides per instance details along with execution logs:

The image shows an example of the report csv file generated by Orchestrator Automation runbook.

Figure 4 – Instance details report csv file

The solution deploys SSM agent across multiple AWS accounts using CloudFormation StackSets, followed by running an Automation runbook in Systems Manager. Upon completion, the automation generates a comprehensive CSV report in S3 containing instance-level details and execution logs, providing visibility into the deployment status across your organization. Please note, if the SSM agent is not installed after using the automation described above, you can use one of the strategies mentioned or resort to manual installation.

Cleanup

When you have completed running and you no longer need the solution in place, remember to remove the provisioned AWS resources. This helps avoid ongoing costs. To clean up:

  1. Navigate to the AWS CloudFormation Console.
  2. Select the stack you created for this solution.
  3. Choose Delete and confirm when prompted.

The deletion process attempts to remove all resources created by both the CloudFormation template and the automation document, including S3 buckets, log files, associated IAM roles and policies, and any other dependent resources.

Conclusion

The automated Systems Manager agent installation solution aims to transform a complex, manual process into a more streamlined operation. By helping to reduce the barrier of manual agent installation, this solution is designed to help organizations leverage Systems Manager’s potential. Organizations can achieve operational efficiency, security compliance, and automated management of their AWS infrastructure.
Now that you have the SSM agent installed on your EC2 instances, Explore AWS Systems Manager: Dive into features like Patch Manager, Session Manager, Parameter Store, and Automation. Each of these tools can significantly enhance your AWS operations.
Don’t stop here. Check out  AWS Systems Manager feature. From automated patch management to secure remote access, and from parameter store to maintenance windows. This can streamline your AWS infrastructure management and enhance your operational efficiency.
Ali Alzand

Ali Alzand

Ali is a Microsoft Specialist Solutions Architect at Amazon Web Services who helps global customers unlock the power of the cloud by migrating, modernizing, and optimizing their Microsoft workloads. He specializes in cloud operations - leveraging AWS services like Systems Manager, Amazon EC2 Windows, and EC2 Image Builder to drive cloud transformation. Outside of work, Ali enjoys exploring the outdoors, firing up the grill on weekends for barbecue with friends, and sampling all the eclectic food has to offer.

Justin Thomas

Justin Thomas

Justin Thomas is a Sr. Cloud Support Engineer with AWS Premium Support. He specializes in AWS Systems Manager, Linux, and Shell Scripting and has a keen interest in providing technical guidance to help customers migrate, optimize, and navigate their cloud infrastructure. Outside of work, Justin enjoys spending time with friends & family, trying out new foods, and watching movies.