AWS Systems Manager connector
The AWS Systems Manager connector connects directly to the AWS Systems Manager API. It lets an agent find the nodes Systems Manager manages, such as EC2 instances and hybrid servers, check which of them are reachable and what software they run, run commands on them, run Automation runbooks, and read and write Parameter Store values, without opening the AWS console.
This connector is currently available in Agent Builder only. Workflow support is planned for a future release.
The AWS Systems Manager connector signs requests to the AWS Systems Manager API using AWS Signature Version 4 (SigV4). You configure an AWS Access Key ID, Secret Access Key, and AWS Region when creating the connector. Every action runs under that account and region.
You can create an AWS Systems Manager connector in Stack Management → Connectors.
- AWS Region
- The AWS region whose managed nodes you want to query, for example
us-east-1oreu-west-1. Requests are sent tossm.<region>.amazonaws.com. - Authentication
- AWS Access Key ID and Secret Access Key. Both are required for every action. The IAM identity behind them needs the Systems Manager permissions of the actions you want to use. See Get API credentials.
| Action | Description |
|---|---|
describeInstanceInformation |
List managed nodes with their instance ID, SSM Agent ping status and version (and whether it is the latest), association status, resource type, platform, host name, and IP address. Stopped and terminated EC2 instances are not returned. Parameters: instanceIds, pingStatus (Online, ConnectionLost, Inactive), platformType (Windows, Linux, MacOS), tags, maxResults (5-50), nextToken. tags cannot be combined with the other filters. |
getInventory |
Read the inventory collected from one managed node, such as its installed software, Windows updates, or patch compliance, with the time it was collected. A node has no inventory until Inventory collection is set up for it in Systems Manager. Parameters: instanceId, typeName (for example AWS:Application, AWS:WindowsUpdate, AWS:PatchSummary), filters (up to 5, each with key, values, and type: Equal, NotEqual, BeginWith, LessThan, GreaterThan), maxResults (1-50), nextToken. |
findNodesByInventory |
Find the managed nodes whose inventory matches filters, for example the nodes with an application installed, with their host name, platform, IP address, and status. Parameters: filters (as for getInventory, with keys written as <type>.<attribute>, for example AWS:Application.Name), maxResults (1-50), nextToken. |
listDocuments |
List the Command documents and Automation runbooks the account can run, with their name, display name, type, owner, platforms, default version, and target resource type. Parameters: documentType (Command, Automation), owner (Self, Amazon, Private, Public, ThirdParty), namePrefix, platformType (Linux, Windows), maxResults (1-50), nextToken. |
getDocument |
Read a document as YAML, including its description, parameters, and steps. Parameters: name (required), documentVersion. |
sendCommand |
Run an SSM document, such as AWS-RunShellScript or AWS-RunPowerShellScript, on up to 50 managed nodes. Returns a commandId immediately, and the command runs asynchronously. Parameters: instanceIds (required, 1-50), documentName (required), parameters (for example { "commands": ["uptime"] }), documentVersion, comment, timeoutSeconds (30-2592000). |
getCommandInvocation |
Get the status, exit code, standard output, and standard error (up to 24,000 characters each) of a command on one node. Parameters: commandId (required), instanceId (required), pluginName (the step to read, for documents with more than one step). |
listCommands |
List the commands sent in the last 30 days with their document, parameters (for AWS-RunShellScript, the shell commands that ran), comment, target nodes, status, and completion counts. Parameters: commandId, instanceId, status, documentName, invokedAfter, invokedBefore (ISO 8601), maxResults (1-50), nextToken. |
cancelCommand |
Cancel a command, on every node it was sent to or only on some of them. Nodes that already finished keep their result. Parameters: commandId (required), instanceIds (1-50). |
startAutomationExecution |
Start an Automation runbook, such as AWS-RestartEC2Instance. Returns an automationExecutionId immediately, and the runbook runs asynchronously. Parameters: documentName (required), parameters (for example { "InstanceId": ["i-0123456789abcdef0"] }), documentVersion, clientToken. |
getAutomationExecution |
Get the status of a runbook execution, the step it is on, its failure message and outputs, and each step with its action, status, failure message and details, and outputs. Parameters: automationExecutionId (required). |
listAutomationExecutions |
List runbook executions, running and finished, with their runbook, status, who started them, start and end times, current step, and failure message. Parameters: documentNamePrefix, status (up to 10 statuses), startTimeAfter, startTimeBefore (ISO 8601), maxResults (1-50), nextToken. |
stopAutomationExecution |
Cancel a runbook execution. Steps that already ran are not undone. Parameters: automationExecutionId (required). |
getParameter |
Read a Parameter Store parameter: its type, value, version, data type, and last modified date. SecureString parameters are never decrypted, so their value is returned as null. Parameters: name (required, optionally with :<version> or :<label>). |
putParameter |
Create a String or StringList Parameter Store parameter, or replace the value of an existing one, and return its new version. SecureString parameters cannot be written or overwritten. Values over 4,096 characters (up to 8,192) need the account's default parameter tier set to Advanced or Intelligent-Tiering. Parameters: name, value, type (String, StringList) (all required), description, overwrite (required to replace an existing value). |
sendCommand runs commands with the privileges of SSM Agent on the node, usually root or SYSTEM, startAutomationExecution runs runbooks that change AWS resources, and putParameter can replace parameter values that applications read. An agent this connector is assigned to can call all three without asking for confirmation. Limit what they can run with the IAM policy described in Get API credentials, and assign the connector only to agents that should change your nodes and resources.
Use the Action configuration settings to customize connector networking, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use xpack.actions.customHostSettings to set per-host configurations.
- Sign in to the AWS Management Console and open IAM.
- Create (or choose) an IAM user or role that will be used only for this connector, then attach a policy granting the Systems Manager actions it uses:
ssm:DescribeInstanceInformation,ssm:ListDocuments,ssm:GetDocument,ssm:ListCommands,ssm:GetCommandInvocation,ssm:GetAutomationExecution,ssm:DescribeAutomationExecutions,ssm:ListInventoryEntries, andssm:GetInventoryon resource*, andssm:GetParameteron the parameters it can read (for examplearn:aws:ssm:<region>:<account-id>:parameter/myapp/*). The AWS managed policy AmazonSSMReadOnlyAccess covers them. The connector never asks forSecureStringvalues to be decrypted, so it needs nokms:Decryptpermission.ssm:SendCommandon both the documents it can run (for examplearn:aws:ssm:<region>::document/AWS-RunShellScript) and the nodes it can run them on (for examplearn:aws:ec2:<region>:<account-id>:instance/*for EC2 instances andarn:aws:ssm:<region>:<account-id>:managed-instance/*for hybrid nodes, narrowed with a tag condition), andssm:CancelCommandon resource*.ssm:StartAutomationExecutionon both the runbooks it can run (for examplearn:aws:ssm:<region>::document/AWS-RestartEC2Instancefor a runbook owned by AWS, orarn:aws:ssm:<region>:<account-id>:document/MyRunbookfor one in your account) andarn:aws:ssm:<region>:<account-id>:automation-execution/*, andssm:StopAutomationExecutionon resource*. A runbook runs as the role passed in itsAutomationAssumeRoleparameter, which also needsiam:PassRolefor that role, or else with these credentials, which then need every permission the runbook uses.ssm:PutParameterandssm:GetParameteron the parameters it can write (for examplearn:aws:ssm:<region>:<account-id>:parameter/myapp/flags/*). Before overwriting a parameter, the connector reads its type to refuse overwriting aSecureString.- Leave out the permissions of the second, third, and fourth items to keep the connector read-only. Those actions then fail with
AccessDeniedException.
- Under Security credentials, create an Access key for that user and copy the Access Key ID and Secret Access Key. Store the secret access key securely because AWS only shows it once.
- Note the AWS region where your managed nodes are registered (for example
us-east-1). - When configuring the connector, enter the Access Key ID, Secret Access Key, and Region.