継続は力なり

タイトル通り定期的な更新を心掛けるブログです。

Nx Plugin for AWS の Quick Start を Terraform で動かしてみたメモ✍

タダです.

AWS のブログで Nx Plugin for AWS の v1.0 が紹介されていました.フルスタックの AWS アプリケーションをジェネレータで組み立てるツールで,インフラを CDK と Terraform のどちらでも生成でき,AI コーディングエージェントから MCP 経由で呼ぶ想定になっているのが気になりました.普段 Terraform を使っているので,ドキュメントの Concepts と Quick Start を Terraform で進めたメモをまとめます.

aws.amazon.com

Nx Plugin for AWS の概要

Nx Plugin for AWS(@aws/nx-plugin)は,モノレポ向けビルドツールの Nx のプラグインとして提供されています.API,Web サイト,認証,AI エージェント,インフラといった部品をそれぞれ Nx のジェネレータとして持っていて,必要なものを 1 コマンドずつワークスペースに追加していく作りです.

Quick Start の実践

ワークスペースの作成

Quick Start の Step 1 です.ドキュメントでは実行時に IaC プロバイダを CDK か Terraform から選ぶプロンプトが出るとありますが,--no-interactive を付けると聞かれずに CDK が既定で選ばれます.Terraform で進めるにはプリセットのオプション --iac=terraform を渡します.

pnpm create @aws/nx-workspace my-project --no-interactive --iac=terraform
cd my-project

私の環境ではワークスペースの作成に 1 分 46 秒かかり,Nx 23.2.0 と @aws/nx-plugin 1.0.0 のワークスペースができました.選んだプロバイダはルートの aws-nx-plugin.config.mts に書き込まれ,以降のジェネレータはここを見て CDK か Terraform かを切り替えます.

import { AwsNxPluginConfig } from '@aws/nx-plugin';

export default {
  iac: { provider: 'terraform' },
  containers: { engine: 'docker' },
  packageManager: { catalogs: true },
} satisfies AwsNxPluginConfig;

また MCP サーバーの設定は最初から入っています.ルートに .mcp.json があり,Claude Code 向けに @aws/nx-plugin-mcp を npx で起動する設定になっていました.

{
  "mcpServers": {
    "nx-plugin-for-aws": {
      "command": "npx",
      "args": ["-y", "@aws/nx-plugin-mcp"]
    }
  }
}

ワークスペースを開いた AI エージェントが,追加の設定なしでジェネレータを探して実行できるようにしてある形です.

ジェネレータでアプリケーションを組み立てる

Step 2 は tRPC API,React の Web サイト,Cognito 認証,Web サイトと API の接続,インフラプロジェクトの 5 つを順に生成します.インフラのジェネレータだけ CDK と Terraform で分かれていて,Terraform は terraform#project です.AI エージェントに自然言語で頼む方法も用意されていますが,今回は何が生成されるかを見たかったので CLI で 1 つずつ実行しました.

$ pnpm nx g '@aws/nx-plugin:ts#api' --no-interactive --name=demo-api
$ pnpm nx g '@aws/nx-plugin:ts#website' --no-interactive --name=demo-website
$ pnpm nx g '@aws/nx-plugin:ts#website#auth' --no-interactive --project=demo-website
$ pnpm nx g '@aws/nx-plugin:connection' --no-interactive --sourceProject=demo-website --targetProject=demo-api
$ pnpm nx g '@aws/nx-plugin:terraform#project' --no-interactive --name=infra

ローカルで動かす

Step 3 は Web サイトから API を呼ぶ処理を足してローカルで確認する手順です.ドキュメントの差分通りに packages/demo-website/src/routes/index.tsx を書き換え,useDemoApi フックから echo プロシージャを呼ぶようにしました.

const trpc = useDemoApi();
const echo = useQuery(
  trpc.echo.queryOptions({ message: 'Hello from the API!' }),
);

pnpm dev を実行すると,tRPC のローカルサーバーが 2022 番ポート,Vite が 4200 番ポートで立ち上がります.API 単体を curl で叩くと,そのまま返ってきました.

$ curl "http://localhost:2022/echo?input=%7B%22message%22%3A%22Hello%20from%20curl%22%7D"
{"result":{"data":{"message":"Hello from curl"}}}

ブラウザで http://localhost:4200 を開くと,Welcome の下に API から返った「Hello from the API!」が表示されました.認証を付けているのにサインイン画面が出なかったのは,CognitoAuth コンポーネントが local-dev モードで Cognito の設定が無いときはログインを飛ばす作りになっているためです.

demo-website のトップページに Welcome と API から返った Hello from the API! が表示されている

Terraform でインフラを定義する

Step 4 は packages/infra/src/main.tf に生成済みのモジュールを並べる手順です.ドキュメントに載っている Terraform の定義が以下です.

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# Deploy website
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

構成を読み解くと,user_identity が Cognito のユーザープールと ID プール,asset_bucket が Lambda のデプロイ用 zip を置く S3 バケットで,demo_api はそのバケット名を受け取って API Gateway と Lambda を作ります.API Gateway の認可は IAM なので,ID プールの認証済みロールに execute-api:Invoke を許可する IAM ポリシーを自分で書いて紐づける形です.demo_website に us-east-1 のプロバイダエイリアスを渡しているのは,CloudFront に付ける WAF の WebACL がバージニア北部にしか作れないためです.東京リージョンにデプロイする場合でも,この 1 モジュールだけはリージョンをまたぐ点は押さえておくとよいです.

ビルドとデプロイ

pnpm build で lint,compile,test をまとめて回します.私の環境では最初 The workspace is out of sync で止まりました.ドキュメントにも注記がある通り,pnpm nx sync で TypeScript のプロジェクト参照と package.json の依存を書き出してから再実行すると通ります.

デプロイの前に,Terraform のステートを置く S3 バケットを作ります.

$ pnpm nx bootstrap infra

これは AWS アカウントとリージョンの組み合わせごとに 1 回だけ実行する初期設定です.続けて apply ターゲットを実行すると,terraform plan の結果を表示してから terraform apply が走ります.

$ pnpm nx apply infra

デプロイ後にローカルの Web サイトからデプロイ済みの API と Cognito を使うには,runtime-config.json を取得してから起動します.

$ pnpm nx load-runtime-config demo-website
$ pnpm nx serve demo-website

サインインには Cognito のユーザープールにユーザーを作る必要があり,ドキュメントでは aws cognito-idp admin-create-user で作成する手順が載っています.初回サインイン時にパスワード変更と MFA の設定を求められるので,検証用でも MFA の方法を決めておく必要があります.

後片付けは pnpm nx destroy infra です.ただし Cognito のユーザープールは削除保護が有効な状態で作られるため,destroy は失敗として報告され,ユーザープールと SMS 送信用の IAM ロールは手動で消す必要があるとドキュメントに書かれています.検証で作って消す運用なら,apply の前に削除保護の扱いを決めておくのが良さそうです.

まとめ

Nx Plugin for AWS の Quick Start を Terraform で進め,ローカル起動と型の共有まで手元で確認しました.API のジェネレータが Terraform モジュールまで一緒に生成してくれるので,次は apply でデプロイまで通してから,MCP 経由で AI エージェントにジェネレータを叩かせる使い方を試してみようと思います.