ICASU CDK Serverless API Sample

本サンプルはサーバレスアーキテクチャでシステムを開発する上で以下の用途で活用可能です。

• アプリケーション実装方法
• IaC(AWS CDK)
• CI/CD
• 監視

詳細はユーザーガイドをご覧ください。

また ICASU の詳細は[こちら]をご覧ください。TODO: リンク先として ICASU の概要ページを作成予定

システム構成図

技術スタック

このサンプルでは以下の技術スタックを使用しています。

機能	技術スタック	補足
言語	TypeScript
ランタイム	Node.js
IaC	AWS CDK
テストフレームワーク	Vitest
デザインパターン	レイヤードアーキテクチャ + Humble Object パターン
データベース	Amazon DynamoDB
コンピューティング	Serverless Express を使用したモノリシック Lambda
API	Amazon API Gateway REST API
認証、ユーザーディレクトリ	Amazon Cognito user pools
パッケージマネージャー	npm
モノレポ管理ツール	npm workspaces
リンター/フォーマッター	eslint-config-classmethod
CI/CD	GitHub Actions	.github/workflows/cicd.yml にて実装。PR のプッシュ時に CI実行、マージ時に CD 実行
アプリケーションログ監視/メトリクス監視		こちら にて詳細を記載

システム設計書

本サンプルのシステム設計書はこちらを参照してください。以下のドキュメントが含まれます。

• シーケンス図
• API 仕様書
• テーブル仕様書
• バケット仕様書
• パラメーター仕様書

Getting Started

Shared Service Sample のデプロイ

Shared Service Sample の実装をデプロイして、次の機能を作成しておきます。

• OIDC プロバイダー
• アラート通知機能
• AWS リソース横断のメトリクス監視機能

推奨の VS Code 拡張のインストール

.vscode/extensions.json に記載されている推奨の VS Code 拡張をインストールします。

npm run install:recommended-vscode-extensions

依存関係インストール

すべてのワークスペースに対して依存関係をインストールします。

npm ci

単体テスト

Lambda 関数のハンドラーで使用するモジュールの単体テストを実行します。

npm run test-unit

パラメーターの指定

CDK アプリのコンテキストとして使用するパラメーターを、次のファイルに指定します。

• ファイル：packages/iac/bin/parameter.ts

CDK スナップショットテスト

各環境に対するスナップショットテストを実行し、合成された CloudFormation テンプレートに差分が無いことを確認します。

npm run test-snapshot

実装変更により差分が発生する場合は、スナップショットを更新します。

npm run test-snapshot:update

デプロイ

開発者のローカル環境からデプロイ

デプロイ先の環境に対応する AWS アカウント ID を環境変数に指定します。

# 開発環境
export DEV_AWS_ACCOUNT_ID=<AWS アカウント ID>

# ステージング環境
export STG_AWS_ACCOUNT_ID=<AWS アカウント ID>

# 本番環境
export PRD_AWS_ACCOUNT_ID=<AWS アカウント ID>

AWS CDK アプリ（開発環境）をデプロイします。

npm run deploy:dev

デプロイ時に CloudFormation 変更セットの使用をスキップして、スタックデプロイを高速化する場合は、次のコマンドを使用します。

npm run deploy:dev:direct

• 参考：[AWS CDK] cdk deploy で変更セットの使用をスキップして、スタックデプロイを高速化してみた | DevelopersIO

GitHub Actions からデプロイ

GitHub Actions の Manual Deploy to Development ワークフローを使用して、任意のブランチを開発環境に手動デプロイすることも可能です。

E2E テスト

API

REST API の E2E テスト（開発環境）を実施します。

npm run test-e2e-api:dev

GitHub Actions Variables の指定

GitHub Actions Variables に、CI/CD ワークフロー で使用する AWS アカウントごとの OIDC 用 IAM Role Arn を指定します。

Variable Name	説明	例
DEV_AWS_OIDC_ROLE_ARN	開発環境用 AWS アカウントの OIDC 用 Role Arn	arn:aws:iam::XXXXXXXXXXXX:role/dev-icasu-cdk-serverless--GitHubActionsOidcGitHubAc-Dpxxxxxxx
STG_AWS_OIDC_ROLE_ARN	ステージング環境用 AWS アカウントの OIDC 用 Role Arn	arn:aws:iam::XXXXXXXXXXXX:role/stg-icasu-cdk-serverless--GitHubActionsOidcGitHubAc-Dpxxxxxxx
PRD_AWS_OIDC_ROLE_ARN	本番環境用 AWS アカウントの OIDC 用 Role Arn	arn:aws:iam::XXXXXXXXXXXX:role/prd-icasu-cdk-serverless--GitHubActionsOidcGitHubAc-Dpxxxxxxx
DEV_AWS_ACCOUNT_ID	開発環境用 AWS アカウント ID	012345678901
STG_AWS_ACCOUNT_ID	ステージング環境用 AWS アカウント ID	012345678901
PRD_AWS_ACCOUNT_ID	本番環境用 AWS アカウント ID	012345678901

T.B.D 組織移行後に GitHub environments を導入予定

貢献について

現在本リポジトリは、クラスメソッド内部のミラーとして機能しています。

今後 PR や Issue 受け入れを検討しており準備している段階です。フィードバックがありましたら、tmk2154, ryutawakatsukiまでお願いします。