bitflicker64 commented on code in PR #393:
URL: https://github.com/apache/hugegraph-ai/pull/393#discussion_r4461349729


##########
docker/charts/README.md:
##########
@@ -0,0 +1,226 @@
+# Kubernetes deployment and migration
+
+HugeGraph RAG's standalone `docker/charts/hg-llm` Helm chart is retired in 
favor
+of the canonical `helm/hugegraph` chart in
+[`apache/hugegraph`](https://github.com/apache/hugegraph/tree/master/helm/hugegraph).
+The canonical integration is 
[apache/hugegraph#3450](https://github.com/apache/hugegraph/pull/3450)
+(development: 
[hugegraph/hugegraph#365](https://github.com/hugegraph/hugegraph/pull/365)).
+
+**Merge order is mandatory:** #3450 must be merged and its RAG templates
+available on ASF `master` **before** this chart retirement is merged. Until
+then, ASF `master` cannot install RAG using the instructions below; the fork's
+feature branch is a development preview, not a durable deployment target.
+The replacement also requires [AI configuration PR 
#96](https://github.com/hugegraph/hugegraph-ai/pull/96)
+and its published `latest`/1.8 RAG image, together with
+[the chart simplification](https://github.com/hugegraph/hugegraph/pull/367).
+Release order is: application configuration support and image publication,
+canonical chart integration, then standalone chart retirement. An older image
+cannot implement the new externally mounted configuration contract.
+
+The following installation and migration commands apply only **after**
+the canonical chart is available. Do not retire a working legacy release first.
+
+## Fresh installation (no existing `hugegraph` release)
+
+Clone the canonical repository, verify that the integration is present, and
+choose **one** topology preset. Use `helm install`, not an upgrade of an
+unrelated existing release.
+
+```bash
+git clone https://github.com/apache/hugegraph.git
+cd hugegraph
+git checkout master
+test -f helm/hugegraph/values-rag.yaml || { echo "Wait for 
apache/hugegraph#3450 before installing RAG" >&2; false; }
+
+# Single-node: 1 PD + 1 Store + 1 Server + 1 RAG
+helm install hugegraph ./helm/hugegraph \
+  -n hugegraph --create-namespace \
+  -f helm/hugegraph/values-single.yaml \
+  -f helm/hugegraph/values-rag.yaml \
+  --set rag.service.type=ClusterIP
+```
+
+For a **new** 3+3+3 cluster, change only the preset:
+
+```bash
+helm install hugegraph ./helm/hugegraph \
+  -n hugegraph --create-namespace \
+  -f helm/hugegraph/values-cluster.yaml \
+  -f helm/hugegraph/values-rag.yaml \
+  --set rag.service.type=ClusterIP
+```
+
+RAG is opt-in (`rag.enabled=false` by default). The canonical chart runs 
**one**
+RAG replica for either preset because its mutable prompt and configuration
+files are not multi-writer safe. RAG's HTTP Service defaults to an internal
+`ClusterIP` in *both* Helm modes; external access is not silently enabled.
+
+For local administrative access from a trusted workstation, use a loopback-only
+port-forward:
+
+```bash
+kubectl -n hugegraph port-forward \
+  service/hugegraph-hugegraph-rag 8001:8001 --address 127.0.0.1

Review Comment:
   Important: for release `hugegraph` the paired chart names the RAG Service 
`hugegraph-rag`, because `hugegraph.fullname` drops the chart suffix when the 
release name contains `hugegraph`, so this port-forward fails with `not found` 
and lines 181-182 send clients to a Service that does not exist. Use 
`hugegraph-rag` here and describe the new name as `<fullname>-rag` on lines 
181-182.



##########
docker/charts/README.md:
##########
@@ -0,0 +1,226 @@
+# Kubernetes deployment and migration
+
+HugeGraph RAG's standalone `docker/charts/hg-llm` Helm chart is retired in 
favor
+of the canonical `helm/hugegraph` chart in
+[`apache/hugegraph`](https://github.com/apache/hugegraph/tree/master/helm/hugegraph).
+The canonical integration is 
[apache/hugegraph#3450](https://github.com/apache/hugegraph/pull/3450)
+(development: 
[hugegraph/hugegraph#365](https://github.com/hugegraph/hugegraph/pull/365)).
+
+**Merge order is mandatory:** #3450 must be merged and its RAG templates
+available on ASF `master` **before** this chart retirement is merged. Until
+then, ASF `master` cannot install RAG using the instructions below; the fork's
+feature branch is a development preview, not a durable deployment target.
+The replacement also requires [AI configuration PR 
#96](https://github.com/hugegraph/hugegraph-ai/pull/96)
+and its published `latest`/1.8 RAG image, together with
+[the chart simplification](https://github.com/hugegraph/hugegraph/pull/367).
+Release order is: application configuration support and image publication,
+canonical chart integration, then standalone chart retirement. An older image
+cannot implement the new externally mounted configuration contract.
+
+The following installation and migration commands apply only **after**
+the canonical chart is available. Do not retire a working legacy release first.
+
+## Fresh installation (no existing `hugegraph` release)
+
+Clone the canonical repository, verify that the integration is present, and
+choose **one** topology preset. Use `helm install`, not an upgrade of an
+unrelated existing release.
+
+```bash
+git clone https://github.com/apache/hugegraph.git
+cd hugegraph
+git checkout master
+test -f helm/hugegraph/values-rag.yaml || { echo "Wait for 
apache/hugegraph#3450 before installing RAG" >&2; false; }
+
+# Single-node: 1 PD + 1 Store + 1 Server + 1 RAG
+helm install hugegraph ./helm/hugegraph \
+  -n hugegraph --create-namespace \
+  -f helm/hugegraph/values-single.yaml \
+  -f helm/hugegraph/values-rag.yaml \
+  --set rag.service.type=ClusterIP
+```
+
+For a **new** 3+3+3 cluster, change only the preset:
+
+```bash
+helm install hugegraph ./helm/hugegraph \
+  -n hugegraph --create-namespace \
+  -f helm/hugegraph/values-cluster.yaml \
+  -f helm/hugegraph/values-rag.yaml \
+  --set rag.service.type=ClusterIP
+```
+
+RAG is opt-in (`rag.enabled=false` by default). The canonical chart runs 
**one**
+RAG replica for either preset because its mutable prompt and configuration
+files are not multi-writer safe. RAG's HTTP Service defaults to an internal
+`ClusterIP` in *both* Helm modes; external access is not silently enabled.
+
+For local administrative access from a trusted workstation, use a loopback-only
+port-forward:
+
+```bash
+kubectl -n hugegraph port-forward \
+  service/hugegraph-hugegraph-rag 8001:8001 --address 127.0.0.1
+# Browse http://127.0.0.1:8001/ locally.
+```
+
+**Security boundary:** The RAG application's own login does **not** protect
+every HTTP route. Enabling its UI login is therefore **not sufficient** for
+public exposure. Keep `ClusterIP` and ingress disabled by default. If remote
+access is necessary, place the Service behind an **authenticated** reverse
+proxy/Ingress and restrictive firewall/NetworkPolicy, with TLS and provider
+usage limits. In strict mode, explicitly allow only required ingress-controller
+and model-provider peers; verify your CNI enforces NetworkPolicy.
+
+A separate HugeGraph database account (rather than the Server administrator)
+can be connected using a Kubernetes Secret:
+
+```bash
+# Create the account with least-privilege graph permissions first.
+kubectl -n hugegraph create secret generic rag-hugegraph-credentials \
+  --from-file=password=/secure/path/rag-hugegraph-password
+```
+
+```yaml
+rag:
+  enabled: true
+  hugegraph:
+    username: rag-service
+    passwordSecret:
+      name: rag-hugegraph-credentials
+      key: password
+```
+
+This Secret authenticates **RAG to HugeGraph Server**; it does not add
+HTTP authentication to the RAG UI/API. Likewise supply model provider secrets
+through `rag.env`/`rag.envFrom`, not plaintext in a values file. See
+[canonical RAG 
documentation](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/rag.md)
+for persistent configuration and the approved exposure boundaries.
+
+## Configure RAG outside the container
+
+The canonical chart mounts a writable resource volume at 
`/var/lib/hugegraph-rag`.

Review Comment:
   Important: the paired chart mounts the RAG volume at 
`/home/work/hugegraph-llm/src/hugegraph_llm/resources` 
(`rag.persistence.mountPath`), not `/var/lib/hugegraph-rag`, so operators who 
back up, inspect or point `HUGEGRAPH_LLM_ENV_PATH` at this path miss the 
persisted `.env`, prompts and indexes. Name the real default path and the 
`rag.persistence.mountPath` key that changes it.



-- 
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]

Reply via email to