Skip to main content
Welcome. This lesson covers AWS Systems Manager Automation (SSM Automation): how automation runbooks (automation documents) are authored, executed, and integrated into event-driven remediation workflows. You’ll learn the document structure, built‑in and custom runbooks, workflow controls (including approvals), cross‑account execution patterns, IAM requirements, monitoring, and production best practices. SSM Automation is designed for operational tasks at scale. It includes 50+ AWS‑maintained runbooks and also supports custom automation documents authored in YAML or JSON. Documents are stored in Systems Manager Documents and can be executed across accounts when the appropriate IAM trust and permissions are set up. Common event sources that invoke automations include EventBridge, AWS Config, CloudWatch, SNS, and Lambda.
An infographic titled "AWS Systems Manager Automation" with four colored panels highlighting features: "50+ AWS Runbooks", "Custom Documents", "Cross‑Account Execution", and "Event‑Driven Integration." Each panel includes an icon and a brief caption about pre-built runbooks, creating YAML/JSON automation documents, centralized cross‑account execution via IAM roles, and integrations with EventBridge, AWS Config, and CloudWatch.

​
Automation document structure

Automation documents follow a simple, predictable schema so you can author repeatable runbooks:
  • schemaVersion – document schema version.
  • description – human readable description.
  • parameters – input variables for the runbook.
  • mainSteps – ordered steps executed by the runbook.
Each mainStep defines an action (e.g., call an AWS API, run a script, invoke Run Command, or call another document), inputs, outputs, and optional error handling. Documents support versioning so you can track changes and roll back if needed.
A slide titled "Automation Documents: Structure and Types" showing a central blue circle labeled "Automation Documents" linked to four labeled boxes: schemaVersion, description, parameters, and mainSteps. The layout visually represents the main components of an automation document.

​
Built‑in vs custom runbooks

AWS provides many common automation documents for routine tasks (patching, stopping instances, creating snapshots, restarting instances, enabling S3 logging, etc.). These AWS‑maintained runbooks are great starting points or references when authoring custom documents.
A slide titled "Automation Documents: Structure and Types" showing a concentric-circle graphic labeled "AWS-Maintained Documents" with an icon of stacked documents in the center. Around it are five example documents: AWS-RunPatchBaseline, AWS-StopInstance, AWS-CreateSnapshot, AWS-RestartEC2Instance, and AWS-ConfigureS3BucketLogging.
Custom automation documents let you encode organization‑specific remediation workflows. They can be multi‑step, include conditional logic and error handling, and call third‑party APIs or internal systems (monitoring, logging, ticketing, etc.). Use custom documents for unique operational requirements or when you must combine multiple service calls and approvals into a single reproducible workflow.
A presentation slide titled "Automation Documents: Structure and Types" with a "Custom Documents" icon on the left. On the right it lists three points: organization-specific remediation workflows; multi-step operations with conditional logic and error handling; and integration with third-party APIs or internal systems.

​
Workflow controls and actions

Document actions support API calls and script execution (PowerShell, Python, shell). SSM Automation provides built‑in workflow controls to orchestrate steps:
  • Branching (if/else) logic
  • Sleep/wait periods
  • Human approval steps (aws:approve)
  • Error handling and retry logic
  • Step outputs that feed into subsequent steps
A presentation slide titled "Document Actions: Building Automation Logic" with a "Workflow Control" label. It shows three action cards: "approve" (pause for human approval), "sleep" (add wait time between steps), and "branch" (apply conditional if/else logic).

​
Cross‑account execution

SSM Automation supports cross‑account remediation. A centralized automation account can assume a role in target member accounts to perform actions (lock down SSH, update security groups, apply ACL changes, etc.). For this pattern to work, the automation execution must be allowed to assume the role in the target account—so configure IAM trust and permissions accordingly.
A simple diagram titled "Cross-Account Automation Architecture" showing a blue "Central Automation Account" box (gear icon) on the left and an orange "Target Accounts" box (target/person icon) on the right, connected by an arrow labeled "Executes remediation."
A common pattern:
  1. AWS Config detects a non‑compliance (or an EventBridge rule matches an event).
  2. EventBridge (or another event source) triggers the automation in the central account.
  3. The automation assumes a role in the target account and runs remediation.
  4. Results and logs flow back to the central account for auditing.
When planning large‑scale remediation, account‑level concurrency limits matter—plan throttling or staggered runs.
Automation execution concurrency is limited (for example, 100 concurrent executions per account). Throttle or stagger large-scale remediation to avoid hitting concurrency limits.
A slide titled "Cross-Account Automation Architecture" showing a left-to-right flow of blue arrows with steps like AWS Config Detection, EventBridge Trigger, Assume Role, and Execute Remediation. It illustrates detecting compliance violations and sending events to a central account so automation can assume a role and perform remediation (stop instance/modify SG/patch).
Centralized automation simplifies updates and auditing—update the document once, and the change applies across all executions that use it. Centralized logging and execution history give you a single place to review results instead of checking each member account individually.
A presentation slide titled "Cross-Account Automation Architecture" showing a "Benefits" section with three numbered boxes: Centralized Logic, Simplified Updates, and Unified Audit Trail, each with a short explanatory line.

​
Human approval (aws:approve) for high‑risk steps

For destructive or irreversible operations—deleting production databases, opening security groups to 0.0.0.0/0, terminating instances—you should insert an aws:approve step. The approval step pauses execution, notifies approvers (for example via SNS), and proceeds only if the minimum required approvals are received. Common scenarios that require approvals:
  • Deleting production data
  • Changing firewall/security group rules to public
  • Terminating instances or data stores in high‑traffic periods
  • Any irreversible configuration change without automated rollback
A presentation slide titled "Approval Workflows for High-Risk Operations" listing five use-case examples that need approval. Examples include deleting production databases, opening security groups to 0.0.0.0/0, terminating EC2 instances, making configuration changes during high-traffic times, and executing irreversible operations without rollback.
A typical approval flow:
  1. Automation reaches an aws:approve step.
  2. Notification sent to designated approvers (e.g., SNS).
  3. Approvers review and respond (approve/deny).
  4. If the minimum approvals are met, automation continues.
  5. If denied or timeout occurs, automation fails.
A horizontal approval flow diagram titled "Approval Workflows for High‑Risk Operations" with five numbered steps. The steps read: automation reaches approve step, notification sent to approvers, approvers review and respond, minimum approvals met → continue, and denied/timeout → fail.
Example YAML for an aws:approve step that posts to an SNS topic and requires two approvals:
Approval timeouts are configurable. Check the AWS Systems Manager Automation documentation for service limits and the maximum allowed approval timeout in your region.

​
Integration points and IAM requirements

SSM Automation integrates tightly with other AWS services—AWS Config and EventBridge commonly detect issues and start automations. When designing automations, ensure IAM roles and service trusts are correct. Key IAM considerations:
Critical permissions to verify: ssm:StartAutomationExecution, ssm:GetAutomationExecution, and iam:PassRole for the role that invokes or runs Automation. Also ensure service trusts (for example, ssm.amazonaws.com or events.amazonaws.com) are properly configured.
A presentation slide titled "IAM Requirements for Automation" highlighting the "Automation Service Role" with bullet points saying it's used for running automation steps and must trust ssm.amazonaws.com. The slide also shows a circular gear/arrow automation icon.
A presentation slide titled "IAM Requirements for Automation" showing a "Critical Permissions" section. It lists four permission boxes — StartAutomationExecution, ssm:GetAutomationExecution, iam:PassRole, and Service-specific — with short descriptions of each.

​
Common use cases

  • Patch management and OS updates
  • Security remediation (fixing non‑compliant security groups)
  • Lifecycle automation (create/delete resources, snapshots)
  • Backup and recovery orchestration
  • Incident response and configuration drift remediation
Consider using AWS‑maintained runbooks for standard tasks and custom documents when you need organization‑specific logic.

​
Monitoring and troubleshooting

Monitor automation executions using the Systems Manager console, CloudWatch Logs, and EventBridge events. OpsCenter can surface recurring automation failures for centralized investigation.
  • View execution steps and status in the Systems Manager Automation console.
  • Stream detailed logs to CloudWatch Logs; export to S3 for long‑term retention.
  • Use EventBridge rules to emit success/failure metrics or trigger alerts.
  • OpsCenter aggregates recurring failures into actionable items.
Execution statuses include: Success, Failed, TimedOut, Cancelled, Pending, and InProgress. Common failure causes:
  • Missing or insufficient IAM permissions (most frequent).
  • Target resource already in an incompatible state or not present.
  • API throttling.
  • Step exceeded configured timeout.
  • Approval timeout if approvers don’t respond.
A slide titled "Monitoring and Troubleshooting Automation." It shows four cards—Systems Manager Console, CloudWatch Logs, EventBridge, and OpsCenter—with brief notes about viewing status/steps, reviewing logs, sending alerts, and tracking recurring issues.
A presentation slide titled "Monitoring and Troubleshooting Automation" showing five workflow statuses — Success, Failed, TimedOut, Cancelled, and Pending — each with a short description of what that status means.

​
Production best practices

  • Validate and test documents in non‑production environments before production deployment.
  • Apply least‑privilege IAM for automation roles and approvers; scope permissions tightly.
  • Reuse and version‑control documents; tag documents and executions for traceability.
  • Export execution logs to S3 and enable CloudTrail for auditability.
  • Use EventBridge filtering to reduce noisy triggers and unnecessary executions.
  • Throttle or schedule heavy automations off‑peak to reduce throttling risk and control cost.
  • Integrate with OpsCenter and CloudWatch dashboards for operational visibility.
A presentation slide titled "Production Automation – Best Practices" showing three checklist panels: Testing & Validation, Security Considerations, and Operational Excellence. Each panel lists brief best-practice items (e.g., test in non-prod, use least‑privilege IAM, enable CloudTrail, tag executions, add CloudWatch alarms).
A presentation slide titled "Production Automation – Best Practices" with two boxed sections. The left box ("Cost Optimization") lists tips like scheduling heavy automations off-peak, using EventBridge filtering, and enabling throttling; the right box ("Compliance & Auditing") suggests exporting logs to S3, creating CloudWatch dashboards, and integrating with OpsCenter.

​
Summary

SSM Automation is a powerful tool for event‑driven, auditable, and repeatable operational workflows. Key takeaways:
  • Documents are simple YAML/JSON structures with parameters and mainSteps.
  • Use AWS‑maintained runbooks for common tasks and custom documents for organization‑specific remediation.
  • Leverage workflow controls (branching, wait, approval) to handle complexity and human‑in‑the‑loop scenarios.
  • Implement cross‑account execution with proper IAM trust relationships to centralize remediation.
  • Monitor, log, and audit all executions—use CloudWatch, S3, CloudTrail, and OpsCenter.
  • Follow least‑privilege IAM, version control, and staging/testing best practices for production automation.
Further reading and references:

Watch Video