AWS 『Kiro』 SPECモードを使って、1時間で消えるWordPressのサービス『SnapSandbox』を作った

1# 要件定義書
2
3## 概要
4
5SnapSandboxは、ユーザーが一時的なWordPress環境を素早く起動できるTerraformベースのPoC（概念実証）サービスです。ユーザーはフロントエンドインターフェースからPHP/WordPressバージョンを選択し、数分以内に完全に機能するWordPressインスタンスを取得できます。サンドボックス環境は1時間後に自動終了し、リソース効率を確保します。インフラ全体はTerraformでコード管理され、再現性と保守性を実現します。
6
7## 要件
8
9### 要件 1
10
11**ユーザーストーリー:** 開発者として、Webインターフェースから一時的なWordPressサンドボックスを作成したい。自分で環境を構築することなく、WordPressの機能を素早くテストできるようにするため。
12
13#### 受入基準
14
151. ユーザーが https://app.seeds-wordpress.click にアクセスした時、システムはPHPバージョン（8.3固定）とWordPressバージョンオプション（5.4、6.x）を含む作成フォームを表示する
162. ユーザーが作成フォームを送信した時、システムは3分以内にサンドボックスIDとドメインURLを返す
173. サンドボックスが作成された時、システムは https://sbx-<id>.seeds-wordpress.click でアクセスを提供する
184. サンドボックスが作成された時、システムはWordPress管理者認証情報（ユーザー名とパスワード）を提供する
19
20### 要件 2
21
22**ユーザーストーリー:** ユーザーとして、ダッシュボードでアクティブなサンドボックスをすべて表示したい。一時的な環境を管理しアクセスできるようにするため。
23
24#### 受入基準
25
261. ユーザーがフロントエンドにアクセスした時、システムはアクティブなサンドボックスのリストを表示する
272. サンドボックスリストを表示する時、システムはサンドボックスID、ドメインURL、WordPressバージョン、PHPバージョン、管理URL、管理者認証情報、ステータス、終了時刻を表示する
283. サンドボックスステータスを表示する時、システムは次のいずれかを表示する：Starting、Ready、Stopped、Error
294. 終了時刻を表示する時、システムはカウントダウンで残り時間を表示する
305. サンドボックスリストが表示される時、システムはAPIポーリングにより5〜10秒ごとに更新する
31
32### 要件 3
33
34**ユーザーストーリー:** システム管理者として、サンドボックスが設定可能な時間後に自動終了するようにしたい。未使用の環境でリソースが無駄にならないようにするため。
35
36#### 受入基準
37
381. サンドボックスが作成された時、システムは設定ファイルで定義された時間（デフォルト1時間）後の自動終了をスケジュールする
392. 設定された時間が経過した時、システムは自動的にサンドボックスを停止する
403. サンドボックスが停止された時、システムはドメインURL経由でのアクセスを不可能にする
414. サンドボックスが停止された時、システムはステータスを「Stopped」に更新する
425. 自動終了時間は設定ファイルで変更可能である
43
44### 要件 4
45
46**ユーザーストーリー:** ユーザーとして、期限前にサンドボックスを手動で停止したい。テストが完了した時にリソースを解放できるようにするため。
47
48#### 受入基準
49
501. ユーザーがサンドボックスの停止ボタンをクリックした時、システムは即座に終了プロセスを開始する
512. 手動停止が要求された時、システムはサンドボックスステータスを「Stopped」に更新する
523. 手動停止が完了した時、システムはサンドボックスをアクセス不可能にする
53
54### 要件 5
55
56**ユーザーストーリー:** 開発者として、インフラをTerraformを使用してコードで管理したい。システムが再現可能で保守可能になるようにするため。
57
58#### 受入基準
59
601. システムをデプロイする時、すべてのAWSリソースはTerraformコードで定義される
612. インフラの変更が必要な時、Terraform設定の更新を通じて行われる
623. デプロイする時、システムはVPC、サブネット、セキュリティグループ、ALB、ECSクラスター、および必要なすべてのAWSサービスを作成する
634. デプロイする時、システムはTLS終端のためのRoute53 DNSとACM証明書を設定する
64
65### 要件 6
66
67**ユーザーストーリー:** システムとして、サンドボックスインスタンスへのトラフィックを効率的にルーティングしたい。ユーザーがWordPress環境に確実にアクセスできるようにするため。
68
69#### 受入基準
70
711. サンドボックスが作成された時、システムは10秒以内にTraefikルーティングを設定する
722. *.seeds-wordpress.click にトラフィックが到着した時、ALBはTLSを終端してTraefikに転送する
733. Traefikがリクエストを受信した時、Hostヘッダーに基づいて適切なWordPressコンテナにルーティングする
744. ルーティング設定が変更された時、Traefikは5秒ごとにS3から同期する
75
76### 要件 7
77
78**ユーザーストーリー:** システムとして、サンドボックス管理のためのRESTful APIを提供したい。フロントエンドがサンドボックスのライフサイクル操作と連携できるようにするため。
79
80#### 受入基準
81
821. PHPとWordPressバージョンでPOST /sandboxが呼び出された時、システムは新しいサンドボックスを作成してサンドボックス詳細を返す
832. GET /sandboxesが呼び出された時、システムはアクティブなサンドボックスのリスト（最大50）を返す
843. GET /sandbox/{id}が呼び出された時、システムは特定のサンドボックスの詳細を返す
854. DELETE /sandbox/{id}が呼び出された時、システムはサンドボックス終了を開始する
865. API呼び出しが行われた時、レスポンスはサンドボックスID、ドメイン、管理URL、認証情報、ステータス、終了時刻を含む
87
88### 要件 8
89
90**ユーザーストーリー:** システムとして、サンドボックスの状態とメタデータを永続化したい。サンドボックスのライフサイクルを追跡・管理できるようにするため。
91
92#### 受入基準
93
941. サンドボックスが作成された時、システムはsandboxIdを主キーとしてDynamoDBにメタデータを保存する
952. サンドボックスデータを保存する時、システムはPHPバージョン、アプリタイプ、WordPressバージョン、ドメイン、タスクARN、IP、ステータス、管理者認証情報、作成時刻、終了時刻を含む
963. サンドボックスを照会する時、システムはGSIを使用してステータスによるフィルタリングをサポートする
974. 管理者パスワードを保存する時、システムはそれらを暗号化する（PoCでは、APIは復号化された値を返すことができる）
98
99### 要件 9
100
101**ユーザーストーリー:** システムとして、コンテナ化された環境でWordPressを実行したい。サンドボックスが分離され、リソース効率的になるようにするため。
102
103#### 受入基準
104
1051. サンドボックスが要求された時、システムはECS RunTaskを使用してWordPressコンテナを開始する
1062. コンテナを開始する時、システムはPHPバージョンに基づいてイメージURI（php83-runtime）をオーバーライドする
1073. コンテナが開始する時、nginx、php-fpm、wp-cli、ローカルMariaDB/SQLiteを含む
1084. コンテナが実行される時、WordPressとデータベースは非永続的である（終了時にデータが失われる）
1095. コンテナが開始する時、環境変数を通じてWordPress管理者ユーザーとパスワードを設定する
110
111### 要件 10
112
113**ユーザーストーリー:** システム管理者として、監視とエラーハンドリングを行いたい。システムの信頼性を確保し、問題をトラブルシューティングできるようにするため。
114
115#### 受入基準
116
1171. システムが動作する時、ALB 5xxエラー、Traefik 4xx/5xxエラー、RunTask失敗、Lambda失敗、S3同期エラーを監視する
1182. エラーが発生した時、CloudWatch Logsにログが記録される
1193. サンドボックス作成が失敗した時、システムはステータスを「Error」に更新する
1204. 設定ファイルで定義された最大同時サンドボックス数（デフォルト3-5）に達した時、新しいリクエストは適切なエラーメッセージで拒否される
1215. 最大同時サンドボックス数は設定ファイルで変更可能である
122#
123## 要件 11
124
125**ユーザーストーリー:** システム管理者として、システムの動作パラメータを設定ファイルで管理したい。運用環境に応じて柔軟に設定を変更できるようにするため。
126
127#### 受入基準
128
1291. システムが起動する時、設定ファイルから自動終了時間を読み込む
1302. システムが起動する時、設定ファイルから最大同時サンドボックス数を読み込む
1313. 設定ファイルが変更された時、システムは再起動なしに新しい設定を適用する
1324. 設定ファイルには以下のパラメータが含まれる：
133   - サンドボックス自動終了時間（分単位）
134   - 最大同時サンドボックス数
135   - その他の運用パラメータ
1365. 設定ファイルが存在しない場合、システムはデフォルト値を使用する

1# 設計書
2
3## 概要
4
5SnapSandboxは、Terraformで管理されるAWSインフラ上で動作する一時的なWordPress環境提供サービスです。ユーザーはWebインターフェースから簡単にWordPressサンドボックスを作成でき、設定可能な時間後に自動終了します。システムは高可用性、スケーラビリティ、セキュリティを考慮した設計となっています。
6
7## アーキテクチャ
8
9### システム全体図
10
11```mermaid
12graph TB
13    User[ユーザー] --> S3[S3 Static Website]
14    User --> ALB[Application Load Balancer]
15    
16    S3 --> APIGW[API Gateway]
17    ALB --> Traefik[Traefik Service]
18    
19    APIGW --> CreateLambda[Create Sandbox Lambda]
20    APIGW --> ListLambda[List Sandboxes Lambda]
21    APIGW --> StopLambda[Stop Sandbox Lambda]
22    
23    CreateLambda --> DDB[DynamoDB]
24    CreateLambda --> ECS[ECS RunTask]
25    CreateLambda --> EventBridge[EventBridge Scheduler]
26    
27    ListLambda --> DDB
28    StopLambda --> DDB
29    StopLambda --> ECS
30    
31    EventBridge --> StopLambda
32    
33    Traefik --> S3Config[S3 Dynamic Config]
34    
35    subgraph "AWS VPC"
36        subgraph "ECS Cluster"
37            Traefik[Traefik Service<br/>固定サービス]
38            WPTasks[WordPress Tasks<br/>動的RunTask]
39        end
40        ALB
41    end
42    
43    Traefik -.-> WPTasks
44```
45
46### ネットワーク設計
47
48- **VPC**: 専用VPC（10.0.0.0/16）
49- **パブリックサブネット**: ALB用（10.0.1.0/24, 10.0.2.0/24）
50- **プライベートサブネット**: ECSクラスター用（10.0.10.0/24, 10.0.20.0/24）
51  - Traefikサービス（固定）
52  - WordPressタスク（動的RunTask）
53- **NAT Gateway**: プライベートサブネットからのインターネットアクセス用
54- **Internet Gateway**: パブリックサブネット用
55
56**ECSクラスター構成**:
57- 単一ECSクラスター内で全コンテナが動作
58- Traefikは固定サービス（desired count: 1）
59- WordPressは動的タスク（RunTaskで起動）
60- 同一VPC・サブネット内でコンテナ間通信
61
62(以下、lambdaやフロントjsの参考実装コードなどが続く)

1# 実装計画
2
3- [x] 1. プロジェクト構造とTerraformベースインフラの構築
4  - プロジェクトディレクトリ構造を作成し、Terraformモジュール分割を実装する
5  - VPC、サブネット、セキュリティグループ、ALBなどの基本ネットワークインフラを定義する
6  - _要件: 5.1, 5.3, 6.2_
7
8- [x] 2. DynamoDBテーブルとIAMロールの実装
9  - サンドボックス状態管理用のDynamoDBテーブルをTerraformで定義する
10  - Lambda実行ロール、ECSタスクロール、ECS実行ロールを最小権限で作成する
11  - _要件: 8.1, 8.2, 8.3, 10.2_
12
13- [x] 3. WordPressコンテナイメージの作成
14  - Apache + PHP + MariaDB + wp-cli + SSM Agentを含むDockerfileを実装する
15  - wp-entrypoint.shスクリプトでWordPress自動セットアップを実装する
16  - _要件: 9.1, 9.2, 9.3, 9.4, 9.5_
17
18- [x] 4. Traefikコンテナとルーティング設定の実装
19  - TraefikコンテナイメージとS3動的設定同期サイドカーを作成する
20  - ECSサービスとしてTraefikを定義し、ALBとの連携を設定する
21  - _要件: 6.1, 6.3, 6.4_
22
23- [x] 5. ECSクラスターとタスク定義の作成
24  - ECSクラスター、WordPressタスク定義、Traefikタスク定義をTerraformで実装する
25  - ECS Exec有効化とSSM権限を設定する
26  - _要件: 5.3, 9.1, 9.2_
27
28- [x] 6. Create Sandbox Lambda関数の実装
29  - サンドボックス作成ロジック（ID生成、DynamoDB書き込み、ECS RunTask実行）を実装する
30  - Traefik設定ファイルのS3更新とEventBridge Schedulerの設定を実装する
31  - _要件: 1.1, 1.2, 1.3, 1.4, 7.1, 8.1, 9.1_
32
33- [x] 7. Stop Sandbox Lambda関数の実装
34  - サンドボックス停止ロジック（ECSタスク停止、DynamoDB更新、Traefik設定削除）を実装する
35  - EventBridge Schedulerからの自動呼び出しと手動停止の両方に対応する
36  - _要件: 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 7.4_
37
38- [x] 8. List Sandboxes Lambda関数の実装
39  - DynamoDB GSIを使用したアクティブサンドボックス一覧取得を実装する
40  - サンドボックス詳細情報の取得APIを実装する
41  - _要件: 2.1, 2.2, 7.2, 7.3, 8.3_
42
43- [x] 9. API GatewayとLambda統合の設定
44  - HTTP API GatewayでRESTfulエンドポイントを定義する
45  - CORS設定とエラーハンドリングを実装する
46  - _要件: 7.1, 7.2, 7.3, 7.4, 7.5_
47
48- [x] 10. 設定管理システムの実装
49  - 設定ファイル読み込み機能をLambda関数に実装する
50  - 自動終了時間と最大同時サンドボックス数の設定可能化を実装する
51  - _要件: 11.1, 11.2, 11.4, 11.5_
52
53- [x] 11. フロントエンドWebアプリケーションの実装
54  - サンドボックス作成フォームとバリデーションを実装する
55  - アクティブサンドボックス一覧表示とリアルタイム更新を実装する
56  - _要件: 1.1, 2.1, 2.2, 2.3, 2.4, 2.5_
57
58- [x] 12. S3静的ウェブサイトホスティングの設定
59  - S3バケット、ウェブサイト設定、パブリックアクセス設定をTerraformで実装する
60  - フロントエンド設定ファイル（config.json）の自動生成を実装する
61  - _要件: 1.1, 2.5_
62
63- [x] 13. Route53 DNSとACM証明書の設定
64  - ドメイン変数化とワイルドカード証明書の自動取得を実装する
65  - ALBとS3ウェブサイトへのDNSルーティングを設定する
66  - _要件: 5.4, 6.2_
67
68- [x] 14. EventBridge Schedulerによる自動終了機能の実装
69  - サンドボックス作成時の自動終了スケジュール設定を実装する
70  - 設定可能な終了時間に基づくスケジューラー管理を実装する
71  - _要件: 3.1, 3.2, 11.1, 11.5_
72
73- [x] 15. デプロイスクリプトとビルドプロセスの作成
74  - ECRリポジトリ作成、Dockerイメージビルド・プッシュスクリプトを実装する
75  - Lambdaパッケージング、Terraform実行、フロントエンドデプロイの自動化を実装する
76  - _要件: 5.1, 5.2_
77
78- [x] 16. エラーハンドリングと監視の実装
79  - Lambda関数のエラーハンドリングとCloudWatchログ出力を実装する
80  - 同時実行数制限とリソース制限のチェック機能を実装する
81  - _要件: 10.1, 10.3, 10.4, 10.5_
82
83- [x] 17. 統合テストとデプロイ検証の実装
84  - サンドボックス作成から停止までの完全フローテストを実装する
85  - デプロイスクリプトの動作確認とトラブルシューティングガイドを作成する
86  - _要件: 1.2, 2.5, 3.2, 4.1_

1# 技術スタック
2
3## インフラストラクチャ
4- **クラウドプロバイダー**: AWS (ap-northeast-1 リージョン)
5- **Infrastructure as Code**: Terraform (>= 1.0)
6- **コンテナオーケストレーション**: ECS Fargate
7- **ロードバランシング**: Application Load Balancer (ALB) + Traefikリバースプロキシ
8- **DNS & TLS**: Route53 + ACM証明書
9
10## バックエンドサービス
11- **API**: AWS API Gateway (HTTP API) + Lambda関数
12- **ランタイム**: Lambda関数用Python 3.11
13- **データベース**: DynamoDB (従量課金)
14- **ストレージ**: S3 (静的ウェブサイトホスティング、設定保存)
15- **スケジューリング**: 自動終了用EventBridge Scheduler
16
17## コンテナスタック
18- **WordPress**: Apache + PHP 8.3 + MariaDB + wp-cliのカスタムDockerイメージ
19- **リバースプロキシ**: S3ベース動的設定のTraefik
20- **ベースイメージ**: 公式PHPとTraefikイメージ
21
22## フロントエンド
23- **技術**: Vanilla JavaScript、HTML5、CSS3
24- **ホスティング**: S3静的ウェブサイト（コスト最適化のためCloudFrontなし）
25- **API通信**: 5-10秒ポーリングのFetch API
26
27## 開発ツール
28- **コンテナ化**: Docker
29- **AWS CLI**: バージョン2.0以上
30- **パッケージ管理**: pip (Python)、npm (フロントエンド用オプション)
31
32## 共通コマンド
33
34### 初期セットアップ
35```bash
36# 設定ファイルのコピーと設定
37cp config/aws-config.example config/aws-config
38cp config/terraform.tfvars.example config/terraform.tfvars
39
40# AWS認証情報の設定
41source config/aws-config
42aws sts get-caller-identity  # 認証情報の確認
43```
44
45### ビルドとデプロイ
46```bash
47# 完全デプロイ（開発環境）
48./scripts/deploy.sh dev
49
50# Dockerイメージのみビルド
51./scripts/build-docker.sh
52
53# フロントエンドのみデプロイ
54./scripts/upload-frontend.sh <bucket-name> <api-url>
55```
56
57### Terraform操作
58```bash
59cd terraform
60terraform init
61terraform plan -var-file="../config/terraform.tfvars"
62terraform apply -var-file="../config/terraform.tfvars"
63terraform destroy -var-file="../config/terraform.tfvars"
64```
65
66### Docker操作
67```bash
68# WordPressイメージビルド
69docker build -t wordpress-sandbox:latest docker/wordpress/
70
71# Traefikイメージビルド
72docker build -t traefik-proxy:latest docker/traefik/
73
74# ECRログイン
75aws ecr get-login-password --region ap-northeast-1 | docker login --username AWS --password-stdin <account>.dkr.ecr.ap-northeast-1.amazonaws.com
76```
77
78### Lambda開発
79```bash
80# Lambda関数のパッケージング
81cd lambda/create-sandbox/
82pip install -r requirements.txt -t .
83zip -r ../create-sandbox.zip . -x "*.pyc" "__pycache__/*"
84```
85
86### デバッグと監視
87```bash
88# CloudWatchログの表示
89aws logs tail /aws/lambda/create-sandbox --follow
90
91# コンテナへのECS Exec
92aws ecs execute-command --cluster snapsandbox-cluster --task <task-arn> --container wordpress --interactive --command "/bin/bash"
93
94# ECSサービスステータス確認
95aws ecs describe-services --cluster snapsandbox-cluster --services traefik
96```
97
98## リソースサイジング（コスト最適化）
99- **Lambda**: 128MBメモリ、30秒タイムアウト
100- **ECSタスク**: 256 CPU (0.25 vCPU)、512MBメモリ
101- **DynamoDB**: オンデマンド課金モード
102- **最大同時サンドボックス数**: 5（設定可能）