AWS CDK でサーバーレス API を構成するサンプルリポジトリ「ICASU アーキテクチャ(Serverless)」の社内向けワークショップを開催しました
こんにちは、製造ビジネステクノロジー部の若槻です。
アプリケーション開発でサーバーレスアーキテクチャを採用することが多い弊部では、AWS CDK でサーバーレス API を構成するサンプルリポジトリとして「ICASU アーキテクチャ(Serverless)」を主に社内向けにメンテナンスしつつ提供しています。
今回、この ICASU アーキテクチャ(Serverless) の社内向けワークショップを開催する機会があったのでレポートします。
そもそも ICASU アーキテクチャとは何か?については以下の記事をご参照ください。
ワークショップの流れ
ワークショップの流れは以下の通りです。進行役の私が参照する用のスクリプトをそのまま載せているので若干粗いのでご了承ください。
- 座学
- 技術スタックの概要説明
- ハンズオン手順(ローカル環境)
- [ICASU CDK Serverless API Sample](https://github.com/classmethod-internal/icasu-cdk-serverless-api-sample)
- Git クローン
- 依存関係インストール
- コードチェック
- 単体テスト
- パラメーターの指定
- Cognito ドメイン
- CDK スナップショットテスト
- 初回実行は失敗
- スナップショットを更新して再度実行
- AWS CLI の認証
- CDK ブートストラップ
- 開発環境にデプロイ
- E2E テスト
- [Shared Service Sample](https://github.com/classmethod-internal/icasu-shared-service-sample)
- Git クローン
- AWS Chatbot の構成
- 環境変数の指定
- CloudFormation テンプレートの生成
- 開発環境にデプロイ
- Slack チャネルにアラームの正常通知が投稿されていることを確認
- [ICASU CDK Serverless API Sample](https://github.com/classmethod-internal/icasu-cdk-serverless-api-sample)
- アラーム動作確認
- Lambda 関数をコンソールから実行して失敗させる
- Slack チャネルにアラームの失敗通知が投稿されていることを確認
- GitHub の自身のユーザーアカウントに icasu-cdk-serverless-api-sample のリポジトリ作成
- ローカルリポジトリのリモートをユーザーアカウントに変更
- https://docs.github.com/ja/get-started/getting-started-with-git/managing-remote-repositories
- develop ブランチをプッシュ
- develop ブランチがデフォルトになっていることを確認する
- Cognito ドメインの変更をコミット、プッシュしてプルリクエストを作成
- CI が実行される
- スペルチェックで落ちるかも、辞書に追加してコミットを再プッシュ
- CI が通ったらマージする
- CD が実行されるが落ちるかも
- OIDC 用ロールを自身の GitHub リポジトリに更新
- パラメーターで GitHub リポジトリを自身のものに変更
- デプロイ
- 失敗した CD を再実行して通ることを確認
- CDK スナップショットの更新
- コミット、プッシュ、プルリクエスト作成
振り返り
ハンズオン実施環境として CloudShell を使ってもらいたかったが断念
以前、ICASU アーキテクチャ(ECS) の方のワークショップを開催した時に、参加者にローカルでハンズオン環境を構築をしてもらおうとしたら AWS CLI の認証などが上手くいかないトラブルが数名で発生し対応に追われるということがありました
なのでそれを踏まえて今回は AWS CloudShell を利用する前提のハンズオンを当初検討していましたが、CloudShell 上で事前検証をしたところなぜか npm install
コマンドが上手く動作しない問題(コマンド実行が完了せずタイムアウトする)が発生しどうしても解決できませんでした。
よって CloudShell 上でのハンズオンは断念し、今回は参加者にはローカル環境でハンズオンを実施してもらう方針としました。
幸いにも今回のワークショップ開催時は既知の問題(環境変数 AWS_PROFILE
が残っていると AWS SDK for JS v3 が上手く動かない等)以外は発生しなかったので AWS の認証周りで大きく時間を取られることはありませんでした。
ただし、やはりハンズオン向けに簡単に使い捨てできるクリーンな環境を使いたいですね。次回に向けて Dev Container なども試してみたいと思います。
ハンズオンは参加者全員の足並みを揃えて進めた
今回のワークショップの参加者は以下のようになりました。
- 参加者:5 名(うち他部署メンバー 1 名)
- オフライン:3 名
- オンライン:2 名
ワークショップのよくある進め方として、あらかじめ配布済みのハンズオン手順をもとに参加者に各自のペースで進めてもらうというものがありますが、今回は人数も多くなかったので参加者全員の足並みを揃えて同期的に進めることを意識しました。これによりハンズオンのステップごとにアーキテクチャの解説を挟んだり、質問を受けたりすることができました。
また、例えば手順中にエラー発生などでハマっている参加者がいれば、画面共有をしてもらって参加者全員で協力してデバッグをするチーム戦のような形式で進めることもできました。今後 ICASU アーキテクチャをサンプルコードとして活用してもらうにあたり、誰かが遭遇したトラブルは他の人も遭遇する可能性があるので、これにより事象内容や解決方法を効率的に共有できたのではないでしょうか。
アカウントレベルで利用するリソースを管理する別リポジトリも活用した
まだ公開はできていないのですが、進行スクリプト中にある「Shared Service Sample」はアカウントレベルで利用するリソースを管理するサンプルリポジトリとなっており、こちらも活用する手順を入れました。このリポジトリでは次のようなリソースが管理されています。
- IAM OIDC Provider (GitHub Actions) の作成
- AWS Chatbot の Slack Configuration の設定
- アカウントレベルの CloudWatch メトリクス監視の設定
2 つのリポジトリを行き来する手順となりましたが、これによってアプリケーションのエラーログの Slack 通知や GitHub Actions からの CDK デプロイ(これは時間切れで出来ませんでした)など実践的な運用方法まで学べるハンズオンとすることができました。
テストや CI が失敗する手順をわざと残した
ハンズオン手順にテストや CI がわざと失敗する項目を残すことで、正常に動作するようになるまでのデバッグや修正の体験をしてもらうようにしました。例えば以下のような手順です。
- CDK のパラメーターを変更した上で CDK スナップショットを実行したらテスト失敗するようになるためスナップショットの更新が必要となる
- パラメーターを自身の名前を含む値に変更したら、スペルチェックツール CSpell で落ちるようになるので辞書ファイルへの追加が必要となる
おわりに
ICASU アーキテクチャ(Serverless) の社内向けワークショップを開催する機会があったのでそのレポートでした。
参加者の人数自体は多くはありませんでしたが、製造ビジネステクノロジー部以外のメンバーにも興味を持ってもらい参加してもらうなど、ICASU アーキテクチャの普及が地道に進んでいるのを感じることができました。
また前述の振り返りで述べた以外にも GitHub 組織の制限でリポジトリのフォークができなかったたり、E2E テストにフレーキーな箇所が見つかったりと、トラブルはありつつも ICASU アーキテクチャへのフィードバックがもらえる良い
機会になりました。
社外向けリポジトリへの次期リリースについては来年冒頭を予定していますので、アップデートをウォッチして下さっている方は今しばらくお待ちください。願わくば来年はもっと頻繁にリリースできる体制や仕組みを整えたいです。また需要があれば社外向けワークショップもありだと思いますがいかがでしょうか。
以上