aws-ssm-send-command-action

Description

GitHub Action for sending commands to AWS Systems Manager. It is a wrapper around the SendCommand API call together with some additional features like waiting for the command to finish and printing logs of failed command invocations.

Usage

- uses: MercuryTechnologies/aws-ssm-send-command-action@v0
  with:
    document-name: 'AWS-RunShellScript'
    targets: '[{"Key":"tag:Name","Values":["MyInstance"]}]'
    parameters: '{"commands":["echo Hello, World!"]}'
    wait-until-command-executed: true
    max-wait-time: 600

Inputs

name	description	required	default
document-name	The name of the AWS Systems Manager document (SSM document) to run. This can be a public document or a custom document. To run a shared document belonging to another account, specify the document Amazon Resource Name (ARN).	true	""
targets	The targets to send the command to. Must be a JSON string of type {Key: string, Values: string[]}[]. Key=InstanceIds,Values=instance-id-1,instance-id-2,instance-id-3 Key=tag:tag-key,Values=tag-value-1,tag-value-2 Key=resource-groups:Name,Values=resource-group-name	true	""
parameters	The parameters to pass to the document, if any. Must be a JSON string of type Record<string, string[]>	false	""
wait-until-command-executed	Whether to wait until the command has been executed	false	false
max-wait-time	The maximum time to wait for the command to finish	false	600
log-failed-command-invocations	Whether to print logs of failed command invocations. If the command target is targeting hundreds or thousands of instances, this can be expensive and slow.	false	false

Outputs

name	description
command-id	The ID of the command that was sent

Credentials

By default, this action relies on the default behavior of the AWS SDK for JavasSript to determine AWS credentials and region. You can use the aws-actions/configure-aws-credentials action to configure the GitHub Actions environment with environment variables containing AWS credentials and your desired region.

- uses: 'aws-actions/configure-aws-credentials@v4'
  with:
    role-to-assume: 'arn:aws:iam::123456789012:role/MyRole'
    aws-region: 'us-west-2'

Permissions

Sending a command requires the ssm:SendCommand permission. It's recommended to write a policy that allows sending commands to specific resources, rather than allowing all resources.

For example, the following policy only allow sending the AWS-RunShellScript document to instances in the production environment

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AWSRunShellScript",
      "Effect": "Allow",
      "Action": "ssm:SendCommand",
      "Resource": "arn:aws:ssm:*:*:document/AWS-RunShellScript"
    },
    {
      "Sid": "ProductionInstances",
      "Effect": "Allow",
      "Action": "ssm:SendCommand",
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringEquals": {
          "ssm:ResourceTag/Environment": "production",
          "ssm:ResourceTag/Role": "webserver"
        }
      }
    }
  ]
}

When using wait-until-command-executed the following extra permissions are required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "WaitUntilCommandExecuted",
      "Effect": "Allow",
      "Action": "ssm:ListCommands",
      "Resource": "*"
    }
  ]
}

When using log-failed-command-invocations the following extra permissions are required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "LogFailedCommandInvocations",
      "Effect": "Allow",
      "Action": ["ssm:ListCommandInvocations", "ssm:GetCommandInvocation"],
      "Resource": "*"
    }
  ]
}

Runs

This action is a node20 action.