Menu
AWS Systems Manager
User Guide

Running Documents from Remote Locations

You can run SSM documents from remote locations by using the AWS-RunDocument pre-defined SSM document. This document currently supports the following remote locations:

  • GitHub repositories (public and private)

  • Amazon S3

  • Documents saved in Systems Manager

The following procedure describes how to run remote SSM documents by using the console. This procedure shows how to run the remote document by using Run Command, but you can also run remote documents by using State Manager or Automation.

Before You Begin

Before you run a remote document, you must complete the following tasks.

  • Create an SSM document and save it in a remote location. For more information, see Creating Systems Manager Documents

  • If you plan to run a remote document that is stored in a private GitHub repository, then you must create a Systems Manager SecureString parameter for your GitHub security access token. You can't access a remote document in a private GitHub repository by manually passing your token over SSH. The access token must be passed as a Systems Manager SecureString parameter. For more information about creating a SecureString parameter, see Creating Systems Manager Parameters.

Run a Remote Document (Console)

Depending on the service you are using, AWS Systems Manager or Amazon EC2 Systems Manager, use one of the following procedures:

To run a remote document (AWS Systems Manager)

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

  2. In the navigation pane, choose Run Command, and then choose Run a Command.

  3. In the Document list, choose AWS-RunDocument.

  4. In the Targets section, identify the instances to which you want to download and run the script by specifying tags or selecting instances manually.

  5. (Optional) In Rate control:

    • In Concurrency, specify either a number or a percentage of instances on which to run the command at the same time.

      Note

      If you selected targets by choosing Amazon EC2 tags, and you are not certain how many instances use the selected tags, then limit the number of instances that can run the document at the same time by specifying a percentage.

    • In Error threshold, specify when to stop running the command on other instances after it fails on either a number or a percentage of instances. For example, if you specify 3 errors, then Systems Manager stops sending the command when the 4th error is received. Instances still processing the command might also send errors.

  6. In the Source Type list, choose an option.

    • If you choose GitHub, specify Source Info information in the following format:

      {"owner":"owner_name", "repository": "repository_name", "path": "path_to_document", "tokenInfo":"{{ssm-secure:SecureString_parameter_name}}" }

      For example:

      {"owner":"TestUser1", "repository": "SSMTestDocsRepo", "path": "SSMDocs/mySSMdoc.yml", "tokenInfo":"{{ssm-secure:myAccessTokenParam}}" }
    • If you choose S3, specify Source Info information in the following format:

      {"path":"URL_to_document_in_S3"}

      For example:

      {"path":"https://s3.amazonaws.com/aws-executecommand-test/scripts/ruby/mySSMdoc.json"}
    • If you choose SSMDocument, specify Source Info information in the following format:

      {"name": "document_name"}

      For example:

      {"name": "mySSMdoc"}
  7. In the Document Parameters field, type parameters for the remote SSM document. For example, if you run the AWS-RunPowerShell document, you could specify:

    {"commands": ["date", "echo \"Hello World\""]}

    If you run the AWS-ConfigureAWSPack document, you could specify:

    { "action":"Install", "name":"AWSPVDriver" }
  8. In Other parameters:

    • In the Comment box, type information about this command.

    • In Timeout (seconds), specify the number of seconds for the system to wait before failing the overall command execution.

  9. (Optional) In Rate control:

    • In Concurrency, specify either a number or a percentage of instances on which to run the command at the same time.

      Note

      If you selected targets by choosing Amazon EC2 tags, and you are not certain how many instances use the selected tags, then limit the number of instances that can run the document at the same time by specifying a percentage.

    • In Error threshold, specify when to stop running the command on other instances after it fails on either a number or a percentage of instances. For example, if you specify 3 errors, then Systems Manager stops sending the command when the 4th error is received. Instances still processing the command might also send errors.

  10. In the Output options section, if you want to save the command output to a file, select the Write command output to an Amazon S3 bucket. Type the bucket and prefix names in the boxes.

  11. In the SNS Notifications section, if you want notifications sent about the status of the command execution, select the Enable SNS notifications check box. For more information about configuring Amazon SNS notifications for Run Command, see Configuring Amazon SNS Notifications for Run Command.

  12. Choose Run.

To run a remote document (Amazon EC2 Systems Manager)

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Run Command, and then choose Run a command.

  3. In the Document list, choose AWS-RunDocument.

  4. In the Select Targets by section, choose an option and select the instances where you want the document to run.

  5. (Optional) In the Execute on field, specify a number of Targets that can run the document concurrently (for example, 10). Or, specify a percentage of the number of targets that can run the document concurrently (for example, 10%).

    Note

    If you selected targets by choosing EC2 tags, and you are not certain how many instances use the selected tags, then limit the number of instances that can run the document by specifying a percentage.

  6. (Optional) In the Stop after field, specify the maximum number of errors allowed before the system stops sending the command to other instances. For example, if you specify 3, then Systems Manager stops sending the command when the 4th error is received. Instances still processing the command might also send errors.

  7. In the Source Type list, choose an option.

    • If you choose GitHub, specify Source information in the following format:

      {"owner":"owner_name", "repository": "repository_name", "path": "path_to_document", "tokenInfo":"{{ssm-secure:SecureString_parameter_name}}" }

      For example:

      {"owner":"TestUser1", "repository": "SSMTestDocsRepo", "path": "SSMDocs/mySSMdoc.yml", "tokenInfo":"{{ssm-secure:myAccessTokenParam}}" }
    • If you choose S3, specify Source information in the following format:

      {"path":"URL_to_document_in_S3"}

      For example:

      {"path":"https://s3.amazonaws.com/aws-executecommand-test/scripts/ruby/mySSMdoc.json"}
    • If you choose SSMDocument, specify Source information in the following format:

      {"name": "document_name"}

      For example:

      {"name": "mySSMdoc"}
  8. In the Document parameters field, type parameters for the remote SSM document. For example, if you run the AWS-RunPowerShell document, you could specify:

    {"commands": ["date", "echo \"Hello World\""]}

    If you run the AWS-ConfigureAWSPack document, you could specify:

    { "action":"Install", "name":"AWSPVDriver" }
  9. In the Comments field, type information about this command.

  10. In the Advanced Options section, choose Write to S3 to store command output in an Amazon S3 bucket. Type the bucket and prefix names in the text boxes.

  11. Choose Enable SNS notifications to receive notifications and status about the command execution. For more information about configuring SNS notifications for Run Command, see Configuring Amazon SNS Notifications for Run Command.

  12. Choose Run.