Run command across accounts and regions with SSM

README.md

SSM Automation Document deployed to management account to execute SSM Run Command Document within each managed location (account + region pair).

1. Configure Automation multi-account IAM roles: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-automation-multiple-accounts-and-regions.html
   • AWS-SystemsManager-AutomationAdministrationRole should be deployed to management account
   • AWS-SystemsManager-AutomationExecutionRole should be deployed to all managed accounts
2. Deploy Automation document via Cfn Stack to management account
3. Deploy Command document via Cfn StackSet to all managed accounts + regions
4. Execute SSM automation in management account to run command document against all matched target instances in all managed accounts + regions:

aws ssm start-automation-execution \
  --region us-east-1 \
  --document-name "MyAutomation" \
  --document-version "\$LATEST" \
  --parameters '{"AutomationAssumeRole":["arn:aws:iam::<management-acct>:role/AWS-SystemsManager-AutomationAdministrationRole"]}' \
  --target-locations '[{"Accounts":["ou-ab12-abcd1234"],
                        "Regions":["us-east-1","us-west-2"],
                        "ExecutionRoleName":"AWS-SystemsManager-AutomationExecutionRole",
                        "TargetLocationMaxErrors":"1",
                        "TargetLocationMaxConcurrency":"5"},
                       {"Accounts":["ou-cd34-cdef3456"],
                        "Regions":["us-east-1","us-west-2"],
                        "ExecutionRoleName":"AWS-SystemsManager-AutomationExecutionRole",
                        "TargetLocationMaxErrors":"1",
                        "TargetLocationMaxConcurrency":"5"}]'

---

The Command Document could be expanded to perform different tasks on an instance using different actions ("plugins"): https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-plugins.html

• Download a file from S3 using aws:downloadContent
• Install / update a package using Distributor and aws:configurePackage
• Apply a Chef Recipe or Ansible Playbook via aws:runDocument and the AWS-provided documents AWS-ApplyChefRecipes / AWS-ApplyAnsiblePlaybooks

Cfn-Stack.yml

AWSTemplateFormatVersion: '2010-09-09'
Description: >
  SSM Automation Document run a custom SSM Command Document
  against a fleet of target instances.

Parameters:
  AutomationDocumentName:
    Type: String
    Description: Name of created SSM Automation Document
    Default: MyAutomation
  CommandDocumentName:
    Type: String
    Description: Name of SSM Command Document to run
    Default: MyCommand

Resources:
  AutomationDocument:
    Type: AWS::SSM::Document
    Properties:
      Name: !Ref AutomationDocumentName
      DocumentType: Automation
      Content:
        description: Run custom Command Document
        schemaVersion: '0.3'
        assumeRole: "{{AutomationAssumeRole}}"
        parameters:
          AutomationAssumeRole:
            type: String
            default: ""
            description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
        mainSteps:
        - name: RunCommand
          action: 'aws:runCommand'
          inputs:
            DocumentName: !Ref CommandDocumentName
            Targets:
              # Target any instance with a Name tag (any value)
              # See other target options: https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Target.html
              - Key: tag-key
                Values:
                  - Name

Cfn-StackSet.yml

AWSTemplateFormatVersion: '2010-09-09'
Description: >
  SSM Command Document to run PowerShell commands on Windows instances and shell
  commands on Linux instances.

Parameters:
  CommandDocumentName:
    Type: String
    Description: Name of created SSM Command Document
    Default: MyCommand

Resources:
  CommandDocument:
    Type: AWS::SSM::Document
    Properties:
      Name: !Ref CommandDocumentName
      DocumentType: Command
      Content:
        schemaVersion: "2.2"
        description: Run PowerShell commands on Windows instances and shell commands on Linux instances
        mainSteps:
        - precondition:
            StringEquals: [platformType, Windows]
          action: "aws:runPowerShellScript"
          name: runPowerShellScript
          inputs:
            runCommand:
            - Write-Output "Hello from PowerShell $($PSVersionTable.PSVersion)"
        - precondition:
            StringEquals: [platformType, Linux]
          action: "aws:runShellScript"
          name: runShellScript
          inputs:
            runCommand:
            - echo "Hello from $SHELL"