Running a simple automation - AWS Systems Manager

Running a simple automation

The following procedures describe how to run a simple Systems Manager automation using the AWS Systems Manager console and AWS Command Line Interface (AWS CLI). The automation runs in the context of the current AWS Identity and Access Management (IAM) user. This means that you don't need to configure additional IAM permissions as long as you have permission to run the runbook, and any actions called by the runbook. If you have administrator permissions in IAM, then you already have permission to run this automation.

Note

For information about how to run an automation that uses an IAM service role or more advanced forms of delegated administration, see Running automations by using different security models.

Running a simple automation (console)

The following procedure describes how to use the Systems Manager console to run a simple automation.

To run a simple automation

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Automation, and then choose Execute automation.

  3. In the Automation document list, choose a runbook. Choose one or more options in the Document categories pane to filter SSM documents according to their purpose. To view a runbook that you own, choose the Owned by me tab. To view a runbook that is shared with your account, choose the Shared with me tab. To view all runbooks, choose the All documents tab.

    Note

    You can view information about a runbook by choosing the runbook name.

  4. In the Document details section, verify that Document version is set to the version that you want to run. The system includes the following version options:

    • Default version at runtime: Choose this option if the Automation runbook is updated periodically and a new default version is assigned.

    • Latest version at runtime: Choose this option if the Automation runbook is updated periodically, and you want to run the version that was most recently updated.

    • 1 (Default): Choose this option to run the first version of the document, which is the default.

  5. Choose Next.

  6. In the Execution Mode section, choose Simple execution.

  7. In the Input parameters section, specify the required inputs. Optionally, you can choose an IAM service role from the AutomationAssumeRole list.

  8. Choose Execute.

The console displays the status of the automation. If the Automation fails to run, see Troubleshooting Systems Manager Automation.

Running a simple automation (command line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for PowerShell to run a simple automation.

To run a simple automation

  1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you have not already.

    For information, see Install or upgrade AWS command line tools.

  2. Run the following command to start a simple automation.

    Linux & macOS
    aws ssm start-automation-execution \ --document-name DocumentName \ --parameters ParametersRequiredByDocument
    Windows
    aws ssm start-automation-execution ^ --document-name DocumentName ^ --parameters ParametersRequiredByDocument
    PowerShell
    Start-SSMAutomationExecution ` -DocumentName DocumentName ` -Parameter ParametersRequiredByDocument

    Here is an example using the runbook AWS-RestartEC2Instance to restart the specified EC2 instance.

    Linux & macOS
    aws ssm start-automation-execution \ --document-name "AWS-RestartEC2Instance" \ --parameters "InstanceId=i-1234567890abcdef0"
    Windows
    aws ssm start-automation-execution ^ --document-name "AWS-RestartEC2Instance" ^ --parameters "InstanceId=i-1234567890abcdef0"
    PowerShell
    Start-SSMAutomationExecution ` -DocumentName AWS-RestartEC2Instance ` -Parameter @{"InstanceId"="i-1234567890abcdef0"}

    The system returns information like the following.

    Linux & macOS
    {
        "AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
    }
    Windows
    {
        "AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab"
    }
    PowerShell
    4105a4fc-f944-11e6-9d32-0123456789ab
  3. Run the following command to retrieve the status of the automation.

    Linux & macOS
    aws ssm describe-automation-executions \ --filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"
    Windows
    aws ssm describe-automation-executions ^ --filter "Key=ExecutionId,Values=4105a4fc-f944-11e6-9d32-0123456789ab"
    PowerShell
    Get-SSMAutomationExecutionList | ` Where {$_.AutomationExecutionId -eq "4105a4fc-f944-11e6-9d32-0123456789ab"}

    The system returns information like the following.

    Linux & macOS
    {
        "AutomationExecutionMetadataList": [
            {
                "AutomationExecutionStatus": "InProgress",
                "CurrentStepName": "stopInstances",
                "Outputs": {},
                "DocumentName": "AWS-RestartEC2Instance",
                "AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
                "DocumentVersion": "1",
                "ResolvedTargets": {
                    "ParameterValues": [],
                    "Truncated": false
                },
                "AutomationType": "Local",
                "Mode": "Auto",
                "ExecutionStartTime": 1564600648.159,
                "CurrentAction": "aws:changeInstanceState",
                "ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
                "LogFile": "",
                "Targets": []
            }
        ]
    }
    Windows
    {
        "AutomationExecutionMetadataList": [
            {
                "AutomationExecutionStatus": "InProgress",
                "CurrentStepName": "stopInstances",
                "Outputs": {},
                "DocumentName": "AWS-RestartEC2Instance",
                "AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0123456789ab",
                "DocumentVersion": "1",
                "ResolvedTargets": {
                    "ParameterValues": [],
                    "Truncated": false
                },
                "AutomationType": "Local",
                "Mode": "Auto",
                "ExecutionStartTime": 1564600648.159,
                "CurrentAction": "aws:changeInstanceState",
                "ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
                "LogFile": "",
                "Targets": []
            }
        ]
    }
    PowerShell
    AutomationExecutionId       : 4105a4fc-f944-11e6-9d32-0123456789ab
    AutomationExecutionStatus   : InProgress
    AutomationType              : Local
    CurrentAction               : aws:changeInstanceState
    CurrentStepName             : startInstances
    DocumentName                : AWS-RestartEC2Instance
    DocumentVersion             : 1
    ExecutedBy                  : arn:aws:sts::123456789012:assumed-role/Administrator/Admin
    ExecutionEndTime            : 1/1/0001 12:00:00 AM
    ExecutionStartTime          : 7/31/2019 7:17:28 PM
    FailureMessage              : 
    LogFile                     : 
    MaxConcurrency              : 
    MaxErrors                   : 
    Mode                        : Auto
    Outputs                     : {}
    ParentAutomationExecutionId : 
    ResolvedTargets             : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
    Target                      : 
    TargetMaps                  : {}
    TargetParameterName         : 
    Targets                     : {}