# ドメイン設定ガイド

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

## 対象バージョンと入口の確認

AGENTIC STAR の入口（ブラウザーや API からの要求を受ける部分）は、バージョンによって異なります。証明書などの設定先が違うため、先に環境の入口を確かめ、対応する節の手順を使ってください。

| バージョン         | 入口                                                    | 使う手順                                                                                                                                                                                                  |
| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **v3.4.0 以降** | NGINX Gateway Fabric（Gateway API の Gateway・HTTPRoute） | このページの本文（[出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B) から [トラブルシューティング](#%E3%83%88%E3%83%A9%E3%83%96%E3%83%AB%E3%82%B7%E3%83%A5%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0) まで） |
| **v3.3.x まで** | ingress-nginx（Ingress）                                | [v3.3.x までの手順（ingress-nginx）](#v33-ingress-nginx)                                                                                                                                                     |

入口は次のコマンドで確かめられます。

```bash
kubectl get svc -n ingress-nginx -l app.kubernetes.io/purpose \
  -o custom-columns='NAME:.metadata.name,ENTRY:.spec.selector.gateway\.networking\.k8s\.io/gateway-name'
```

- すべての行の `ENTRY` に `front`・`admin` などの名前が表示される: 入口は NGINX Gateway Fabric です（v3.4.0 以降の手順を使います）
- `ENTRY` が `<none>`: 入口は ingress-nginx です（v3.3.x までの手順を使います）
- 何も表示されない（LoadBalancer の Service を持たない環境）: 管理コンソールのバージョン管理画面に表示されるバージョンで判断してください

> **v3.3.x から v3.4.0 にアップデートした環境**
>
> v3.3.x までの手順で設定した証明書や、CDN・ロードバランサーを前に置くための設定は、v3.4.0 以降の入口では使われません。独自のドメインを設定している環境は、[v3.3.x からアップデートした環境の設定の移行](#migrate-from-v33) を行ってください。

## 出荷時の状態

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

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

4 つの LoadBalancer エンドポイントが割り当てられています。エンドポイントごとに、入口（NGINX Gateway Fabric）の Gateway が 1 つあります。Service と Gateway は、どちらも `ingress-nginx` Namespace にあります。

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

各エンドポイントに対して自己署名証明書が適用済みです（4 つのエンドポイントをすべて SAN に含む 1 枚の証明書）。証明書は `ingress-nginx` Namespace の TLS の Secret にあり、すべての Gateway の HTTPS のリスナーが同じ Secret を参照しています。HTTP（80）で届いた要求は、HTTPS へ転送されます。

> **Service と Namespace の名前**
>
> LoadBalancer の Service 名（`ingress-nginx-front` など）と Namespace 名（`ingress-nginx`）は、v3.3.x までと同じです。v3.4.0 以降の新しい環境に、ingress-nginx そのものは入っていません。

Gateway の状態と、HTTPS のリスナーが参照している Secret の名前は、次のコマンドで確かめられます（以降の手順でも、設定の確認に使います）。

```bash
kubectl get gateway -n ingress-nginx -o custom-columns=\
'NAME:.metadata.name,'\
'PROGRAMMED:.status.conditions[?(@.type=="Programmed")].status,'\
'SECRET:.spec.listeners[?(@.name=="https")].tls.certificateRefs[0].name,'\
'CERT:.status.listeners[?(@.name=="https")].conditions[?(@.type=="ResolvedRefs")].status'
```

出荷時の表示は次のとおりです。`PROGRAMMED` と `CERT`（証明書の Secret を読めたか）が `True` であれば、入口は正常です。`SECRET` は出荷時の自己署名証明書の Secret 名です（例は `selfsigned-tls-cert`。環境によって名前が異なる場合は、表示された名前を以降の手順で使います）。

```text
NAME     PROGRAMMED   SECRET                CERT
admin    True         selfsigned-tls-cert   True
auth     True         selfsigned-tls-cert   True
extapi   True         selfsigned-tls-cert   True
front    True         selfsigned-tls-cert   True
kc       True         selfsigned-tls-cert   True
```

> **5 つ目の入口（認証サーバーの外の入口）**
>
> 認証サーバーには、外部ツール（Claude Code・Codex などの AI クライアントや、OIDC に対応したアプリケーション）から利用者が自分のアカウントでログインするための **5 つ目の入口** があります。出荷時は閉じていて、上の表の 4 つだけが外に出ています。開けると `ingress-nginx-kc` が 5 つ目の LoadBalancer として増えます（Gateway `kc` は、閉じている間も置かれています）。開け方・閉じ方は[認証サーバーの外の入口（外部ツールでのログイン）](#kc-direct-login)を参照してください。

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

`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 機能が必要な場合 |
| **外部証明書**              | 入口（NGINX Gateway Fabric） | 手動管理         | 既存の証明書がある場合                |
| **Let's Encrypt 自動発行** | 入口（NGINX Gateway Fabric） | 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                                     |
| `kc.example.com`    | `ingress-nginx-kc`     | 認証サーバーの外の入口（[開けている場合のみ](#kc-direct-login)） |

#### クラウド別の 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>
kc.example.com.     IN  A  <IP5>   # 認証サーバーの外の入口を開けている場合のみ
```

**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 名>
kc.example.com.     IN  CNAME  <ingress-nginx-kc の 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
```

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

### 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/agentic-star-front \
  --version 3.4.0 \
  --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 3.4.0 \
  --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" \
  --set env.EXTAPI_PUBLIC_URL="https://api.example.com" \
  --set env.MP_OAUTH_TOKEN_URL="https://auth.example.com/api/v1/oauth/token" \
  --set env.AUTH_PUBLIC_URL="https://auth.example.com" \
  --set env.ADMIN_PUBLIC_URL="https://admin.example.com" \
  -n agentic-star-admin
```

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

```bash
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/agentic-star-auth \
  --version 3.4.0 \
  --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\,https://auth.example.com/*\,https://admin.example.com/*" \
  --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
```

**認証基盤（keycloak-extensions）:**

パスキーの確認に使う `WEBAUTHN_RP_ID`・`WEBAUTHN_ORIGIN` を、認証サービスの新しいドメインに直します。この 2 つは `keycloakx.extraEnv`（複数行の文字列）の中にあるため、今の値を取り出して書き換えてから適用します。

```bash
HELM_DRIVER=configmap helm get values keycloak-extensions -n librechat-auth -o yaml > keycloak-extensions-values.yaml
```

`keycloak-extensions-values.yaml` の `keycloakx.extraEnv` の中で、`WEBAUTHN_RP_ID` の value を `auth.example.com` に、`WEBAUTHN_ORIGIN` の value を `https://auth.example.com` に書き換えてから、次を実行します。

```bash
HELM_DRIVER=configmap helm upgrade keycloak-extensions agenticai-prod/keycloak-extensions \
  --version 3.4.0 \
  --reuse-values \
  -f keycloak-extensions-values.yaml \
  -n librechat-auth
```

取り出したファイルには接続のパスワードなどの秘密の値が含まれます。作業の後に削除してください。

**外部 API（agenticai-extapi）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 3.4.0 \
  --reuse-values \
  --set config.APIGW_PUBLIC_URL="https://api.example.com" \
  --set config.A2A_PUBLIC_URL="https://api.example.com" \
  --set config.MP_OAUTH_TOKEN_URL="https://auth.example.com/api/v1/oauth/token" \
  -n agenticai-extapi-service
```

**認証サーバーの外の入口（開けている場合のみ）:**

認証サーバーの外の入口を開けている環境では、`helm upgrade` の代わりに開閉コマンドを新しいドメインで実行し直します。認証サーバーが外に名乗る URL（外の住所）と、外部 API に渡すトークンの発行元を一度に入れ替え、発行元が切り替わったことまで確かめます。手で `helm upgrade` する場合に渡す値は [Helm Values リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/reference/helm-values-ref.md#kc-direct-login-values)を参照してください。

```bash
bash kc_direct_login.sh open --address kc.example.com
```

発行元が変わるため、外部ツールを使っている利用者はログインし直す必要があります。

> **注記**
>
> - 入口（NGINX Gateway Fabric）は、ホスト名を限定せずに要求を受け付けます。ドメインを変えるときに、入口の側でホスト名を登録する必要はありません（v3.3.x までの `server-alias` に当たる設定はありません）
> - 認証サーバーの外の入口を開けている場合、外部 API に渡すトークンの発行元は上の開閉コマンドが入れ替えます
> - `--set` でカンマを含む値を指定する場合は `\,` でエスケープしてください

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

以下のいずれかの方法に進んでください。どの方法も、次の節の手順で入口の設定を変えます。

## 入口（NGINX Gateway Fabric）の設定を変える

入口の設定は、Helm リリース `agentic-star-edge`（Namespace `ingress-nginx`）の値で決まります。証明書と HTTP の扱いは、Gateway の一覧 `gateways` の中の、次の 2 つの値です。

| 値                                                | 意味                                                                                         | 出荷時             |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------ | --------------- |
| `gateways[].listeners.https.certificateRef.name` | HTTPS のリスナーが使う証明書の Secret 名。Secret（種類は `kubernetes.io/tls`）は `ingress-nginx` Namespace に置く | 自己署名証明書の Secret |
| `gateways[].httpsRedirect`                       | `true`: HTTP（80）で届いた要求を HTTPS へ転送する。`false`: HTTP（80）で届いた要求も、そのままアプリケーションへ届ける              | `true`          |

`gateways` はリストのため、今の一覧を取り出し、書き換えてから、一覧の全体を渡して適用します。

**1. 今の `gateways` の値をファイルに取り出す**

```bash
HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx -o yaml \
  | yq '{"gateways": .gateways}' > edge-gateways.yaml
```

`edge-gateways.yaml` に、`front`・`admin`・`auth`・`extapi`・`kc` の 5 つの Gateway が入っていることを確かめてください。

**2. ファイルの値を書き換える**

書き換える内容は、[方法 1](#method-1)・[方法 2](#method-2)・[方法 3](#method-3) の手順に書いてあります。

**3. 適用する**

```bash
HELM_DRIVER=configmap helm upgrade agentic-star-edge agenticai-prod/agentic-star-edge \
  --version 3.4.0 \
  --reuse-values \
  -f edge-gateways.yaml \
  -n ingress-nginx
```

`--version` には、共通手順 2 で確かめた `agentic-star-edge` の現在のバージョンを指定します。設定を変えても、LoadBalancer のアドレス（IP アドレス・ELB DNS 名）は変わりません。

**4. 確かめる**

[出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B) の `kubectl get gateway` のコマンドで、5 つの Gateway の `PROGRAMMED` と `CERT` が `True` であることを確かめます。

> **注意**
>
> - `gateways` を `--set 'gateways[0]…'` のように一部だけ指定しないでください。リストは指定した内容で全体が置き換わるため、適用がエラーになるか、ほかの Gateway の設定が失われます。必ず上の手順のように、一覧の全体をファイルで渡してください
> - `yq` は mikefarah 版の v4 を使います。`yq` が無い場合は、`helm get values agentic-star-edge -n ingress-nginx -o yaml` の出力のうち `gateways:` の部分だけを `edge-gateways.yaml` に保存し、エディタで書き換えてください。出力のほかの部分には、接続のパスワードなどの秘密の値が含まれることがあるため、保存しないでください

> **アップデートの後は入口の設定を確かめる**
>
> AGENTIC STAR のアップデートで入口のチャートが更新されると、この節の手順で変えた値（証明書の Secret 名・HTTP の転送・利用者の IP アドレスの設定）が、出荷時の値や v3.3.x までの入口の設定に戻ることがあります。アップデートの後は、この節の「4. 確かめる」のコマンドと `HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx` で値を確かめ、変わっていたら設定し直してください。

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

クラウドサービスで SSL 終端を行い、入口へは HTTP（80）でつなぎます。

```text
ユーザー → HTTPS (443) → CDN / ロードバランサー (SSL 終端) → HTTP (80) → 入口（NGINX Gateway Fabric） → Pod
```

出荷時の入口は、HTTP（80）で届いた要求を HTTPS へ転送します。CDN / ロードバランサーから HTTP（80）で入口につなぐ構成では、この転送を止めて、HTTP（80）で届いた要求をアプリケーションへ届けるようにします。

### 入口の HTTP の転送を止める

```bash
# 1. 今の gateways の値を取り出す
HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx -o yaml \
  | yq '{"gateways": .gateways}' > edge-gateways.yaml

# 2. すべての Gateway で、HTTP から HTTPS への転送を止める
yq -i '.gateways[].httpsRedirect = false' edge-gateways.yaml

# 3. 適用する
HELM_DRIVER=configmap helm upgrade agentic-star-edge agenticai-prod/agentic-star-edge \
  --version 3.4.0 \
  --reuse-values \
  -f edge-gateways.yaml \
  -n ingress-nginx
```

認証サーバーの外の入口（Gateway `kc`）も、同じ手順で一緒に変わります。

適用の後、次のコマンドで確かめます。

```bash
kubectl get httproute -n ingress-nginx
curl -sS -o /dev/null -w '%{http_code}\n' http://<ingress-nginx-front のアドレス>/
```

- 1 つ目: 転送用の HTTPRoute（`front-https-redirect` など）が表示されなければ、転送は止まっています（`No resources found in ingress-nginx namespace.`）
- 2 つ目: `301`（HTTPS への転送）ではなく `200` が返れば、HTTP（80）で届いた要求がアプリケーションへ届いています（LoadBalancer への接続を制限している環境では、CDN / ロードバランサーを通して確かめてください）

> **注意**
>
> 転送を止めると、LoadBalancer に HTTP（80）で直接届いた要求も、アプリケーションへ届くようになります。LoadBalancer には、CDN / ロードバランサーからの接続だけを許可してください。この許可の設定は、転送を止める前に済ませてください（下の「クラウド別の構成」の NSG・セキュリティグループの手順）。

> **注記**
>
> - 入口の HTTPS（443）のリスナーと証明書は、そのまま残ります
> - CDN / ロードバランサーから入口へも HTTPS（443）でつなぐ構成では、この手順は行わず、[方法 2](#method-2) か [方法 3](#method-3) で入口に正規の証明書を設定してください

### 利用者の IP アドレスの設定

CDN / ロードバランサー（リバースプロキシ）を前段に置くと、入口から見た接続元は、利用者ではなく前段の IP アドレスになります。そのままでは、利用者の IP アドレスを使う機能（接続元 IP の制限など）が、前段の IP アドレスで判定されます。前段が付けるヘッダーから利用者の IP アドレスを読むように、入口に次の値を設定してください。

| 値                        | 意味                                                                     |
| ------------------------ | ---------------------------------------------------------------------- |
| `realIp.enabled`         | `true` にすると、下のヘッダーから利用者の IP アドレスを読む。`false` は、入口に直接つないだ接続元の IP アドレスを使う |
| `realIp.header`          | 利用者の IP アドレスが入っているヘッダーの名前                                              |
| `realIp.trustedCidrsCsv` | ヘッダーを信頼する接続元（前段）の CIDR。複数あるときはカンマで区切る。`realIp.enabled` が `true` のときは必須 |

前段ごとの値は次のとおりです。

| 前段                                                 | `realIp.header`    | `realIp.trustedCidrsCsv`                |
| -------------------------------------------------- | ------------------ | --------------------------------------- |
| Azure Front Door                                   | `X-Azure-SocketIP` | サービスタグ `AzureFrontDoor.Backend` のアドレス範囲 |
| GCP の外部アプリケーション ロードバランサー                           | `X-Forwarded-For`  | `130.211.0.0/22,35.191.0.0/16`          |
| その他（AWS の CloudFront・Application Load Balancer など） | `X-Forwarded-For`  | 前段が入口につなぐときの接続元の CIDR                   |

次の内容で `edge-realip.yaml` を作り、値を環境に合わせてから適用します。

```yaml
realIp:
  enabled: true
  header: X-Forwarded-For
  trustedCidrsCsv: "203.0.113.0/24,198.51.100.0/24"
```

```bash
HELM_DRIVER=configmap helm upgrade agentic-star-edge agenticai-prod/agentic-star-edge \
  --version 3.4.0 \
  --reuse-values \
  -f edge-realip.yaml \
  -n ingress-nginx
```

今の設定は、次のコマンドで確かめられます。

```bash
HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx -o yaml | yq '.realIp'
```

> **注意**
>
> `realIp.trustedCidrsCsv` には、前段の CIDR だけを指定してください。前段を置かない構成では、`realIp.enabled` を `true` にしないでください。どちらも、利用者の IP アドレスを正しく判定できなくなります。

### クラウド別の構成

#### Azure: Front Door

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

主な手順:

1. DNS ゾーンを作成し NS 委任を設定
2. AFD プロファイル・WAF ポリシーを作成
3. カスタムドメインを登録し証明書を発行
4. オリジングループに各 LoadBalancer（`ingress-nginx-front` など）の IP を登録（認証サーバーの外の入口を開けている場合は `ingress-nginx-kc` の IP を 5 つ目のオリジンとして登録）
5. ルーティングルールでドメインとオリジンを紐付け（認証サーバーのドメインも同様に紐付け）
6. NSG ルールを更新（AFD からのアクセスのみ許可）
7. 入口の設定を更新（上の「入口の HTTP の転送を止める」と「利用者の IP アドレスの設定」）

#### 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 オリジン。認証サーバーの外の入口を開けている場合は `ingress-nginx-kc` の NLB を 5 つ目に）
3. ビヘイビアでパス／ホストごとにオリジンを振り分け（認証サーバーのドメイン用のビヘイビアも足す）
4. Route 53 で各カスタムドメインの **CNAME**（または Alias）を CloudFront ディストリビューションのドメインに向ける
5. NLB のセキュリティグループを CloudFront 管理 Prefix List（`com.amazonaws.global.cloudfront.origin-facing`）からのアクセスのみに制限
6. 入口の設定を更新（上の「入口の HTTP の転送を止める」と「利用者の IP アドレスの設定」）

> **ヒント**
>
> 追加コンポーネントを増やしたくない場合は、CloudFront を使用せず NLB の前段に直接 Route 53 を置く構成も可能です。その場合は SSL 終端を入口（NGINX Gateway Fabric）または 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. バックエンドサービスに各 LoadBalancer（`ingress-nginx-front` など）の IP を登録（認証サーバーの外の入口を開けている場合は `ingress-nginx-kc` の IP もバックエンドに足し、URL マップのホストルールで認証サーバーのドメインをそのバックエンドに向ける）
4. Cloud DNS で DNS を設定
5. 入口の設定を更新（上の「入口の HTTP の転送を止める」と「利用者の IP アドレスの設定」）

## 方法 2: 外部証明書

外部で発行した証明書を入口（NGINX Gateway Fabric）で使用します。

```text
ユーザー → HTTPS (443) → 入口（NGINX Gateway Fabric）(SSL 終端 / 正規証明書) → HTTP → Pod
```

### 手順

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

入口が読む Secret は、`ingress-nginx` Namespace に置きます（各サービスの Namespace に置く必要はありません）。

```bash
kubectl create secret tls app-tls-cert \
  --cert=tls.crt --key=tls.key \
  -n ingress-nginx
```

> **注記**
>
> - 1 枚の証明書を、すべての Gateway で使います。証明書の SAN に、設定したすべてのドメイン（例: `chat.example.com`・`admin.example.com`・`auth.example.com`・`api.example.com`）を含めてください。ワイルドカード証明書（`*.example.com`）も使えます
> - 認証サーバーの外の入口を開けている場合は、認証サーバーのドメイン（例 `kc.example.com`）も SAN に含めてください
> - `tls.crt` には、サーバー証明書に続けて中間証明書を入れてください

#### 2. 入口の証明書を切り替える

```bash
# 1. 今の gateways の値を取り出す
HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx -o yaml \
  | yq '{"gateways": .gateways}' > edge-gateways.yaml

# 2. すべての Gateway の HTTPS のリスナーの証明書を、正規証明書の Secret にする
yq -i '.gateways[].listeners.https.certificateRef.name = "app-tls-cert"' edge-gateways.yaml

# 3. 適用する
HELM_DRIVER=configmap helm upgrade agentic-star-edge agenticai-prod/agentic-star-edge \
  --version 3.4.0 \
  --reuse-values \
  -f edge-gateways.yaml \
  -n ingress-nginx
```

#### 3. 確認

[出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B) の `kubectl get gateway` のコマンドで、5 つの Gateway の `SECRET` が `app-tls-cert`、`PROGRAMMED` と `CERT` が `True` であることを確かめます。続けて、外から証明書を確かめます。

```bash
openssl s_client -connect chat.example.com:443 -servername chat.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -enddate
```

登録した証明書の subject・issuer・有効期限が表示されれば、切り替わっています。ほかのドメインも同じように確かめてください。

#### 4. 出荷時の自己署名証明書の Secret を削除

正規証明書でつながることを確かめたら、`ingress-nginx` Namespace に残っている出荷時の自己署名証明書の Secret（[出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B) の `kubectl get gateway` の `SECRET` に表示されていた名前。例: `selfsigned-tls-cert`）を削除します。

```bash
kubectl delete secret <出荷時の Secret 名> -n ingress-nginx
```

出荷時の Secret が残っていると、後のアップデートで、入口の証明書の設定がこの Secret に戻ることがあります。入口が今参照している Secret（手順 3 の `SECRET` に表示される名前）は、削除しないでください。

### 証明書を更新するとき

有効期限の前に証明書を入れ替えるときは、同じ名前の Secret の中身を新しい証明書に置き換えます。入口の設定を変える必要はありません。

```bash
kubectl create secret tls app-tls-cert \
  --cert=tls.crt --key=tls.key \
  -n ingress-nginx \
  --dry-run=client -o yaml | kubectl apply -f -
```

置き換えた後、手順 3 の `openssl` のコマンドで、新しい有効期限が表示されることを確かめてください。

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

cert-manager を使用して Let's Encrypt 証明書を自動発行・更新します。発行のときのドメインの確認（ACME HTTP-01 チャレンジ）は、入口（NGINX Gateway Fabric）の Gateway を通して行います。

```text
ユーザー → HTTPS (443) → 入口（NGINX Gateway Fabric）(SSL 終端 / Let's Encrypt 証明書) → HTTP → Pod
```

### 前提条件

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

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

  <!-- -->

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

- ポート 80 へのアクセスが、インターネットから許可されていること（ACME HTTP-01 チャレンジ用）。接続元を制限している環境では、HTTP-01 チャレンジは通りません

- 入口が、HTTP（80）で届いた要求を HTTPS へ転送する設定（出荷時の設定）であること。[方法 1](#method-1) で転送を止めた環境では、HTTP-01 チャレンジは通りません

### 手順

#### 1. cert-manager で Gateway API を有効にする

出荷時の cert-manager は、Gateway API を使う設定になっていません。次のコマンドで有効にします。`--version` には、共通手順 2 の `helm list` で確かめた cert-manager の現在のバージョン（`CHART` の列の `cert-manager-` の後ろ。例 `v1.20.0`）を指定します。v3.3.x 以前からアップデートした環境では、構築したときのバージョンのままのことがあります。

```bash
helm repo add jetstack https://charts.jetstack.io
helm repo update

HELM_DRIVER=configmap helm upgrade cert-manager jetstack/cert-manager \
  --version <cert-manager の現在のバージョン> \
  --reuse-values \
  --set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
  --set config.kind="ControllerConfiguration" \
  --set config.enableGatewayAPI=true \
  -n cert-manager

kubectl rollout status deployment/cert-manager -n cert-manager
```

次のコマンドで `enableGatewayAPI: true` が表示されれば、有効になっています。

```bash
kubectl get configmap cert-manager -n cert-manager -o jsonpath='{.data.config\.yaml}'
```

#### 2. ClusterIssuer を作成

次の内容で `cluster-issuer.yaml` を作り、`email` を通知を受けるメールアドレスに変えてから適用します（名前 `letsencrypt-prod` は次の手順で使います）。`parentRefs` には、入口の 5 つの Gateway を書きます。

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: front
                namespace: ingress-nginx
                kind: Gateway
                sectionName: http
              - name: admin
                namespace: ingress-nginx
                kind: Gateway
                sectionName: http
              - name: auth
                namespace: ingress-nginx
                kind: Gateway
                sectionName: http
              - name: extapi
                namespace: ingress-nginx
                kind: Gateway
                sectionName: http
              - name: kc
                namespace: ingress-nginx
                kind: Gateway
                sectionName: http
```

```bash
kubectl apply -f cluster-issuer.yaml
kubectl get clusterissuer letsencrypt-prod
```

`READY` が `True` であることを確かめます。

#### 3. 証明書（Certificate）を作成

次の内容で `certificate.yaml` を作り、`dnsNames` を共通手順 4 で設定したドメインに変えてから適用します。Certificate は、入口と同じ `ingress-nginx` Namespace に作ります。

```yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: app-tls-cert
  namespace: ingress-nginx
spec:
  secretName: app-tls-cert
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - chat.example.com
    - admin.example.com
    - auth.example.com
    - api.example.com
```

```bash
kubectl apply -f certificate.yaml
kubectl get certificate app-tls-cert -n ingress-nginx
```

`READY` が `True` になるまで待ちます（数分かかることがあります）。`True` になると、cert-manager が Secret `app-tls-cert` を `ingress-nginx` Namespace に作ります。

> **注記**
>
> 認証サーバーの外の入口を開けている場合は、`dnsNames` に認証サーバーのドメイン（例 `kc.example.com`）を足してください。ドメインの DNS レコードが `ingress-nginx-kc` を指している必要があります。

#### 4. 入口の証明書を切り替える

Certificate の `READY` が `True` になってから、[方法 2 の手順 2](#method-2) と同じコマンドで、入口の証明書を `app-tls-cert` に切り替えます。Secret ができる前に切り替えると、入口が証明書を読めず、HTTPS でつながらなくなります。

#### 5. 確認と、出荷時の Secret の削除

[方法 2 の手順 3・手順 4](#method-2) と同じ手順で、証明書が切り替わったことを確かめ、出荷時の自己署名証明書の Secret を削除します。証明書の更新は cert-manager が自動で行い、入口の設定を変える必要はありません。

> **HTTP-01 チャレンジが使えない環境**
>
> 接続元を制限している環境や、方法 1 と組み合わせる環境では、ClusterIssuer の `solvers` に DNS-01 の solver を指定してください（設定は cert-manager の文書を参照）。手順 3 以降は同じです。DNS-01 では、手順 1 の Gateway API の有効化は要りません。

## v3.3.x からアップデートした環境の設定の移行

v3.3.x から v3.4.0 へのアップデート（[更新ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/update-guide.md)の「A-10. v3.4.0 へのアップデートでの入口の切り替え」）で、入口は ingress-nginx から NGINX Gateway Fabric に切り替わります。[v3.3.x までの手順](#v33-ingress-nginx)で Ingress に入れた設定は、切り替えの後は使われません。独自のドメインを設定している環境は、この節の手順で、入口に設定を入れ直してください。

### 引き継がれる設定と、入れ直す設定

| v3.3.x までの設定                                     | アップデートの後                                                                           | 行う作業                                         |
| ------------------------------------------------ | ---------------------------------------------------------------------------------- | -------------------------------------------- |
| DNS レコード・LoadBalancer のアドレス                      | 変わらない                                                                              | なし                                           |
| 各サービスのドメイン / URL の設定（共通手順 4 の値）                  | 引き継がれる。入口はホスト名を限定せずに受け付けるため、`server-alias` に当たる設定は要らない                             | なし                                           |
| LoadBalancer の接続元の制限（`loadBalancerSourceRanges`） | 引き継がれる                                                                             | なし                                           |
| 入口の接続元の制限・利用者の IP アドレスの設定（ingress-nginx の設定）     | 引き継がれる                                                                             | なし（[利用者の IP アドレスの設定](#real-ip) のコマンドで確かめられる） |
| 方法 1（CDN / ロードバランサー経由）の `ssl-redirect` の設定       | 引き継がれない。入口は HTTP（80）で届いた要求を HTTPS へ転送する                                            | [方法 1 の「入口の HTTP の転送を止める」](#method-1)        |
| 方法 2（外部証明書）の証明書                                  | 下の「入口が使う証明書」のとおり。ingress-nginx の既定の証明書を `ingress-nginx/app-tls-cert` にしてあれば、引き継がれる | 確かめて、正規証明書でなければ [方法 2](#method-2)            |
| 方法 3（Let's Encrypt）の証明書                          | 引き継がれない（Ingress ごとに発行した証明書は使われない）                                                  | [方法 3](#method-3) で発行し直す                     |
| 認証サーバーの外の入口                                      | 入口と一緒に切り替わる。証明書と HTTP の扱いは、ほかの 4 つと同じ入口の設定で決まる                                     | 上の作業に含まれる（証明書には認証サーバーのドメインも含める）              |

### 入口が使う証明書

切り替えのとき、入口（NGINX Gateway Fabric）が使う証明書の Secret は、次の順で決まります。

1. ingress-nginx の既定の証明書（`--default-ssl-certificate`）が `ingress-nginx` Namespace の Secret を指していて、その Secret があれば、その Secret
2. 1 に当たらなければ、`ingress-nginx` Namespace の `selfsigned-tls-cert`

決まった Secret が `ingress-nginx` Namespace に無いと、入口を切り替えられず、アップデートの完了画面で `entry` が失敗になります（入口は ingress-nginx のまま動き続けます）。v3.3.x までの方法 2・方法 3 の手順で `selfsigned-tls-cert` を削除した環境は、これに当たることがあります。

### アップデートの前に確かめること

次のコマンドで、ingress-nginx の既定の証明書と、`ingress-nginx` Namespace にある TLS の Secret を確かめます。

```bash
kubectl get deploy ingress-nginx-controller -n ingress-nginx \
  -o jsonpath='{range .spec.template.spec.containers[0].args[*]}{@}{"\n"}{end}' \
  | grep default-ssl-certificate
kubectl get secret -n ingress-nginx --field-selector type=kubernetes.io/tls
```

1 つ目の出力は `--default-ssl-certificate=ingress-nginx/<Secret 名>` の形です。この `<Secret 名>`（表示されない場合や、Namespace が `ingress-nginx` でない場合は `selfsigned-tls-cert`）が 2 つ目の一覧にあれば、入口はその Secret で切り替わります。

一覧に無い場合は、アップデートの前に、その名前で Secret を作っておきます。

```bash
kubectl create secret tls <Secret 名> \
  --cert=tls.crt --key=tls.key \
  -n ingress-nginx
```

- 方法 2（外部証明書）の環境: 正規証明書（`tls.crt`・`tls.key`）で作ります。入口は、切り替えの直後から正規証明書を使います

- 方法 3（Let's Encrypt）の環境: 一時的な自己署名証明書で作り、アップデートの直後に [方法 3](#method-3) で発行し直します。一時的な証明書の間は、ブラウザに証明書の警告が表示されます

  ```bash
  openssl req -x509 -nodes -newkey rsa:2048 -days 30 \
    -keyout tls.key -out tls.crt \
    -subj "/CN=chat.example.com" \
    -addext "subjectAltName=DNS:chat.example.com,DNS:admin.example.com,DNS:auth.example.com,DNS:api.example.com"
  ```

### アップデートの直後に行うこと

利用の少ない時間帯にアップデートし、完了したら、次の順に行います。

**1. 入口が切り替わったことを確かめる**

[対象バージョンと入口の確認](#entry-version) のコマンドで、すべての行の `ENTRY` に名前が表示されることを確かめます。完了画面で `entry` が失敗になった場合は、下の「アップデートで `entry` が失敗になった場合」を参照してください。

**2. 入口の状態と証明書を確かめる**

[出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B) の `kubectl get gateway` のコマンドで、5 つの Gateway の `PROGRAMMED` と `CERT` が `True` であることと、`SECRET` の名前を確かめます。

**3. v3.3.x までの構成に合わせて、入口に設定を入れる**

- 方法 1 の環境: [入口の HTTP の転送を止める](#method-1)。CDN / ロードバランサーを通してつながることを確かめる
- 方法 2 の環境: `SECRET` が正規証明書の Secret でなければ、[方法 2](#method-2) の手順 1〜3 を行う。`app-tls-cert` が `ingress-nginx` Namespace に既にある場合は、手順 1 は要らない
- 方法 3 の環境: [方法 3](#method-3) の手順 1〜5 を行う。手順 2 の `kubectl apply` で、v3.3.x までの ClusterIssuer（Ingress を使う設定）は、Gateway を使う設定に置き換わる

**4. 各ドメインでつながることを確かめる**

ブラウザで各ドメインを開き、証明書の警告が出ないことと、ログインできることを確かめます。

**5. 使わなくなった設定を片付ける**

- 方法 2・方法 3 の環境: 正規証明書でつながることを確かめてから、[方法 2 の手順 4](#method-2) のとおり、`ingress-nginx` Namespace の出荷時の Secret（残っている場合）と、アップデートの前に作った一時的な Secret を削除します。入口が参照している Secret（手順 2 の `SECRET`）は削除しないでください

- 方法 3 の環境: v3.3.x までの手順で入れた、各サービスの cert-manager 連携を止めます。止めないと、使われなくなった Ingress ごとの証明書の更新が、失敗を繰り返します

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

  # 管理画面
  HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
    --version 3.4.0 --reuse-values \
    --set global.ingress.tls.useCertManager=false \
    -n agentic-star-admin

  # 認証サービス
  HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/agentic-star-auth \
    --version 3.4.0 --reuse-values \
    --set global.ingress.tls.useCertManager=false \
    -n librechat-auth

  # 外部 API
  HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
    --version 3.4.0 --reuse-values \
    --set global.ingress.tls.useCertManager=false \
    -n agenticai-extapi-service
  ```

  その後、`kubectl get certificate -A` で、各サービスの Namespace に Certificate が残っていれば削除します（`ingress-nginx` Namespace の `app-tls-cert` は削除しないでください）。

### アップデートで `entry` が失敗になった場合

完了画面のエラーメッセージに、HTTPS のリスナーと証明書の Secret についての記載がある場合は、入口が使う証明書の Secret が `ingress-nginx` Namespace にありません。入口は ingress-nginx のまま動いています。

1. [出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B) の `kubectl get gateway` のコマンドで、`SECRET` に表示される名前を確かめる
2. 「アップデートの前に確かめること」の `kubectl create secret tls` のコマンドで、その名前の Secret を `ingress-nginx` Namespace に作る
3. `CERT` が `True` になったことを確かめてから、バージョン管理画面で同じバージョンへのアップデートをもう一度実行する（更新済みのサービスはスキップされ、切り替えがやり直されます）
4. 「アップデートの直後に行うこと」を行う

## 認証サーバーの外の入口（外部ツールでのログイン）

認証サーバーには、利用者が外部ツール（Claude Code・Codex などの AI クライアントや、OIDC に対応したアプリケーション）から自分のアカウントでログインし、ユーザー API や MCP を使うための外の入口があります。**既定では閉じています。** 開け閉めは、インストール後に管理者がコマンドで行います。外部ツール側の準備（クライアントの作成・承認の運用）は [API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md)を参照してください。外部ツールのクライアントには、メイン画面と同じく管理者の承認とメールアドレスの確認が済んだ利用者だけを通すログインの流れを付けてください（[ログインの流れを付ける](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#login-flow)）。

コマンドの使い方は、v3.3.x までの環境でも同じです。v3.3.x までの環境で異なる点は、[認証サーバーの外の入口（v3.3.x まで）](#v33-kc)を参照してください。

### 何が外に出るか

開けると、認証サーバーのうちログインに要る **12 本の道だけ** が外に出ます（`<realm>` はインストーラーの `config.yaml` の `keycloak.realm_name`）。

| 一致   | パス                                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------------------------- |
| 完全一致 | `/realms/<realm>/protocol/openid-connect/auth`・`token`・`certs`・`userinfo`・`logout`・`logout/logout-confirm`・`revoke` |
| 完全一致 | `/realms/<realm>/.well-known/openid-configuration`、`/.well-known/oauth-authorization-server/realms/<realm>`         |
| 前方一致 | `/realms/<realm>/login-actions/`、`/realms/<realm>/broker/`、`/resources/`                                            |

認証サーバーのコンソールや管理 API は外に出ません。メイン画面のログインの流れも変わりません。

### 前提

- コマンド `kc_direct_login.sh` は、インストーラーの配布物（zip）に入っています。インストールした端末に残っていない場合は、配布場所から同じバージョンの zip を取得してください
- v3.4.0 にアップデートした環境では、アップデート後のバージョンの配布物のコマンドを使ってください。v3.3.x までの配布物のコマンドは、入口（NGINX Gateway Fabric）に対応していません
- 実行する端末に `kubectl`（対象クラスターに接続済み）・`helm` 3.14 以上・`yq`・`openssl`・`curl` が必要です。コマンドは `config.yaml` を読まず、接続先のクラスターから必要な値を読みます
- `keycloak-extensions`・`init-platform`・`agenticai-extapi` の各チャートが、配布物のバージョン以上であること。古い場合はコマンドが止まるので、先に GUI からアップグレードしてください

### 開ける

```bash
bash kc_direct_login.sh open --address <ドメイン|auto>
```

| `--address` の値         | 使える環境            | 動き                                                           |
| ---------------------- | ---------------- | ------------------------------------------------------------ |
| `kc.example.com`（ドメイン） | すべて              | 認証サーバーが外に名乗る住所をこのドメインにする。スキーム（`https://`）・パス・ポートは付けず、英小文字で書く |
| `auto`                 | ドメインを設定していない環境のみ | `ingress-nginx-kc` に割り当てられた IP（AWS は NLB の DNS 名）を住所にする      |

コマンドは、実行の前に「認証サーバーが入れ替わること」と、出荷時の自己署名証明書を使っている環境では「今の 4 つの入口の証明書も作り直すこと」を表示して確認を求めます（`--yes` で省略できます）。その後、次の順に進みます。

1. ドメインを設定していない環境では、5 つ目の LoadBalancer `ingress-nginx-kc` を作り、アドレスの割り当てを待つ（認証サービスの LoadBalancer に送信元 IP の制限 `loadBalancerSourceRanges` があれば、同じ制限をコピーする）
2. 出荷時の自己署名証明書を使っている環境では、証明書に認証サーバーの住所を足して作り直し、入口が使う `ingress-nginx` Namespace を含む 5 つの Namespace の Secret を置き換える
3. 認証サーバーに外の住所の設定を渡して入れ替える
4. 入口の Gateway `kc` に、認証サーバーへの経路（`librechat-auth` Namespace の HTTPRoute `keycloak-direct-login`）を作る
5. 外から見たディスカバリー（`/.well-known/openid-configuration`）の発行元が外の住所になったことを確かめる
6. 外部 API に、外の入口で出たトークンの発行元（`https://<住所>/realms/<realm>`）を渡す

終わると、外の住所・発行元・外の口のアドレスを表示します。ドメインを指定した場合は、そのドメインの DNS レコードを `ingress-nginx-kc` のアドレスに向けてください（[DNS レコードの設定](#1-%E3%83%89%E3%83%A1%E3%82%A4%E3%83%B3%E3%82%92%E5%8F%96%E5%BE%97%E3%81%97-dns-%E3%83%AC%E3%82%B3%E3%83%BC%E3%83%89%E3%82%92%E8%A8%AD%E5%AE%9A)）。

外の入口の証明書と HTTP の扱いは、ほかの 4 つの入口と同じく、入口の設定（Gateway `kc`）で決まります。[方法 1〜3](#ssl-%E8%A8%AD%E5%AE%9A%E6%96%B9%E6%B3%95%E3%81%AE%E9%81%B8%E6%8A%9E) の手順は、Gateway `kc` も一緒に設定します。正規証明書を使う場合は、証明書に認証サーバーのドメインを含めてください。

> **初めからドメインを設定してインストールした環境**
>
> LoadBalancer を個別に持たない環境では、コマンドは `ingress-nginx-kc` を作りません。今の 4 つの入口と同じ経路（前段の CDN / ロードバランサー）に、認証サーバーのドメインの行き先として、入口の Gateway `kc`（`ingress-nginx` Namespace の Service `kc-agentic-star-edge`）を足し、証明書を用意してください（[方法 1〜3](#ssl-%E8%A8%AD%E5%AE%9A%E6%96%B9%E6%B3%95%E3%81%AE%E9%81%B8%E6%8A%9E)）。

### 閉じる

```bash
bash kc_direct_login.sh close
```

外部 API から発行元を外し、認証サーバーの外の住所の設定を消して入れ替え、`ingress-nginx-kc` と、入口の認証サーバーへの経路（HTTPRoute `keycloak-direct-login`）を削除します。外部ツールで取得したトークンは、閉じた時点で外部 API で使えなくなります。入口の Gateway `kc` と、その証明書・HTTP の扱いの設定は残り、次に開けるときに使われます。

### 状態を見る

```bash
bash kc_direct_login.sh status
```

開いているか（開いている・閉じている・途中）、realm、外の住所、外部 API の発行元、`ingress-nginx-kc` のアドレス、入口の認証サーバーへの経路（HTTPRoute）の有無、証明書の種類（出荷時の自己署名証明書か、購入者の証明書か）、各チャートのバージョンを表示します。「途中」は開け閉めが途中で止まった状態なので、`open` か `close` を実行し直してください。

### 住所を変える

新しいドメインで `open` を実行し直します。外の住所と、外部 API の発行元が入れ替わります。発行元が変わるので、**外部ツールを使っている利用者はログインし直します。** 出荷時の自己署名証明書を使っている環境で `ingress-nginx-kc` の IP（AWS は NLB の DNS 名）が変わった場合は、確認のうえ証明書を作り直します。

### ドメインを設定していない環境での注意

- 開けるときに作り直す自己署名証明書は、既存の 4 つの入口と共有の 1 枚です。作り直すと、利用者のブラウザで証明書の警告が出直します
- 外部ツールは、出荷時の自己署名証明書のままではつながりません。確かめる間だけつなぐ手順（Claude Code・Codex）は [AI クライアント接続ガイド（MCP） — ドメインを設定していない環境で確かめるとき](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/ai-client-guide.md#self-signed) を参照してください。外部ツールでのログインを本番で使う場合は、正式なドメインと証明書を設定してください

> **開け閉めのたびに認証サーバーが入れ替わる**
>
> 外の住所の設定は認証サーバーの起動時の設定なので、開ける・閉じる・住所を変えるたびに認証サーバーが再起動します。出荷時の構成（認証サーバー 1 台）では、その間メイン画面のログインとトークンの更新もできません。利用者の少ない時間に行ってください。

> **接続元を制限したい場合**
>
> 外の入口そのものには、接続元 IP やリクエスト回数の制限はありません（利用者ごとのログイン失敗のロックは認証サーバーが行います）。IP で制限したい場合は、前段に WAF を置くか、`ingress-nginx-kc` の `loadBalancerSourceRanges` を設定してください（[方法 1](#method-1)）。

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

v3.4.0 以降（入口が NGINX Gateway Fabric）の環境の確認方法です。v3.3.x までの環境は、[トラブルシューティング（v3.3.x まで）](#v33-troubleshooting)を参照してください。

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

```bash
# Gateway の状態確認（PROGRAMMED が True か）
kubectl get gateway -n ingress-nginx

# リスナーと証明書の状態確認（<name> は front・admin・auth・extapi・kc）
kubectl describe gateway <name> -n ingress-nginx

# TLS Secret の存在確認（<Secret 名> は、出荷時の状態の kubectl get gateway のコマンドの SECRET）
kubectl get secret <Secret 名> -n ingress-nginx

# 各サービスの HTTPRoute の状態確認
kubectl get httproute -A

# 入口のログ確認
kubectl logs -n ingress-nginx deployment/<name>-agentic-star-edge
kubectl logs -n ingress-nginx deployment/nginx-gateway
```

**よくある原因:**

- ブラウザで証明書例外を許可していない
- TLS Secret が `ingress-nginx` Namespace に存在しない
- 入口の Pod が再起動中

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

```bash
HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx
```

出力には、接続のパスワードなどの秘密の値が含まれることがあります。画面の共有やファイルへの保存に注意してください。

### 証明書を切り替えた後に HTTPS でつながらない

```bash
kubectl describe gateway <name> -n ingress-nginx
```

`https` のリスナーの `ResolvedRefs` が `False` の場合は、リスナーが参照している Secret を読めていません。

**よくある原因:**

- Secret が `ingress-nginx` Namespace に無い（各サービスの Namespace に作っている）
- Secret の名前が、入口の設定（`gateways[].listeners.https.certificateRef.name`）と違う
- Secret の種類が `kubernetes.io/tls` でない、または証明書と秘密鍵の組が正しくない

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

```bash
# Certificate リソースの状態確認
kubectl describe certificate app-tls-cert -n ingress-nginx

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

# Challenge リソースで ACME 検証状況確認
kubectl get challenge -n ingress-nginx

# チャレンジ用の HTTPRoute が Gateway に受け付けられているか確認
kubectl get httproute -n ingress-nginx
```

**よくある原因:**

- DNS が LoadBalancer のエンドポイントを指していない（Azure/GCP は A レコードで IP、AWS は CNAME で ELB DNS 名）
- ポート 80 へのアクセスがブロックされている
- cert-manager で Gateway API を有効にしていない（[方法 3 の手順 1](#method-3)）
- 入口の HTTP の転送を止めている（[方法 1](#method-1) と組み合わせている）
- ClusterIssuer のメールアドレスが無効

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

```bash
kubectl get httproute -n ingress-nginx
```

転送用の HTTPRoute（`front-https-redirect` など）が無い場合は、入口の `gateways[].httpsRedirect` が `false` になっています。[入口の設定を変える](#edge-settings) の手順で `true` に戻してください。

## v3.3.x までの手順（ingress-nginx）

この節は、入口が ingress-nginx の環境（v3.3.x まで）の手順です。v3.4.0 以降の環境では、この節の設定（`global.ingress.tls.*`・Ingress の注釈）は使われません。v3.4.0 以降の環境は、このページの本文の手順を使ってください。

出荷時の状態（エンドポイントの構成・制限事項）、SSL 設定方法の選択、共通手順の 1〜3（DNS レコードの設定・チャートバージョンの確認・Helm リポジトリの追加）は、v3.4.0 以降と同じです。本文の [出荷時の状態](#%E5%87%BA%E8%8D%B7%E6%99%82%E3%81%AE%E7%8A%B6%E6%85%8B)・[SSL 設定方法の選択](#ssl-%E8%A8%AD%E5%AE%9A%E6%96%B9%E6%B3%95%E3%81%AE%E9%81%B8%E6%8A%9E)・[アップグレード共通手順](#%E3%82%A2%E3%83%83%E3%83%97%E3%82%B0%E3%83%AC%E3%83%BC%E3%83%89%E5%85%B1%E9%80%9A%E6%89%8B%E9%A0%86) を参照してください。v3.3.x までは、次の点が異なります。

- 入口は ingress-nginx（Ingress Controller）で、Gateway はありません。方法 2・方法 3 の SSL 終端は Ingress です
- 自己署名証明書の Secret `selfsigned-tls-cert` は、5 つの Namespace（`agentic-star-front`・`agentic-star-admin`・`librechat-auth`・`agenticai-extapi-service`・`ingress-nginx`）にあり、各サービスの Ingress が参照しています
- チャートのバージョンの例は `agentic-star-front-3.3.0`、`agenticai-admin-3.3.0` 等です

### ドメイン / URL 設定を更新（v3.3.x まで）

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

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

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

```bash
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/agentic-star-front \
  --version 3.3.0 \
  --reuse-values \
  --set appConfig.domainClient="https://chat.example.com" \
  --set appConfig.domainServer="https://chat.example.com" \
  --set appConfig.authBaseUrl="https://auth.example.com" \
  --set ingress.main.annotations."nginx\.ingress\.kubernetes\.io/server-alias"="chat.example.com" \
  --set ingress.monitoring.annotations."nginx\.ingress\.kubernetes\.io/server-alias"="chat.example.com" \
  --set ingress.vnc.annotations."nginx\.ingress\.kubernetes\.io/server-alias"="chat.example.com" \
  -n agentic-star-front
```

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

```bash
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 3.3.0 \
  --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" \
  --set env.EXTAPI_PUBLIC_URL="https://api.example.com" \
  --set env.MP_OAUTH_TOKEN_URL="https://auth.example.com/api/v1/oauth/token" \
  --set env.AUTH_PUBLIC_URL="https://auth.example.com" \
  --set env.ADMIN_PUBLIC_URL="https://admin.example.com" \
  --set ingress.client.annotations."nginx\.ingress\.kubernetes\.io/server-alias"="admin.example.com" \
  -n agentic-star-admin
```

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

```bash
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/agentic-star-auth \
  --version 3.3.0 \
  --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\,https://auth.example.com/*\,https://admin.example.com/*" \
  --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" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/server-alias"="auth.example.com" \
  -n librechat-auth
```

**認証基盤（keycloak-extensions）:**

パスキーの確認に使う `WEBAUTHN_RP_ID`・`WEBAUTHN_ORIGIN` を、認証サービスの新しいドメインに直します。この 2 つは `keycloakx.extraEnv`（複数行の文字列）の中にあるため、今の値を取り出して書き換えてから適用します。

```bash
HELM_DRIVER=configmap helm get values keycloak-extensions -n librechat-auth -o yaml > keycloak-extensions-values.yaml
```

`keycloak-extensions-values.yaml` の `keycloakx.extraEnv` の中で、`WEBAUTHN_RP_ID` の value を `auth.example.com` に、`WEBAUTHN_ORIGIN` の value を `https://auth.example.com` に書き換えてから、次を実行します。

```bash
HELM_DRIVER=configmap helm upgrade keycloak-extensions agenticai-prod/keycloak-extensions \
  --version 3.3.0 \
  --reuse-values \
  -f keycloak-extensions-values.yaml \
  -n librechat-auth
```

取り出したファイルには接続のパスワードなどの秘密の値が含まれます。作業の後に削除してください。

**外部 API（agenticai-extapi）:**

```bash
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 3.3.0 \
  --reuse-values \
  --set config.APIGW_PUBLIC_URL="https://api.example.com" \
  --set config.A2A_PUBLIC_URL="https://api.example.com" \
  --set config.MP_OAUTH_TOKEN_URL="https://auth.example.com/api/v1/oauth/token" \
  --set ingress.annotations."nginx\.ingress\.kubernetes\.io/server-alias"="api.example.com" \
  -n agenticai-extapi-service
```

**認証サーバーの外の入口（開けている場合のみ）:**

認証サーバーの外の入口を開けている環境では、`helm upgrade` の代わりに開閉コマンドを新しいドメインで実行し直します。認証サーバーが外に名乗る URL（外の住所）・入口の別名・外部 API に渡すトークンの発行元の 3 つを一度に入れ替え、発行元が切り替わったことまで確かめます。手で `helm upgrade` する場合に渡す値は [Helm Values リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/reference/helm-values-ref.md#kc-direct-login-values)を参照してください。

```bash
bash kc_direct_login.sh open --address kc.example.com
```

発行元が変わるため、外部ツールを使っている利用者はログインし直す必要があります。

> **注記**
>
> - 各サービスの `server-alias` は、Ingress が受け付けるホスト名です。新しいドメインに合わせて更新してください
> - 認証サーバーの外の入口を開けている場合、外部 API に渡すトークンの発行元は上の開閉コマンドが入れ替えます
> - `--set` でカンマを含む値を指定する場合は `\,` でエスケープしてください

### 方法 1: CDN / ロードバランサー経由（v3.3.x まで）

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

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

#### Helm でデプロイ

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

```bash
# メインアプリケーション
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/agentic-star-front \
  --version 3.3.0 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.main.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.main.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  --set ingress.monitoring.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.monitoring.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  --set ingress.vnc.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.vnc.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 3.3.0 --reuse-values \
  --set global.ingress.tls.enabled=false \
  --set ingress.client.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set ingress.client.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n agentic-star-admin

# 認証サービス
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/agentic-star-auth \
  --version 3.3.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 librechat-auth

# 外部 API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 3.3.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

# 認証サーバーの外の入口（開けている場合のみ。入口の TLS を外し、https への誘導を止める）
HELM_DRIVER=configmap helm upgrade keycloak-extensions agenticai-prod/keycloak-extensions \
  --version 3.3.0 --reuse-values \
  --set-json 'keycloakx.ingress.tls=[]' \
  --set keycloakx.ingress.annotations."nginx\.ingress\.kubernetes\.io/ssl-redirect"="false" \
  --set keycloakx.ingress.annotations."nginx\.ingress\.kubernetes\.io/force-ssl-redirect"="false" \
  -n librechat-auth
```

> **注記**
>
> 認証サーバーの入口（`keycloak-extensions`）は、他の 4 つのサービスと違い `global.ingress.tls.*` を読みません。TLS と注釈は `keycloakx.ingress.*` に直接渡します。開閉コマンドは、この値を最初に開けるときだけ入れ、その後は購入者が変えた値を残します。

#### クラウド別の構成

クラウド別の構成（Azure Front Door・AWS CloudFront + NLB・GCP Cloud Load Balancing）は、本文の [クラウド別の構成](#cloud-specific) と同じです。「入口の設定を更新」の手順は、上の「Helm でデプロイ」に読み替えてください。

### 方法 2: 外部証明書（v3.3.x まで）

外部で発行した証明書を 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 を再デプロイしてください。
>
> 認証サーバーの外の入口を開けている場合は、`librechat-auth` Namespace の `app-tls-cert` を認証サービスと認証サーバーの入口で共有します。証明書の SAN に認証サーバーのドメイン（例 `kc.example.com`）も含めてください。

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

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

```bash
# メインアプリケーション
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/agentic-star-front \
  --version 3.3.0 --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 3.3.0 --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/agentic-star-auth \
  --version 3.3.0 --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 3.3.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

# 認証サーバーの外の入口（開けている場合のみ。認証サービスと同じ Secret を使う）
HELM_DRIVER=configmap helm upgrade keycloak-extensions agenticai-prod/keycloak-extensions \
  --version 3.3.0 --reuse-values \
  --set keycloakx.ingress.tls[0].hosts[0]="kc.agentic.internal" \
  --set keycloakx.ingress.tls[0].secretName="app-tls-cert" \
  -n librechat-auth
```

### 方法 3: Let's Encrypt 自動発行（v3.3.x まで）

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` を作り、`email` を通知を受けるメールアドレスに変えてから適用します（名前 `letsencrypt-prod` は次の手順で使います）。

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx
```

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

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

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

```bash
# メインアプリケーション
HELM_DRIVER=configmap helm upgrade librechat agenticai-prod/agentic-star-front \
  --version 3.3.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" \
  --set global.domain="chat.example.com" \
  -n agentic-star-front

# 管理画面
HELM_DRIVER=configmap helm upgrade agenticai-admin agenticai-prod/agenticai-admin \
  --version 3.3.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" \
  --set ingress.client.host="admin.example.com" \
  -n agentic-star-admin

# 認証サービス
HELM_DRIVER=configmap helm upgrade librechat-auth agenticai-prod/agentic-star-auth \
  --version 3.3.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" \
  --set ingress.host="auth.example.com" \
  -n librechat-auth

# 外部 API
HELM_DRIVER=configmap helm upgrade agenticai-extapi agenticai-prod/agenticai-extapi \
  --version 3.3.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" \
  --set-json 'ingress.hosts=[{"host":"api.example.com","paths":[{"path":"/","pathType":"Prefix"}]}]' \
  -n agenticai-extapi-service
```

> **注記**
>
> Let's Encrypt は、証明書の名前（ホスト名）に独自ドメインを求めます。上のコマンドは各サービスの Ingress のホスト名を独自ドメイン（例: `chat.example.com`・`admin.example.com`・`auth.example.com`・`api.example.com`）にします。「ドメイン / URL 設定を更新」のドメインと同じ値にしてください。ホスト名を変えた後は、LoadBalancer の IP アドレスでは画面を開けません。

> **注記**
>
> 認証サーバーの外の入口は、方法 3 の対象外です。外の入口は今の証明書のまま使います。

> **注記**
>
> 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>
```

### 認証サーバーの外の入口（v3.3.x まで）

開け閉め・状態の確認・住所の変更のコマンドは、本文の [認証サーバーの外の入口（外部ツールでのログイン）](#kc-direct-login) と同じです。v3.3.x までは、次の点が異なります。

- 外の入口は ingress-nginx の Ingress（`librechat-auth` Namespace の `keycloak-extensions-keycloakx`）で、Gateway と HTTPRoute は使いません。開けるときは、認証サーバーに外の住所と入口の設定を渡して入れ替えます（本文の「開ける」の手順 4 はありません）
- 証明書（TLS の Secret 名）と `https` への誘導は、Ingress の値（`keycloakx.ingress.tls`・`keycloakx.ingress.annotations`）で決まります。開閉コマンドは、この値を最初に開けるときだけ入れ、その後は購入者が変えた値を残します。閉じてもこの値は残り、次に開けるときに使われます（方法 1・方法 2 の、認証サーバーの外の入口のコマンド）
- 住所を変えると、外の住所・入口の別名（`server-alias`）・外部 API の発行元が入れ替わります
- 出荷時の自己署名証明書を作り直すときは、5 つの Namespace の `selfsigned-tls-cert` を置き換えます
- 初めからドメインを設定してインストールした環境では、今の 4 つの入口と同じ経路（前段の CDN / ロードバランサー、または Ingress Controller）に認証サーバーのドメインの行き先を足し、証明書を用意します（方法 1〜3 の認証サーバーの行）

### トラブルシューティング（v3.3.x まで）

#### 出荷時の自己署名証明書でログインできない（v3.3.x まで）

```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 設定を確認する（v3.3.x まで）

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

#### 証明書が発行されない（Let's Encrypt。v3.3.x まで）

```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 にリダイレクトされない（v3.3.x まで）

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

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