AWS Systems Manager ExecModule

Overview

AwsSystemsManagerModule brings governed AWS Systems Manager operations into ValkyrAI workflows. It discovers managed nodes, dispatches and reconciles Run Command executions, reads and changes Parameter Store values, and starts or inspects Automation runbooks. The connector uses ValkyrAI's native map ABI and a verified IntegrationAccount; credentials never belong in workflow input.

The connector implements thirteen operations:

• describe_managed_nodes inventories bounded EC2 and hybrid managed nodes.
• list_commands, get_command_invocation, send_command, and cancel_command cover reviewable Run Command dispatch and reconciliation.
• get_parameter, list_parameters, get_parameters_by_path, put_parameter, and delete_parameter cover Parameter Store discovery and lifecycle.
• start_automation, get_automation, and stop_automation cover asynchronous runbook execution.

n8n's reusable AWS credential and region model provides the functional workflow reference. Its AWS credential supports SSM-compatible signing and composable AWS calls, while ValkyrAI adds a dedicated Systems Manager module with strict operation-specific fields, managed-node and hierarchy bounds, explicit mutation confirmations, confidential output classification, read-only retry, and deterministic provider-state reconciliation.

Usage

1. Identify the exact region, managed nodes, documents, parameter paths, and Automation runbooks the workflow may access.
2. Create a least-privilege IAM principal restricted to those SSM actions and resources.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsSystemsManagerModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use discovery operations before mutation: inventory nodes, inspect parameter metadata, and review the exact SSM document or runbook.
6. Supply only fields accepted by the selected operation. Unexpected fields fail before provider access.
7. Reconcile the returned command or Automation execution ID after a timeout; never blindly replay a mutation.

Never place an AWS access key, secret key, session token, or credentials object in module input. Those fields are rejected before any network request. Command text and output, Parameter Store values, KMS key references, runbook parameters, provider tokens, and Automation failure details are confidential and belong only in ACL-scoped workflow state.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the thirteen documented operations.
region	string	Every execution	None	AWS region such as us-west-2; custom endpoints are not accepted.
nextToken	string	Optional list field	None	Opaque provider token, at most 4,096 characters.
limit	integer	Optional list field	100	Total result bound from 1 through 10,000.
returnAll	boolean	Optional list field	false	Follow pages until limit, exhaustion, or 100 pages.
commandId	string	Invocation/cancel; optional list filter	None	UUID returned by send_command.
instanceId	string	get_command_invocation	None	EC2 i-... or hybrid mi-... managed-node ID.
instanceIds	array	send_command; optional cancel subset	None	1-50 unique EC2 or hybrid managed-node IDs.
pluginName	string	Optional invocation field	None	Command plugin name, at most 128 characters.
documentName	string	Command/Automation start	None	SSM document name or SSM document ARN whose region matches region.
documentVersion	string	Optional command/Automation field	None	Positive version, $DEFAULT, or $LATEST.
parameters	object	Optional command/Automation field	Empty	Up to 50 names, each containing 1-50 strings of at most 4,096 characters.
comment	string	Optional send_command field	None	Safe text up to 100 characters.
timeoutSeconds	integer	Optional send_command field	3600	30-2,592,000 seconds before an unstarted command expires.
maxConcurrency	string	Optional command/Automation field	Provider default	Positive count or 1-100 percent.
maxErrors	string	Optional command/Automation field	Provider default	Non-negative count or 0-100 percent.
parameterName	string	Single Parameter Store operations	None	Hierarchical name up to 1,011 characters; reserved aws/ssm prefixes are rejected.
parameterPath	string	get_parameters_by_path	None	Hierarchy root under the same Parameter Store naming rules.
withDecryption	boolean	Parameter reads	false	Explicitly decrypt SecureString values into confidential output.
recursive	boolean	Parameter path reads	false	Traverse all hierarchy levels below parameterPath.
parameterValue	string	put_parameter	None	1-8,192 characters; never echoed in receipts or errors.
parameterType	string	Optional put_parameter field	STRING	STRING, STRING_LIST, or SECURE_STRING.
keyId	string	Optional secure write field	None	KMS key ID/alias/ARN; accepted only with SECURE_STRING.
overwrite	boolean	Optional put_parameter field	false	Create a new version of an existing name.
tier	string	Optional put_parameter field	Provider default	STANDARD, ADVANCED, or INTELLIGENT_TIERING.
dataType	string	Optional put_parameter field	Provider default	Bounded provider data type such as text or aws:ec2:image.
description	string	Optional put_parameter field	None	Safe text up to 1,024 characters.
allowedPattern	string	Optional put_parameter field	None	Provider-side validation expression up to 1,024 characters.
automationExecutionId	string	Automation read/stop	None	UUID returned by start_automation.
clientToken	string	start_automation	None	Unique UUID idempotency token required before provider access.
automationMode	string	Optional start_automation field	AUTO	AUTO or INTERACTIVE.
stopType	string	Optional stop_automation field	CANCEL	COMPLETE or CANCEL.
confirmSendCommand	boolean	send_command	false	Must be exactly true.
confirmCancelCommand	boolean	cancel_command	false	Must be exactly true.
confirmPutParameter	boolean	put_parameter	false	Must be exactly true.
confirmDeleteParameter	boolean	delete_parameter	false	Must be exactly true.
confirmStartAutomation	boolean	start_automation	false	Must be exactly true.
confirmStopAutomation	boolean	stop_automation	false	Must be exactly true.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	Managed-node, command, parameter, or Automation result family.
items	array	List/path success	Bounded normalized records.
count	integer	Items are present	Number of returned items.
pages	integer	Paginated success	Provider pages consumed.
hasMore	boolean	Paginated success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Success	Command, parameter, or Automation receipt.
requestId	string	AWS supplies one	Bounded request reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Managed-node discovery returns platform, agent, resource, association, ping, and host summaries. Command dispatch returns an immutable command ID when AWS supplies one; invocation reads can include bounded standard output and standard error. Parameter reads include the value because retrieval is the purpose of the operation, so the entire output remains confidential. Automation reads return status, timestamps, current step, bounded failure detail, step count, and output keys without copying runbook output values.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Systems Manager
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions enabled for the workflow:

• Inventory: ssm:DescribeInstanceInformation.
• Run Command reads: ssm:ListCommands and ssm:GetCommandInvocation.
• Run Command mutation: ssm:SendCommand and ssm:CancelCommand, scoped to approved documents and managed nodes with tag/resource conditions where supported.
• Parameter reads: ssm:GetParameter, ssm:GetParametersByPath, and ssm:DescribeParameters; add kms:Decrypt only for exact approved KMS keys when withDecryption=true.
• Parameter changes: ssm:PutParameter and ssm:DeleteParameter; add kms:Encrypt/kms:GenerateDataKey only for approved secure parameters.
• Automation: ssm:StartAutomationExecution, ssm:GetAutomationExecution, and ssm:StopAutomationExecution; include narrowly scoped iam:PassRole only when a reviewed runbook requires it.

The connector currently supports a long-lived access-key pair. STS session credentials, role assumption, workload identity, custom endpoints, Session Manager interactive channels, Fleet Manager, Maintenance Windows, State Manager associations, Patch Manager, OpsCenter, Change Manager, Distributor, Inventory upload, resource data sync, and multi-account target locations are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, document, node, parameter, runbook, pagination, and safety fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-systems-manager-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"send_command\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
describe_managed_nodes	Lists bounded EC2 and hybrid managed-node summaries.	Read-only; each page retries transient failures.
list_commands	Lists bounded Run Command summaries, optionally for one command ID.	Read-only; opaque pagination and bounded retry.
get_command_invocation	Reads one node/plugin invocation including bounded output.	Read-only; bounded retry.
send_command	Dispatches one reviewed SSM document to 1-50 explicit managed nodes.	Confirmed external mutation; exactly one provider attempt.
cancel_command	Requests cancellation for a command or node subset.	Confirmed mutation; exactly one provider attempt.
get_parameter	Reads one parameter, optionally decrypting SecureString.	Read-only; bounded retry; output is confidential.
list_parameters	Lists metadata without parameter values.	Read-only; opaque pagination and bounded retry.
get_parameters_by_path	Reads bounded values below one hierarchy path.	Read-only; opaque pagination and bounded retry.
put_parameter	Creates or versions a parameter with optional KMS/tier/data-type controls.	Confirmed mutation; exactly one provider attempt.
delete_parameter	Deletes one parameter name.	Destructive; confirmation and exactly one attempt.
start_automation	Starts an SSM Automation runbook with a caller UUID token.	Confirmed asynchronous mutation; exactly one attempt.
get_automation	Reads execution status, timestamps, current step, and output keys.	Read-only; bounded retry.
stop_automation	Requests CANCEL or COMPLETE for one execution.	Confirmed mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, ID, hierarchy, document, parameter map, pagination value, or confirmation.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_SSM_HTTP_400	Invalid document/parameter, target not online, unsupported state, duplicate token, or provider limit.	Reads may retry selected transient codes	Inspect exact provider state and request ID.
AWS_SSM_HTTP_403	IAM, KMS, document, managed-node, service-role, or resource condition denied.	No	Grant only the missing action/resource/condition.
AWS_SSM_HTTP_404	Command, invocation, parameter, document, node, or Automation execution no longer exists.	No	Reconcile the exact immutable identifier.
AWS_SSM_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; mutations report ambiguity	Inspect command, parameter version, or execution before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; mutations report ambiguity	Treat provider acceptance as unknown until exact state is checked.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, command text, parameter values, runbook inputs, KMS references, and provider details from leaking through errors.

Example

Dispatch a reviewed AWS-owned inventory document:

{
  "operation": "send_command",
  "region": "us-west-2",
  "documentName": "AWS-GatherSoftwareInventory",
  "instanceIds": ["i-0123456789abcdef0"],
  "comment": "approved inventory refresh",
  "timeoutSeconds": 900,
  "maxConcurrency": "1",
  "maxErrors": "0",
  "confirmSendCommand": true
}

Expected result shape:

{
  "status": "success",
  "operation": "send_command",
  "attempts": 1,
  "resultType": "command_dispatch",
  "data": {
    "accepted": true,
    "expectedStatus": "Pending",
    "commandId": "12345678-1234-4234-9234-123456789012",
    "status": "Pending",
    "targetCount": 1
  },
  "requestId": "aws-request-reference"
}

The receipt proves only that AWS accepted the command. Poll get_command_invocation with the exact command and managed-node IDs until a terminal status, and treat command output as confidential.

Notes

• Pagination: describe_managed_nodes, list_commands, list_parameters, and get_parameters_by_path return one page unless returnAll=true; the connector follows opaque tokens with unchanged inputs and stops at limit, exhaustion, or 100 pages.
• Rate limits: Systems Manager quotas vary by account, region, action, managed-node fleet, and Automation concurrency. Read calls use at most five configured attempts with bounded backoff. Commands, parameter changes, and Automation mutations never retry automatically.
• API limits: managed-node lists use provider pages of at most 50; parameter path pages at most 10; command targets at 50 explicit node IDs; document/runbook parameters at 50 names and 50 values per name; list results at 10,000; pages at 100; parameter values at 8,192 characters; and Run Command start timeout at 2,592,000 seconds. AWS can impose tighter operation-, tier-, or account-specific limits.
• Idempotency: start_automation requires a caller UUID token. Run Command and Parameter Store operations do not become replay-safe merely because the input is stable. Reconcile command IDs, current parameter version/value policy, and Automation execution IDs before any retry.
• Asynchronous behavior: Run Command and Automation continue after acceptance. Poll the corresponding read operation for terminal state; never interpret the acceptance response as completion.
• Destructive behavior: delete_parameter can break applications immediately and removes the selected parameter name. send_command can execute arbitrary document-defined actions on nodes. stop_automation can leave partially applied changes. Scope IAM, require independent review, and prefer AWS-owned documents or version-pinned custom documents.
• Secure values: withDecryption=true intentionally places decrypted values in confidential workflow output. Keep explicit ACLs, avoid logs, and prefer downstream bindings that do not serialize secrets. The connector never echoes parameterValue, command parameters, or runbook parameters in mutation receipts or error messages.
• Document trust: a document name alone is not proof of safe behavior. Pin a reviewed version when practical, restrict document sharing and IAM, and inspect custom document ownership before execution.
• Deferred operations: tag/target fan-out, command S3/CloudWatch output configuration, SNS notifications, Maintenance Windows, State Manager, Patch Manager, Session Manager channels, OpsCenter, Change Manager, Inventory upload, Distributor, multi-account Automation, and custom endpoints are intentionally not implemented.
• Provider verification boundary: deterministic tests cover validation, operation families, pagination, retry boundaries, confirmations, credential/value redaction, error normalization, registration, and metadata. Live AWS behavior remains unverified until an authorized AWS account, reviewed managed node, document/runbook, and parameter namespace are supplied.
• Functional reference: n8n's AWS credential model informs reusable credentials and regional workflow ergonomics. AWS Systems Manager API reference defines provider operations. ValkyrAI adds the review, confirmation, redaction, and retry boundaries described above.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsSystemsManagerModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS Systems Manager API reference
• AWS CloudFormation ExecModule
• AWS Step Functions ExecModule
• AWS EventBridge ExecModule
• AWS Kinesis Data Streams ExecModule
• Integration Account Console