为何AWS SSM运行命令文档无法访问Parameter Store参数？

问题场景 #

在SSM运行命令文档中使用Parameter Store参数时遇到两类问题：

问题1：直接在runCommand中引用参数导致文档无法保存 #

测试文档内容：

---
schemaVersion: "2.2"
description: "Testing Parameter Store."
parameters:
  controlString: 
    type: String
    description: "my-ecr String parameter"
    default: "{{ ssm:my-ecr }}"
mainSteps:
- action: "aws:runShellScript"
  name: "from_doc"
  description: "Prints ECR from document parameter"
  inputs:
    runCommand:
    - "echo 'Hello {{ controlString }}!'"
- action: "aws:runShellScript"
  name: "from_store"
  description: "Prints ECR from Parameter Store"
  inputs:
    runCommand:
    - "echo 'Hello {{ ssm:my-ecr }}!'"

保存时触发报错：

InvalidDocumentContent: SSM parameter can't be referenced inside input: echo 'Hello {{ ssm:my-ecr }}!' at Line: 16, Column: 20

问题2：通过文档参数默认值引用时，命令执行无输出 #

修改后仅保留参数中转逻辑的文档：

---
schemaVersion: "2.2"
description: "Testing Parameter Store."
parameters:
  controlString: 
    type: String
    description: "my-ecr String parameter"
    default: "{{ ssm:my-ecr }}"
mainSteps:
- action: "aws:runShellScript"
  name: "from_doc"
  description: "Prints ECR from document parameter"
  inputs:
    runCommand:
    - "echo 'Hello {{ controlString }}!'"

文档可正常保存，但执行后无输出；将参数替换为硬编码字符串时，脚本运行正常。已确认参数my-ecr为简单字符串类型，更换新参数后问题依旧。

原因分析 #

1. 直接在runCommand中引用参数的限制
   SSM文档的参数引用规则明确：仅允许在文档parameters字段的默认值、或部分特定顶层字段中使用{{ ssm:xxx }}语法直接引用Parameter Store参数。aws:runShellScript的runCommand属于输入内容字段，不支持这种直接引用，因此文档无法通过校验。

2. 参数中转后无输出的核心原因

• 权限缺失：执行文档的IAM实体（托管实例的SSM服务角色、发起命令的IAM用户/角色）缺少ssm:GetParameter权限，无法读取Parameter Store中的my-ecr参数，导致参数值未被正确注入，controlString为空，echo命令无有效输出。
• SSM Agent版本问题：旧版本SSM Agent可能对参数引用的语法解析存在兼容问题，无法正确替换{{ controlString }}变量。
• 区域不匹配：如果参数创建在非命令执行的默认区域，未指定区域后缀的引用会找不到参数，导致值为空。

解决方案 #

针对问题1：规范参数引用方式 #

必须通过文档parameters字段中转，即先定义文档参数，将其默认值设为{{ ssm:my-ecr }}，再在runCommand中引用文档参数{{ controlString }}，避免直接在输入内容里引用Parameter Store参数。

针对问题2：解决无输出问题 #

• 添加IAM权限：为执行文档的IAM实体添加以下权限策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ssm:GetParameter",
      "Resource": "arn:aws:ssm:<你的区域>:<你的账号ID>:parameter/my-ecr"
    }
  ]
}

• 升级SSM Agent：确保托管实例上的SSM Agent为最新版本，修复旧版本可能存在的参数解析bug。
• 调试变量值：修改runCommand添加调试命令，确认参数是否被正确注入：

runCommand:
  - "set -x"
  - "echo 'Hello {{ controlString }}!'"
  - "echo 'Parameter value: {{ controlString }}'"

• 指定参数区域：如果参数不在命令执行的默认区域，修改文档参数的默认值为带区域的引用，例如{{ ssm:my-ecr::us-west-2 }}。

内容的提问来源于stack exchange，提问作者James