AWS Systems Manager
User Guide

Running Automation Workflows in Multiple AWS Regions and Accounts

You can run AWS Systems Manager Automations across multiple AWS Regions and AWS accounts or AWS Organizational Units (OUs) from an Automation management account. Running Automations in multiple Regions and accounts or OUs reduces the time required to administer your AWS resources while enhancing the security of your computing environment.

For example, you can centrally implement patching and security updates, remediate compliance drift on VPC configurations or Amazon S3 bucket policies, and manage resources, such as Amazon EC2 instances, at scale. The following graphic shows an example of a user who is running the AWS-RestartEC2Instances document in multiple Regions and accounts from an Automation management account. The Automation locates the instances by using the specified tags in the specified Regions and accounts.

Note

When you run an Automation across multiple Regions and accounts, you target resources by using tags or the name of an AWS resource group. The Automation fails to run on those resources that don't have the specified tag or that aren't included in the specified resource group.


                    Illustration showing Systems Manager Automation running in multiple
                        Regions and multiple accounts.

Important

Your account is charged for running Automations in multiple Regions and accounts. Multi-Region and account step executions are considered special steps. There is no step limit for special steps, but your account is charged for each step processed by Systems Manager. For more information, see the AWS Systems Manager Pricing page.

How It Works

Running Automations across multiple Regions and accounts or OUs works as follows:

  1. Verify that all resources on which you want to run the Automation, in all Regions and accounts or OUs, use identical tags. If they don't, you can add them to an AWS resource group and target that group. For more information, see What Is AWS Resource Groups?

  2. Sign in to the AWS Identity and Access Management (IAM) account that you want to configure as the Automation Master account.

  3. Use the procedure in this topic to create an IAM execution role called AWS-SystemsManager-AutomationExecutionRole. This role gives the user permission to run Automation workflows.

  4. Use the procedure in this topic to create a second IAM role called AWS-SystemsManager-AutomationAdministrationRole. This role gives the user permission to run Automation workflows in multiple AWS accounts and OUs.

  5. Choose the Automation document, Regions, and accounts or OUs where you want to run the Automation workflow.

  6. Run the Automation.

  7. Use the GetAutomationExecution, DescribeAutomationStepExecutions, and DescribeAutomationExecutions API actions from the AWS Systems Manager console or the AWS CLI to monitor workflow progress.

Setting Up Management Account Permissions for Multi-Region and Multi-Account Automation Execution

Use the following procedure to create the required IAM roles for Systems Manager Automation multi-Region and multi-account execution by using AWS CloudFormation. This procedure describes how to create the AWS-SystemsManager-AutomationExecutionRole role. You must create this role in every account that you want to target to run multi-Region and multi-account Automations.

This procedure also describes how to create the AWS-SystemsManager-AutomationAdministrationRole role. You only need to create this role in the Automation management account.

To create the required IAM roles for Multi-Region and Multi-Account Automation Executions by using AWS CloudFormation

  1. Download the AWS-SystemsManager-AutomationExecutionRole.zip folder. This folder includes the AWS-SystemsManager-AutomationExecutionRole.json AWS CloudFormation template file.

  2. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  3. Choose Create Stack.

  4. In the Choose a template section, choose Upload a template to Amazon S3.

  5. Choose Browse, and then choose the AWS-SystemsManager-AutomationExecutionRole.json AWS CloudFormation template file.

  6. Choose Next.

  7. On the Specify Details page, in the Stack Name field, enter a name.

  8. In the Parameters section, in the MasterAccountID field, enter the ID for the account that you want to use to run multi-Region and multi-account Automations.

  9. Choose Next.

  10. On the Options page, enter values for any options you want to use. Choose Next.

  11. On the Review page, scroll down and choose the I acknowledge that AWS CloudFormation might create IAM resources option.

  12. Choose Create.

    AWS CloudFormation shows the CREATE_IN_PROGRESS status for approximately three minutes. The status changes to CREATE_COMPLETE.

  13. Repeat this procedure in every account that you want to target to run multi-Region and multi-account Automations.

  14. Download the AWS-SystemManager-AutomationAdministrationRole.zip folder and repeat this procedure for the AWS-SystemManager-AutomationAdministrationRole role. You only need to create the AWS-SystemManager-AutomationAdministrationRole role in the Automation management account.

Run an Automation in Multiple Regions and Accounts (Console)

The following procedure describes how to use the Systems Manager console to run an Automation in multiple Regions and accounts from the Automation management account.

Before You Begin

Before you complete the following procedure, note the following information:

  • AWS account IDs or OUs where you want to run the Automation.

  • AWS Systems Manager Regions where you want to run the Automation.

  • The tag key and the tag value, or the name of the resource group, where you want to run the Automation.

To run an Automation workflow in multiple Regions and accounts

  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 document. Choose one or more options in the Document categories pane to filter SSM documents according to their purpose. To view a document that you own, choose the Owned by me tab. To view a document that is shared with your account, choose the Shared with me tab. To view all documents, choose the All documents tab.

    Note

    You can view information about a document by choosing the document 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 document is updated periodically and a new default version is assigned.

    • Latest version at runtime: Choose this option if the Automation document 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. On the Execute automation document page, choose Multi-account and Region.

  7. In the Target accounts and Regions section, use the Accounts and organizational (OUs) field to specify the different AWS accounts or AWS Organizational Units (OUs) where you want to run the Automation. Separate multiple accounts or OUs with a comma.

  8. Use the AWS Regions list to choose one or more Regions where you want to run the Automation.

  9. Use the Multi-Region and account rate control options to restrict the Automation execution to a limited number of accounts running in a limited number of Regions. These options don't restrict the number of AWS resources that can run the Automations.

    1. In the Location (account-Region pair) concurrency section, choose an option to restrict the number of Automation workflows that can run in multiple accounts and Regions at the same time. For example, if you choose to run an Automation in five (5) AWS accounts, which are located in four (4) AWS Regions, then Systems Manager runs Automations in a total of 20 account-Region pairs. You can use this option to specify an absolute number, such as 2, so that the Automation only runs in two account-Region pairs at the same time. Or you can specify a percentage of the account-Region pairs that can run at the same time. For example, with 20 account-Region pairs, if you specify 20%, then the Automation simultaneously runs in a maximum of five (5) account-Region pairs.

      • Choose targets to enter an absolute number of account-Region pairs that can run the Automation workflow simultaneously.

      • Choose percent to enter a percentage of the total number of account-Region pairs that can run the Automation workflow simultaneously.

    2. In the Error threshold section, choose an option:

      • Choose errors to enter an absolute number of errors allowed before Automation stops sending the workflow to other resources.

      • Choose percent to enter a percentage of errors allowed before Automation stops sending the workflow to other resources.

  10. In the Targets section, choose how you want to target the AWS Resources where you want to run the Automation. These options are required.

    1. Use the Parameter list to choose a parameter. The items in the Parameter list are determined by the parameters in the Automation document that you selected at the start of this procedure. By choosing a parameter you define the type of resource on which the Automation workflow runs.

    2. Use the Targets list to choose how you want to target resources. If you chose to target resources by using AWS Resource Groups, then choose the name of the group from the Resource Group list.

      If you chose to target resources by using tags, then enter the tag key and (optionally) the tag value in the fields provided. Choose Add.

      If you chose to target resources by using parameter values, then enter the parameter value for the parameter you chose in the Input parameters section.

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

    Note

    You may not need to choose some of the options in the Input parameters section. This is because you targeted resources in multiple Regions and accounts by using tags or a resource group. For example, if you chose the AWS-RestartEC2Instance document, then you don't need to specify or choose instance IDs in the Input parameters section. The Automation execution locates the instances to restart by using the tags you specified.

  12. Use the options in the Rate control section to restrict the number of AWS resources that can run the Automation within each account-Region pair.

    In the Concurrency section, choose an option:

    • Choose targets to enter an absolute number of targets that can run the Automation workflow simultaneously.

    • Choose percentage to enter a percentage of the target set that can run the Automation workflow simultaneously.

  13. In the Error threshold section, choose an option:

    • Choose errors to enter an absolute number of errors allowed before Automation stops sending the workflow to other resources.

    • Choose percentage to enter a percentage of errors allowed before Automation stops sending the workflow to other resources.

  14. Choose Execute.

Run an Automation in Multiple Regions and Accounts (Command Line)

The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for PowerShell to run an Automation in multiple Regions and accounts from the Automation management account.

Before You Begin

Before you complete the following procedure, note the following information:

  • AWS account IDs or OUs where you want to run the Automation.

  • AWS Systems Manager Regions where you want to run the Automation.

  • The tag key and the tag value, or the name of the resource group, where you want to run the Automation.

To run an Automation workflow in multiple Regions and accounts

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

    For information, see Install or Upgrade the AWS CLI or Install or Upgrade the AWS Tools for PowerShell.

  2. Use the following format to create a command to run an Automation workflow in multiple Regions and accounts.

    LinuxWindowsPowerShell
    Linux
    aws ssm start-automation-execution \ --document-name name_of_Automation_document \ --parameters AutomationAssumeRole=arn:aws:iam::Automation_management_account_ID:role/AWS-SystemsManager-AutomationAdministrationRole \ --target-parameter-name parameter_name (required) \ --targets Key=tag_key,Values=tag_value \ --target-locations Accounts=account_ID_1,account_ID_2,account_ID_3,Regions=Region_1,Region_2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    Windows
    aws ssm start-automation-execution ^ --document-name name_of_Automation_document ^ --parameters AutomationAssumeRole=arn:aws:iam::Automation_management_account_ID:role/AWS-SystemsManager-AutomationAdministrationRole ^ --target-parameter-name parameter_name (required) ^ --targets Key=tag_key,Values=tag_value ^ --target-locations Accounts=account_ID_1,account_ID_2,account_ID_3,Regions=Region_1,Region_2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target $Targets.Key = "target_key" $Targets.Values = "target_value" Start-SSMAutomationExecution ` -DocumentName "name_of_Automation_document" ` -Parameter @{ "AutomationAssumeRole"="arn:aws:iam::Automation_management_account_ID:role/AWS-SystemsManager-AutomationAdministrationRole" } ` -TargetParameterName "parameter_name (required)" ` -Target $Targets ` -TargetLocation @{ "Accounts"="account_ID_1","account_ID_2","account_ID_3"; "Regions"="Region_1","Region_2"; "ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

    Here are a few examples.

    Example 1: This example restarts Amazon EC2 instances in the 123456789012 and 987654321098 accounts, which are located in the us-east-2 and us-west-1 Regions. The instances must be tagged with the tag key-pair value Env-PROD.

    LinuxWindowsPowerShell
    Linux
    aws ssm start-automation-execution \ --document-name AWS-RestartEC2Instance \ --parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole \ --target-parameter-name InstanceId \ --targets Key=tag:Env,Values=PROD \ --target-locations Accounts=123456789012,987654321098,Regions=us-east-2,us-west-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    Windows
    aws ssm start-automation-execution ^ --document-name AWS-RestartEC2Instance ^ --parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole ^ --target-parameter-name InstanceId ^ --targets Key=tag:Env,Values=PROD ^ --target-locations Accounts=123456789012,987654321098,Regions=us-east-2,us-west-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target $Targets.Key = "tag:Env" $Targets.Values = "PROD" Start-SSMAutomationExecution ` -DocumentName "AWS-RestartEC2Instance" ` -Parameter @{ "AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole" } ` -TargetParameterName "InstanceId" ` -Target $Targets ` -TargetLocation @{ "Accounts"="123456789012","987654321098"; "Regions"="us-east-2","us-west-1"; "ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

    Example 2: This example restarts Amazon EC2 instances in the 123456789012 and 987654321098 accounts, which are located in the eu-central-1 Region. The instances must be members of the prod-instances AWS resource group.

    LinuxWindowsPowerShell
    Linux
    aws ssm start-automation-execution \ --document-name AWS-RestartEC2Instance \ --parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole \ --target-parameter-name InstanceId \ --targets Key=ResourceGroup,Values=prod-instances \ --target-locations Accounts=123456789012,987654321098,Regions=eu-central-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    Windows
    aws ssm start-automation-execution ^ --document-name AWS-RestartEC2Instance ^ --parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole ^ --target-parameter-name InstanceId ^ --targets Key=ResourceGroup,Values=prod-instances ^ --target-locations Accounts=123456789012,987654321098,Regions=eu-central-1,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target $Targets.Key = "ResourceGroup" $Targets.Values = "prod-instances" Start-SSMAutomationExecution ` -DocumentName "AWS-RestartEC2Instance" ` -Parameter @{ "AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole" } ` -TargetParameterName "InstanceId" ` -Target $Targets ` -TargetLocation @{ "Accounts"="123456789012","987654321098"; "Regions"="eu-central-1"; "ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

    Example 3: This example restarts Amazon EC2 instances in the ou-1a2b3c-4d5e6c AWS organizational unit (OU). The instances are located in the us-west-1 and us-west-2 Regions. The instances must be members of the WebServices AWS resource group.

    LinuxWindowsPowerShell
    Linux
    aws ssm start-automation-execution \ --document-name AWS-RestartEC2Instance \ --parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole \ --target-parameter-name InstanceId \ --targets Key=ResourceGroup,Values=WebServices \ --target-locations Accounts=ou-1a2b3c-4d5e6c,Regions=us-west-1,us-west-2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    Windows
    aws ssm start-automation-execution ^ --document-name AWS-RestartEC2Instance ^ --parameters AutomationAssumeRole=arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole ^ --target-parameter-name InstanceId ^ --targets Key=ResourceGroup,Values=WebServices ^ --target-locations Accounts=ou-1a2b3c-4d5e6c,Regions=us-west-1,us-west-2,ExecutionRoleName=AWS-SystemsManager-AutomationExecutionRole
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target $Targets.Key = "ResourceGroup" $Targets.Values = "WebServices" Start-SSMAutomationExecution ` -DocumentName "AWS-RestartEC2Instance" ` -Parameter @{ "AutomationAssumeRole"="arn:aws:iam::123456789012:role/AWS-SystemsManager-AutomationAdministrationRole" } ` -TargetParameterName "InstanceId" ` -Target $Targets ` -TargetLocation @{ "Accounts"="ou-1a2b3c-4d5e6c"; "Regions"="us-west-1"; "ExecutionRoleName"="AWS-SystemsManager-AutomationExecutionRole" }

    The system returns information similar to the following.

    LinuxWindowsPowerShell
    Linux
    {
        "AutomationExecutionId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
    }
    Windows
    {
        "AutomationExecutionId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
    }
    PowerShell
    4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
  3. Run the following command to view the workflow execution.

    LinuxWindowsPowerShell
    Linux
    aws ssm describe-automation-executions \ --filters Key=ExecutionId,Values=4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
    Windows
    aws ssm describe-automation-executions ^ --filters Key=ExecutionId,Values=4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
    PowerShell
    Get-SSMAutomationExecutionList | ` Where {$_.AutomationExecutionId -eq "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"}
  4. Run the following command to view details about the execution progress.

    LinuxWindowsPowerShell
    Linux
    aws ssm get-automation-execution \ --automation-execution-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
    Windows
    aws ssm get-automation-execution ^ --automation-execution-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
    PowerShell
    Get-SSMAutomationExecution ` -AutomationExecutionId a4a3c0e9-7efd-462a-8594-01234EXAMPLE

    Note

    You can also monitor the status of the workflow in the console. In the execution list, choose the execution you just ran and then choose the Steps tab. This tab shows he status of the workflow actions.

Centralized multi-account and multi-Region patching with AWS Systems Manager Automation