Serverless Frameworkでデプロイ失敗？IAMに必要な権限と解決策メモ【AWS】

はじめに

AWSでServerless Frameworkを使ってサーバーレスアプリケーションをデプロイする際、突然「CREATE_FAILED」というエラーに遭遇したことはありませんか？私も最近、本番環境へのデプロイ中にこのエラーに直面し、数時間のトラブルシューティングを余儀なくされました。

この記事では、実際に私が経験した「apigateway:TagResource」権限不足によるデプロイ失敗と、その解決プロセスを詳しく解説します。同じトラブルに遭遇した方はもちろん、これからServerless Frameworkを使う予定の方にも、事前にIAM権限を適切に設定するための実践的な知識を提供します。

発生したエラーの詳細

Serverless Frameworkで「sls deploy」コマンドを実行した際、以下のようなエラーメッセージが表示されました。

リソース HttpApiStage は CREATE_FAILED 状態です
User is not authorized to perform: apigateway:TagResource on resource: arn:aws:apigateway:ap-northeast-1::/apis/xxxxx/stages/default

エラーの原因を理解する

このエラーは、CloudFormationがAPI Gateway HTTP APIのステージを作成する際に、リソースにタグを付与しようとした時点で発生しました。Serverless Frameworkは内部的にCloudFormationを使用してAWSリソースをデプロイしますが、その際に自動的にタグ付けを行います。

しかし、デプロイに使用しているIAMユーザーまたはロールに「apigateway:TagResource」権限が付与されていなかったため、この操作が拒否されたのです。一見シンプルな権限不足ですが、これはServerless Frameworkを使う多くの開発者が見落としがちなポイントです。

なぜこの権限が必要なのか

AWS API Gatewayでは、リソース管理とコスト配分のためにタグ付けが推奨されています。Serverless Frameworkは、デプロイしたリソースを追跡・管理するために、自動的に以下のようなタグを付与します。

• サービス名（SERVERLESS_SERVICE）
• ステージ名（SERVERLESS_STAGE）
• デプロイ日時（SERVERLESS_ALIAS）

これらのタグは、複数のサービスやステージを運用する際に非常に有用ですが、そのためには適切なIAM権限が必要になります。

解決策：IAMポリシーの適切な設定

この問題を解決するには、デプロイに使用しているIAMユーザーまたはロールに、必要な権限を追加する必要があります。以下、具体的な手順を説明します。

Step 1: 必要な権限を特定する

今回のケースで必要な権限は「apigateway:TagResource」ですが、実際にはServerless Frameworkを使った開発では、他にも多くの権限が必要です。以下は、最小限必要な権限の一例です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "apigateway:POST",
        "apigateway:GET",
        "apigateway:PUT",
        "apigateway:DELETE",
        "apigateway:PATCH",
        "apigateway:TagResource",
        "apigateway:UntagResource"
      ],
      "Resource": "*"
    }
  ]
}

Step 2: IAMポリシーを作成・アタッチする

AWS Management Consoleから、以下の手順でポリシーを設定します。

1. IAMコンソールを開き、対象のユーザーまたはロールを選択
2. 「ポリシーをアタッチ」をクリック
3. カスタムポリシーを作成するか、既存のポリシーを編集
4. 上記のJSON形式の権限を追加
5. 変更を保存

Step 3: 再デプロイと確認

権限を追加した後、再度「sls deploy」コマンドを実行します。私の場合、このステップで無事にデプロイが成功し、API Gatewayのエンドポイントが正常に作成されました。デプロイ時間は約2分程度でした。

本番環境での推奨事項

セキュリティのベストプラクティスとして、本番環境では以下の点に注意してください。

• Resource を “*” ではなく、具体的なARNに限定する
• 最小権限の原則に従い、必要な権限のみを付与する
• 定期的にIAMポリシーをレビューし、不要な権限を削除する
• CloudTrailでAPI呼び出しをログ記録し、権限の使用状況を監視する

追加のトラブルシューティング：DynamoDBのValidationException

同じ開発プロジェクトで、もう一つ別のエラーにも遭遇しました。DynamoDBへのバッチ書き込み時に「ValidationException」が発生したケースです。

エラーの原因

このエラーは、DynamoDBテーブルに書き込もうとしたデータの形式が、テーブルのスキーマ定義と一致していなかったことが原因でした。具体的には、パーティションキーのデータ型が文字列（String）で定義されているのに、数値（Number）を渡していました。

解決方法

データを送信する前に、以下のような検証ロジックを追加することで解決しました。

// データ型を明示的に文字列に変換
const item = {
  id: String(numericId),  // 数値を文字列に変換
  timestamp: Date.now(),
  data: JSON.stringify(payload)
};

この経験から学んだのは、DynamoDBを使う際は、データ型の整合性を事前にしっかりチェックすることの重要性です。特にTypeScriptを使っている場合は、型定義をしっかり行うことで、このようなエラーを未然に防ぐことができます。

Serverless FrameworkでのIAM権限管理のベストプラクティス

今回の経験を踏まえて、Serverless Frameworkを使う際のIAM権限管理について、いくつか実践的なアドバイスを共有します。

1. CI/CD用の専用IAMユーザーを作成する

本番環境へのデプロイは、個人のAWSアカウントではなく、CI/CD専用のIAMユーザーを作成して行うことを推奨します。これにより、権限の管理が容易になり、監査ログも追跡しやすくなります。

2. serverless.ymlでiamRoleStatementsを定義する

Lambda関数の実行に必要な権限は、serverless.ymlファイル内で明示的に定義することができます。これにより、Infrastructure as Codeの原則に従った管理が可能になります。

3. Serverless Framework Dashboardの活用

公式のServerless Framework Dashboardを使用すると、デプロイ履歴やエラーログを一元管理でき、権限エラーの早期発見に役立ちます。

まとめ

• Serverless Frameworkのデプロイには、API Gateway操作のための適切なIAM権限が必須です
• 特に「apigateway:TagResource」権限は見落としやすいポイントなので、事前にポリシーに含めておきましょう
• セキュリティのベストプラクティスとして、最小権限の原則に従い、必要な権限のみを付与することが重要です
• DynamoDBを使う際は、データ型の整合性チェックを徹底し、ValidationExceptionを未然に防ぎましょう
• 本番環境では、CI/CD専用のIAMユーザーを作成し、権限管理を適切に行うことが推奨されます
• エラーが発生した際は、CloudFormationスタックのイベントログを確認することで、根本原因を特定できます

AWSとServerless Frameworkを使った開発では、このようなIAM権限に関するトラブルは避けて通れません。しかし、一度経験して適切に対処法を理解しておけば、次回からはスムーズにデプロイができるようになります。この記事が、同じ問題に直面した方の解決の一助になれば幸いです。