Ssm Automation Diagnostics

SSM Automation Diagnostics

When to use

Any SSM Automation investigation — execution failures, step errors, document creation, versioning, approval workflows, rate control, cross-account automation, multi-region execution, change calendar integration, maintenance window automation, custom actions, output parameters, or service role configuration.

Investigation workflow

Step 1 — Collect and triage

aws ssm describe-automation-executions --filters Key=ExecutionStatus,Values=Failed --max-results 10
aws ssm list-documents --document-filter-list key=DocumentType,value=Automation --max-results 20
aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=true"

Step 2 — Domain deep dive

aws ssm get-automation-execution --automation-execution-id <execution-id>
aws ssm describe-automation-step-executions --automation-execution-id <execution-id>
aws ssm describe-document --name <document-name> --document-version '$LATEST'

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=ssm.amazonaws.com --max-results 20
aws ssm get-calendar-state --calendar-names <calendar-name>
aws iam get-role --role-name <automation-role-name>

Read references/guardrails.md before concluding on any SSM Automation issue.

Tool quick reference

Gotchas: SSM Automation

• Automation documents have TWO execution modes: Simple (sequential steps) and Rate Control (concurrent targets). Rate control requires MaxConcurrency and MaxErrors parameters.
• Cross-account automation requires a management account or delegated admin in Organizations, plus target account IAM roles with proper trust policies.
• Change Calendar integration blocks automation execution when the calendar is CLOSED. Automations fail with CalendarStateIsClosedException, not a permissions error.
• Approval steps have a configurable timeout (default 7 days). If no approver acts, the execution times out — it does NOT auto-approve or auto-reject.
• Output parameters from one step are referenced as {{stepName.outputKey}} in subsequent steps. Incorrect references cause silent failures with empty values, not errors.
• Service roles for automation need both ssm:* permissions AND permissions for the actions the document performs (ec2, s3, lambda, etc.).
• Document versioning uses $DEFAULT and $LATEST. Executions use $DEFAULT unless explicitly specified. Updating a document does NOT change $DEFAULT automatically.

Anti-hallucination rules

1. Always cite specific execution IDs, step names, or API responses as evidence.
2. Simple execution vs Rate Control execution have different failure modes. Never conflate them.
3. Cross-account automation requires Organizations setup. Never suggest it works with standalone accounts.
4. Change Calendar blocks executions, it does NOT modify them. Never claim calendars alter automation behavior.
5. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

14 runbooks