bitflicker64 commented on code in PR #3450: URL: https://github.com/apache/hugegraph/pull/3450#discussion_r4461350786
########## helm/hugegraph/docs/rag.md: ########## @@ -0,0 +1,379 @@ +# Optional HugeGraph RAG deployment + +The canonical HugeGraph chart can deploy the `hugegraph/rag` application from +[hugegraph-ai](https://github.com/apache/hugegraph-ai) beside PD, Store, Server +and Hubble. RAG is opt-in and does not change the existing graph topology. + + + +## Minimal same-release configuration + +For the normal case, the only RAG value that must be set is: + +```yaml +rag: + enabled: true +``` + +The chart derives the complete connection to the Server in the same release: + +- `GRAPH_URL` uses the release-scoped Server Service and `server.port`; +- `GRAPH_NAME` defaults to `hugegraph`; +- `GRAPH_SPACE` follows `server.graphSpace`; +- `GRAPH_USER` defaults to `admin`; and +- `GRAPH_PWD` comes from the existing Server administrator Secret when Server + authentication is enabled. + +Do not repeat a Server Pod IP, REST port, graph space or administrator Secret for +this topology. `GRAPH_NAME` cannot be inferred from the Server values and defaults +to `hugegraph`; set `rag.hugegraph.graphName` when the target graph differs. A +custom `rag.port` is also applied consistently to the RAG process, container, +Service and probes. + +The supplied overlay keeps the ordinary settings in one reviewed file: + +```bash +# One PD + Store + Server, plus one RAG Pod +helm upgrade --install hugegraph ./helm/hugegraph \ + -n hugegraph --create-namespace \ + -f helm/hugegraph/values-single.yaml \ + -f helm/hugegraph/values-rag.yaml + +# 3 + 3 + 3 HugeGraph cluster, plus one RAG Pod +helm upgrade --install hugegraph ./helm/hugegraph \ + -n hugegraph --create-namespace \ + -f helm/hugegraph/values-cluster.yaml \ + -f helm/hugegraph/values-rag.yaml +``` + +When `rag.persistence.enabled` is unset, RAG inherits the top-level +`persistence.enabled` value. The chart default is `true`, so a bare +`--set rag.enabled=true` creates one retained PVC. Set the RAG-specific value only +when this component must differ from the rest of the release. + +Model, embedding and prompt settings can be entered through the RAG interface +and retained on the PVC. Kubernetes Secrets remain preferable for declarative +production credentials. + +## Automatic HugeGraph wiring and credentials + +With `rag.hugegraph.autoConfigure=true` and an empty `rag.hugegraph.url`, the +same-release connection above is generated automatically. A matching entry in +`rag.env` replaces its generated counterpart. + +The automatic `admin` identity is convenient for evaluation but has full Server +privileges. Production deployments should create a dedicated least-privilege +HugeGraph account and override only its identity and Secret while retaining the +automatically derived address: + +```yaml +rag: + enabled: true + hugegraph: + username: rag-service + passwordSecret: + name: rag-hugegraph-credentials + key: password +``` + +The chart-managed Server Secret is covered by a pod-template checksum. An +explicit `rag.hugegraph.passwordSecret` is covered by its live resource version +during an online `helm upgrade`. In both cases, the restarted Pod uses the new +Secret even when an older value exists in the retained `.env` file. + +Offline renderers and GitOps controllers cannot use Helm `lookup` to observe a +live Secret's resource version. Rotating an explicit +`rag.hugegraph.passwordSecret` while applying otherwise identical rendered +manifests therefore needs an explicit rollout trigger after the Secret has been +updated. Either restart the Deployment: + +```bash +RELEASE=hugegraph +kubectl -n hugegraph rollout restart deployment/${RELEASE}-hugegraph-rag Review Comment: Minor: with the documented release name `hugegraph`, `hugegraph.fullname` resolves to `hugegraph`, so the objects are `hugegraph-rag` and `hugegraph-rag-data`, and this command and those at lines 162, 269 and 291 target `hugegraph-hugegraph-rag`, which does not exist. Use the real names, or select the Deployment by `app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=rag`. ########## helm/hugegraph/templates/rag-deployment.yaml: ########## @@ -0,0 +1,289 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +{{ include "hugegraph.resolveValues" . }} +{{- $rag := get .Values "rag" | default dict }} +{{- if get $rag "enabled" | default false }} +{{- include "hugegraph.rag.validate" . }} +{{- $graph := get $rag "hugegraph" | default dict }} +{{- $autoConfigure := true }} +{{- if hasKey $graph "autoConfigure" }}{{- $autoConfigure = get $graph "autoConfigure" }}{{- end }} +{{- $persistenceEnabled := eq (include "hugegraph.rag.persistenceEnabled" .) "true" }} +{{- $envNames := dict }} +{{- range get $rag "env" | default list }} +{{- $_ := set $envNames (.name | toString) true }} +{{- end }} +{{- $password := get $graph "passwordSecret" | default dict }} +{{- $explicitPasswordSecret := trim (get $password "name" | default "") }} +{{- $passwordSecret := include "hugegraph.rag.passwordSecretName" . }} +{{- $injectPassword := and $autoConfigure $passwordSecret (not (hasKey $envNames "GRAPH_PWD")) (or $explicitPasswordSecret (not (hasKey $envNames "GRAPH_URL"))) }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "hugegraph.rag.name" . }} + labels: + {{- include "hugegraph.labels" . | nindent 4 }} + app.kubernetes.io/component: rag +spec: + replicas: {{ include "hugegraph.rag.replicas" . | int }} + # The application keeps mutable runtime configuration in-process. Recreate + # preserves the chart's single-active-pod contract even when persistence is off. + strategy: + type: Recreate + selector: + matchLabels: + {{- include "hugegraph.selectorLabels" . | nindent 6 }} + app.kubernetes.io/component: rag + template: + metadata: + labels: + {{- include "hugegraph.selectorLabels" . | nindent 8 }} + app.kubernetes.io/component: rag + {{- with get $rag "podLabels" }}{{ toYaml . | nindent 8 }}{{- end }} + {{- if or $injectPassword (get $rag "podAnnotations") }} + annotations: + {{- if $injectPassword }} + {{- if $explicitPasswordSecret }} + {{- $live := lookup "v1" "Secret" .Release.Namespace $passwordSecret | default dict }} + checksum/hugegraph-auth: {{ printf "%s|%s|%s" $passwordSecret (include "hugegraph.rag.passwordSecretKey" .) (dig "metadata" "resourceVersion" "" $live) | sha256sum | quote }} + {{- else }} + checksum/hugegraph-auth: {{ include "hugegraph.server.authChecksum" . | quote }} + {{- end }} + {{- end }} + {{- with get $rag "podAnnotations" }}{{ toYaml . | nindent 8 }}{{- end }} + {{- end }} + spec: + {{- $serviceAccount := get $rag "serviceAccount" | default dict }} + {{- $serviceAccountCreate := true }} + {{- if hasKey $serviceAccount "create" }}{{- $serviceAccountCreate = get $serviceAccount "create" }}{{- end }} + automountServiceAccountToken: {{ get $serviceAccount "automountServiceAccountToken" | default false }} Review Comment: Important: the RAG Pod keeps Kubernetes service links, so a `qdrant` or `milvus` Service in the same namespace injects `QDRANT_PORT=tcp://<ip>:6333` or `MILVUS_PORT=tcp://<ip>:19530`, and `IndexConfig` raises `ValueError` at import on `int(os.environ.get("QDRANT_PORT", "6333"))`. Set `enableServiceLinks: false` in the RAG Pod spec. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
