現在、AIを使った採用支援ツール(https://noxx.net)を開発しています。このプロダクトでは、仕事情報の分析や応募してきた候補者の評価のために、Step Functionsを含めて100を超えるLambda function を実行しています。インフラを含めたプロダクト内のすべてのサービスはAWS Cloud Development Kit（CDK）により開発/運用されています。
この記事では、プロジェクトをモノレポとして整理するところから、多数のLambda functionのデプロイ管理まで、サーバーレスシステムを設計/実装した方法を共有します。

アーキテクチャの概要

まず、このサーバーレスモノレポアーキテクチャを明確に理解できるよう、パッケージディレクトリの概要を紹介します。

.
├── bin
│   ├── core-stack.ts
│   ├── domain-specific-stack.ts
...
│   └── more-domain-specific-stack.ts
├── docker-compose.yml
├── functions
│   ├── domain-specific-functions
│   │   ├── function-A
│   │   │   ├── index.ts
│   │   │   ├── package.json
│   │   │   └── pnpm-lock.yaml
│   │   ├── function-B
...
├── hasura
│   ├── config.yaml
│   ├── docker-compose.yml
...
├── layers
│   ├── llm-layer
...
│   ├── pinecone-layer
│   ├── postgres-layer
│   ├── prisma-layer
│   └── s3-layer
├── lib
│   ├── infra-stack.ts // Deployment for Network, DB, Bastion Servers
...
│   └── domain-specific-stack.ts
├── package.json
├── pnpm-lock.yaml
├── scripts
└── tsconfig.json

プロジェクトは、pnpmで管理される複数のスタックを持っています。一時期、チーム内でのキャッシュの一貫性のためにyarn v2を好んで使用していましたが、最終的にはリポジトリ内のキャッシュサイズが増加するため、pnpm に移行しました。

ディレクトリ構造の狙いは、何がどこにあるか理解しやすく、ナビゲートしやすいものにすることでした。キーポイントは次のとおりです。

スタックはVertical Splitのアイデア（https://x.com/TkDodo/status/1749717832642736184?s=20）に従ってドメインごとに分けられています。

components / hooks / types / utils (and constants) is the split I'm seeing in many codebases, yet it's the one I dislike the most. It groups by type, not by domain. "useTheme" will live next to "useTodo", but not next to ThemeProvider ... why? pic.twitter.com/2Cg7O9CuTe
— Dominik 🔮 (@TkDodo) January 23, 2024

Lambda functionはドメインごとにグループ化されています。例えば、job description (職務記述書) というドメイン内の関数には analyze、persist、update-job-statusなどが含まれます。
複数のLambda Layerがあります。レイヤーは、データベース、外部API、フレームワークなどのインフラストラクチャごとに整理されています。

マルチスタック

CDKプロジェクトでは全ての記述を1スタックに書くこともできますが、将来的なプロジェクトのスケーラビリティを考慮し、マルチスタックを採用しました。マルチスタックには以下のようなメリットがあります。

デプロイ時間の短縮
スタックごとの明確な責任範囲；カップリングが低く、凝集度が高い
チーム作業時の競合が少ない

以下は、スタックの構築例です。

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props: Props) {
    super(scope, id, props);

    const secretManagerPolicy = new PolicyStatement({
      effect: Effect.ALLOW,
      actions: ["secretsmanager:GetSecretValue"],
      resources: [
        `arn:aws:secretsmanager:${Aws.REGION}:${Aws.ACCOUNT_ID}:secret:*`,
      ],
    });

    // --- Secret ---
    // secret arn
    const secretArn = ssm.StringParameter.valueFromLookup(
      this,
      "rds-secret-arn",
    );

    // convert the parameter value into a token to be resolved after the lookup has been completed.
    const secret = secretsmanager.Secret.fromSecretCompleteArn(
      this,
      "Secret",
      Lazy.string({ produce: () => secretArn }),
    );

    // --- VPC ---
    // vpc id
    const vpcId = ssm.StringParameter.valueFromLookup(this, "vpc-id");
    const vpc = ec2.Vpc.fromLookup(this, "Vpc", {
      vpcId,
    });

    // --- Security Group ---
    const sgId = ssm.StringParameter.valueFromLookup(this, "outbound-sg-id");

    const sg = ec2.SecurityGroup.fromSecurityGroupId(this, "OutboundSG", sgId);

    // --- Layer ---
    const prismaLayer = new lambda.LayerVersion(this, "PrismaLayer", {
      compatibleRuntimes: [lambda.Runtime.NODEJS_18_X],
      code: lambda.Code.fromAsset(
        path.join(`${__dirname}/../`, "layers/prisma-layer/nodejs.zip"),
      ),
    });

    const example = new lambda_nodejs.NodejsFunction(
      this,
      "example",
      {
        runtime: lambda.Runtime.NODEJS_18_X,
        vpc,
        securityGroups: [sg],
        handler: "handler",
        entry: path.join(
          `${__dirname}/../`,
          "functions",
          "application/example/index.ts",
        ),
        environment: {
          SECRET_ID: secret.secretArn || "",
        },
        memorySize: 256,
        timeout: Duration.seconds(30),
        layers: [prismaLayer],
        bundling: {
          externalModules: [
            "@aws-sdk/client-secrets-manager",
            "prisma-layer", // exclude the layer to reduce size
          ],
        },
      },
    );
    example.addToRolePolicy(secretManagerPolicy);

    // store the lambda ARN in SSM to call from apollo-server
    new ssm.StringParameter(this, "exampleLambda", {
      parameterName: "example-lambda-arn",
      stringValue: example.functionArn,
    });
  }
}

このスタックをポイントごとに説明します。

スタックをまたぐものは、AWS Systems Manager(SSM)を通じて共有されます。シークレットキーはインフラストラクチャスタックから渡されます。secretArn はCDKのコンパイル後に解決される必要があるため、fromSecretCompleteArn を使用してシークレットキーを読み込んでいます。

    // secret arn
    const secretArn = ssm.StringParameter.valueFromLookup(
      this,
      "rds-secret-arn",
    );

    // convert the parameter value into a token to be resolved after the lookup has been completed.
    const secret = secretsmanager.Secret.fromSecretCompleteArn(
      this,
      "Secret",
      Lazy.string({ produce: () => secretArn }),
    );

DBへのアクセスを制限するセキュリティグループなども同様です。

    // --- Security Group ---
    const sgId = ssm.StringParameter.valueFromLookup(this, "outbound-sg-id");

    const sg = ec2.SecurityGroup.fromSecurityGroupId(this, "OutboundSG", sgId);

レイヤーはスタックごとに作成され、スタック内でのみ共有されます。これにより、レイヤーの更新が他のスタックに影響を与えることがなくなります。

    // --- Layer ---
    const prismaLayer = new lambda.LayerVersion(this, "PrismaLayer", {
      compatibleRuntimes: [lambda.Runtime.NODEJS_18_X],
      code: lambda.Code.fromAsset(
        path.join(`${__dirname}/../`, "layers/prisma-layer/nodejs.zip"),
      ),
    });

スタック外からこの関数を使用する必要がある場合（例：GraphQLサーバーのリゾルバから呼び出す場合）、arnをSSMに格納します。

  // store the lambda ARN in SSM to call from apollo-server
    new ssm.StringParameter(this, "exampleLambda", {
      parameterName: "example-lambda-arn",
      stringValue: example.functionArn,
    });

マルチスタックアーキテクチャを構築する際、注意すべき点の一つはスタックの依存関係です。このプロジェクトではネットワークとDBのセットアップを含むインフラスタックは他のすべてのスタックから参照されます。よってデプロイの順序については慎重に考える必要があります。後ほどデプロイのセクションでどのようにCI/CDを構築したか説明します。

開発していて感じるのは、スタックは小さくし、その範囲を制限することが管理面でよいということです。Lambda function、SQS、SNSなどリソース数が10を超える場合、スタックを分割することを検討したほうがよいです。

デプロイ

デプロイにはGitHub Actionを使用しています。以前AWSのデプロイツールであるCodePipelineを試したけど、体験としては今ひとつでした。具体的には、例えばデプロイアセットのサイズ制限があり、パイプライン内でいくつかのアセットを削除するための回避策を講じる必要があるなどです。GitHub Actionでは、ローカルで使用するcdkコマンドを使用できるため、自信を持ってデプロイを行うことができます。

GitHub Actionからのデプロイにはクロスアカウントシステムを構築しました。基本的なアイデアは、特定のアカウント（ツールアカウントと呼ばれる）が各アカウント（例：dev、stg、production）でデプロイを実行できるようにするものです。詳細は、https://aws.amazon.com/blogs/devops/cross-account-and-cross-region-deployment-using-github-actions-and-aws-cdk/ を参照してください。GitHub Actionはツールアカウントを使用してロールを引き受け、特定の環境に対してデプロイを行うことができます。

マルチスタックアーキテクチャのおかげで、スタックデプロイを並行して実行でき、ビルド時間をかなり短縮できています。前述のように、システム内の多くのスタックはインフラスタックとBackend-for-frontent（GraphQL）のスタックの間に依存関係があります。なので、インフラスタックのデプロイ => アプリケーションサービスのデプロイ => BFFのデプロイという風に複数の GitHub Actionを組んでいます。

デバッグ／ローカルテスト

ローカルテストとデバッグにはSAM（Serverless Application Model）を使用しています。デプロイをせずにLambda functionを実行可能になるので、開発環境への影響やデプロイ待ち時間を減らすことができます。sam local コマンドを実行するたびに、最新のコードをコンパイルするため cdk synth を実行する必要がある点だけが、注意が必要です。

docs.aws.amazon.com

その他の小技

Node.js（lambda_nodejs）を使用してLambda functionを開発する際の問題の一つは、バンドルされたアプリケーションサイズが大きくなり、AWSコンソール上でデプロイされたコードが読みづらく(ときには読むことすらできず)、デバッグが難しいことがあります。esbundleがLambda Layerも含めたすべての関連コードを一つのファイルにまとめてしまうためです。