# AWS: Invoke an SSM Command

Run a pre-approved operation on a Linux EC2 instance through AWS Systems Manager, without SSH access to the instance.


> **Availability:** See the [Incident Workflow Actions Overview table](/workflow-actions) for the plans this workflow is available on.

> **Premium Workflow:** This is a Premium Workflow billed separately from your PagerDuty plan. In the workflow action picker, this action appears as **SSM: Invoke Command**.

## Description

Run one of three pre-approved operations on a Linux EC2 instance through AWS Systems Manager (SSM), without SSH access to the instance.

This action is useful for:

- Collecting recent system logs and kernel messages during triage, without direct SSH or console access to the instance.
- Restarting a specific systemd, SysV, or init.d service as a remediation step (for example, a crashed or hung application service).
- Running a quick host health check — uptime, disk usage, memory, and top CPU-consuming processes — to assess instance health during an incident.

## Prerequisites

- The target instance must be registered with AWS Systems Manager. The instance needs the SSM Agent running and an IAM instance profile with, at minimum, the `AmazonSSMManagedInstanceCore` policy attached. If the instance is not registered, the action fails with an instance-not-registered error.
- The AWS connection's IAM role needs `ssm:SendCommand`, scoped to both the `AWS-RunShellScript` document and the target instance, and `ssm:GetCommandInvocation`.

## Instructions

1. If you have not done so, follow the instructions to [Create an Incident Workflow](/ai-automation/automation/incident-workflows#create-an-incident-workflow).
2. When the instructions prompt you to [add actions](/ai-automation/automation/incident-workflows#add-actions), select **this action**.
3. Enter the following **Inputs** and click **Save**.
4. Continue following instructions to **Publish** the Workflow.
5. When the action runs, you will see the **Outputs** listed below.

## Inputs

> **Field References:** Fields with the **\{+\}** icon accept [Field References](/ai-automation/automation/incident-workflows#field-references), which can be useful for referencing incident data or outputs created in prior workflow steps. To add Field References, click **\{+\}**, or enter `{{`, and select relevant fields. Refer to the [Field References](/ai-automation/automation/incident-workflows#field-references) article for more information.

| Name                    | Description                                                                                                                                                                                                   |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Integration (Required)  | Select a [Workflow Integration](/ai-automation/automation/incident-workflows/workflow-integrations) or click **New AWS Connection** to establish a new one.                                                                         |
| Instance Id (Required)  | The ID of the Linux EC2 instance to run the operation on (for example, `i-0123456789abcdef0`). The instance must be registered with AWS Systems Manager. For more information, see the Prerequisites section. |
| Operation (Required)    | The pre-approved operation to run: **Collect Logs**, **Restart Services**, or **Run Diagnostics**.                                                                                                            |
| Service Name            | Required only when **Operation** is **Restart Services**. The name of the systemd, SysV, or init.d service to restart (for example, `nginx`), exactly as it is registered on the instance.                    |
| Region                  | The AWS region the instance is in (for example, `us-west-2`). If left blank, the action uses the default region configured on the integration.                                                                |

## Outputs

| Name           | Description                                                                                                                                        |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status         | A short, machine-readable, one-line summary of the result. Use it in downstream workflow conditions or automation without parsing the full output. |
| Stdout         | The full standard output captured from the command.                                                                                                |
| Stderr         | The standard error output captured from the command, if any.                                                                                       |
| Result         | Value that shows if the action was successful or not. Either "Success" or "Failed."                                                                |
| Result Summary | Brief description of what the action did or if it failed.                                                                                          |
| Error          | Brief description that is populated if the action failed.                                                                                          |

> **Action Limitations:** - This action supports Linux instances only.
> - This action does not accept free-text or arbitrary shell commands. It exposes only the three pre-approved operations, which limits what a workflow author or a misconfigured automation can run on your infrastructure.

> **Tips:** - **Restart Services confirms the outcome**: After restarting a service, the action checks the service's actual running state. If the restart fails, the action reports **Result** as "Failed" instead of assuming success after issuing the restart command.
> - **Field references**: Reference **Instance Id** from **EC2: Describe Instances** or the incident's custom details so the workflow can run unattended when an alert triggers it.