Advanced Walkthrough: Create an Automation Document

This walkthrough shows you how to create and execute a custom Automation document. After you run Automation, the system performs the following tasks.

Launches a Windows instance from a specified AMI.
Executes a command using Run Command that applies Windows updates to the instance.
Stops the instance.
Creates a new Windows AMI.
Terminates the original instance.

Automation Sample Document

Automation executes Systems Manager automation documents written in JSON. Automation documents include the actions to be performed during workflow execution. For more information about Systems Manager documents, see Systems Manager Documents. For information about actions you can add to a document, see Actions Reference for Automation Documents

The following list shows the supported actions:

aws:runInstance: Launches one or more instances for a given AMI ID.
aws:runCommand: Remote command execution. Executes an SSM Run Command document.
aws:invokeLambdaFunction: Enables you to run external worker functions in your automation workflow.
aws:changeInstanceState: Changes an instance state to stopped, terminated or running.
aws:createImage: Creates an AMI from a running instance.
aws:deleteImage: Deletes an AMI.

You can view these actions in the sample Automation document in the following procedure.

To create a patched AMI using Automation

Collect the following information. You will specify this information later in this procedure.
- The source ID of the AMI to update. For information about how to locate the source ID, see Finding a Linux AMI Using the Amazon EC2 Console.
- An AWS Identity and Access Management (IAM) instance role that gives Systems Manager permission to perform actions on your instances. For more information, see Configuring Access to Automation.
- An IAM role for Automation that Systems Manager uses to perform actions on your behalf. This is called the [Definition: assume role]. For more information, see Configuring Access to Automation.

Copy the following example document into a text editor such as Notepad. Change the value of assumeRole to the role ARN you created earlier when you created an IAM role for Automation and change the value of IamInstanceProfileName to the name of the role you created earlier. Save the document on a local drive as patchWindowsAmi.json.

{
   "description":"Systems Manager Automation Demo - Patch and Create a New AMI",
   "schemaVersion":"0.3",
   "assumeRole":"the role ARN you created",
   "parameters":{
      "sourceAMIid":{
         "type":"String",
         "description":"AMI to patch"
      },
      "targetAMIname":{
         "type":"String",
         "description":"Name of new AMI",
         "default":"patchedAMI-{{global:DATE_TIME}}"
      }
   },
   "mainSteps":[
      {
         "name":"startInstances",
         "action":"aws:runInstances",
         "timeoutSeconds":1200,
         "maxAttempts":1,
         "onFailure":"Abort",
         "inputs":{
            "ImageId":"{{ sourceAMIid }}",
            "InstanceType":"m3.large",
            "MinInstanceCount":1,
            "MaxInstanceCount":1,
            "IamInstanceProfileName":"the name of the IAM role you created"
         }
      },
      {
         "name":"installMissingWindowsUpdates",
         "action":"aws:runCommand",
         "maxAttempts":1,
         "onFailure":"Continue",
         "inputs":{
            "DocumentName":"AWS-InstallMissingWindowsUpdates",
            "InstanceIds":[
               "{{ startInstances.InstanceIds }}"
            ],
            "Parameters":{
               "UpdateLevel":"Important"
            }
         }
      },
      {
         "name":"stopInstance",
         "action":"aws:changeInstanceState",
         "maxAttempts":1,
         "onFailure":"Continue",
         "inputs":{
            "InstanceIds":[
               "{{ startInstances.InstanceIds }}"
            ],
            "DesiredState":"stopped"
         }
      },
      {
         "name":"createImage",
         "action":"aws:createImage",
         "maxAttempts":1,
         "onFailure":"Continue",
         "inputs":{
            "InstanceId":"{{ startInstances.InstanceIds }}",
            "ImageName":"{{ targetAMIname }}",
            "NoReboot":true,
            "ImageDescription":"AMI created by EC2 Automation"
         }
      },
      {
         "name":"terminateInstance",
         "action":"aws:changeInstanceState",
         "maxAttempts":1,
         "onFailure":"Continue",
         "inputs":{
            "InstanceIds":[
               "{{ startInstances.InstanceIds }}"
            ],
            "DesiredState":"terminated"
         }
      }
   ],
   "outputs":[
      "createImage.ImageId"
   ]
}

Download the AWS CLI to your local machine.

Edit the following command, and specify the path to the patchWindowsAmi.json file on your local machine. Execute the command to create the required Automation document.

aws ssm create-document --name "patchWindowsAmi" --content file:///Users/test-user/Documents/patchWindowsAmi.json --document-type Automation

The system returns information about the command progress.

{
    "DocumentDescription": {
        "Status": "Creating", 
        "Hash": "fdeacee0a97ea710f6efc1dc43a9025ce3a34c5743a11e30a4ac6f42127f3a8e", 
        "Name": "patchWindowsAmi", 
        "DocumentType": "Ec2Automation", 
        "PlatformTypes": [], 
        "DocumentVersion": "1", 
        "HashType": "Sha256", 
        "CreatedDate": 1475776111.117, 
        "Owner": "860547654709"
    }
}

Execute the following command to view a list of documents that you can access.

aws ssm list-documents --document-filter-list key=Owner,value=Self

The system returns information like the following:

{
   "DocumentIdentifiers":[
      {
         "Name":" patchWindowsAmi",
         "PlatformTypes": [

         ],
         "DocumentVersion": "5",
         "DocumentType": "Automation",
         "Owner": "12345678901",
         "SchemaVersion": "0.3"
      }
   ]
}

Execute the following command to view details about the patchWindowsAmi document.

aws ssm describe-document --name patchWindowsAmi

The system returns information like the following:

{
   "Document": {
      "Status": "Active",
      "Hash": "99d5b2e33571a6bb52c629283bca0a164026cd201876adf0a76de16766fb98ac",
      "Name": "patchWindowsAmi",
      "Parameters": [
         {
            "DefaultValue": "ami-3f0c4628",
            "Type": "String",
            "Name": "sourceAMIid",
            "Description": "AMI to patch"
         },
         {
            "DefaultValue": "patchedAMI-{{global:DATE_TIME}}",
            "Type": "String",
            "Name": "targetAMIname",
            "Description": "Name of new AMI"
         }
      ],
      "DocumentType": "Automation",
      "PlatformTypes": [

      ],
      "DocumentVersion": "5",
      "HashType": "Sha256",
      "CreatedDate": 1478904417.477,
      "Owner": "12345678901",
      "SchemaVersion": "0.3",
      "DefaultVersion": "5",
      "LatestVersion": "5",
      "Description": "Automation Demo - Patch and Create a New AMI"
   }
}

Execute the following command to run the patchWindowsAmi document and run the Automation workflow. This command takes two input parameters: the ID of the AMI to be patched, and the name of the new AMI. The example command below uses a recent EC2 AMI to minimize the number of patches that need to be applied. If you run this command more than once, you must specify a unique value for targetAMIname. AMI names must be unique.
```
aws ssm start-automation-execution --document-name="patchWindowsAmi" --parameters sourceAMIid="ami-bd3ba0aa"
```
The command returns an execution ID. Copy this ID to the clipboard. You will use this ID to view the status of the workflow.
```
{
    "AutomationExecutionId": "ID"
}
```
You can monitor the status of the workflow in the EC2 console. Check the console to verify that a new instance is launching. After the instance launch is complete, you can confirm that the Run Command action was executed. After Run Command execution is complete, you should see a new AMI in your list of AMI images.
To view the workflow execution using the CLI, execute the following command:
```
aws ssm describe-automation-executions
```
To view details about the execution progress, execute the following command.
```
aws ssm get-automation-execution --automation-execution-id ID
```

Note

Depending on the number of patches applied, the Windows patching process executed in this sample workflow can take 30 minutes or more to complete.

Document Conventions

« Previous Next »