Serverless Framework (v3)で X-Ray を追加しようとしたら、エラーになった話

Serverless Framework v3を使用して、既存のスタックに AWS X-Ray トレーシングを追加しようとしたところ、以下のエラーが発生しました。

provider:
  name: aws
  tracing:
    lambda: true
    apiGateway: true

エラー内容は次のとおりです：

UPDATE_FAILED: IamRoleLambdaExecution (AWS::IAM::Role)
Resource handler returned message: "User: arn:aws:sts::027273742350:assumed-role/shifter-api-v3-circleci/deploy-development- is not authorized to perform: iam:PutRolePolicy on resource: role shifter-api-v3-development-us-east-1-lambdaRole because no identity-based policy allows the iam:PutRolePolicy action (Service: Iam, Status Code: 403, Request ID: 4395c753-56a8-4f24-84d5-f28d5abcc1cc)"

原因の分析

X-Ray トレーシング有効化の仕組み

Serverless Framework で X-Ray トレーシングを有効化すると、内部的に以下の処理が行われます。Lambda関数でトレーシングを有効化し、Lambda実行ロールに必要な X-Ray 権限を付与します。同時に API Gateway でもトレーシングを有効化されます。

権限不足の詳細

デプロイ用のIAMロール（shifter-api-v3-circleci）には以下の管理ポリシーがアタッチされていました。

• AmazonAPIGatewayAdministrator
• AmazonS3FullAccess
• AmazonSSMReadOnlyAccess
• AWSCloudFormationFullAccess
• AWSLambda_FullAccess
• IAMReadOnlyAccess（読み取り専用）

問題は IAMReadOnlyAccess が読み取り専用のため、Lambda実行ロールに X-Ray 権限を付与するための iam:PutRolePolicy アクションが実行できなかったことでした。

解決方法

Step 1: CloudFormation スタックの復旧

エラーが発生したスタックは UPDATE_ROLLBACK_FAILED 状態になっている可能性があります。まず、スタックの状態を確認し、必要に応じて更新ロールバックを実行してください。

# スタックの状態確認
aws cloudformation describe-stacks --stack-name shifter-api-v3-development

# 更新ロールバックの続行
aws cloudformation continue-update-rollback --stack-name shifter-api-v3-development

CloudFormation の UPDATE_ROLLBACK_FAILED 状態から回復する方法については、AWS の公式ドキュメントを参照してください。

Step 2: 必要な権限の追加

デプロイ用のIAMロールに、X-Ray トレーシング有効化のための最小権限を追加します。

aws iam put-role-policy \
  --role-name shifter-api-v3-circleci \
  --policy-name ServerlessXRayDeployPolicy \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "iam:PutRolePolicy",
          "iam:GetRolePolicy"
        ],
        "Resource": "arn:aws:iam::027273742350:role/shifter-api-v3-*-lambdaRole"
      }
    ]
  }'

Step 3: 権限の確認とデプロイ

# インラインポリシーの確認
aws iam list-role-policies --role-name shifter-api-v3-circleci

# 再デプロイ
serverless deploy

重要なポイント

既存スタックへの X-Ray 追加時の注意点

既存の Serverless Framework スタックに後から X-Ray トレーシングを追加する場合、CloudFormation がLambda関数の設定を更新してトレーシングを有効化し、その後Lambda実行ロールに権限を付与します。この際、Step 1の時点で適切な権限がないとエラーが発生してしまいます。

最小権限の原則

今回追加した権限は最小限に抑えました。Action は iam:PutRolePolicy と iam:GetRolePolicy のみとし、Resource は対象スタックのLambda実行ロール（shifter-api-v3-*-lambdaRole）のみに限定しています。

CloudFormation エラー時の対処

CloudFormation のデプロイエラーが発生した場合、まずスタック状態の確認を行い、必要に応じて更新ロールバックを実行してください。その後、根本原因を解決してから再デプロイを実行します。

まとめ

Serverless Framework v3で X-Ray トレーシングを既存スタックに追加する際は、デプロイ用IAMロールに iam:PutRolePolicy 権限を追加する必要があります。CloudFormation の更新エラーが発生した場合は、まず更新ロールバックで状態を復旧することが重要でしょう。

最小権限の原則に従って、必要な権限のみを付与することで、セキュリティを保ちながらスムーズに X-Ray トレーシングを有効化できます。

参考: CloudFormation の UPDATE_ROLLBACK_FAILED 状態から回復する方法