はじめに
OSS活動をしようと思い、good first issue terraformでIssueを探していたところ、terraform-aws-modulesのAWS Step Functionsの権限に関するIssueを見つけました。
本記事では、そのIssueに取り組む過程で学んだことを記事としてまとめます。
Issueの概要
Step FunctionsのExpressワークフローにおいて、CloudWatch Logsへの書き込み権限が不足しているという内容のIssueでした。
-
不足している権限:
logs:CreateLogStreamとlogs:PutLogEvents -
現状:
main.tf内のポリシー定義には8つの権限しかないが、AWS公式ドキュメントには10個の権限が必要と記載されている。 - 影響: ログが正しく書き込めないため、コンソール上で実行ステータスが "Unknown" になる。(本来はSucceeded/Failedが表示される。)
terraform-aws-step-functionsリポジトリのIssue #76 です。
検証：再現環境の構築
まずは、実際に権限不足によってどのような挙動になるのか、ローカル環境でTerraformを実行して検証しました。
検証ステップ
- Issueに示されたコードを元に
main.tfを作成。 -
terraform applyでExpressワークフローを作成。 - ワークフローを実行し、CloudWatch Logsとコンソールを確認。
結果：ステータスの乖離が発生
-
一覧画面:
Succeededと表示される。
-
詳細画面: ステータスが
Unknownになる。
続いて、Terraformで不足していた権限（logs:CreateLogStream, logs:PutLogEvents）をIAMポリシーに追加して再デプロイしました。
これで解決すると思っていましたが、依然として詳細画面のステータスは Unknown のままでした。
追加検証
不具合の原因を確認するため、追加検証を行いました。
追加検証の内容
- 検証①: マネジメントコンソールから手動で権限を追加 → 変化なし
- 検証②: CloudWatchのリソースベースポリシーを設定 → 変化なし
-
検証③: ログレベルが
ALLであることを確認 → 既にALLだった -
検証④: マネジメントコンソールで「デフォルト設定」で新規作成 → これでも
Unknown
追加検証の意図と理由
追加検証の各ステップは、「不具合の原因がどこに潜んでいるか」切り分ける意図で行いました。
検証①：マネジメントコンソールから手動で権限を追加
- なぜ行ったか： 自身のTerraform設定ミスという可能性を排除するためです。
- 詳細： AWS上で直接権限を付与して挙動が変わらなければ、「コードの書き方」ではなく「権限の内容そのもの」あるいは「別の場所」に原因があると判断できます。
検証②：CloudWatchのリソースベースポリシーを設定
- なぜ行ったか： 公式ドキュメントのトラブルシューティングに記載されていたことと「IAM（操作側）」ではなく「リソース（受け入れ側）」の制限を疑ったためです。
- 詳細： AWSのサービスからログを出す際、IAMポリシー（アイデンティティベース）だけでなく、CloudWatch Logs側で「書き込みを許可する」というリソースベースポリシーが必要な場合があります(参照)。IAMだけでは解決しない「配送の拒否」が起きていないかを確認するために実施しました。
検証③：ログレベルが ALL であることを確認
- なぜ行ったか： 公式ドキュメントのトラブルシューティングに記載されていたことと「分析するための材料（ログ）がそもそも足りているか」を確認するためです。
-
詳細： コンソールがステータスを判定するために特定のログイベント（ExecutionSucceededなど）を必要としている場合、ログレベルが
ERRORなどに絞られていると、成功ログが送られず、コンソール側が「成功したかどうかわからない（Unknown）」と判断してしまう可能性があるためです。
検証④：マネジメントコンソールで「デフォルト設定」で新規作成
- なぜ行ったか： 「terraform-aws-modules」の問題か、「AWSサービスそのもの」の仕様かを切り分けるためです。
-
詳細： AWSが用意した「デフォルト設定」は、AWSが推奨する構成です。これで作成しても
Unknownが出るのであれば、Terraformコードや設定にミスがあるのではなく、「Express Workflowというサービス自体の仕様（またはAWS側のバグ）」であると結論づけることができるからです。
トラブルシューティングの思考プロセス
検証①では自分の設定ミスを疑い実施し、検証②,③は公式ドキュメントに記載のトラブルシューティングを実施し、検証④はAWSサービス自体を疑い実施しました。
公式のトラブルシューティングについて
AWS公式ドキュメントの「CloudWatch Logs へのログ記録のトラブルシューティング」には、上記で実施した検証の他に、ポリシーの文字数制限（5,120文字以内）や、アカウントのCloudWatch Logsログリソースポリシー数（10個以内）を確認するよう記載があります。しかし、今回は小規模環境での検証であることから実施しませんでした。
結論：Express Workflow 特有の挙動
調査の結果、この挙動は設定ミスではなく、Express Workflowの仕様であることが分かりました。
「データソースの違い」による表示の差
| 画面 | データの取得元 | 状態 | 理由 |
|---|---|---|---|
| Executions 一覧 | Step Functions サービスの実行記録 | Succeeded | 実行完了自体はサービス側が把握しているため。 |
| 個別実行の詳細画面 | CloudWatch Logs のログデータ | Unknown | ログからグラフやステータスを逆算する処理が未完了、またはマッピングに時間がかかっている。 |
公式の見解
Express Workflowは秒間数万回という高負荷な実行を想定しています。そのため：
- コンソール表示（ログからの解析）は「ベストエフォート」である。
- 公式ドキュメントにも「すべての実行がコンソールに表示されるわけではない」旨の記述がある。
つまり、設定が正しくても Unknown と表示されるのはAWS側の仕様（または表示の遅延）であり、異常ではないという結論に至りました。
OSSへのコントリビューション
「表示がUnknownになる」こと自体はAWSの仕様ですが、「IAMポリシーにドキュメント通りの権限が足りていない」のは事実でした。
そのため下記を実施し、不足している権限を追加しました。
- リポジトリをForkし、不足していた2つの権限を追加。
- 既存のコード規約やPRの命名規則を確認。
- ドキュメントとの整合性を修正するPRを作成。
まとめ
今回のOSS活動を通じて学んだことは以下の3点です。
- 公式ドキュメントを確認する: サービスの詳細な仕様やトラブルシューティング方法の参考にできる。
- 「仕様」を見極めるための切り分け: コンソールでデフォルト作成しても再現するかどうかを確認する手法は、有効な切り分け手段になる。
- Express Workflowの特性を理解する: 高スループットなサービスでは、整合性よりもパフォーマンスが優先される箇所がある。
公式ドキュメントの重要性を再確認し、有効な切り分け方法やStep Functionsの深い仕様まで理解することができました。