ドメイン設定ガイド

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

出荷時の状態

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

LoadBalancer エンドポイントの構成

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

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

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

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

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

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

AWS で IP が表示されない理由

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

出荷時の制限事項

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

危険

自己署名証明書のまま本番運用すると、以下のリスクがあります：

ブラウザの証明書警告による利用者の混乱
中間者攻撃を検知できない（ユーザーが警告を無視する習慣がつく）
WebAuthn（Passkey）機能が利用不可
一部クライアント SDK が接続拒否する可能性

必ず正式ドメインと正規 SSL 証明書を設定してからサービスを公開してください。

SSL 設定方法の選択

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

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

アップグレード共通手順

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

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

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

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

クラウド別の DNS 設定例

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

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

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

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

注記

ドメイン設定後も、各 Service のエンドポイント（Azure/GCP は IP、AWS は ELB DNS 名）はそのまま維持されます。DNS レコードが対応するエンドポイントを指すだけで、ルーティングは変わりません。

AWS Marketplace 版では NLB の IP が AWS 側で変動しうるため、必ず CNAME で ELB DNS 名を指してください。A レコードに NLB の IP を直接登録すると、IP 変更時にアクセス不能になります。Route 53 を利用する場合は、エイリアスレコード（A レコード Alias）で NLB を指す方法も使用できます。

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

curl
HELM_DRIVER=configmap helm list -A

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

3. Helm リポジトリを追加

curl
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）:

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

管理画面（agenticai-admin）:

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

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

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

注記

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

5. SSL 証明書を設定

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

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

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

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

Helm でデプロイ

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

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

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

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

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

クラウド別の構成

Azure: Front Door

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

主な手順:

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

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 オリジン）
ビヘイビアでパス／ホストごとにオリジンを振り分け
Route 53 で各カスタムドメインの CNAME（または Alias）を CloudFront ディストリビューションのドメインに向ける
NLB のセキュリティグループを CloudFront 管理 Prefix List（com.amazonaws.global.cloudfront.origin-facing）からのアクセスのみに制限

ヒント

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

注意

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

GCP: Cloud Load Balancing

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

方法 2: 外部証明書

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

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

手順

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

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

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

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

注記

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

2. Helm でデプロイ

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

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

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

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

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

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

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

ユーザー → 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 を編集し、メールアドレスを変更してから適用します。

curl
kubectl apply -f cluster-issuer.yaml

2. Helm でデプロイ

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

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

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

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

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

注記

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

3. 証明書発行を確認

curl
kubectl get certificate -n <namespace>
kubectl describe certificate <cert-name> -n <namespace>

トラブルシューティング

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

curl
# 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 設定を確認する

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

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

curl
# 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 にリダイレクトされない

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

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

出荷時の状態​

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

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

出荷時の制限事項​

SSL 設定方法の選択​

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

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

クラウド別の DNS 設定例​

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

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

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

5. SSL 証明書を設定​

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

Helm でデプロイ​

クラウド別の構成​

Azure: Front Door​

AWS: CloudFront + NLB​

GCP: Cloud Load Balancing​

方法 2: 外部証明書​

手順​

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

2. Helm でデプロイ​

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

前提条件​

手順​

1. ClusterIssuer を作成​

2. Helm でデプロイ​

3. 証明書発行を確認​

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

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

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

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

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

出荷時の状態

LoadBalancer エンドポイントの構成

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

出荷時の制限事項

SSL 設定方法の選択

アップグレード共通手順

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

クラウド別の DNS 設定例

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

3. Helm リポジトリを追加

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

5. SSL 証明書を設定

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

Helm でデプロイ

クラウド別の構成

Azure: Front Door

AWS: CloudFront + NLB

GCP: Cloud Load Balancing

方法 2: 外部証明書

手順

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

2. Helm でデプロイ

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

前提条件

手順

1. ClusterIssuer を作成

2. Helm でデプロイ

3. 証明書発行を確認

トラブルシューティング

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

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

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

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