chatqna-helm-deploy

ChatQnA Helm デプロイ

Chat Question and Answer Core のサンプルアプリケーション Helm チャートを、sample-applications/chat-question-and-answer-core/chart/ から Helm を使用して Kubernetes にデプロイします。チャートの依存関係は chatqna-core と chatqna-ui です。これらは Docker Compose デプロイと同じソースコードからビルドされます。また、バックエンドと UI のリバースプロキシとして nginx も含まれています。

コードベースのルート：sample-applications/chat-question-and-answer-core/

前提条件

1. 接続可能な Kubernetes クラスターがあり、kubectl からアクセスできるよう設定されていることを確認します。

     kubectl get nodes
   

2. For GPU, discover resource keys before writing values:

     kubectl get nodes -o json | jq -r '.items[] | "\(.metadata.name):\n" + (.status.allocatable | to_entries | map(select(.key | test("gpu|npu|vpu|accel";"i"))) | map("  \(.key): \(.value)") | join("\n"))'
   

   Common Intel keys are gpu.intel.com/i915, gpu.intel.com/xe

What This Skill Produces

• A running ChatQnA Core Helm release in a target namespace for one runtime:
  • OpenVINO CPU
  • OpenVINO GPU
  • Ollama
• A generated override file (values-override.yaml) that translates Docker Compose and setup_env.sh style inputs to Helm values keys.
• A verified deployment state using pods, services, and health endpoint checks.
• A concise deployment report containing:
  • runtime selected and GPU mode
  • chart source (local path or OCI chart)
  • values files used and major override keys
  • access URL and API docs URL
  • warnings (missing token, GPU key, model constraints)

When to Use

• "Deploy chatqna core to Kubernetes"
• "Helm install chatqna-core"
• "Configure values.yaml for chatqna core"
• "Translate docker compose setup_env.sh into helm values"
• "Deploy OpenVINO GPU profile with Helm"
• "Deploy Ollama with chart values"

Inputs To Confirm

Before running commands, confirm or infer these values:

1. Runtime: openvino or ollama
2. Device target: cpu or gpu (GPU valid only for OpenVINO)
3. Namespace and release name (default release: chatqna-core)
4. Chart source:
   • local chart path (./chart), or
   • OCI chart (oci://registry-1.docker.io/intel/chat-question-and-answer-core)
5. Image source and tags:
   • prebuilt registry tags, or
   • custom/private registry and tags
6. Model settings (EMBEDDING_MODEL, LLM_MODEL, optional RERANKER_MODEL)
7. Optional Hugging Face token (HUGGINGFACEHUB_API_TOKEN) for OpenVINO
8. Optional proxy values (http_proxy, https_proxy, no_proxy)

If runtime/device values are missing, default to openvino + cpu.

If prebuilt images are used and tags are not specified by the user, default to the tags in chart/values.yaml.

Use Helm and kubectl commands for deployment actions in this skill.

Decision Logic

• If runtime is ollama:
  • select -f values.yaml -f values-ollama.yaml
  • force CPU-only devices
• If runtime is openvino and device is gpu:
  • select -f values.yaml -f values-openvino.yaml
  • set gpu.enabled=true
  • require gpu.key from cluster labels
• If runtime is openvino and device is cpu:
  • select -f values.yaml -f values-openvino.yaml
  • set gpu.enabled=false
• If requested values conflict with chart validation (for example GPU model device with gpu.enabled=false), correct values before install.

Compose and setup_env.sh Translation

Use the reference mapping in ./references/compose-setupenv-to-helm-mapping.md if the user asks to map Compose or setup_env.sh inputs to Helm values.

Deployment Workflow

Run from sample-applications/chat-question-and-answer-core.

1. Preflight

kubectl version --client
helm version
kubectl config current-context

ローカルのソースチャートを使用する場合：

cd chart
helm dependency build

OCI チャートを使用する場合：

helm pull oci://registry-1.docker.io/intel/chat-question-and-answer-core --version <version>
tar -xvf chat-question-and-answer-core-<version>.tgz
cd chat-question-and-answer-core
helm dependency build

名前空間が存在することを確認します：

kubectl create namespace <namespace> --dry-run=client -o yaml | kubectl apply -f -

2. values のオーバーライドファイルを作成する

参照マッピングを使用して、ユーザーの意図、または Compose／setup_env 形式の入力を変換し、values-override.yaml を作成または更新します。値を設定したシークレットやトークンはコミットしないでください。

プロキシ経由で実行する場合は、現在のシステム環境の値を使用して、次のキーを values-override.yaml に含めます：

global:
	http_proxy: "${http_proxy}"
	https_proxy: "${https_proxy}"
	no_proxy: "${no_proxy}"

実行環境に応じてベースファイルを選択します：

• OpenVINO：values.yaml + values-openvino.yaml + values-override.yaml
• Ollama：values.yaml + values-ollama.yaml + values-override.yaml

3. レンダリング済みマニフェストを検証する

helm template chatqna-core \
	-f values.yaml \
	-f values-<runtime>.yaml \
	-f values-override.yaml \
	.

4. リリースをインストールまたはアップグレードする

helm upgrade --install chatqna-core \
	-f values.yaml \
	-f values-<runtime>.yaml \
	-f values-override.yaml \
	. \
	--namespace <namespace>

5. デプロイを検証する

kubectl get pods -n <namespace>
kubectl get services -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp | tail -n 30
kubectl rollout status deploy/chatqna-core -n <namespace>
kubectl rollout status deploy/chatqna-core-nginx -n <namespace>

ヘルスエンドポイントの証拠：

chatqna_hostip=$(kubectl get pods -l app=chatqna-core-nginx -n <namespace> -o jsonpath='{.items[0].status.hostIP}')
chatqna_port=$(kubectl get service chatqna-core-nginx -n <namespace> -o jsonpath='{.spec.ports[0].nodePort}')
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${chatqna_hostip}:${chatqna_port}/v1/chatqna/health"

6. アクセスと削除

# UI
echo "http://${chatqna_hostip}:${chatqna_port}"

# API docs
echo "http://${chatqna_hostip}:${chatqna_port}/v1/chatqna/docs"

# Uninstall
helm uninstall chatqna-core -n <namespace>

障害への対処

• Helm テンプレートの検証に失敗した場合：
  • 失敗の原因となった正確なキーを報告し、修正後のキー／値を提案します。
• GPU が要求されているが、gpu.key がない場合：
  • ユーザーに kubectl describe node の実行と、デバイスプラグインのキーの提示を案内し、 gpu.enabled=true を指定して再実行します。
• Pod の準備ができていない場合：
  • 失敗している Pod の kubectl describe pod と kubectl logs の出力を収集します。
• ヘルスチェックが 200 以外を返す場合：
  • chatqna-core のログを確認し、モデルのダウンロードや設定に関する問題を調べます。
  • 初回起動時は、モデルの取得／変換により時間がかかる場合があることを伝えます。
• PVC が停止している場合：
  • 停止している PVC を一覧表示し、明示的に要求された場合に限り削除します。
• より大きなストレージが必要な場合：
  • values-override.yaml の PVC サイズを増やし、helm upgrade を再実行します。

完了条件

1. 実行環境に応じた正しい values ファイルを指定して、インストールコマンドが実行されていること。
2. Compose／setup_env の入力（提供されている場合）が、具体的な values-override.yaml に変換されていること。
3. 対象の名前空間で Pod／サービスが正常であること。
4. ヘルスエンドポイントが HTTP_STATUS:200 を返すこと。
5. ユーザーに UI URL、API ドキュメント URL、リリース／名前空間、アンインストールコマンドが提示されていること。
6. 応答に未加工の検証結果（kubectl get、ロールアウトの状態、 ヘルスチェックの出力）が含まれていること。