# AWS Marketplace クイックスタート

AWS Marketplace から AGENTIC STAR を購入し、デプロイが完了するまでの手順を解説します。サブスクライブ後、AWS CloudFormation コンソールでパラメータを入力してスタックを作成すると、VPC・EKS・RDS・S3 等のインフラ構築から Kubernetes 上のアプリケーションインストールまで、ネストされた CloudFormation テンプレートにより自動的に行われます。

## 前提条件

- AWS アカウント
- 以下の AWS リソースを CloudFormation で作成・管理できる IAM 権限
  <!-- -->
  - EKS、EC2、VPC、IAM、RDS、S3、CloudFormation、Bedrock
- **EC2 vCPU クォータの確保**（下記を参照）
- **Bedrock Guardrails サポート対象リージョンの選択と、Bedrock モデルアクセスの事前申請**（下記を参照）
- **Service-linked Role の事前作成**（下記を参照、未作成でも初回デプロイ時に自動作成される）
- デプロイ完了後にクラスタへ接続するため、ローカルに `kubectl` および AWS CLI v2 がインストール済みであること

### Bedrock Guardrails（`SecurityRegion` パラメータ）

本プロダクトはコンテンツセーフティと PII 検出のために **Amazon Bedrock Guardrails + Amazon Comprehend** を利用します。CloudFormation の `SecurityRegion` パラメータ（デフォルト `ap-northeast-1`）がこれらの実行リージョンを決定し、メインインフラ（EKS / RDS）のリージョンとは独立して指定できます。データレジデンシー要件に合わせて、同じ地理的範囲内のリージョンを選んでください。

#### `SecurityRegion` のサポート対象リージョン

CloudFormation テンプレート (`main-template.yaml`) の `AllowedValues` で次の 12 リージョンに限定されています。

`ap-northeast-1` (Tokyo) / `ap-northeast-2` (Seoul) / `ap-south-1` (Mumbai) / `ap-southeast-1` (Singapore) / `ap-southeast-2` (Sydney) / `us-east-1` (N. Virginia) / `us-east-2` (Ohio) / `us-west-2` (Oregon) / `ca-central-1` (Canada Central) / `eu-central-1` (Frankfurt) / `eu-west-1` (Ireland) / `eu-west-2` (London)

#### Bedrock モデルアクセスの事前申請

`SecurityRegion` の AWS Console で **Bedrock → Model access** に移動し、Guardrails が利用する基盤モデル（最低限 **Anthropic Claude** ファミリー）のアクセスをリクエストしてください。承認は通常、数分〜数時間で完了します。

#### 利用可否の事前確認

```bash
# Bedrock の応答確認
aws bedrock list-foundation-models --region ap-northeast-1 --max-results 1

# Comprehend の応答確認
aws comprehend list-endpoints --region ap-northeast-1
```

どちらもエラー無く JSON を返すことを確認してからデプロイを開始してください。

### Service-linked Role の事前作成

以下の Service-linked Role は初回利用時に自動作成されますが、事前作成しておくと初回デプロイの待ち時間を短縮できます。既に存在する場合は `Already exists` と表示されますが、無視して問題ありません。

```bash
aws iam create-service-linked-role --aws-service-name eks.amazonaws.com         || true
aws iam create-service-linked-role --aws-service-name rds.amazonaws.com         || true
aws iam create-service-linked-role --aws-service-name elasticloadbalancing.amazonaws.com || true
```

### EC2 vCPU クォータ

EKS のノードは、アカウントのリージョンごとの EC2 vCPU クォータ（Service Quotas の **Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances**）の範囲でしか起動しません。クォータが足りないとノードグループの作成やノードの追加が失敗し、スタックの作成は長い時間がたってから失敗します。新しいアカウントではこのクォータの既定値が小さいことがあるため、デプロイを始める前にデプロイ先のリージョンで次の量を確保してください。

| クォータ                                                                 | 必要量                                                                                          |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances** | 最低 16、推奨 32（既定の `m5.2xlarge`（8 vCPU）× System 1 台 + User 1 台 = 16 vCPU。推奨値はオートスケーラーが 2 台足せる分） |

- 必要量はアプリケーション一式の導入に要する分です（CPU 要求の合計は約 8 vCPU。これに DaemonSet がノード 1 台あたり約 0.6 vCPU 加わります）。エージェントの実行が増えるとオートスケーラーがノードを足すため（既定の上限は System 8 台 + User 10 台）、運用規模に応じて余裕を持たせてください
- EKS Advanced Settings で選べるインスタンスタイプ（`t3.*` / `m5.*`）はすべてこのクォータの対象です。ノード数やインスタンスタイプを変える場合は、合計の vCPU に合わせて確保してください
- RDS for PostgreSQL はこのクォータを消費しません

#### クォータの確認

```bash
# デプロイ先リージョンの上限を表示（例: バージニア北部）
aws service-quotas get-service-quota --service-code ec2 \
  --quota-code L-1216C47A --region us-east-1 \
  --query 'Quota.[QuotaName,Value]' --output table
```

現在の使用量は、AWS コンソールの **Service Quotas** → **Amazon Elastic Compute Cloud (Amazon EC2)** → 該当クォータの「使用率」で確認できます。上限から使用量を引いた空きが必要量以上であることを確認します。

#### クォータの引き上げ

同じ画面の **「アカウントレベルでの引き上げをリクエスト」** から新しい上限を申請します。CLI では次のように申請できます。承認には時間がかかることがあるため、デプロイの前に済ませておいてください。

```bash
aws service-quotas request-service-quota-increase --service-code ec2 \
  --quota-code L-1216C47A --desired-value 32 --region us-east-1
```

## 手順

### 1. AWS Marketplace で AGENTIC STAR Advanced をサブスクライブ

[AWS Marketplace](https://aws.amazon.com/marketplace) で「AGENTIC STAR Advanced」を検索し、**\[Continue to Subscribe]** をクリックします。利用規約に同意すると **\[Continue to Configuration]** が表示されます。

### 2. 配信方法とリージョンを選択

**\[Continue to Configuration]** をクリックし、以下を選択します。

| 項目                   | 値                   |
| -------------------- | ------------------- |
| **Delivery Method**  | CloudFormation      |
| **Software Version** | 最新版を選択              |
| **Region**           | デプロイ先のリージョン（前提条件参照） |

選択後、**\[Continue to Launch]** をクリックします。

### 3. CloudFormation の起動

**Launch this software** ページで、Choose Action から **「Launch CloudFormation」** を選択し、**\[Launch]** をクリックします。AWS CloudFormation コンソールに自動遷移し、`main-template.yaml` がプリロードされた状態で開きます。

> **注記**
>
> `Amazon EC2 Image ID` （`ImageId` パラメータ）は AWS Marketplace が自動的に設定します。**変更しないでください。** また、`MPS3BucketName` / `MPS3BucketRegion` / `MPS3KeyPrefix` の 3 つのパラメータも AWS Marketplace が自動的に設定するため、変更しないでください。

### 4. スタック名の設定

| 項目             | 説明                                 |
| -------------- | ---------------------------------- |
| **Stack name** | CloudFormation スタックの識別名（リージョン内で一意） |

### 5. General Settings（一般設定）

| パラメータ                      | 説明                       | デフォルト値        | 制約                                                                                                                 |
| -------------------------- | ------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Environment Name**       | 環境の識別名（リソース名のプレフィックスに使用） | `agenticstar` | 3〜21文字、先頭は小文字、小文字英数字とハイフン                                                                                          |
| **Administrator Email**    | 初期管理者のメールアドレス            | —             | 有効なメールアドレス形式（最大 254 文字）                                                                                            |
| **Administrator Password** | 初期管理者のパスワード              | —             | 12〜128文字、大文字・小文字・数字・特殊文字を各1文字以上含む。特殊文字は `@$!%*?&` だけ使える                                                            |
| **Primary Language**       | UI の表示言語                 | `ja`          | `ja` / `en` / `fr` / `es` / `th` / `ar` / `id` / `zh-Hans` / `zh-Hant` / `pt-BR` / `de-DE` / `it-IT` / `vi` / `ko` |

### 6. PostgreSQL Settings（データベース設定）

| パラメータ                                               | 説明              | デフォルト値           | 制約                                               |
| --------------------------------------------------- | --------------- | ---------------- | ------------------------------------------------ |
| **PostgreSQL Instance Identifier**                  | RDS インスタンスの識別子  | `marketplace-db` | 1〜63文字                                           |
| **PostgreSQL Instance Class (default recommended)** | RDS のインスタンスクラス  | `db.m5.large`    | `db.m5.large` / `db.m5.xlarge` / `db.m5.2xlarge` |
| **PostgreSQL Multi-AZ Deployment**                  | Multi-AZ 配置にするか | `false`          | `true` / `false`                                 |
| **PostgreSQL Admin Username**                       | DB 管理者ユーザー名     | `db_admin`       | 1〜16文字                                           |
| **PostgreSQL Admin Password**                       | DB 管理者パスワード     | —                | 8〜128文字。`/` `@` `"` `スペース` は使用不可                 |

> **備考**
>
> DB エンジン（PostgreSQL 16.10）とストレージ（32 GiB から最大 500 GiB へ自動拡張）はテンプレート内で固定設定されています。

### 7. EKS Advanced Settings（EKS 詳細設定）

System Node Group と User Node Group の 2 種類のマネージドノードグループを構成します。

**System Pool（システムノードグループ）**

| パラメータ                           | デフォルト値       | 範囲 / 選択肢                                                                          |
| ------------------------------- | ------------ | --------------------------------------------------------------------------------- |
| System Pool VM Size             | `m5.2xlarge` | `t3.medium` / `t3.large` / `m5.large` / `m5.xlarge` / `m5.2xlarge` / `m5.4xlarge` |
| System Pool Node Count（Desired） | 1            | 1〜20                                                                              |
| System Pool Min Count           | 1            | 1〜20                                                                              |
| System Pool Max Count           | 8            | 1〜20                                                                              |

**User Pool（ユーザーノードグループ）**

| パラメータ                         | デフォルト値       | 範囲 / 選択肢                                                                          |
| ----------------------------- | ------------ | --------------------------------------------------------------------------------- |
| User Pool VM Size             | `m5.2xlarge` | `t3.medium` / `t3.large` / `m5.large` / `m5.xlarge` / `m5.2xlarge` / `m5.4xlarge` |
| User Pool Node Count（Desired） | 1            | 1〜20                                                                              |
| User Pool Min Count           | 1            | 1〜20                                                                              |
| User Pool Max Count           | 10           | 1〜20                                                                              |

> **注意**
>
> 既定（`m5.2xlarge` × System 1 台 + User 1 台）はアプリケーション一式を導入する最小構成です。インスタンスタイプを小さくすると、リソース不足が発生する可能性があります。ノード数とインスタンスタイプを変える場合は、[EC2 vCPU クォータ](#vcpu-quota)も合わせて確保してください。

### 8. Datadog Settings（オプション）

Datadog 連携を利用する場合に設定します。

| パラメータ                          | 説明                                 | デフォルト値              | 選択肢                                                                                                |
| ------------------------------ | ---------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| **Enable Datadog Integration** | Datadog 連携の有効化                     | `false`             | `true` / `false`                                                                                   |
| **Datadog API Key**            | Datadog の API キー（`true` 選択時に必須）    | （空）                 | —                                                                                                  |
| **Datadog Application Key**    | Datadog のアプリケーションキー（`true` 選択時に必須） | （空）                 | —                                                                                                  |
| **Datadog Site**               | Datadog サイト                        | `ap1.datadoghq.com` | `ap1.datadoghq.com` / `datadoghq.com` / `us3.datadoghq.com` / `us5.datadoghq.com` / `datadoghq.eu` |

### 9. IAM の確認とスタック作成

「**Capabilities**」セクションで、**The following resource(s) require capabilities: \[AWS::IAM::Role]** に表示されるチェックボックスをすべて選択し、**\[Create stack]** をクリックします。

デプロイでは以下のリソースが自動的に作成されます。

- **VPC**（パブリック / EKS プライベート / DB プライベートの各サブネット、NAT Gateway、Elastic IP）
- **Amazon EKS クラスタ**（Kubernetes 1.35、System / User の 2 つのマネージドノードグループ、ノードあたり 128 GiB）
- **RDS for PostgreSQL**（v16.10、インスタンスクラスと Multi-AZ はフォームの指定どおり、pgvector 拡張インストール済み）
- **S3 バケット**（プライベート用：暗号化・バージョニング・ライフサイクル設定済み、パブリック用：CORS 設定済み）
- **AWS Bedrock Guardrail**（コンテンツセーフティ + PII 検出 / 多言語対応）
- **AGENTIC STAR アプリケーション一式**（Helm チャートにより自動インストール）

> **備考**
>
> デプロイ時間は環境により異なります。CloudFormation コンソールの **Events** タブで進行状況を確認できます。

> **注意**
>
> スタックの作成が失敗した場合（`ROLLBACK_COMPLETE` など）は、**Events** タブで最初に失敗したリソースの理由を確認し、原因（vCPU クォータの不足など）を直してから、スタックを削除して作り直してください。失敗したスタックに対する手作業での復旧は提供していません。

## デプロイ完了後

スタックが `CREATE_COMPLETE` になったら、CloudFormation コンソールの **Outputs** タブから以下の値を取得します。

| 出力キー                      | 用途                                                        |
| ------------------------- | --------------------------------------------------------- |
| `EKSClusterName`          | EKS クラスタ名                                                 |
| `EKSKubectlConfigCommand` | `kubectl` を EKS に接続するための `aws eks update-kubeconfig` コマンド |
| `DBInstanceEndpoint`      | RDS のエンドポイント                                              |
| `S3PublicBucketURL`       | パブリック S3 バケットの Web サイト URL                                |

### kubectl のセットアップ

`Outputs` の `EKSKubectlConfigCommand` に表示されたコマンドをローカル環境で実行します。

```bash
# Outputs に表示されるコマンドの例（実際の値は Outputs を参照してください）
aws eks update-kubeconfig --region <region> --name <EKSClusterName>
```

接続後、すべての Pod が `Running` であることを確認します。

```bash
kubectl get pods -A
```

### アクセス用 URL の確認

AGENTIC STAR は用途別に 4 つの LoadBalancer（AWS Network Load Balancer）を作成します。

```bash
kubectl get svc -n ingress-nginx -o wide | grep LoadBalancer
```

| サービス名                  | 用途          | アクセス URL                 |
| ---------------------- | ----------- | ------------------------ |
| `ingress-nginx-front`  | メイン画面       | `https://<ELB-DNS-NAME>` |
| `ingress-nginx-admin`  | 管理画面        | `https://<ELB-DNS-NAME>` |
| `ingress-nginx-extapi` | API エンドポイント | `https://<ELB-DNS-NAME>` |

> **注記**
>
> ログイン画面（`ingress-nginx-auth`）は OAuth リダイレクトの仕様上、URL を直接開くとログイン後の画面遷移が成立しません。**メイン画面の URL からアクセスし、認証が必要なタイミングでログイン画面へ自動遷移する**フローでご利用ください。

> **ELB DNS 名について**
>
> AWS の Network Load Balancer は複数 Availability Zone にまたがる ENI 構成のため、固定 IP ではなく `xxxxxxxx.elb.<region>.amazonaws.com` 形式の DNS 名（ELB DNS 名）が払い出されます。AWS が裏で IP を変更しうるため、`kubectl get svc` の `EXTERNAL-IP` 列に表示される DNS 名を必ず利用してください。

自己署名証明書を使用しているため、ブラウザで証明書の警告が表示されます。初回アクセス時は警告を許可して続行してください。

> **ヒント**
>
> カスタムドメインを設定する場合は、各 LoadBalancer の **ELB DNS 名** を DNS の **CNAME** で指してください（A レコードによる IP 直指定は AWS では不可）。詳しくは[ドメイン設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/domain-guide.md)を参照してください。

### ログイン

管理画面の URL にブラウザでアクセスし、CloudFormation で入力した **Administrator Email** と **Administrator Password** でログインしてください。

次のステップとして、管理画面での初期設定を行います。詳しくは[設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md)を参照してください。

API の利用を開始する場合は、[マーケットプレイス版 API クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/quickstart/call-api.md)を参照してください。
