Amazon Web Services (AWS) Simple Systems Manager (SSM) is a service that allows you to manage servers either on AWS or on-premises. One of the features of SSM is the Run Command, which allows you to execute commands across a set of servers. SSM Documents are essentially scripts or automation that SSM uses as part of its Run Command feature, and for other features like State Manager and Automation.

SSM Documents

An SSM Document defines the actions that Systems Manager performs on your managed instances. These documents are JSON or YAML-formatted and specify tasks or sets of tasks that are handled by the instance(s). There are different types of SSM Documents:

1. Command Documents: Used to run commands, either inline scripts or calls to other command-line interfaces.

2. Policy Documents: Used to configure instance policies, such as roles and permissions.

3. Automation Documents: Define actions for the Systems Manager Automation service to perform.

4. Package Documents: Define actions to install packages.

5. Application Configuration Schema: These are templates that define configuration specifications for applications.

AWS provides pre-defined, commonly used documents, but you can also create custom documents for specialized tasks.

SSM Run Command

Run Command is a capability of AWS Systems Manager that you can use to manage the configuration of your servers. You can use Run Command to:

• Execute shell commands/scripts

• Install or uninstall applications

• Update software

• Join an instance to a Windows domain

• And more…

The Run Command function uses SSM Documents to define the actions it should take. You can select a target set of instances based on various criteria, like tags, or specify individual instance IDs. Once a command is executed, you can also track its status and retrieve the output, either in the AWS Management Console, CLI, or through the API.

How it Works Together

1. Step 1: You choose an SSM Document that represents the command or script you want to run.

2. Step 2: You specify the target set of instances on which to run the command.

3. Step 3: Run Command executes the command on the target instances, taking care of distributing the command, ensuring it's executed, and gathering the results.

Run Command keeps track of the status of the commands and can provide a detailed log of what happened on each instance. This makes it easier to manage a large fleet of instances for both Windows and Linux environments. It provides a more secure and auditable way to manage remote execution compared to traditional methods like SSH or RDP.

AWS SSM and Run Command help in reducing the operational overhead and also improves security by allowing administrators to perform tasks without requiring direct access to the instances.

Workshop: Use the SSM Run command to install the Apache server on EC2 Instances

To use AWS Systems Manager Run Command to install Apache and display a "Hello World" message with the hostname on three Amazon Linux 2 instances in the us-east-1 region, you can follow these steps:

Prerequisites

1. Make sure you have AWS CLI installed and configured with necessary permissions.

2. Make sure you have launched three Amazon Linux 2 EC2 instances in us-east-1 and they have the AWS Systems Manager Agent (SSM Agent) installed (which is by default on Amazon Linux 2). Make sure that the Security Group is configured to allow traffic on port 80 from 0.0.0.0/0 anywhere.

   💡

   To launch instances use the following guide: How to launch a single EC2 instance via AWS CLI

3. The EC2 instances must have an IAM role attached that allows them to interact with the Systems Manager service. Use AWS-managed AmazonEC2RoleforSSM.

Steps

1. Open AWS Systems Manager in the AWS Console

Navigate to AWS Systems Manager from the AWS Management Console.

2. Go to 'Run Command'

Click on the "Run Command" on the left-hand side under "Node Management" section.

3. Create and Execute Command

1. Click on the "Run command" button.

   

2. In the search box, type AWS-RunShellScript to use the pre-defined document to run shell commands.

   

3. In the "Targets" section, select the instances either manually by instance IDs or by specifying tags. Make sure to select the three Amazon Linux 2 instances launched in us-east-1.

   

4. In the "Commands" box, paste the following shell script:

#!/bin/bash
# Install Apache
yum update -y
yum install -y httpd

# Start Apache
systemctl start httpd
systemctl enable httpd

# Create an index.html file
echo "Hello World, my hostname is $(hostname)" > /var/www/html/index.html

1. Disable S3 bucket output

   

2. Leave the other settings as default.

3. Click "Run".

AWS will run these commands on the selected instances. It will install Apache, start the service, and create an index.html file with the text "Hello World, my hostname is <machine_hostname>", where <machine_hostname> will be replaced with the actual hostname of the machine.

4. Monitor Command Execution

After you execute the command, you'll be taken to a page where you can monitor the status of the command execution on each instance. It will show "Success" when the command successfully runs on an instance.

5. Verify Apache Installation

To verify that Apache was installed correctly and is serving your custom "Hello World" page, navigate to each EC2 instance's public IP or domain name in your web browser.

You should see a message like "Hello World, my hostname is <machine_hostname>", where <machine_hostname> is the actual hostname of the machine.

And that's it! You've used AWS Systems Manager Run Command to install Apache on multiple instances and serve a custom HTML page.

References

1. AWS Systems Manager Documents

2. Creating SSM document content

3. AWS Systems Manager Run Command