CloudFormation使用Fn::Sub配置EBS CSI驱动IAM角色报错求助

常见错误场景及原因 #

你遇到的「Fn::Sub参数格式错误」或IAM语法报错，通常是因为以下两种问题：

1. 错误地将!Sub应用在JSON/YAML对象层级（比如整个Condition或Statement），而非字符串内容
2. 替换Condition中的键时，未使用Fn::Sub的数组模式，导致生成的IAM策略语法非法

正确写法示例 #

场景1：替换OIDC提供商URL与服务账户信息

当需要在信任策略的Condition键中替换变量（比如OIDC提供商地址），必须使用!Sub的数组模式（模板字符串+变量映射），确保生成合法的键值对：

Resources:
  EBSCSIRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Federated: !Sub "arn:aws:iam::${AWS::AccountId}:oidc-provider/${ClusterOIDCProvider}"
            Action: sts:AssumeRoleWithWebIdentity
            Condition:
              StringEquals: !Sub
                - "${ClusterOIDCProvider}:sub": "system:serviceaccount:${ServiceAccountNamespace}:${ServiceAccountName}"
                - ServiceAccountNamespace: kube-system
                  ServiceAccountName: ebs-csi-controller-sa
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy

场景2：仅替换AWS账户ID

如果只需要替换ARN中的账户ID，直接使用!Sub的字符串模式即可：

Principal:
  Federated: !Sub "arn:aws:iam::${AWS::AccountId}:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/XXXXXXXXX"

避坑要点 #

• Fn::Sub仅用于字符串替换，不能直接包裹整个Statement或Condition对象
• 替换Condition的键时，必须用数组模式明确变量映射，否则会生成非法的IAM策略键
• 提前用CloudFormation验证模板：

  aws cloudformation validate-template --template-body file://your-ebs-csi-template.yaml
  

• 若部署时IAM报错，可在CloudFormation控制台查看「生成的角色信任策略」，检查替换后的实际内容是否符合IAM语法要求

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