Skip to main content

Application

AWS SSM Application Manager – Runbook Validation Rules

When generating or reviewing AWS CDK (TypeScript) or CloudFormation code related to SSM Automation runbooks or Application Manager applications, ALWAYS validate and enforce the following rules.

1. Runbook Type​

  • Runbooks MUST be AWS SSM documents of type Automation
  • Reject or flag any document using:
    • Command
    • Policy
    • Session
  • CDK constructs MUST set:
    • documentType = AUTOMATION

2. Application Manager Association (Mandatory)​

Every Automation runbook MUST be explicitly associated with an SSM Application Manager application.

Acceptable association methods:

  • Tagging the document with:
    • Key: AppManagerApplication
    • Value: <application-name>
  • OR passing and consuming one of:
    • ApplicationId
    • ApplicationName

Runbooks without an explicit application reference MUST be flagged as invalid.

3. Region Consistency​

  • Application Manager applications and runbooks MUST be created in the same AWS region
  • Copilot should warn if stacks reference applications or documents across regions

4. Application Existence​

  • Applications MUST be created using SSM Application Manager APIs
  • Tag-only resource groupings are NOT sufficient
  • CDK code MUST include or reference an actual Application Manager application resource

5. IAM Visibility Requirements​

Generated IAM roles or policies MUST allow:

  • ssm:DescribeDocument
  • ssm:GetDocument
  • ssm:ListDocuments
  • ssm:ListApplications

Missing permissions MUST be highlighted.

6. CDK-Specific Requirements​

When using AWS CDK (TypeScript):

  • Runbooks MUST be explicitly tagged for Application Manager
  • Copilot MUST NOT assume automatic discovery
  • Prefer explicit Tags.of(resource).add(...) over implicit tagging

AWS SSM Automation – Approval Step Rules​

When generating or reviewing AWS CDK (TypeScript) or CloudFormation code for SSM Automation runbooks with approval steps, Copilot MUST enforce the following rules.

1️⃣ Approval Role Requirements​

  • Approval steps cannot use AWS SSO reserved roles (AWSReservedSSO_*) or Permission Set ARNs.
  • Approval steps must reference a stable IAM principal:
    • IAM User
    • IAM Role (non-SSO-managed)
  • The IAM principal must exist in the same AWS account and region as the Automation runbook.

2️⃣ IAM Role Creation (Best Practice)​

  • Copilot should generate a dedicated IAM Role for approvals if one does not exist:
    • Example role name: SSM-ChangeApprover
    • Minimum permissions: 
      {
        "Effect": "Allow",
        "Action": [
          "ssm:SendAutomationSignal",
          "ssm:GetAutomationExecution",
          "ssm:DescribeAutomationExecutions"
        ],
        "Resource": "*"
      }
    • Trust policy allows SSO users or admins to assume it: 
      {
        "Effect": "Allow",
        "Principal": { "AWS": "<user-or-group-ARN>" },
        "Action": "sts:AssumeRole"
      }

3️⃣ Runbook Approval Step​

  • When generating a aws:approve step, Copilot MUST:
    • Reference the stable IAM role ARN (not SSO reserved roles)
    • Include Approvers with valid IAM principal(s)
    • Include optional Message and TimeoutSeconds fields
  • Example YAML snippet:
- name: ChangeApproval
  action: aws:approve
  inputs:
    Approvers:
      - arn:aws:iam::123456789012:role/SSM-ChangeApprover
    Message: "Approve production change"
    TimeoutSeconds: 7200