GitHub Actions部署Serverless时KMS Grant的granteePrincipal正则错误排查

错误本质：ARN格式无效 #

这个错误不是策略问题，而是你指定的granteePrincipal ARN格式不符合KMS的正则约束。报错里的正则^[\w+=,.@:/-]+$只允许字母、数字、下划线、加号、等号、逗号、点号、@、冒号、斜杠、横杠这些字符，而你用的!Sub arn:aws:iam::XXaccount-idXX:role/role-name里的XXaccount-idXX是未替换的占位符，包含不符合规则的大写X和横杠组合，直接触发了格式校验失败。另外如果!Sub语法没有在你的部署框架（比如CloudFormation/Serverless）中正确渲染，保留了!Sub关键字也会导致格式错误。

granteePrincipal是什么？有何影响？ #

• granteePrincipal是KMS Grant中明确的被授权实体，必须是IAM用户、角色、服务主体等的合法ARN。KMS会将Grant定义的加密/解密等权限赋予这个实体。
• 一旦granteePrincipal格式错误，KMS Grant创建会直接失败，依赖该Grant的Serverless部署操作（比如加密Lambda代码、访问加密的配置资源等）会中断，导致部署失败。

修复策略与解决建议 #

1. 正确生成合法ARN #

• 直接替换占位符：把XXaccount-idXX换成你的实际AWS账号ID（纯数字，比如123456789012），去掉未渲染的!Sub关键字，示例：

granteePrincipal: "arn:aws:iam::123456789012:role/role-name"

• 用框架变量自动渲染：如果用Serverless框架或CloudFormation，确保!Sub能正确解析账号ID，示例：

granteePrincipal: !Sub "arn:aws:iam::${AWS::AccountId}:role/role-name"

2. 验证格式合规性 #

确保最终生成的ARN完全匹配KMS的正则要求：

• 无占位符字符、空格或其他特殊符号
• 所有字符都属于[\w+=,.@:/-]范围

3. 排查GitHub Actions变量传递 #

如果账号ID是通过GitHub Secrets或环境变量传递的：

• 检查变量值是否为纯数字账号ID，无多余字符（比如引号、换行）
• 确保部署脚本中正确引用变量，没有拼接错误

4. 手动验证Grant创建（可选） #

用AWS CLI先测试Grant创建，确认格式正确：

aws kms create-grant \
  --key-id <你的KMS密钥ARN> \
  --grantee-principal arn:aws:iam::123456789012:role/role-name \
  --operations Encrypt Decrypt

如果命令执行成功，说明格式没问题，再回到Serverless部署流程排查框架渲染或变量传递的问题。

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