ドメイン設定ガイド
AGENTIC STAR マーケットプレイス版のカスタムドメイン設定と SSL 証明書のアップグレード手順を解説します。
対象バージョンと入口の確認
AGENTIC STAR の入口(ブラウザーや API からの要求を受ける部分)は、バージョンによって異なります。証明書などの設定先が違うため、先に環境の入口を確かめ、対応する節の手順を使ってください。
| バージョン | 入口 | 使う手順 |
|---|---|---|
| v3.4.0 以降 | NGINX Gateway Fabric(Gateway API の Gateway・HTTPRoute) | このページの本文(出荷時の状態 から トラブルシューティング まで) |
| v3.3.x まで | ingress-nginx(Ingress) | v3.3.x までの手順(ingress-nginx) |
入口は次のコマンドで確かめられます。
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 までの手順で設定した証明書や、CDN・ロードバランサーを前に置くための設定は、v3.4.0 以降の入口では使われません。独自のドメインを設定している環境は、v3.3.x からアップデートした環境の設定の移行 を行ってください。
出荷時の状態
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 へ転送されます。
LoadBalancer の Service 名(ingress-nginx-front など)と Namespace 名(ingress-nginx)は、v3.3.x までと同じです。v3.4.0 以降の新しい環境に、ingress-nginx そのものは入っていません。
Gateway の状態と、HTTPS のリスナーが参照している Secret の名前は、次のコマンドで確かめられます(以降の手順でも、設定の確認に使います)。
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。環境によって名前が異なる場合は、表示された名前を以降の手順で使います)。
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
認証サーバーには、外部ツール(Claude Code・Codex などの AI クライアントや、OIDC に対応したアプリケーション)から利用者が自分のアカウントでログインするための 5 つ目の入口 があります。出荷時は閉じていて、上の表の 4 つだけが外に出ています。開けると ingress-nginx-kc が 5 つ目の LoadBalancer として増えます(Gateway kc は、閉じている間も置かれています)。開け方・閉じ方は認証サーバーの外の入口(外部ツールでのログイン)を参照してください。
クラウドによるエンドポイント表記の違い
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 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 | 認証サーバーの外の入口(開けている場合のみ) |
クラウド別の DNS 設定例
Azure / GCP(A レコードで IP を指定):
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 名を指定):
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 チャートバージョンを確認
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 リポジトリを追加
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):
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):
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):
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(複数行の文字列)の中にあるため、今の値を取り出して書き換えてから適用します。
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 に書き換えてから、次を実行します。
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):
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 リファレンスを参照してください。
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 の値をファイルに取り出す
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・方法 2・方法 3 の手順に書いてあります。
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
--version には、共通手順 2 で確かめた agentic-star-edge の現在のバージョンを指定します。設定を変えても、LoadBalancer のアドレス(IP アドレス・ELB DNS 名)は変わりません。
4. 確かめる
出荷時の状態 の 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)でつなぎます。
ユーザー → HTTPS (443) → CDN / ロードバランサー (SSL 終端) → HTTP (80) → 入口(NGINX Gateway Fabric) → Pod
出荷時の入口は、HTTP(80)で届いた要求を HTTPS へ転送します。CDN / ロードバランサーから HTTP(80)で入口につなぐ構成では、この転送を止めて、HTTP(80)で届いた要求をアプリケーションへ届けるようにします。
入口の HTTP の転送を止める
# 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)も、同じ手順で一緒に変わります。
適用の後、次のコマンドで確かめます。
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・セキュリティグループの手順)。
利用者の 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 を作り、値を環境に合わせてから適用します。
realIp:
enabled: true
header: X-Forwarded-For
trustedCidrsCsv: "203.0.113.0/24,198.51.100.0/24"
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
今の設定は、次のコマンドで確かめられます。
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 設定を実現できます。
主な手順:
- DNS ゾーンを作成し NS 委任を設定
- AFD プロファイル・WAF ポリシーを作成
- カスタムドメインを登録し証明書を発行
- オリジングループに各 LoadBalancer(
ingress-nginx-frontなど)の IP を登録(認証サーバーの外の入口を開けている場合はingress-nginx-kcの IP を 5 つ目のオリジンとして登録) - ルーティングルールでドメインとオリジンを紐付け(認証サーバーのドメインも同様に紐付け)
- NSG ルールを更新(AFD からのアクセスのみ許可)
- 入口の設定を更新(上の「入口の HTTP の転送を止める」と「利用者の IP アドレスの設定」)
AWS: CloudFront + NLB
AWS Marketplace 版では LoadBalancer として NLB が払い出されるため、CloudFront のオリジンには NLB の DNS 名を直接指定 する構成を推奨します。NLB の IP は AWS 側で変動しうるため、ALB のターゲットグループに IP 登録する従来構成は安定しません。
- ACM(AWS Certificate Manager)で証明書を発行(CloudFront 用は us-east-1 で発行する必要があります)
- CloudFront ディストリビューションを作成し、各 Service の NLB DNS 名 をオリジンに設定(用途別に 4 オリジン。認証サーバーの外の入口を開けている場合は
ingress-nginx-kcの NLB を 5 つ目に) - ビヘイビアでパス/ホストごとにオリジンを振り分け(認証サーバーのドメイン用のビヘイビアも足す)
- Route 53 で各カスタムドメインの CNAME(または Alias)を CloudFront ディストリビューションのドメインに向ける
- NLB のセキュリティグループを CloudFront 管理 Prefix List(
com.amazonaws.global.cloudfront.origin-facing)からのアクセスのみに制限 - 入口の設定を更新(上の「入口の 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
- Google-managed SSL 証明書を作成
- 外部 HTTPS ロードバランサーを作成
- バックエンドサービスに各 LoadBalancer(
ingress-nginx-frontなど)の IP を登録(認証サーバーの外の入口を開けている場合はingress-nginx-kcの IP もバックエンドに足し、URL マップのホストルールで認証サーバーのドメインをそのバックエンドに向ける) - Cloud DNS で DNS を設定
- 入口の設定を更新(上の「入口の HTTP の転送を止める」と「利用者の IP アドレスの設定」)
方法 2: 外部証明書
外部で発行した証明書を入口(NGINX Gateway Fabric)で使用します。
ユーザー → HTTPS (443) → 入口(NGINX Gateway Fabric)(SSL 終端 / 正規証明書) → HTTP → Pod
手順
1. 証明書を Kubernetes Secret として登録
入口が読む Secret は、ingress-nginx Namespace に置きます(各サービスの Namespace に置く必要はありません)。
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. 入口の証明書を切り替える
# 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. 確認
出荷時の状態 の kubectl get gateway のコマンドで、5 つの Gateway の SECRET が app-tls-cert、PROGRAMMED と CERT が True であることを確かめます。続けて、外から証明書を確かめます。
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(出荷時の状態 の kubectl get gateway の SECRET に表示されていた名前。例: selfsigned-tls-cert)を削除します。
kubectl delete secret <出荷時の Secret 名> -n ingress-nginx
出荷時の Secret が残っていると、後のアップデートで、入口の証明書の設定がこの Secret に戻ることがあります。入口が今参照している Secret(手順 3 の SECRET に表示される名前)は、削除しないでください。
証明書を更新するとき
有効期限の前に証明書を入れ替えるときは、同じ名前の Secret の中身を新しい証明書に置き換えます。入口の設定を変える必要はありません。
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 を通して行います。
ユーザー → 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 で転送を止めた環境では、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 以前からアップデートした環境では、構築したときのバージョンのままのことがあります。
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 が表示されれば、有効になっています。
kubectl get configmap cert-manager -n cert-manager -o jsonpath='{.data.config\.yaml}'
2. ClusterIssuer を作成
次の内容で cluster-issuer.yaml を作り、email を通知を受けるメールアドレスに変えてから適用します(名前 letsencrypt-prod は次の手順で使います)。parentRefs には、入口の 5 つの Gateway を書きます。
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
kubectl apply -f cluster-issuer.yaml
kubectl get clusterissuer letsencrypt-prod
READY が True であることを確かめます。
3. 証明書(Certificate)を作成
次の内容で certificate.yaml を作り、dnsNames を共通手順 4 で設定したドメインに変えてから適用します。Certificate は、入口と同じ ingress-nginx Namespace に作ります。
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
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 と同じコマンドで、入口の証明書を app-tls-cert に切り替えます。Secret ができる前に切り替えると、入口が証明書を読めず、HTTPS でつながらなくなります。
5. 確認と、出荷時の Secret の削除
方法 2 の手順 3・手順 4 と同じ手順で、証明書が切り替わったことを確かめ、出荷時の自己署名証明書の Secret を削除します。証明書の更新は cert-manager が自動で行い、入口の設定を変える必要はありません。
接続元を制限している環境や、方法 1 と組み合わせる環境では、ClusterIssuer の solvers に DNS-01 の solver を指定してください(設定は cert-manager の文書を参照)。手順 3 以降は同じです。DNS-01 では、手順 1 の Gateway API の有効化は要りません。
v3.3.x からアップデートした環境の設定の移行
v3.3.x から v3.4.0 へのアップデート(更新ガイドの「A-10. v3.4.0 へのアップデートでの入口の切り替え」)で、入口は ingress-nginx から NGINX Gateway Fabric に切り替わります。v3.3.x までの手順で Ingress に入れた設定は、切り替えの後は使われません。独自のドメインを設定している環境は、この節の手順で、入口に設定を入れ直してください。
引き継がれる設定と、入れ直す設定
| v3.3.x までの設定 | アップデートの後 | 行う作業 |
|---|---|---|
| DNS レコード・LoadBalancer のアドレス | 変わらない | なし |
| 各サービスのドメイン / URL の設定(共通手順 4 の値) | 引き継がれる。入口はホスト名を限定せずに受け付けるため、server-alias に当たる設定は要らない | なし |
LoadBalancer の接続元の制限(loadBalancerSourceRanges) | 引き継がれる | なし |
| 入口の接続元の制限・利用者の IP アドレスの設定(ingress-nginx の設定) | 引き継がれる | なし(利用者の IP アドレスの設定 のコマンドで確かめられる) |
方法 1(CDN / ロードバランサー経由)の ssl-redirect の設定 | 引き継がれない。入口は HTTP(80)で届いた要求を HTTPS へ転送する | 方法 1 の「入口の HTTP の転送を止める」 |
| 方法 2(外部証明書)の証明書 | 下の「入口が使う証明書」のとおり。ingress-nginx の既定の証明書を ingress-nginx/app-tls-cert にしてあれば、引き継がれる | 確かめて、正規証明書でなければ 方法 2 |
| 方法 3(Let's Encrypt)の証明書 | 引き継がれない(Ingress ごとに発行した証明書は使われない) | 方法 3 で発行し直す |
| 認証サーバーの外の入口 | 入口と一緒に切り替わる。証明書と HTTP の扱いは、ほかの 4 つと同じ入口の設定で決まる | 上の作業に含まれる(証明書には認証サーバーのドメインも含める) |
入口が使う証明書
切り替えのとき、入口(NGINX Gateway Fabric)が使う証明書の Secret は、次の順で決まります。
- ingress-nginx の既定の証明書(
--default-ssl-certificate)がingress-nginxNamespace の Secret を指していて、その Secret があれば、その Secret - 1 に当たらなければ、
ingress-nginxNamespace の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 を確かめます。
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 を作っておきます。
kubectl create secret tls <Secret 名> \
--cert=tls.crt --key=tls.key \
-n ingress-nginx
-
方法 2(外部証明書)の環境: 正規証明書(
tls.crt・tls.key)で作ります。入口は、切り替えの直後から正規証明書を使います -
方法 3(Let's Encrypt)の環境: 一時的な自己署名証明書で作り、アップデートの直後に 方法 3 で発行し直します。一時的な証明書の間は、ブラウザに証明書の警告が表示されます
curlopenssl 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 に名前が表示されることを確かめます。完了画面で entry が失敗になった場合は、下の「アップデートで entry が失敗になった場合」を参照してください。
2. 入口の状態と証明書を確かめる
出荷時の状態 の kubectl get gateway のコマンドで、5 つの Gateway の PROGRAMMED と CERT が True であることと、SECRET の名前を確かめます。
3. v3.3.x までの構成に合わせて、入口に設定を入れる
- 方法 1 の環境: 入口の HTTP の転送を止める。CDN / ロードバランサーを通してつながることを確かめる
- 方法 2 の環境:
SECRETが正規証明書の Secret でなければ、方法 2 の手順 1〜3 を行う。app-tls-certがingress-nginxNamespace に既にある場合は、手順 1 は要らない - 方法 3 の環境: 方法 3 の手順 1〜5 を行う。手順 2 の
kubectl applyで、v3.3.x までの ClusterIssuer(Ingress を使う設定)は、Gateway を使う設定に置き換わる
4. 各ドメインでつながることを確かめる
ブラウザで各ドメインを開き、証明書の警告が出ないことと、ログインできることを確かめます。
5. 使わなくなった設定を片付ける
-
方法 2・方法 3 の環境: 正規証明書でつながることを確かめてから、方法 2 の手順 4 のとおり、
ingress-nginxNamespace の出荷時の Secret(残っている場合)と、アップデートの前に作った一時的な Secret を削除します。入口が参照している Secret(手順 2 のSECRET)は削除しないでください -
方法 3 の環境: v3.3.x までの手順で入れた、各サービスの cert-manager 連携を止めます。止めないと、使われなくなった Ingress ごとの証明書の更新が、失敗を繰り返します
curl# メインアプリケーション
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-nginxNamespace のapp-tls-certは削除しないでください)。
アップデートで entry が失敗になった場合
完了画面のエラーメッセージに、HTTPS のリスナーと証明書の Secret についての記載がある場合は、入口が使う証明書の Secret が ingress-nginx Namespace にありません。入口は ingress-nginx のまま動いています。
- 出荷時の状態 の
kubectl get gatewayのコマンドで、SECRETに表示される名前を確かめる - 「アップデートの前に確かめること」の
kubectl create secret tlsのコマンドで、その名前の Secret をingress-nginxNamespace に作る CERTがTrueになったことを確かめてから、バージョン管理画面で同じバージョンへのアップデートをもう一度実行する(更新済みのサービスはスキップされ、切り替えがやり直されます)- 「アップデートの直後に行うこと」を行う
認証サーバーの外の入口(外部ツールでのログイン)
認証サーバーには、利用者が外部ツール(Claude Code・Codex などの AI クライアントや、OIDC に対応したアプリケーション)から自分のアカウントでログインし、ユーザー API や MCP を使うための外の入口があります。既定では閉じています。 開け閉めは、インストール後に管理者がコマンドで行います。外部ツール側の準備(クライアントの作成・承認の運用)は API 利用準備ガイドを参照してください。外部ツールのクライアントには、メイン画面と同じく管理者の承認とメールアドレスの確認が済んだ利用者だけを通すログインの流れを付けてください(ログインの流れを付ける)。
コマンドの使い方は、v3.3.x までの環境でも同じです。v3.3.x までの環境で異なる点は、認証サーバーの外の入口(v3.3.x まで)を参照してください。
何が外に出るか
開けると、認証サーバーのうちログインに要る 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(対象クラスターに接続済み)・helm3.14 以上・yq・openssl・curlが必要です。コマンドはconfig.yamlを読まず、接続先のクラスターから必要な値を読みます keycloak-extensions・init-platform・agenticai-extapiの各チャートが、配布物のバージョン以上であること。古い場合はコマンドが止まるので、先に GUI からアップグレードしてください
開ける
bash kc_direct_login.sh open --address <ドメイン|auto>
--address の値 | 使える環境 | 動き |
|---|---|---|
kc.example.com(ドメイン) | すべて | 認証サーバーが外に名乗る住所をこのドメインにする。スキーム(https://)・パス・ポートは付けず、英小文字で書く |
auto | ドメインを設定していない環境のみ | ingress-nginx-kc に割り当てられた IP(AWS は NLB の DNS 名)を住所にする |
コマンドは、実行の前に「認証サーバーが入れ替わること」と、出荷時の自己署名証明書を使っている環境では「今の 4 つの入口の証明書も作り直すこと」を表示して確認を求めます(--yes で省略できます)。その後、次の順に進みます。
- ドメインを設定していない環境では、5 つ目の LoadBalancer
ingress-nginx-kcを作り、アドレスの割り当てを待つ(認証サービスの LoadBalancer に送信元 IP の制限loadBalancerSourceRangesがあれば、同じ制限をコピーする) - 出荷時の自己署名証明書を使っている環境では、証明書に認証サーバーの住所を足して作り直し、入口が使う
ingress-nginxNamespace を含む 5 つの Namespace の Secret を置き換える - 認証サーバーに外の住所の設定を渡して入れ替える
- 入口の Gateway
kcに、認証サーバーへの経路(librechat-authNamespace の HTTPRoutekeycloak-direct-login)を作る - 外から見たディスカバリー(
/.well-known/openid-configuration)の発行元が外の住所になったことを確かめる - 外部 API に、外の入口で出たトークンの発行元(
https://<住所>/realms/<realm>)を渡す
終わると、外の住所・発行元・外の口のアドレスを表示します。ドメインを指定した場合は、そのドメインの DNS レコードを ingress-nginx-kc のアドレスに向けてください(DNS レコードの設定)。
外の入口の証明書と HTTP の扱いは、ほかの 4 つの入口と同じく、入口の設定(Gateway kc)で決まります。方法 1〜3 の手順は、Gateway kc も一緒に設定します。正規証明書を使う場合は、証明書に認証サーバーのドメインを含めてください。
LoadBalancer を個別に持たない環境では、コマンドは ingress-nginx-kc を作りません。今の 4 つの入口と同じ経路(前段の CDN / ロードバランサー)に、認証サーバーのドメインの行き先として、入口の Gateway kc(ingress-nginx Namespace の Service kc-agentic-star-edge)を足し、証明書を用意してください(方法 1〜3)。
閉じる
bash kc_direct_login.sh close
外部 API から発行元を外し、認証サーバーの外の住所の設定を消して入れ替え、ingress-nginx-kc と、入口の認証サーバーへの経路(HTTPRoute keycloak-direct-login)を削除します。外部ツールで取得したトークンは、閉じた時点で外部 API で使えなくなります。入口の Gateway kc と、その証明書・HTTP の扱いの設定は残り、次に開けるときに使われます。
状態を見る
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) — ドメインを設定していない環境で確かめるとき を参照してください。外部ツールでのログインを本番で使う場合は、正式なドメインと証明書を設定してください
外の住所の設定は認証サーバーの起動時の設定なので、開ける・閉じる・住所を変えるたびに認証サーバーが再起動します。出荷時の構成(認証サーバー 1 台)では、その間メイン画面のログインとトークンの更新もできません。利用者の少ない時間に行ってください。
外の入口そのものには、接続元 IP やリクエスト回数の制限はありません(利用者ごとのログイン失敗のロックは認証サーバーが行います)。IP で制限したい場合は、前段に WAF を置くか、ingress-nginx-kc の loadBalancerSourceRanges を設定してください(方法 1)。
トラブルシューティング
v3.4.0 以降(入口が NGINX Gateway Fabric)の環境の確認方法です。v3.3.x までの環境は、トラブルシューティング(v3.3.x まで)を参照してください。
出荷時の自己署名証明書でログインできない
# 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-nginxNamespace に存在しない - 入口の Pod が再起動中
現在適用されている入口の設定を確認する
HELM_DRIVER=configmap helm get values agentic-star-edge -n ingress-nginx
出力には、接続のパスワードなどの秘密の値が含まれることがあります。画面の共有やファイルへの保存に注意してください。
証明書を切り替えた後に HTTPS でつながらない
kubectl describe gateway <name> -n ingress-nginx
https のリスナーの ResolvedRefs が False の場合は、リスナーが参照している Secret を読めていません。
よくある原因:
- Secret が
ingress-nginxNamespace に無い(各サービスの Namespace に作っている) - Secret の名前が、入口の設定(
gateways[].listeners.https.certificateRef.name)と違う - Secret の種類が
kubernetes.io/tlsでない、または証明書と秘密鍵の組が正しくない
証明書が発行されない(Let's Encrypt)
# 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)
- 入口の HTTP の転送を止めている(方法 1 と組み合わせている)
- ClusterIssuer のメールアドレスが無効
HTTPS にリダイレクトされない
kubectl get httproute -n ingress-nginx
転送用の HTTPRoute(front-https-redirect など)が無い場合は、入口の gateways[].httpsRedirect が false になっています。入口の設定を変える の手順で 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 以降と同じです。本文の 出荷時の状態・SSL 設定方法の選択・アップグレード共通手順 を参照してください。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):
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):
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):
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(複数行の文字列)の中にあるため、今の値を取り出して書き換えてから適用します。
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 に書き換えてから、次を実行します。
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):
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 リファレンスを参照してください。
bash kc_direct_login.sh open --address kc.example.com
発行元が変わるため、外部ツールを使っている利用者はログインし直す必要があります。
- 各サービスの
server-aliasは、Ingress が受け付けるホスト名です。新しいドメインに合わせて更新してください - 認証サーバーの外の入口を開けている場合、外部 API に渡すトークンの発行元は上の開閉コマンドが入れ替えます
--setでカンマを含む値を指定する場合は\,でエスケープしてください
方法 1: CDN / ロードバランサー経由(v3.3.x まで)
クラウドサービスで SSL 終端を行い、Ingress 側の TLS は無効化します。
ユーザー → HTTPS (443) → CDN / ロードバランサー (SSL 終端) → HTTP (80) → Ingress Controller → Pod
Helm でデプロイ
各サービスに対して以下のコマンドを実行します。
# メインアプリケーション
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)は、本文の クラウド別の構成 と同じです。「入口の設定を更新」の手順は、上の「Helm でデプロイ」に読み替えてください。
方法 2: 外部証明書(v3.3.x まで)
外部で発行した証明書を Ingress で使用します。
ユーザー → HTTPS (443) → Ingress Controller (SSL 終端 / 正規証明書) → HTTP → Pod
1. 証明書を Kubernetes Secret として登録
既存の自己署名証明書 Secret を削除し、正規証明書で置き換えます。
# 既存の自己署名証明書 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 名を正規証明書に切り替えます。
# メインアプリケーション
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 証明書を自動発行・更新します。
ユーザー → 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 は次の手順で使います)。
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
kubectl apply -f cluster-issuer.yaml
2. Helm でデプロイ
各サービスに対して cert-manager 連携を有効化します。
# メインアプリケーション
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. 証明書発行を確認
kubectl get certificate -n <namespace>
kubectl describe certificate <cert-name> -n <namespace>
認証サーバーの外の入口(v3.3.x まで)
開け閉め・状態の確認・住所の変更のコマンドは、本文の 認証サーバーの外の入口(外部ツールでのログイン) と同じです。v3.3.x までは、次の点が異なります。
- 外の入口は ingress-nginx の Ingress(
librechat-authNamespace の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 まで)
# 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 まで)
HELM_DRIVER=configmap helm get values <release-name> -n <namespace>
証明書が発行されない(Let's Encrypt。v3.3.x まで)
# 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 まで)
HELM_DRIVER=configmap helm get values <release-name> -n <namespace>
nginx.ingress.kubernetes.io/ssl-redirect が "true" になっているか確認してください。