AWSセットアップ手順

この手順では、既存のAWS SAM定義を使って問い合わせフォームの送信環境を構築する。最初は送信を無効にした状態でデプロイし、設定を確認してから検証環境で有効にする。AWSリソースの作成や実メール送信を伴う操作は、以下のコマンドを実行した時点で行われる。本書を追加した段階では実行していない。

WindowsのPowerShell 7を例に、リポジトリのルートから操作する。APIの形式、メール送信、重複管理、停止方法の詳細は構築・運用手順を参照する。

1. SAMとTerraformの選択

今回の構成では、既存のSAM定義を継続して使う。SAMはCloudFormationでAWSリソースを管理し、Lambdaのコードをビルド・パッケージ化して配置する機能も備えている。すでに作成したテンプレートを使えるため、別の定義へ書き直す作業が不要になる。AWS公式資料

Terraformでも同じ構成を管理できる。組織内の標準がTerraformである場合や、AWS以外の基盤も共通の方法で管理する場合には採用を検討できる。一方、このフォームだけのために導入する場合は、状態ファイルの保管・権限・同時更新の制御と、Lambdaコードのビルド・配布方法を追加で決める必要がある。

判断する事項 今回のSAM構成 Terraformを採用する場合
定義 既存のtemplate.yamlを利用 リソース定義を作成・検証する
実環境との対応関係 CloudFormationのスタックで管理 Terraformの状態ファイルで管理
Lambdaコード sam buildとsam deployで配置 ビルド、ZIPなどの成果物、更新検知を設計する
環境の分離 スタック、関数名、設定を分ける 状態と変数、リソース名を分ける
秘密情報 Secrets ManagerのARNを参照 同様にARNだけを参照する設計が可能

Terraformへ秘密情報の実値を渡す設計では、引数やリソースによって状態ファイルに値が残る。sensitiveは主に表示を抑制する指定で、状態への保存を一律に防ぐものではない。採用時は状態へのアクセスを制限し、秘密情報の実値を読み込まずARNだけを管理する方法を優先する。HashiCorp公式資料

SAMとTerraformで同じリソースを並行して更新しない。まだAWSへ構築していない段階なら定義の切替で対応できるが、構築後の移行では、CloudFormationからの管理解除とTerraformへの取り込みを含めた手順が必要になる。

2. 構築前に用意するもの

項目 確認する内容
AWSアカウント 構築先のアカウントID、作業者の認証方法、東京リージョンの利用可否
作業権限 CloudFormation、デプロイ成果物用S3、IAM、Lambda、API Gateway、DynamoDB、Logs、CloudWatch、SNSを作成・更新できる権限
秘密情報の管理権限 Secrets Managerへ登録できる担当者と、対象ARNを確認できる権限
SMTP さくらレンタルサーバーのホスト名、587または465番、ユーザー名、パスワード
メール SMTPで送信を許可されたFrom、固定のTo、管理者通知先
検証用サイト 組織が管理するHTTPSのホスト名と、そこへ静的サイトを配置する方法
Turnstile 検証用・本番用のウィジェット、サイトキー、秘密鍵、許可ホスト名

デプロイ作業者の権限とLambda実行ロールの権限は分ける。前者は基盤を作成するための権限、後者は送信処理を動かすための権限である。Lambdaの実行ロールはテンプレートで定義済みだが、作業者側の権限はAWS管理者と調整する。組織の権限境界やSCPで制限されている場合も、管理者へ確認する。

検証用と本番用では、スタック名、関数名、SMTP・Turnstileのシークレットを分ける。検証用のメール宛先には、試験メールを受信してよいアドレスを指定する。

3. ローカル環境とAWS認証

AWS CLI v2とAWS SAM CLIを、それぞれ公式手順に従ってインストールする。通常のビルドとデプロイではDockerを使用しない。sam localやsam build --use-containerを使う場合に別途用意する。

aws --version
sam --version
node --version
npm --version

作業端末のNode.jsは、Webサイトとバックエンドのテストに合わせて24系を使用する。Lambdaの実行環境はテンプレートでnodejs22.xに固定しており、作業端末の版とは別に管理する。SAMも外部のNode.js・npmを使うため、npm runで動く同梱Node.jsだけに依存せず、作業端末のPATHも確認する。

組織がIAM Identity Centerを使用している場合は、次の例で名前付きプロファイルを設定する。開始URL、SSOリージョン、利用するアカウントとロールはAWS管理者から確認する。Identity Centerを使っていない場合は、組織で指定された認証方法でプロファイルを用意する。AWS公式手順

aws configure sso --profile tectas-dev
aws sso login --profile tectas-dev
aws sts get-caller-identity --profile tectas-dev

最後の出力でアカウントIDとロールを確認する。AWSアカウントのルート認証情報はデプロイに使わず、認証情報をリポジトリへ保存しない。

以降の例では、次の変数を使う。実際の名前は組織の命名規則に合わせる。

$awsProfile = 'tectas-dev'
$awsRegion = 'ap-northeast-1'
$stackName = 'tectas-contact-dev'
$configEnv = 'dev'

4. 秘密情報とTurnstileの準備

AWSコンソールで東京リージョンを開き、Secrets ManagerにSMTP用とTurnstile用のシークレットを作成する。シークレットタイプは「その他のシークレット」を選び、プレーンテキストのJSONとして登録する。名前は、例えばtectas/contact/dev/smtpとtectas/contact/dev/turnstileのように環境を区別する。

JSONの書式は秘密情報の登録手順に従う。SMTPのportは文字列ではなく数値にする。SMTP用にはidempotencyKeyも必要で、暗号学的乱数32バイトを16進数にした64桁の値を設定する。秘密情報の実値は、この文書やSAMパラメーターへ転記しない。

暗号化キーは、現在のテンプレートでは既定のSecrets Manager管理キーを使用する。自動ローテーションを有効にする処理は実装していないため、SMTPとTurnstileの更新は運用手順に沿って行う。登録後に2つのARNを控え、SAMへ渡す。

Turnstileには検証用サイトの実際のホスト名を許可する。ブラウザー用サイトキーとSecrets Managerへ入れた秘密鍵は、同じウィジェットの組み合わせにする。画面から送るactionは実装でcontactに固定している。

実環境のAPIは、指定したHTTPSのAllowedOriginだけを許可する。localhostでAPIへ実送信する前提にはしていない。ローカル画面テストは代替応答で実行し、AWS・SMTPを含む結合試験はHTTPSの検証用サイトで行う。

5. 検証とビルド

npm ci
npm ci --prefix backend/contact-form
npm test --prefix backend/contact-form
npm run check
sam validate --lint --template-file infra/contact-form/template.yaml --region $awsRegion --profile $awsProfile
sam build --template-file infra/contact-form/template.yaml --build-dir .aws-sam/contact-form

ビルド後、.aws-sam/contact-form/template.yamlが生成されていることを確認する。以降のデプロイには、このビルド済みテンプレートを明示して使う。dist/はWebサイト用の成果物で、Lambdaのデプロイには使用しない。

6. 送信を無効にして初回デプロイ

sam deploy --guided --template-file .aws-sam/contact-form/template.yaml --stack-name $stackName --region $awsRegion --profile $awsProfile --config-env $configEnv --config-file ../../.samconfig.local.toml

設定ファイルのパスは、指定したテンプレートの場所を基準にする。上の../../.samconfig.local.tomlはリポジトリ直下を指し、このファイルはGitの追跡対象から除外している。SMTPパスワードなどは保存せず、シークレットのARNだけをパラメーターに指定する。SAM設定ファイルの仕様

対話画面では次の内容を設定する。その他の値はパラメーター一覧に従う。

設定 検証環境の指定
FunctionName tectas-contact-devなど、本番と重複しない名前
AllowedOrigin HTTPSの検証用サイトのオリジン。パスと末尾の/は付けない
MailFrom / MailTo Fromは1件。Toは固定の1件またはカンマ区切りの複数アドレス。guidedの入力欄に一覧を1つの値として指定
SmtpSecretArn / TurnstileSecretArn 検証用に登録したARN
SendingEnabled false
NotificationEmail 通知を受ける管理者のメールアドレス
変更セットの実行前確認 有効にする
IAMロールの作成許可 テンプレート内の権限を確認したうえで許可
APIを認証なしで公開する確認が出た場合 公開フォームの受付として許可。Lambda側で入力とTurnstileを検証する
ロールバックの無効化 無効化しない。失敗時のロールバックを維持
設定の保存 .samconfig.local.tomlのdev環境へ保存

SAMはコード配置用のS3バケットについても案内する。既存の組織管理バケットを使うか、SAMが管理するバケットを使うかを確認する。これはWebサイトの配信用バケットではない。

作成予定の変更セットを確認してから適用する。初回はAPI、Lambda、DynamoDB、ログ、IAMロール、SNS、監視設定などが作成される。SAMのデプロイはCloudFormationを通じて実行される。AWS公式仕様

7. 作成結果と通知の確認

aws cloudformation describe-stacks --stack-name $stackName --region $awsRegion --profile $awsProfile --query 'Stacks[0].Outputs' --output table

出力からContactApiUrl、FunctionName、TableName、LogGroupNameを確認する。CloudFormationがCREATE_COMPLETEまたはUPDATE_COMPLETEになっていること、DynamoDBとログが東京リージョンにあることも確認する。

SNSの購読確認メールが届いたら、管理者が確認リンクを開く。CloudWatchのアラームから参照されるSNSトピックに、確認済みのメール購読があることをコンソールで確認する。

APIへ実際の問い合わせを送る前に、SendingEnabled=falseであることを確認する。この状態では、許可オリジンからのPOSTに503とdependency_errorを返し、SMTPへ接続しない。停止中のアクセスでも障害用のアラームが発報し得るため、初期確認中の通知として区別する。

8. 検証用サイトへの接続と送信有効化

検証用サイトのビルド環境へ、出力されたAPI URLと検証用Turnstileサイトキーを設定する。設定名は次の2つで、秘密鍵は含めない。

PUBLIC_CONTACT_API_URL=https://API-ID.execute-api.ap-northeast-1.amazonaws.com/contact
PUBLIC_TURNSTILE_SITE_KEY=検証用ウィジェットのサイトキー
npm run build:preview

dist-preview/をHTTPSの検証用サイトへ配置する。このビルドは検索エンジン向けにnoindexを出力する。CSPなどを設定している場合は、TurnstileとAPIへの接続を許可する。配置後のURLがAllowedOriginと一致していることを確認する。

設定を確認したら、第6節と同じsam deploy --guidedコマンドを再実行する。保存済みのパラメーターを確認し、SendingEnabledだけをtrueへ変更する。他の値は維持し、変更セットを確認して反映する。単独の--parameter-overrides指定で保存済みパラメーター一式を置き換えないようにする。

検証用サイトから1件投稿し、次を確認する。この操作では実際のメールが送信される。

  • 指定したToに1通届き、投稿者への自動返信がない。
  • From、Reply-To、件名、本文が意図した内容になっている。
  • 画面に送信済みと表示される。
  • DynamoDBに受付状態SENTと時間・日のカウンターが作成され、本文は保存されていない。
  • CloudWatchのログに処理結果が記録され、氏名・メールアドレス・本文・秘密情報が含まれていない。

その他の正常・異常系は受入確認に従う。上限到達などの試験は検証用の低い設定値で実施し、本番の上限を試験のために消費しない。

9. 本番構築と更新

検証が完了したら、AWSプロファイル、$stackName、$configEnvを本番用へ切り替える。関数名、シークレットARN、許可オリジン、From・To、通知先も本番用へ変更する。初回は再びSendingEnabled=falseで構築し、出力と設定を確認してから有効にする。

本番サイトの設定には本番API URLとTurnstileサイトキーを使用する。これらをGitLabのCI/CD変数へ登録し、静的サイトの自動デプロイの手順でタグを作成して配置する。検証用のAPI URLやTurnstileテストキーを本番へ残さない。

コードやテンプレートを更新するときは、第5節のビルド後に次を実行する。ビルド済みテンプレートと設定環境を毎回指定し、意図しないスタックへの更新を避ける。

sam deploy --template-file .aws-sam/contact-form/template.yaml --stack-name $stackName --region $awsRegion --profile $awsProfile --config-env $configEnv --config-file ../../.samconfig.local.toml --confirm-changeset

SMTPアカウントやTurnstileの秘密値を更新する場合は、Secrets Manager側の値を変更する。コード内へ転記しない。idempotencyKeyの扱いとキャッシュ時間は秘密情報の登録手順に従う。

10. 停止・復旧と作業記録

通常停止は対話デプロイでSendingEnabled=falseへ変更する。緊急停止はLambdaの予約済み同時実行数を0にして行うが、開始済みの送信までは取り消せない。コンソールで変更した場合は、後でテンプレートと実環境を一致させる。

デプロイ失敗時はCloudFormationのイベントで失敗したリソースを確認する。権限不足、同名関数の存在、シークレットのリージョン違いなどを調べる。DynamoDBの保持設定があるため、スタックを削除して作り直す前に、既存の受付記録を保持する必要があるかを確認する。

構築後は、アカウントID、リージョン、スタック名、API URL、シークレットARN、通知先、制限値、受入試験の結果と担当者を運用記録へ残す。秘密値は記録しない。料金の予算通知も設定し、通知を設定しても費用の発生が自動停止するわけではないことを共有する。