GitLab CI/CD部署AWS API Gateway动态设置StageName报错解决

问题背景 #

通过GitLab CI/CD部署AWS API Gateway时，希望根据栈名（dev-stack、qa-stack）动态设置StageName属性，使用CloudFormation的FindInMap函数实现后，部署触发错误：

[InvalidResourceException('TestingAPI', "Type of property 'StageName' is invalid.")]

报错原因 #

AWS::Serverless::Api的StageName属性属于SAM资源的模板解析阶段属性，要求必须是字符串字面量，不支持直接使用FindInMap这类CloudFormation动态函数作为输入值，SAM在模板校验阶段会判定类型无效。

无需中断流水线的解决方案 #

方案1：通过CloudFormation参数传递（推荐） #

在模板中定义参数，GitLab CI/CD流水线根据目标栈名动态传递对应参数值：

1. 更新SAM模板：

Parameters:
  StageNameParam:
    Type: String
    AllowedValues: [dev, qa, prod]
    Description: API Gateway的Stage名称

Resources:  
  TestingAPI:
    Type: AWS::Serverless::Api
    Properties:
      StageName: !Ref StageNameParam

2. 在GitLab CI/CD部署命令中，根据栈名传递参数：

# 部署dev栈时
aws cloudformation deploy \
  --stack-name dev-stack \
  --template-file template.yaml \
  --parameter-overrides StageNameParam=dev

# 部署qa栈时
aws cloudformation deploy \
  --stack-name qa-stack \
  --template-file template.yaml \
  --parameter-overrides StageNameParam=qa

方案2：使用Conditions结合固定值映射 #

通过CloudFormation条件判断栈名，选择对应的StageName：

Conditions:
  IsDevStack: !Equals [!Ref AWS::StackName, dev-stack]
  IsQaStack: !Equals [!Ref AWS::StackName, qa-stack]

Resources:  
  TestingAPI:
    Type: AWS::Serverless::Api
    Properties:
      StageName: !If
        - IsDevStack
        - dev
        - !If
          - IsQaStack
          - qa
          - prod # 默认值

方案3：通过Fn::Sub截取栈名前缀（适用于栈名格式固定的场景） #

如果栈名格式为{stage}-stack，可以通过字符串截取直接生成StageName：

Resources:  
  TestingAPI:
    Type: AWS::Serverless::Api
    Properties:
      StageName: !Select [0, !Split ["-", !Ref AWS::StackName]]

总结 #

方案1的参数传递方式最灵活，适配CI/CD流水线的动态部署需求，无需修改模板逻辑即可扩展更多环境；方案2和3适合栈名规则固定的场景，无需在流水线中额外传递参数。

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