Amazon Web Services Simple Systems Manager (SSM) is a service that enables you to remotely manage the configuration of your Amazon EC2 instances. It allows you to run commands (called “documents”) on your instances from either the AWS console or the SSM API. You can get additional details by looking at the Simple Systems Manager documentation and the related section in the EC2 documentation.

Particularly useful is the pre-defined “shell script” document that AWS provides. This allows you to run an arbitrary shell script on one or many instances, optionally sending the output to an S3 bucket. However, for a variety of reasons you may not want to use this document directly. Instead, you can create a custom document of your own that offers reusability, flexibility, and tighter permissions control.

Defining a new SSM document

We’ll start by creating a file that contains the contents of our SSM document, which is defined in JSON. Call it whatever you like, but I’ll assume it’s called “apt-get-upgrade.json”.

The document we’ll create will allow you to run “apt-get update” followed by either “apt-get upgrade” or “apt-get dist-upgrade” in order to update all the packages on your instance(s) that are managed by the apt package manager.

The contents should look like this . . .

  "schemaVersion": "1.2",
  "description": "Upgrade packages managed by apt",
  "parameters": {
      "default": "",
      "description":"The type of upgrade to perform. Use \"dist-upgrade\" to perform a \"dist-upgrade\". Otherwise, an \"upgrade\" will be performed."
  "runtimeConfig": {
    "aws:runShellScript": {
      "properties": [
          "id": "",
          "runCommand": [
            "set -e",
            "apt-get update",
            "if [ '{{ upgradeType }}' == 'dist-upgrade' ]; then",
            "  apt-get -y dist-upgrade",
            "  apt-get -y upgrade",

In this document, the parameters section defines a single parameter called “upgradeType” that can be used in your script as “{{ upgradeType }}”. We’re using it here to decide whether to run “apt-get dist-upgrade” or “apt-get upgrade”. The script itself is defined as an array of lines in the “runCommand” section.

Sending the SSM document to AWS

Now that we have a document, we need to send it to AWS. I’m going to skip over the part about IAM permissions, but you’ll need to have the appropriate CreateDocument permissions in order to proceed. See the SSM Documentation for details.

Currently, you can only create a custom SSM document via the SSM API. We’ll use the AWS CLI to do that here. It’s just one command:

aws ssm create-document --content file://apt-get-upgrade.json --name "apt-get-upgrade"

That’s it! You should now be able to execute this script on any EC2 instance that is properly set up with the SSM agent.

Cleaning up

If you need to delete the SSM document that was just created, that also has to be done via the API. Here’s how . . .

aws ssm delete-document --name "apt-get-upgrade"