# ドメイン設定ガイド

AGENTIC STAR マーケットプレイス版のカスタムドメイン設定と SSL 証明書のアップグレード手順を解説します。

## 出荷時の状態

AGENTIC STAR は**自己署名証明書による HTTPS** で動作する状態で出荷されています。

### LoadBalancer エンドポイントの構成

4 つの LoadBalancer エンドポイントが割り当てられています。

| Service 名              | 用途          |
| ---------------------- | ----------- |
| `ingress-nginx-front`  | メインアプリケーション |
| `ingress-nginx-admin`  | 管理画面        |
| `ingress-nginx-auth`   | 認証サービス      |
| `ingress-nginx-extapi` | 外部 API      |

各エンドポイントに対して自己署名証明書が適用済みです（4 つのエンドポイントをすべて SAN に含む 1 枚の証明書）。

#### クラウドによるエンドポイント表記の違い

`kubectl get svc -n ingress-nginx` の `EXTERNAL-IP` 列の表記は、利用するクラウドによって異なります。

| クラウド      | EXTERNAL-IP の表記 | DNS レコード | 備考                                                                   |
| --------- | --------------- | -------- | -------------------------------------------------------------------- |
| **Azure** | 静的 IP アドレス      | A レコード   | Standard Load Balancer の Public IP（デフォルトで静的）                         |
| **AWS**   | ELB DNS 名       | CNAME    | Network Load Balancer の DNS 名（`xxxxxxxx.elb.<region>.amazonaws.com`） |
| **GCP**   | 静的 IP アドレス      | A レコード   | グローバル外部 LB / リージョナル LB のいずれの場合も IP 直接                                |

> **AWS で IP が表示されない理由**
>
> AWS Network Load Balancer は複数 Availability Zone にまたがる ENI 構成のため固定 IP を持たず、AWS が裏で IP を変更しうる仕様です。長期参照は ELB DNS 名で行ってください。本ガイドでは「IP1〜IP4」「IP アドレス」などの表現を使用しますが、AWS 環境では「ELB DNS 名」と読み替えてください。

### 出荷時の制限事項

| 項目                  | 状態                     |
| ------------------- | ---------------------- |
| HTTPS 通信            | 動作（ブラウザ証明書警告あり）        |
| OAuth / Keycloak 認証 | 動作                     |
| Secure Cookie       | 動作                     |
| WebAuthn（Passkey）   | **不可**（正式ドメイン設定後に利用可能） |

> **危険**
>
> 自己署名証明書のまま本番運用すると、以下のリスクがあります：
>
> - ブラウザの証明書警告による利用者の混乱
> - 中間者攻撃を検知できない（ユーザーが警告を無視する習慣がつく）
> - WebAuthn（Passkey）機能が利用不可
> - 一部クライアント SDK が接続拒否する可能性
>
> **必ず正式ドメインと正規 SSL 証明書を設定してからサービスを公開してください。**

## SSL 設定方法の選択

ドメイン取得後、以下のいずれかの方法で正規 SSL 証明書にアップグレードしてください。

| 方法                     | SSL 終端   | 証明書管理        | 推奨ケース                      |
| ---------------------- | -------- | ------------ | -------------------------- |
| **CDN / ロードバランサー経由**   | クラウドサービス | クラウドで管理      | WAF / DDoS 保護、CDN 機能が必要な場合 |
| **外部証明書**              | Ingress  | 手動管理         | 既存の証明書がある場合                |
| **Let's Encrypt 自動発行** | Ingress  | cert-manager | 無料で自動更新したい場合               |

## アップグレード共通手順

どの方法を選択する場合も、以下の共通手順が必要です。

### 1. ドメインを取得し DNS レコードを設定

各サービスに対応するドメインを用意し、各 LoadBalancer エンドポイントを指すよう DNS レコードを設定してください。レコードタイプはクラウドによって異なります。

| ドメイン例               | 向き先 Service            | 用途          |
| ------------------- | ---------------------- | ----------- |
| `chat.example.com`  | `ingress-nginx-front`  | メインアプリケーション |
| `admin.example.com` | `ingress-nginx-admin`  | 管理画面        |
| `auth.example.com`  | `ingress-nginx-auth`   | 認証サービス      |
| `api.example.com`   | `ingress-nginx-extapi` | 外部 API      |

#### クラウド別の DNS 設定例

**Azure / GCP（A レコードで IP を指定）:**

```text
chat.example.com.   IN  A  <IP1>
admin.example.com.  IN  A  <IP2>
auth.example.com.   IN  A  <IP3>
api.example.com.    IN  A  <IP4>
```

**AWS（CNAME で ELB DNS 名を指定）:**

```text
chat.example.com.   IN  CNAME  <ingress-nginx-front の ELB DNS 名>
admin.example.com.  IN  CNAME  <ingress-nginx-admin の ELB DNS 名>
auth.example.com.   IN  CNAME  <ingress-nginx-auth の ELB DNS 名>
api.example.com.    IN  CNAME  <ingress-nginx-extapi の ELB DNS 名>
```

> **注記**
>
> ドメイン設定後も、各 Service のエンドポイント（Azure/GCP は IP、AWS は ELB DNS 名）はそのまま維持されます。DNS レコードが対応するエンドポイントを指すだけで、ルーティングは変わりません。
>
> AWS Marketplace 版では NLB の IP が AWS 側で変動しうるため、必ず CNAME で ELB DNS 名を指してください。A レコードに NLB の IP を直接登録すると、IP 変更時にアクセス不能になります。Route 53 を利用する場合は、エイリアスレコード（A レコード Alias）で NLB を指す方法も使用できます。

### 2. 現在の Helm チャートバージョンを確認

```bash
HELM_DRIVER=configmap helm list -A
```

各サービスのチャート名・バージョンを確認してください（例: `librechat-1.1.3`、`agenticai-admin-1.1.3` 等）。以降の手順では、同じバージョンのチャートを使用します。

### 3. Helm リポジトリを追加

```bash
helm repo add agenticai-prod https://agtstrmarketplacecharts.blob.core.windows.net/charts
helm repo update
```

### 4. ドメイン / URL 設定を更新

各サービスの ConfigMap に含まれる IP アドレスベースの URL を、`helm upgrade --reuse-values --set` でドメインベースに変更します。`--reuse-values` により既存の設定値はすべて保持され、`--set` で指定した値のみが上書きされます。

> **注意**
>
> チャートバージョンは手順 2 で確認した現在デプロイ済みのバージョンと同じものを指定してください。

**メインアプリケーション（librechat）:**

```bash
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 \
  --reuse-values \
  --set appConfig.domainClient="https://chat.example.com" \
  --set appConfig.domainServer="https://chat.example.com" \
  --set appConfig.authBaseUrl="https://auth.example.com" \
  -n agentic-star-front
```

**管理画面（agenticai-admin）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 \
  --reuse-values \
  --set env.AFD_CHATBOARD_ADMIN_DOMAIN="admin.example.com" \
  --set env.AFD_CHATBOARD_FRONT_AUTH_DOMAIN="auth.example.com\,chat.example.com" \
  --set env.ALLOWED_ORIGINS="https://auth.example.com\,https://admin.example.com" \
  --set env.CHATBOARD_FRONT_DOMAIN="chat.example.com" \
  -n agentic-star-admin
```

**認証サービス（librechat-auth）:**

```bash
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 \
  --reuse-values \
  --set env.ADMIN_CONSOLE_URL="https://admin.example.com" \
  --set env.ALLOWED_ORIGINS="https://chat.example.com\,https://auth.example.com" \
  --set env.ALLOWED_REDIRECT_URIS="https://chat.example.com/oauth/librechat/callback" \
  --set env.APP_URL="https://auth.example.com" \
  --set env.LIBRECHAT_URL="https://chat.example.com" \
  --set env.NEXT_PUBLIC_APP_URL="https://auth.example.com" \
  --set env.WEBAUTHN_ORIGIN="https://auth.example.com" \
  --set env.WEBAUTHN_RP_ID="auth.example.com" \
  -n librechat-auth
```

> **注記**
>
> - `agenticai-extapi`（agenticai-extapi-service）はクラスタ内部 URL のみを使用しているため、通常は変更不要です
> - `--set` でカンマを含む値を指定する場合は `\,` でエスケープしてください

### 5. SSL 証明書を設定

以下のいずれかの方法に進んでください。

## 方法 1: CDN / ロードバランサー経由

クラウドサービスで SSL 終端を行い、Ingress 側の TLS は無効化します。

```text
ユーザー → HTTPS (443) → CDN / ロードバランサー (SSL 終端) → HTTP (80) → Ingress Controller → Pod
```

### Helm でデプロイ

各サービスに対して以下のコマンドを実行します。

```bash
# メインアプリケーション
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agentic-star-front

# 管理画面
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agentic-star-admin

# 認証サービス
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n librechat-auth

# 外部 API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 1.0.0 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agenticai-extapi-service
```

### クラウド別の構成

#### Azure: Front Door

Azure Front Door を使用することで、WAF によるセキュリティ保護と Azure マネージド証明書による SSL/TLS 設定を実現できます。

主な手順:

1. DNS ゾーンを作成し NS 委任を設定
2. AFD プロファイル・WAF ポリシーを作成
3. カスタムドメインを登録し証明書を発行
4. オリジングループに AKS Ingress IP を登録
5. ルーティングルールでドメインとオリジンを紐付け
6. NSG ルールを更新（AFD からのアクセスのみ許可）
7. Ingress / Helm 設定を更新

#### AWS: CloudFront + NLB

AWS Marketplace 版では LoadBalancer として NLB が払い出されるため、CloudFront のオリジンには **NLB の DNS 名を直接指定** する構成を推奨します。NLB の IP は AWS 側で変動しうるため、ALB のターゲットグループに IP 登録する従来構成は安定しません。

1. ACM（AWS Certificate Manager）で証明書を発行（CloudFront 用は **us-east-1** で発行する必要があります）
2. CloudFront ディストリビューションを作成し、各 Service の **NLB DNS 名** をオリジンに設定（用途別に 4 オリジン）
3. ビヘイビアでパス／ホストごとにオリジンを振り分け
4. Route 53 で各カスタムドメインの **CNAME**（または Alias）を CloudFront ディストリビューションのドメインに向ける
5. NLB のセキュリティグループを CloudFront 管理 Prefix List（`com.amazonaws.global.cloudfront.origin-facing`）からのアクセスのみに制限

> **ヒント**
>
> 追加コンポーネントを増やしたくない場合は、CloudFront を使用せず NLB の前段に直接 Route 53 を置く構成も可能です。その場合は SSL 終端を Ingress 側または NLB の TLS リスナーで行います（後述の「方法 2: 外部証明書」「方法 3: Let's Encrypt 自動発行」を参照）。

> **注意**
>
> ALB を経由する構成（AWS Load Balancer Controller で IP target 登録）も技術的には可能ですが、NLB と ALB を多段にすることで運用が複雑化するため、上記の CloudFront → NLB 直結構成を推奨します。

#### GCP: Cloud Load Balancing

1. Google-managed SSL 証明書を作成
2. 外部 HTTPS ロードバランサーを作成
3. バックエンドサービスに Ingress IP を登録
4. Cloud DNS で DNS を設定

> **前段プロキシを置く場合は trustProxy を設定**
>
> Front Door / CloudFront / Cloud Load Balancing など**リバースプロキシを Ingress の前段に置く構成**では、Helm で `appConfig.trustProxy=2` を設定してください。未設定（既定 1）だと送信元 IP が実利用者ではなく**前段プロキシの IP** になり、アクセス制限（不正アクセス防止・レート制限）で同一 IP を共有する無関係な利用者まで巻き込むことがあります。多段構成では段数に合わせて値を増やします。詳細は [Helm Values リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/reference/helm-values-ref.md) を参照。

## 方法 2: 外部証明書

外部で発行した証明書を Ingress で使用します。

```text
ユーザー → HTTPS (443) → Ingress Controller (SSL 終端 / 正規証明書) → HTTP → Pod
```

### 手順

#### 1. 証明書を Kubernetes Secret として登録

既存の自己署名証明書 Secret を削除し、正規証明書で置き換えます。

```bash
# 既存の自己署名証明書 Secret を削除（5 つの Namespace すべてから）
kubectl delete secret selfsigned-tls-cert -n agentic-star-front
kubectl delete secret selfsigned-tls-cert -n agentic-star-admin
kubectl delete secret selfsigned-tls-cert -n librechat-auth
kubectl delete secret selfsigned-tls-cert -n agenticai-extapi-service
kubectl delete secret selfsigned-tls-cert -n ingress-nginx

# 正規証明書の Secret を作成（5 つの Namespace すべてに）
for ns in agentic-star-front agentic-star-admin librechat-auth agenticai-extapi-service ingress-nginx; do
  kubectl create secret tls app-tls-cert \
    --cert=tls.crt --key=tls.key \
    -n $ns
done
```

> **注記**
>
> `ingress-nginx` Namespace の Secret は Ingress Controller の `default-ssl-certificate` で使用されます。`ingress-nginx-values.yaml` の `controller.extraArgs.default-ssl-certificate` を `"ingress-nginx/app-tls-cert"` に変更し、Ingress Controller を再デプロイしてください。

#### 2. Helm でデプロイ

各サービスに対して、TLS Secret 名を正規証明書に切り替えます。

```bash
# メインアプリケーション
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n agentic-star-front

# 管理画面
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n agentic-star-admin

# 認証サービス
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n librechat-auth

# 外部 API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 1.0.0 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=false \
  -n agenticai-extapi-service
```

## 方法 3: Let's Encrypt 自動発行

cert-manager を使用して Let's Encrypt 証明書を自動発行・更新します。

```text
ユーザー → HTTPS (443) → Ingress Controller (SSL 終端 / Let's Encrypt 証明書) → HTTP → Pod
```

### 前提条件

- cert-manager がインストール済み（AGENTIC STAR に含まれています）

- ドメインの DNS 設定が各 LoadBalancer エンドポイントを指していること

  <!-- -->

  - Azure / GCP: A レコードで Ingress の IP を指していること
  - AWS: CNAME で Ingress の ELB DNS 名を指していること

- ポート 80 へのアクセスが許可されていること（ACME HTTP-01 チャレンジ用）

### 手順

#### 1. ClusterIssuer を作成

同梱の `cluster-issuer.yaml` を編集し、メールアドレスを変更してから適用します。

```bash
kubectl apply -f cluster-issuer.yaml
```

#### 2. Helm でデプロイ

各サービスに対して cert-manager 連携を有効化します。

```bash
# メインアプリケーション
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/librechat \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n agentic-star-front

# 管理画面
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n agentic-star-admin

# 認証サービス
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/librechat-auth \
  --version 1.1.3 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n librechat-auth

# 外部 API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 1.0.0 --reuse-values \
  --set global.ingress.tls.enabled=true \
  --set global.ingress.tls.secretName="app-tls-cert" \
  --set global.ingress.tls.useCertManager=true \
  --set global.ingress.tls.clusterIssuer="letsencrypt-prod" \
  -n agenticai-extapi-service
```

> **注記**
>
> cert-manager が Secret 名（`app-tls-cert`）で新しい証明書を自動作成します。出荷時の自己署名証明書 Secret（`selfsigned-tls-cert`）は各 Namespace から手動で削除してください。また、Ingress Controller の `default-ssl-certificate` も `"ingress-nginx/app-tls-cert"` に更新してください。

#### 3. 証明書発行を確認

```bash
kubectl get certificate -n <namespace>
kubectl describe certificate <cert-name> -n <namespace>
```

## トラブルシューティング

### 出荷時の自己署名証明書でログインできない

```bash
# Ingress の状態確認
kubectl describe ingress <name> -n <namespace>

# TLS Secret の存在確認
kubectl get secret selfsigned-tls-cert -n <namespace>

# Ingress Controller ログ確認
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller
```

**よくある原因:**

- ブラウザで証明書例外を許可していない
- TLS Secret が正しい Namespace に存在しない
- Ingress Controller が再起動中

### 現在適用されている TLS 設定を確認する

```bash
HELM_DRIVER=configmap helm get values <release-name> -n <namespace>
```

### 証明書が発行されない（Let's Encrypt）

```bash
# Certificate リソースの状態確認
kubectl describe certificate <name> -n <namespace>

# cert-manager ログ確認
kubectl logs -n cert-manager deployment/cert-manager

# Challenge リソースで ACME 検証状況確認
kubectl get challenge -n <namespace>
```

**よくある原因:**

- DNS が Ingress のエンドポイントを指していない（Azure/GCP は A レコードで IP、AWS は CNAME で ELB DNS 名）
- ポート 80 へのアクセスがブロックされている
- ClusterIssuer のメールアドレスが無効

### HTTPS にリダイレクトされない

```bash
HELM_DRIVER=configmap helm get values <release-name> -n <namespace>
```

`nginx.ingress.kubernetes.io/ssl-redirect` が `"true"` になっているか確認してください。
