AWS Lambda
DockerコンテナとAWS Lambda Web Adapterを使用して、MastraアプリケーションをAWS Lambdaにデプロイします。 このアプローチにより、Mastraサーバーを自動スケーリング機能付きのコンテナ化されたLambda関数として実行できます。
このガイドでは、Mastraアプリケーションがデフォルトの
npx create-mastra@latest
コマンドを使用して作成されていることを前提としています。
新しいMastraアプリケーションの作成方法の詳細については、
はじめにガイドを参照してください
前提条件
AWS Lambdaにデプロイする前に、以下が必要です:
- AWS CLI がインストールされ、設定されていること
- Docker がインストールされ、実行されていること
- Lambda、ECR、IAMの適切な権限を持つAWSアカウント
- 適切なメモリストレージで設定されたMastraアプリケーション
メモリ設定
AWS Lambdaは一時的なファイルシステムを使用するため、
ファイルシステムに書き込まれたファイルは短期間のみ存在し、失われる可能性があります。
ファイルURLを使用するLibSQLStore
など、
ファイルシステムを使用するMastraストレージプロバイダーの使用は避けてください。
Lambda関数にはファイルシステムストレージに制限があります。Mastraアプリケーションをインメモリまたは外部ストレージプロバイダーを使用するように設定してください:
オプション1:インメモリ(最もシンプル)
import { LibSQLStore } from "@mastra/libsql";
const storage = new LibSQLStore({
url: ":memory:", // インメモリストレージ
});
オプション2:外部ストレージプロバイダー
Lambda呼び出し間で永続的なメモリを使用するには、TursoでLibSQLStoreを使用するか、PostgreStore
などの他のストレージプロバイダーを使用してください:
import { LibSQLStore } from "@mastra/libsql";
const storage = new LibSQLStore({
url: "libsql://your-database.turso.io", // 外部Tursoデータベース
authToken: process.env.TURSO_AUTH_TOKEN,
});
メモリ設定オプションの詳細については、メモリドキュメントを参照してください。
Dockerfileの作成
プロジェクトルートにDockerfileを作成
MastraプロジェクトのルートディレクトリにDockerfile
を作成します:
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY src ./src
RUN npx mastra build
RUN apk add --no-cache gcompat
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.0 /lambda-adapter /opt/extensions/lambda-adapter
RUN addgroup -g 1001 -S nodejs && \
adduser -S mastra -u 1001 && \
chown -R mastra:nodejs /app
USER mastra
ENV PORT=8080
ENV NODE_ENV=production
ENV READINESS_CHECK_PATH="/api"
EXPOSE 8080
CMD ["node", "--import=./.mastra/output/instrumentation.mjs", ".mastra/output/index.mjs"]
ビルドとデプロイ
環境変数を設定する
デプロイメントプロセス用の環境変数を設定します:
export PROJECT_NAME="your-mastra-app"
export AWS_REGION="us-east-1"
export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
Dockerイメージをビルドする
Dockerイメージをローカルでビルドします:
docker build -t "$PROJECT_NAME" .
ECRリポジトリを作成する
Dockerイメージを保存するためのAmazon ECRリポジトリを作成します:
aws ecr create-repository --repository-name "$PROJECT_NAME" --region "$AWS_REGION"
DockerをECRで認証する
Amazon ECRにログインします:
aws ecr get-login-password --region "$AWS_REGION" | docker login --username AWS --password-stdin "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com"
イメージにタグを付けてプッシュする
ECRリポジトリURIでイメージにタグを付けてプッシュします:
docker tag "$PROJECT_NAME":latest "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest
docker push "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$PROJECT_NAME":latest
Lambda関数を作成する
AWSコンソールを使用してLambda関数を作成します:
- AWS Lambda Console に移動します
- Create functionをクリックします
- Container imageを選択します
- 関数を設定します:
- Function name: 関数名(例:
mastra-app
) - Container image URI: Browse imagesをクリックしてECRリポジトリを選択し、
latest
タグを選択します - Architecture: Dockerビルドに一致するアーキテクチャを選択します(通常は
x86_64
)
- Function name: 関数名(例:
Function URLを設定する
外部アクセス用にFunction URLを有効にします:
- Lambda関数の設定で、Configuration > Function URLに移動します
- Create function URLをクリックします
- Auth typeをNONEに設定します(パブリックアクセス用)
- CORS設定を構成します:
- Allow-Origin:
*
(本番環境では自分のドメインに制限) - Allow-Headers:
content-type
- Allow-Methods:
*
(本番環境では監査して制限)
- Allow-Origin:
- Saveをクリックします
環境変数を設定する
Lambda関数の設定で環境変数を追加します:
- Configuration > Environment variablesに移動します
- Mastraアプリケーションに必要な変数を追加します:
OPENAI_API_KEY
: OpenAI APIキー(OpenAIを使用する場合)ANTHROPIC_API_KEY
: Anthropic APIキー(Anthropicを使用する場合)TURSO_AUTH_TOKEN
: Turso認証トークン(TursoでLibSQLを使用する場合)- 必要に応じてその他のプロバイダー固有のAPIキー
関数設定を調整する
関数のメモリとタイムアウト設定を構成します:
- Configuration > General configurationに移動します
- 以下の推奨値を設定します:
- Memory: 512 MB(アプリケーションのニーズに応じて調整)
- Timeout: 30秒(アプリケーションのニーズに応じて調整)
- Ephemeral storage: 512 MB(オプション、一時ファイル用)
デプロイメントのテスト
デプロイ後、Lambda関数をテストします:
- LambdaコンソールからFunction URLをコピーします
- ブラウザでURLにアクセスして、Mastraのサーバーホーム画面を確認します
- 生成されたAPIエンドポイントを使用してエージェントとワークフローをテストします
利用可能なAPIエンドポイントの詳細については、Serverドキュメントを参照してください。
クライアントの接続
Lambda関数URLを使用するようにクライアントアプリケーションを更新します:
import { MastraClient } from "@mastra/client-js";
const mastraClient = new MastraClient({
baseUrl: "https://your-function-url.lambda-url.us-east-1.on.aws",
});
トラブルシューティング
関数タイムアウトエラー
Lambda関数がタイムアウトする場合:
- Configuration > General configurationでタイムアウト値を増やす
- より高速なコールドスタートのためにMastraアプリケーションを最適化する
- 一貫したパフォーマンスのためにプロビジョンド同時実行の使用を検討する
メモリの問題
メモリ関連のエラーが発生した場合:
- Configuration > General configurationでメモリ割り当てを増やす
- CloudWatch Logsでメモリ使用量を監視する
- アプリケーションのメモリ使用量を最適化する
CORSの問題
ホームページではなくエンドポイントにアクセスする際にCORSエラーが発生する場合:
- MastraサーバーコンフィギュレーションでCORSヘッダーが適切に設定されていることを確認する
- Lambda Function URLのCORSコンフィギュレーションを確認する
- クライアントが正しいURLにリクエストを送信していることを確認する
コンテナイメージの問題
Lambda関数の起動に失敗する場合:
- Dockerイメージがローカルで正常にビルドされることを確認する
- DockerfileのCMD命令が正しいことを確認する
- コンテナ起動エラーについてCloudWatch Logsを確認する
- Lambda Web Adapterがコンテナに適切にインストールされていることを確認する
本番環境での考慮事項
本番環境でのデプロイメントについて:
セキュリティ
- CORS originを信頼できるドメインに制限する
- 他のAWSサービスへの安全なアクセスにAWS IAMロールを使用する
- 機密性の高い環境変数をAWS Secrets ManagerまたはParameter Storeに保存する
監視
- Lambda関数のCloudWatch監視を有効にする
- エラーとパフォーマンスメトリクスのCloudWatchアラームを設定する
- 分散トレーシングにAWS X-Rayを使用する
スケーリング
- 予測可能なパフォーマンスのためにプロビジョンド同時実行を設定する
- 同時実行数を監視し、必要に応じて制限を調整する
- より複雑なルーティングニーズにはApplication Load Balancerの使用を検討する