From 182a275183c1d19de583e590098b204f2f3f6711 Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 04:32:59 +0000 Subject: [PATCH 01/11] docs: explain optional Helm engines --- .../quickstart/hugegraph/hugegraph-helm.md | 77 ++++++++++++++++-- .../quickstart/hugegraph/hugegraph-helm.md | 81 +++++++++++++++++-- 2 files changed, 148 insertions(+), 10 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 94341fa9b9..868004a602 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -6,7 +6,7 @@ search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, 内网部 --- 本文适用于 HugeGraph **1.8.0 及以后版本**，需要支持 OCI 的 Helm **3.10+** 和 Kubernetes (K8s) **1.23+**。 -可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本，例如 `0.2.x` 的 Chart 可以部署 `1.8.x` 的服务。 +可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本，例如 `0.3.x` 的 Chart 可以部署 `1.8.x` 的服务。 > [!WARNING] > 当前开发 Chart 使用 `latest` 镜像，适合测试。 @@ -60,7 +60,8 @@ helm install hugegraph ./hugegraph-helm -n hugegraph \ --create-namespace --wait --timeout 10m ``` -单节点试用预设替代默认安装，将各组件设为 1 副本并放宽调度限制，适合资源受限环境。 +单节点试用预设使用 HStore 的 1 PD + 1 Store + 1 Server 与 Hubble，放宽调度限制，适合资源受限环境。 +SeaTunnel 和 Vermeer 仍保持关闭。 ## 2 模式和访问入口 @@ -80,12 +81,12 @@ hugegraph-helm/ server-deployment.yaml # Server 引擎无状态 Deployment（注入 serviceId / graphSpace） hubble-deployment.yaml # 可视化控制台 Deployment tests/ # 冒烟验证测试钩子（helm test，支持自定义 testGraphAlias） - examples/ # 7 种生产场景完整示例（含 local PV、GitOps 凭据、Ingress 等） + examples/ # 部署示例（local PV、GitOps 凭据、可选引擎、Ingress 等） docs/operations.md # 生命周期进阶运维与故障恢复手册 ``` 默认 `mode: easy`，Server 和 Hubble 自动分配 NodePort，PD 保持 ClusterIP。可以直接使用 HTTP，无需域名、证书或额外确认参数。 -`mode: strict` 默认将 Server/Hubble 设为 ClusterIP，并开启 NetworkPolicy。两个模式都保留鉴权和持久化。 +`mode: strict` 默认将 Server/Hubble 和已启用可选组件的 HTTP 入口设为 ClusterIP，并开启 NetworkPolicy。两个模式都保留鉴权和持久化。 优先级是组件显式参数高于全局参数，全局参数高于模式默认值，显式 `false` 也会生效。 全局参数包括 `persistence.enabled` 和 `global.imageRegistry`，严格预设为 `values-strict.yaml`。 @@ -107,11 +108,64 @@ kubectl -n hugegraph get secret hugegraph-admin \ 默认 `externalTrafficPolicy: Cluster` 下，访问的节点不必运行目标 Pod。ClusterIP 是集群内部的虚拟服务地址，不是节点 IP，普通笔记本通常不能直接访问。 也可以运行 `kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088`，在本机打开 `http://127.0.0.1:8088`。 -三个客户端 Service 都支持 `externalTrafficPolicy`、`loadBalancerClass`、`loadBalancerIP`、`loadBalancerSourceRanges`、`externalIPs` +基础 PD/Server/Hubble 三类客户端 Service 支持 `externalTrafficPolicy`、`loadBalancerClass`、`loadBalancerIP`、`loadBalancerSourceRanges`、`externalIPs` 和 `allocateLoadBalancerNodePorts`，具体行为取决于集群及负载均衡实现。LoadBalancer 专用字段应配合对应类型使用。 NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据集群配置的范围校验，chart 不再强制 `30000–32767`。 原 HTTP 暴露确认参数保留兼容，但不再阻止渲染。 +### 可选引擎：默认关闭 + +`values-single.yaml` 和 `values-cluster.yaml` 都不会开启 SeaTunnel 或 Vermeer。 +这两个预设选择 HugeGraph 的 HStore 拓扑；`seatunnel.mode` 和 `vermeer.mode` 分别选择可选引擎的拓扑， +顶层 `mode: easy/strict` 则独立控制 HTTP 入口与网络隔离。 + +| 组件 | 默认状态 | 按需启用 | +|---|---|---| +| Hubble | 开启 | `hubble.enabled=false` 切换为仅 API 部署 | +| SeaTunnel | 关闭 | `seatunnel.enabled=true` 开启导入导出与原生 UI | +| Vermeer | 关闭 | `vermeer.enabled=true` 开启图计算、Hubble 联动与原生 UI | + +下面示例从 HugeGraph 仓库根目录安装源码 Chart。 +启用 Vermeer 前须确认 Hubble/Vermeer 镜像包含对应能力，并固定已验证的镜像引用； +已发布 Chart 或可变的 `latest` 标签本身不能证明应用改动已经包含在镜像中。 + +> [!DETAILS]- SeaTunnel：按需开启原生导入、导出和迁移 +> ```bash +> helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ +> -f helm/hugegraph/values-single.yaml \ +> --set seatunnel.enabled=true --set seatunnel.mode=standalone \ +> --wait --timeout 30m +> ``` +> +> 单机模式运行一个常驻 hybrid 成员；设置 `seatunnel.mode=cluster` 和 `seatunnel.replicas=2` 可运行多个成员。 +> 两种模式都有原生 UI/API，使用独立的 HTTP Basic 凭据。 +> HTTP 入口在 easy 下为 NodePort、strict 下为 ClusterIP；成员端口 5801 始终限制为可信的同 release peers。 +> Helm 准备引擎和示例，不自动建图或执行作业；checkpoint 使用临时本地文件。 +> 访问、凭据、复制示例和恢复限制见 [SeaTunnel 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 + +> [!DETAILS]- Vermeer：按需开启图计算，自动接入 Hubble +> ```bash +> helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ +> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> --set vermeer.enabled=true --set vermeer.mode=standalone \ +> --wait --timeout 20m +> ``` +> +> 先在 `my-images.yaml` 中选择匹配的 Hubble/Vermeer 镜像。 +> 单机模式使用一个 Pod，内含独立的 Master 和 Worker 原生进程容器，各自挂载数据卷。 +> 设置 `vermeer.mode=cluster` 后为 1 个 Master Pod 加 `vermeer.worker.replicas` 个 Worker Pod，默认 3 个 Worker。 +> 多 Worker 提供分布式计算；单 Master 不承诺自动故障切换。 +> +> 保持 Hubble 默认的 PD 模式，Chart 会自动提供 Master 内部地址和服务令牌，无需手工填写。 +> 以 HugeGraph 管理员登录 Hubble，选择 HStore 图，加载／重载后运行九种支持算法之一， +> 查看／取消异步任务并分页浏览结果，结束后卸载计算副本。 +> 此流程不把结果写回 HugeGraph 属性；普通图读取用户不会因此获得直接扫描 Store 的权限。 +> +> Vermeer 原生 UI/API 也同时提供：easy 下使用 NodePort，strict 下使用 ClusterIP，令牌登录与 Hubble 登录相互独立。 +> 执行 `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` 后访问 `http://127.0.0.1:6688/`。 +> 匹配镜像、令牌获取、部署凭据、持久化和模式切换见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 +> 原生联动要求 `hubble.mode=pd`；设置 `hubble.enabled=false` 时仍可通过原生入口使用 Vermeer。 + ### 服务身份与图空间 默认 `server.serviceId` 与 `server.graphSpace` 均为 `DEFAULT`。如需将 Server 注册到指定的业务服务名或图空间，可通过 values 指定： @@ -141,6 +195,9 @@ GitOps 凭据、仅 API 部署以及无域名的 HTTP Ingress。 等待 PD 的 init container 复用 Store 镜像，Helm test 复用 Server 镜像。这两个镜像已包含 `curl`，无需额外 curl 镜像或启动时安装软件。 自定义镜像可以继续使用显式 `store.waitImage` 和 `server.waitImage` 覆盖。 +启用 SeaTunnel 时还需同步其配置的 `apache/seatunnel` 镜像，启用 Vermeer 时还需匹配的 `hugegraph/vermeer` 构建。 +Vermeer 的 Master、Worker 和服务令牌初始化复用同一镜像；所有已启用镜像及显式 helper 覆盖都应同步。 + ### 存储配置 `storageClassName` 为空时继承集群默认 StorageClass，`"-"` 表示显式不使用 StorageClass。 @@ -149,6 +206,11 @@ local PV 需要预建宿主机目录、匹配容量、`nodeAffinity` 和 `kubern 新建临时实例可以设置 `persistence.enabled=false` 使用 `emptyDir`，组件存储开关优先。 PVC 失败不会自动降级为临时存储，已经初始化的 PD/Store 切换存储模式会被拒绝。 +Vermeer 的 Master 和 Worker 使用独立数据卷，单 Pod 模式也不共享 Pebble 目录。 +单机模式增加 2 个卷；集群模式为 1 个 Master 卷加每 Worker 1 个卷，默认增加 4 个。 +因此默认基础拓扑加 Vermeer 单机／集群分别需要 9／11 个卷，轻量 HugeGraph 预设加 Vermeer 单机需要 5 个。 +七卷 local PV 示例仅覆盖基础安装；SeaTunnel checkpoint 仍使用临时本地文件。 + ### 离线安装和私库 先选择最新版本，再按该版本下载 Chart，将 `.tgz` 搬入内网。可以直接安装，也可以接入已有的 OCI 或 HTTP 私库。 @@ -208,6 +270,11 @@ GitOps 使用加密的固定值，或预先创建 Secret 并配置 `pd.auth.exis Hubble 默认开启，当前镜像的登录仍依赖 Server 鉴权。只使用 API 可以设置 `hubble.enabled=false`， 如需关闭 API 鉴权，再设置 `server.auth.enabled=false`。未使用的凭据配置可以留在 values 中。 +可选引擎启用后增加独立入口凭据：SeaTunnel 使用原生 HTTP Basic；Vermeer 使用保留的签名因子 Secret， +通过 `vermeer.auth.value` 或 `vermeer.auth.existingSecret/key` 配置，Hubble 会自动生成长期服务令牌。GitOps 需要保留稳定的凭据来源。 +Worker Schema 读取默认复用部署管理员凭据，也可通过 `vermeer.hugegraphCredentials.existingSecret/key` 指向现有用户的受保护用户名密码 JSON； +该用户需具备目标图的 Schema 权限，Chart 不会自动创建账户。 + ## 5 升级和验证 使用 Helm 原生值复用保留已有部署的 UI、入口、存储和凭据设置。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 994bf5f437..26f112f3e1 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -7,7 +7,7 @@ search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, OCI, GHCR, This guide covers HugeGraph **1.8.0 and later**, using Helm **3.10+** with OCI support and Kubernetes (K8s) **1.23+**. Install `hugegraph-helm` from GHCR or Docker Hub. Chart and HugeGraph versions are maintained separately: -for example, a `0.2.x` Chart can deploy a `1.8.x` service. +for example, a `0.3.x` Chart can deploy a `1.8.x` service. > [!WARNING] > The current development Chart uses `latest` images and is intended for testing. @@ -64,7 +64,8 @@ helm install hugegraph ./hugegraph-helm -n hugegraph \ --create-namespace --wait --timeout 10m ``` -The single-node preset replaces the default installation with one replica per component and relaxed scheduling constraints. +The single-node preset selects 1 PD + 1 Store + 1 Server using HStore, plus Hubble, with relaxed scheduling constraints. +It leaves SeaTunnel and Vermeer disabled. ## 2 Modes and entry points @@ -84,12 +85,13 @@ hugegraph-helm/ server-deployment.yaml # Server Deployment (injects serviceId and graphSpace) hubble-deployment.yaml # Hubble UI Deployment tests/ # Smoke validation hook (helm test, supports custom testGraphAlias) - examples/ # Seven complete production scenario examples (local PVs, GitOps secrets, Ingress) + examples/ # Deployment examples: local PVs, GitOps credentials, optional engines and Ingress docs/operations.md # Lifecycle operations and recovery guide ``` `mode: easy` is the default. Server and Hubble use automatic NodePorts; PD stays ClusterIP. HTTP works without a domain, certificate or acknowledgement. -`mode: strict` defaults Server/Hubble to ClusterIP and enables NetworkPolicy. Both modes keep authentication and persistence. +`mode: strict` defaults Server/Hubble and enabled optional HTTP entries to ClusterIP and enables NetworkPolicy. +Both modes keep authentication and persistence. Explicit component parameters take priority over global parameters, which take priority over mode defaults; explicit `false` remains an override. The global parameters are `persistence.enabled` and `global.imageRegistry`. Strict mode is also available through `values-strict.yaml`. @@ -111,11 +113,66 @@ Open Hubble on its assigned NodePort and log in as `admin` with this password. A The internal ClusterIP is a virtual Service address, not a node IP; a laptop normally cannot reach it directly. Use `kubectl -n hugegraph port-forward svc/hugegraph-hubble 8088:8088` for a local browser at `http://127.0.0.1:8088`. -Each client Service supports `externalTrafficPolicy`, `loadBalancerClass`, `loadBalancerIP`, `loadBalancerSourceRanges`, `externalIPs` +The base PD/Server/Hubble client Services support `externalTrafficPolicy`, `loadBalancerClass`, `loadBalancerIP`, `loadBalancerSourceRanges`, `externalIPs` and `allocateLoadBalancerNodePorts`, subject to the cluster/controller's capabilities. Use LoadBalancer fields with that Service type. NodePort omission or `0` means automatic allocation. Fixed ports are validated against the cluster's configured range by Kubernetes; the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields remain accepted but no longer gate rendering. +### Optional engines: disabled by default + +SeaTunnel and Vermeer remain disabled with both `values-single.yaml` and `values-cluster.yaml`. +These presets select HugeGraph's HStore topology; `seatunnel.mode` and `vermeer.mode` select the optional engines' own topology. +Top-level `mode: easy/strict` separately controls HTTP entry and network isolation. + +| Component | Default | Opt in | +|---|---|---| +| Hubble | Enabled | `hubble.enabled=false` selects API-only access | +| SeaTunnel | Disabled | `seatunnel.enabled=true` enables import/export and its native UI | +| Vermeer | Disabled | `vermeer.enabled=true` enables computation, Hubble integration and its native UI | + +The examples below use the source Chart from the HugeGraph repository root. +Vermeer and Hubble need compatible image builds; verify their capabilities and pin the tested references before installing. +A published Chart or a moving `latest` tag does not prove that the required application changes are already available. + +> [!DETAILS]- SeaTunnel: enable native import, export and migration +> ```bash +> helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ +> -f helm/hugegraph/values-single.yaml \ +> --set seatunnel.enabled=true --set seatunnel.mode=standalone \ +> --wait --timeout 30m +> ``` +> +> Standalone starts one long-running hybrid member. Set `seatunnel.mode=cluster` and `seatunnel.replicas=2` +> for multiple hybrid members. Both include the native UI/API, protected by separate HTTP Basic credentials. +> HTTP inherits NodePort in easy mode or ClusterIP in strict mode; member port 5801 stays restricted to trusted release peers. +> Helm prepares the engine and examples; create graphs and submit jobs yourself. Checkpoints use temporary local files. +> See the [SeaTunnel deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) +> for access, credentials, copy examples and recovery limits. + +> [!DETAILS]- Vermeer: enable graph computation and automatic Hubble connection +> ```bash +> helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ +> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> --set vermeer.enabled=true --set vermeer.mode=standalone \ +> --wait --timeout 20m +> ``` +> +> Select matching Hubble/Vermeer image references in `my-images.yaml` first. +> Standalone uses one Pod with separate native Master and Worker containers and separate data volumes. +> Set `vermeer.mode=cluster` for one Master Pod plus `vermeer.worker.replicas` Worker Pods (default 3). +> Multiple Workers provide distributed computation; the single Master has no automatic failover guarantee. +> +> Keep Hubble in its default PD mode. The Chart supplies the internal Master URL and service token automatically. +> Log in to Hubble as the HugeGraph administrator, select an HStore graph, load/reload it, run one of the nine supported algorithms, +> inspect/cancel the asynchronous task and page through results. Unload the compute copy when finished. +> This workflow does not write results into HugeGraph properties. Ordinary graph readers do not receive direct Store-scan privileges. +> +> The native Vermeer UI/API is also exposed: easy uses NodePort, strict uses ClusterIP. Its administrator token login is separate from Hubble. +> Use `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` and open `http://127.0.0.1:6688/`. +> The [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> covers matching builds, token retrieval, deployment credentials, storage and mode changes. +> Hubble requires `hubble.mode=pd` for this native integration; API-only Vermeer remains usable with `hubble.enabled=false`. + ### Server service identity and graph space Both `server.serviceId` and `server.graphSpace` default to `DEFAULT`. To register the Server with a specific service name or graph space in PD: @@ -146,6 +203,9 @@ The default mirror inventory is only `hugegraph/pd`, `hugegraph/store`, `hugegra Store's PD wait init container and the Helm test reuse Store and Server images respectively, which already contain `curl`. No separate curl image or runtime package installation is required. Explicit `store.waitImage` / `server.waitImage` overrides remain supported. +Enabled SeaTunnel additionally needs its configured `apache/seatunnel` image; enabled Vermeer needs its matching `hugegraph/vermeer` build. +Vermeer reuses that image for Master, Worker and service-token initialization. Mirror every enabled image and explicit helper override. + ### Storage configuration For storage, empty `storageClassName` inherits the cluster default, while `"-"` explicitly selects no StorageClass. @@ -154,6 +214,11 @@ Local PVs require prepared host directories, matching capacities, `nodeAffinity` For a new temporary installation, set `persistence.enabled=false` to use `emptyDir`; component storage flags override it. The chart never replaces a failed PVC with temporary storage and rejects PD/Store storage-mode changes on initialized releases. +Vermeer uses separate Master and Worker claims, even in its single-Pod mode: two additional volumes in standalone, +or one Master volume plus one per Worker in cluster mode. With the default base topology this means 9 or 11 volumes respectively. +The small HugeGraph preset plus standalone Vermeer needs 5. The seven-volume local example covers only the base installation. +SeaTunnel checkpoints remain temporary local files. + ### Offline installation and internal repositories Select the latest version, download that Chart and move the `.tgz` into your network. @@ -215,6 +280,12 @@ update the Secret/source to that same password, then restart the Server Deployme Hubble is enabled by default and its current login requires Server authentication. Set `hubble.enabled=false` for API-only access; optionally also set `server.auth.enabled=false` for an unauthenticated API. Inactive credential settings may remain in your values file. +Enabled optional engines add independent entry credentials. SeaTunnel uses native HTTP Basic authentication; +Vermeer uses a kept signing factor configured through `vermeer.auth.value` or `vermeer.auth.existingSecret/key`. +Hubble generates its long-lived Vermeer service token automatically from that factor. For GitOps, preserve stable credential sources. +Worker Schema reads reuse the deployment administrator credential unless `vermeer.hugegraphCredentials.existingSecret/key` supplies +a protected username/password JSON for an existing account with the required Schema permissions. No account is created automatically. + ## 5 Upgrade and verification Use native Helm value reuse to preserve an existing deployment's UI, entry, storage and credentials: From cd96c91b38c9d20d537683fb3b5a397319f6e63f Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 04:35:27 +0000 Subject: [PATCH 02/11] docs: align Vermeer Helm operations --- .../quickstart/computing/hugegraph-vermeer.md | 26 ++++++++++++++++++- .../hugegraph/hugegraph-helm-operations.md | 23 +++++++++++++++- .../quickstart/hugegraph/hugegraph-helm.md | 2 +- .../quickstart/computing/hugegraph-vermeer.md | 26 ++++++++++++++++++- .../hugegraph/hugegraph-helm-operations.md | 25 +++++++++++++++++- .../quickstart/hugegraph/hugegraph-helm.md | 2 +- 6 files changed, 98 insertions(+), 6 deletions(-) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index f32225842b..6e54bace0d 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -14,7 +14,8 @@ Vermeer 是使用 Go 编写的高性能内存优先图计算框架，支持一 master 是负责通信、转发、汇总的节点，计算量和占用资源量较少。worker 是计算节点，用于存储图数据和运行计算任务，占用大量内存和 cpu。grpc 和 rest 模块分别负责内部通信和外部调用。 -启动时，程序先设置内置默认值，再读取工作目录下 `config/.ini` 的 `[default]` 节，最后由显式命令行参数覆盖对应配置；例如 `--env=master` 读取 `config/master.ini`。Docker 镜像把仓库中的配置复制到 `/go/bin/config/`，并以 `/go/bin/` 为工作目录。挂载宿主机目录到 `/go/bin/config` 会遮住镜像自带文件，因此该目录必须包含实际使用的 ini 文件。配置读取器不从环境变量取值。 +启动时，程序先设置内置默认值，再读取工作目录下 `config/.ini` 的 `[default]` 节，最后由显式命令行参数覆盖对应配置；例如 `--env=master` 读取 `config/master.ini`。Docker 镜像把仓库中的配置复制到 `/go/bin/config/`，并以 `/go/bin/` 为工作目录。挂载宿主机目录到 `/go/bin/config` 会遮住镜像自带文件，因此该目录必须包含实际使用的 ini 文件。普通 INI 配置键不会自动映射环境变量。专门的部署凭据设置还支持 +`VERMEER_PD_PASSWORD_FILE`、`VERMEER_PD_PEERS`、`VERMEER_HUGEGRAPH_CREDENTIALS_FILE` 及文档中的签名因子／密码文件设置。 默认端口如下： @@ -37,6 +38,29 @@ flowchart LR ### 1.2 运行方法 +> [!DETAILS]- Helm：与 HugeGraph、Hubble 一起部署 Vermeer +> HugeGraph Helm Chart 提供可选的原生 Vermeer 集成，两种 HugeGraph 拓扑预设都默认关闭。 +> 先在 `my-images.yaml` 选好匹配的 Hubble/Vermeer 构建，再从 HugeGraph 仓库根目录运行： +> +> ```bash +> helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ +> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> --set vermeer.enabled=true --set vermeer.mode=standalone \ +> --wait --timeout 20m +> ``` +> +> 单机为一个 Pod 内独立的 Master 和 Worker 容器；设置 `vermeer.mode=cluster` 与 `vermeer.worker.replicas=3`， +> 则使用 1 个 Master Pod 和可调数量的 Worker Pod。两者都依赖 HStore/PD 数据链路，轻量 HugeGraph 预设已提供它。 +> 顶层 `mode: easy/strict` 独立选择 NodePort 或 ClusterIP HTTP 入口以及网络策略默认值。 +> +> Hubble 自动获得 Master 内部地址与服务令牌。HugeGraph 管理员可以加载／重载图、运行九种支持算法、查看／取消任务、 +> 分页浏览结果并卸载计算副本；结果不会写回图属性。原生 Vermeer UI/API 也同时提供，使用独立管理员令牌登录。 +> 不承诺 Master 自动故障切换或运行中任务自动恢复。 +> 镜像前提、凭据、端口和持久化见 [Helm 可选引擎](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) +> 与 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 +> 不要仅凭现有 `latest` 标签假定镜像已包含新能力。 + + > [!WARNING] > 生产环境必须启用 HugeGraph Server [认证与授权](/cn/docs/config/config-authentication/)、IP 白名单和最小权限授权，并保留 `audit-*.log` 审计记录。Server Auth 不会保护 Vermeer、PD 和 Store 的独立接口；这些 HTTP、gRPC 端口必须限制在可信网络及调用方范围内，Vermeer 对外入口需配置访问控制。 > diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 0dfaa73839..91fe8813f4 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -11,7 +11,7 @@ search_keywords: [HugeGraph Helm 运维, local PV, NetworkPolicy, PD, Store] ## 1 存储和内网镜像 {#1-storage-and-private-images} -默认安装需要七个持久卷。动态存储需要正常的 provisioner，静态 local 存储需要预建目录和绑定节点的匹配 PV。 +基础安装需要七个持久卷。动态存储需要正常的 provisioner，静态 local 存储需要预建目录和绑定节点的匹配 PV。 [完整例子](https://github.com/apache/hugegraph/tree/master/helm/hugegraph/examples)包含七个 local PV、`WaitForFirstConsumer`、镜像仓库和 GitOps Secret。 `WaitForFirstConsumer` 的 PVC 初期 Pending 可以是正常等待；持续 Pending 应检查 PVC/Pod 事件和 PV 匹配。 PVC 已绑定但目录不存在或权限不匹配时可能挂载失败，不能把故障 PVC 静默替换成临时目录。 @@ -25,6 +25,8 @@ kubectl get pv,storageclass 出现 `ImagePullBackOff` 时检查 Pod 事件、仓库连通性和拉取凭据。默认只需四个组件镜像，等待 Store/Helm test 复用已包含 curl 的组件镜像。 如显式覆盖 helper 镜像，该镜像也需要同步到内网仓库。 +启用 SeaTunnel 还需配置的 `apache/seatunnel` 镜像；启用 Vermeer 还需匹配的 `hugegraph/vermeer` 构建，Master、Worker 和令牌初始化共用它。 +基础 local PV 示例不包含 Vermeer 卷：单机增加两个，集群增加一个 Master 卷及每 Worker 一个卷，默认增加四个。 ## 2 端口和健康检查 {#2-ports-and-health} @@ -34,6 +36,25 @@ PD `/v1/ready` 需要 Raft leader，`/v1/health` 只说明监听器已启动，S Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTimeoutSeconds` 调整。 本地模板渲染不能验证集群连通性、卷挂载或 JVM 运行容量。 +> [!DETAILS]- 可选引擎：就绪、凭据和恢复 +> SeaTunnel 和 Vermeer 在两种 HugeGraph 预设中都默认关闭，启用后增加独立入口凭据与网络规则。 +> SeaTunnel HTTP/UI 使用 8080 和 Basic 鉴权；成员／CLI 端口 5801 在 easy 下也限制为可信的同 release peers。 +> 常驻 hybrid 进程不代表 checkpoint 已通过 PVC 持久化。 +> +> Vermeer Master HTTP/gRPC 为 6688/6689，Worker HTTP/gRPC 为 6788/6789；仅鉴权后的 Master HTTP 对外提供入口。 +> 单机为一个 Pod 中独立的 Master/Worker 容器和数据卷；集群默认为 1 个 Master 加 3 个 Worker Pod。 +> 保留的签名因子和自动生成的 Hubble 长期服务令牌，与 Server 登录和 PD 凭据相互独立。 +> 修改外部 Secret 后需滚动相关 Vermeer 工作负载及 Hubble，才能刷新进程凭据和服务令牌。 +> +> Master/Worker 监听器健康不代表当前空间已可计算。以服务凭据检查 `/api/v1/workers/availability`， +> 再通过 Hubble 实测加载和已知算法结果；公共 Worker 池避免新空间需要手工分配。 +> 持久化元数据不保证内存图、结果缓存或运行中任务自动恢复。 +> 切换拓扑或 Worker 数前停止新提交、完成／取消任务并卸载计算图，变更后检查可用性并重新加载。 +> 单机和集群使用不同 Worker claim，模式切换不会迁移本地文件。 +> +> 令牌获取、凭据来源、保留卷与升级步骤见 [Vermeer 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> 和 [SeaTunnel 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 + ### Helm test 检查范围 {#helm-test-coverage} `helm test` 逐 Server Pod 检查图绑定（默认检查 `DEFAULT-hugegraph`，可通过 `server.testGraphAlias` 指定图别名），并要求当前可见关联索引处于 `CREATED` 状态。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 868004a602..734933912a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -113,7 +113,7 @@ kubectl -n hugegraph get secret hugegraph-admin \ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据集群配置的范围校验，chart 不再强制 `30000–32767`。 原 HTTP 暴露确认参数保留兼容，但不再阻止渲染。 -### 可选引擎：默认关闭 +### 可选引擎：默认关闭 {#optional-engines} `values-single.yaml` 和 `values-cluster.yaml` 都不会开启 SeaTunnel 或 Vermeer。 这两个预设选择 HugeGraph 的 HStore 拓扑；`seatunnel.mode` 和 `vermeer.mode` 分别选择可选引擎的拓扑， diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index 4a48997f9f..afb8f7b94c 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -14,7 +14,8 @@ Vermeer is a high-performance, memory-first graph computing framework written in The master handles communication, forwarding, and aggregation, with modest computation and resource usage. Workers store graph data and execute tasks, consuming most memory and CPU. gRPC handles internal communication; REST provides external APIs. -At startup, built-in defaults are loaded first, followed by the `[default]` section of `config/.ini` under the working directory, then explicit command-line overrides. For example, `--env=master` reads `config/master.ini`. The Docker image copies repository configuration to `/go/bin/config/` and works from `/go/bin/`. A host bind mount hides the bundled files, so it must contain every ini file used. The configuration reader does not read environment variables. +At startup, built-in defaults are loaded first, followed by the `[default]` section of `config/.ini` under the working directory, then explicit command-line overrides. For example, `--env=master` reads `config/master.ini`. The Docker image copies repository configuration to `/go/bin/config/` and works from `/go/bin/`. A host bind mount hides the bundled files, so it must contain every ini file used. Ordinary INI keys are not mapped automatically from environment variables. Dedicated deployment credential settings also support +`VERMEER_PD_PASSWORD_FILE`, `VERMEER_PD_PEERS`, `VERMEER_HUGEGRAPH_CREDENTIALS_FILE` and the documented token-factor/password file settings. Default ports: @@ -37,6 +38,29 @@ flowchart LR ### 1.2 Running Vermeer +> [!DETAILS]- Helm: deploy Vermeer together with HugeGraph and Hubble +> The HugeGraph Helm Chart offers an optional native Vermeer integration. It is disabled by default in both HugeGraph topology presets. +> From the HugeGraph repository root, after selecting compatible Hubble/Vermeer builds in `my-images.yaml`: +> +> ```bash +> helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ +> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> --set vermeer.enabled=true --set vermeer.mode=standalone \ +> --wait --timeout 20m +> ``` +> +> Standalone uses one Pod with separate Master and Worker containers. Cluster mode uses one Master Pod plus configurable Worker Pods: +> set `vermeer.mode=cluster` and `vermeer.worker.replicas=3`. Both require the HStore/PD data path; the small HugeGraph preset provides it. +> Top-level `mode: easy/strict` independently selects NodePort or ClusterIP HTTP entry and network policy defaults. +> +> Hubble receives the internal Master URL and service token automatically. A HugeGraph administrator can load/reload a graph, +> run nine supported algorithms, inspect/cancel tasks, page through results and unload the compute copy. Results are not written back to graph properties. +> The native Vermeer UI/API is available too, with separate administrator-token login. No Master failover or automatic task recovery is promised. +> See [Helm optional engines](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and the +> [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> for image prerequisites, credentials, ports and retained data. Do not assume an existing `latest` image contains the required new capabilities. + + > [!WARNING] > In production, enable [Server authentication and authorization](/docs/config/config-authentication/), an IP allowlist, and minimum permissions; retain `audit-*.log`. Server Auth does not protect independent Vermeer, PD, or Store APIs. Restrict these HTTP/gRPC ports to trusted networks and callers, and configure access controls at the Vermeer external entry point. > diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index c4ceec088c..b8901dd84d 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -11,7 +11,7 @@ Commands assume release/namespace `hugegraph`; substitute the actual workload na ## 1 Storage and private images -The default installation needs seven persistent volumes. Dynamic storage requires a working provisioner; static local storage requires prepared directories +The base installation needs seven persistent volumes. Dynamic storage requires a working provisioner; static local storage requires prepared directories and matching PVs on the named nodes. Use the [complete examples](https://github.com/apache/hugegraph/tree/master/helm/hugegraph/examples) for all seven local PVs, `WaitForFirstConsumer`, registry mirrors and GitOps Secrets. An initially Pending PVC with `WaitForFirstConsumer` can be normal; persistent Pending needs PVC/Pod events and PV matching checks. @@ -26,6 +26,9 @@ kubectl get pv,storageclass For `ImagePullBackOff`, inspect Pod events and registry access/credentials. The default image inventory contains four component images; Store wait and Helm test reuse existing component images with `curl` already installed. Explicit helper-image overrides must also be mirrored. +Enabled SeaTunnel adds its configured `apache/seatunnel` image; enabled Vermeer adds a compatible `hugegraph/vermeer` build, +reused by Master, Worker and token initialization. The base local-PV example omits Vermeer claims: standalone adds two, +while cluster adds one Master claim plus one per Worker (four additional claims by default). ## 2 Ports and health @@ -35,6 +38,26 @@ PD `/v1/ready` requires a Raft leader; `/v1/health` only confirms the listener. Server waits up to `server.storageWaitTimeoutSeconds` (default 300) before its application startup; adjust it for slow storage bootstrap. No local Helm rendering verifies live cluster reachability, volumes or JVM capacity. +> [!DETAILS]- Optional engines: readiness, credentials and recovery +> SeaTunnel and Vermeer stay disabled in both HugeGraph presets; enabling either adds separate entry credentials and network rules. +> SeaTunnel HTTP/UI uses 8080 and Basic authentication; member/CLI 5801 is restricted to trusted release peers even in easy mode. +> Its long-running hybrid process does not provide PVC-backed checkpoint recovery. +> +> Vermeer Master HTTP/gRPC uses 6688/6689, and Worker HTTP/gRPC uses 6788/6789. Only authenticated Master HTTP is exposed. +> Standalone has one Pod with separate Master/Worker containers and data volumes; cluster has one Master plus three Worker Pods by default. +> Its kept signing factor and generated long-lived Hubble token are separate from Server login and PD credentials. +> Changing an external Secret requires rolling the dependent Vermeer workloads and Hubble so the token is regenerated. +> +> Master/Worker listener health does not prove space-level compute readiness. Check `/api/v1/workers/availability` with the service credential, +> then verify loading and a known algorithm result through Hubble. The common Worker pool avoids manual allocation for new spaces. +> Persistent metadata does not restore in-memory graphs, result caches or running jobs automatically. +> Stop submissions, finish/cancel tasks and unload compute graphs before topology/Worker-count changes; inspect availability and reload afterward. +> Standalone and cluster use different Worker claims, so changing modes does not migrate local files. +> +> Follow the [Vermeer operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> and [SeaTunnel operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) +> for token retrieval, credential sources, retained claims and exact upgrade commands. + ### Helm test coverage `helm test` validates graph binding on every Server Pod (`DEFAULT-hugegraph` by default, or configured via `server.testGraphAlias`), and requires diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 26f112f3e1..50d325eecf 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -118,7 +118,7 @@ and `allocateLoadBalancerNodePorts`, subject to the cluster/controller's capabil NodePort omission or `0` means automatic allocation. Fixed ports are validated against the cluster's configured range by Kubernetes; the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields remain accepted but no longer gate rendering. -### Optional engines: disabled by default +### Optional engines: disabled by default {#optional-engines} SeaTunnel and Vermeer remain disabled with both `values-single.yaml` and `values-cluster.yaml`. These presets select HugeGraph's HStore topology; `seatunnel.mode` and `vermeer.mode` select the optional engines' own topology. From 948174c907254bba6ceeff63576ffe38369381ec Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 04:38:19 +0000 Subject: [PATCH 03/11] docs: match Helm chart version examples --- content/cn/docs/quickstart/hugegraph/hugegraph-helm.md | 2 +- content/en/docs/quickstart/hugegraph/hugegraph-helm.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 734933912a..4285174737 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -6,7 +6,7 @@ search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, 内网部 --- 本文适用于 HugeGraph **1.8.0 及以后版本**，需要支持 OCI 的 Helm **3.10+** 和 Kubernetes (K8s) **1.23+**。 -可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本，例如 `0.3.x` 的 Chart 可以部署 `1.8.x` 的服务。 +可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本，例如 `0.4.x` 的 Chart 可以部署 `1.8.x` 的服务。 > [!WARNING] > 当前开发 Chart 使用 `latest` 镜像，适合测试。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 50d325eecf..4528701f58 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -7,7 +7,7 @@ search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, OCI, GHCR, This guide covers HugeGraph **1.8.0 and later**, using Helm **3.10+** with OCI support and Kubernetes (K8s) **1.23+**. Install `hugegraph-helm` from GHCR or Docker Hub. Chart and HugeGraph versions are maintained separately: -for example, a `0.3.x` Chart can deploy a `1.8.x` service. +for example, a `0.4.x` Chart can deploy a `1.8.x` service. > [!WARNING] > The current development Chart uses `latest` images and is intended for testing. From 9aee1218b9dd005f54be9108163c506504ce0a28 Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 04:38:49 +0000 Subject: [PATCH 04/11] docs: keep optional engine tables readable --- content/cn/docs/quickstart/hugegraph/hugegraph-helm.md | 10 ++++++---- content/en/docs/quickstart/hugegraph/hugegraph-helm.md | 10 ++++++---- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 4285174737..03eb5a4688 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -119,11 +119,13 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 这两个预设选择 HugeGraph 的 HStore 拓扑；`seatunnel.mode` 和 `vermeer.mode` 分别选择可选引擎的拓扑， 顶层 `mode: easy/strict` 则独立控制 HTTP 入口与网络隔离。 -| 组件 | 默认状态 | 按需启用 | +| 组件 | 默认值 | 开关 | |---|---|---| -| Hubble | 开启 | `hubble.enabled=false` 切换为仅 API 部署 | -| SeaTunnel | 关闭 | `seatunnel.enabled=true` 开启导入导出与原生 UI | -| Vermeer | 关闭 | `vermeer.enabled=true` 开启图计算、Hubble 联动与原生 UI | +| Hubble | `true` | `hubble.enabled` | +| SeaTunnel | `false` | `seatunnel.enabled` | +| Vermeer | `false` | `vermeer.enabled` | + +将引擎开关设为 `true` 即可启用；`hubble.enabled=false` 切换为仅 API 部署。 下面示例从 HugeGraph 仓库根目录安装源码 Chart。 启用 Vermeer 前须确认 Hubble/Vermeer 镜像包含对应能力，并固定已验证的镜像引用； diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 4528701f58..87481071ad 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -124,11 +124,13 @@ SeaTunnel and Vermeer remain disabled with both `values-single.yaml` and `values These presets select HugeGraph's HStore topology; `seatunnel.mode` and `vermeer.mode` select the optional engines' own topology. Top-level `mode: easy/strict` separately controls HTTP entry and network isolation. -| Component | Default | Opt in | +| Component | Default | Switch | |---|---|---| -| Hubble | Enabled | `hubble.enabled=false` selects API-only access | -| SeaTunnel | Disabled | `seatunnel.enabled=true` enables import/export and its native UI | -| Vermeer | Disabled | `vermeer.enabled=true` enables computation, Hubble integration and its native UI | +| Hubble | `true` | `hubble.enabled` | +| SeaTunnel | `false` | `seatunnel.enabled` | +| Vermeer | `false` | `vermeer.enabled` | + +Set an engine's switch to `true` to enable it. Set `hubble.enabled=false` for API-only access. The examples below use the source Chart from the HugeGraph repository root. Vermeer and Hubble need compatible image builds; verify their capabilities and pin the tested references before installing. From 5ee6e6c0681954897a90d886b989703e44b9b00a Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 04:47:17 +0000 Subject: [PATCH 05/11] docs: preserve Helm metadata namespace --- .../quickstart/computing/hugegraph-vermeer.md | 7 ++++++ .../hugegraph/hugegraph-helm-operations.md | 22 ++++++++++++++++++ .../quickstart/hugegraph/hugegraph-helm.md | 11 +++++++++ .../quickstart/computing/hugegraph-vermeer.md | 8 +++++++ .../hugegraph/hugegraph-helm-operations.md | 23 +++++++++++++++++++ .../quickstart/hugegraph/hugegraph-helm.md | 11 +++++++++ 6 files changed, 82 insertions(+) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index 6e54bace0d..01f921b068 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -53,6 +53,13 @@ flowchart LR > 则使用 1 个 Master Pod 和可调数量的 Worker Pod。两者都依赖 HStore/PD 数据链路，轻量 HugeGraph 预设已提供它。 > 顶层 `mode: easy/strict` 独立选择 NodePort 或 ClusterIP HTTP 入口以及网络策略默认值。 > +> 保留已初始化的 `metadataCluster`，默认 `hg-test`；Chart 统一 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER` 供 Schema 读取。 +> 这是 PD 元数据前缀，不是 Raft 名称；改变它不会迁移已有图，不要为了启用 Vermeer 将其改成 `hg`。 +> 加载报 `Schema missing` 或 `no such vertex label` 时，先检查命名空间和运行中 Store Pod 的环境是否对齐。 +> 旧自定义前缀先按 [Helm 运维](/cn/docs/quickstart/hugegraph/hugegraph-helm-operations/#metadata-namespace)核对并记录既有值。 +> 旧 release 首次启用先导出／审阅 `helm get values --all -o yaml`，再用 `-f` 传入，升级时不加 `--reuse-values`，完整流程见部署指南。 +> `OnDelete` 需按既有受控流程更新 Store Pod，新环境才会生效；替换 `emptyDir` Pod 会丢弃其数据，不能视为无损迁移。 +> > Hubble 自动获得 Master 内部地址与服务令牌。HugeGraph 管理员可以加载／重载图、运行九种支持算法、查看／取消任务、 > 分页浏览结果并卸载计算副本；结果不会写回图属性。原生 Vermeer UI/API 也同时提供，使用独立管理员令牌登录。 > 不承诺 Master 自动故障切换或运行中任务自动恢复。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 91fe8813f4..2862bc79e8 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -36,6 +36,28 @@ PD `/v1/ready` 需要 Raft leader，`/v1/health` 只说明监听器已启动，S Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTimeoutSeconds` 调整。 本地模板渲染不能验证集群连通性、卷挂载或 JVM 运行容量。 +### 保留元数据命名空间 {#metadata-namespace} + +`metadataCluster: hg-test` 保留旧 Server 的 PD 元数据前缀，并统一配置 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER`。 +它不是 Raft 名称，也不是元数据迁移开关；不要为了启用 Vermeer 把已初始化部署切换成 `hg`。 +若 Server REST 查询正常，而 Vermeer 扫描 Store 报 `Schema missing` 或 `no such vertex label`， +先核对共享值、既有 Server 元数据命名空间，以及每个运行中 Store Pod 的环境是否一致。 + +在线升级会拒绝与 Server Deployment 记录的 annotation 或显式 `HG_SERVER_CLUSTER` 冲突的目标值。 +标准旧 `hg-test` 部署无需额外认领操作。若旧自定义镜像用了其他前缀且 Chart 无法确认， +先读取既有 Server 日志／配置，确认实际值，再在 Server Deployment 记录该值，并在审阅后的 Helm values 中将 `metadataCluster` 设为同一值： + +```bash +kubectl -n hugegraph annotate deployment hugegraph-server \ + hugegraph.apache.org/metadata-cluster='<核实过的既有命名空间>' +``` + +只在完成核对后替换占位符；annotation 记录原本使用的命名空间，不复制或迁移 PD key。 +离线／GitOps 渲染无法检查在线 Deployment，应显式保留核实后的值。 +集群预设的 `store.updateStrategy.type=OnDelete` 不会因模板更新而替换正在运行的 Pod， +须按[逐个更新 Store 的既有流程](#6-rolling-store-images-safely)更新 Pod，新环境才会生效。 +替换使用 `emptyDir` 的 Pod 会丢弃其临时数据，这种滚动操作不能视为无损恢复或迁移。 + > [!DETAILS]- 可选引擎：就绪、凭据和恢复 > SeaTunnel 和 Vermeer 在两种 HugeGraph 预设中都默认关闭，启用后增加独立入口凭据与网络规则。 > SeaTunnel HTTP/UI 使用 8080 和 Basic 鉴权；成员／CLI 端口 5801 在 easy 下也限制为可信的同 release peers。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 03eb5a4688..66ff479193 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -167,6 +167,17 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > 执行 `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` 后访问 `http://127.0.0.1:6688/`。 > 匹配镜像、令牌获取、部署凭据、持久化和模式切换见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 > 原生联动要求 `hubble.mode=pd`；设置 `hubble.enabled=false` 时仍可通过原生入口使用 Vermeer。 +> 对新增 Vermeer 之前的旧 release 首次启用时，先导出并审阅 `helm get values --all -o yaml`，再用 `-f` 传入， +> 不加 `--reuse-values`，以便加载新 Vermeer 默认值。保留既有 `metadataCluster`，完整命令见部署指南。 + +### PD 元数据命名空间 {#metadata-namespace} + +顶层 `metadataCluster` 默认为 `hg-test`，保留既有 Server 元数据前缀。 +Chart 将同一值注入 Server 的 `HG_SERVER_CLUSTER` 和 Store 的 `PD_CLUSTER`，让 Store 扫描读取到 Server 写入的 Schema。 +该前缀独立于 Raft 名称、服务 ID 和图空间；新部署可在初始化前选择其他标识符。 +初始化后改变该值不会迁移元数据或图数据，启用 Vermeer 时应保留原 Server 的值。 +标准旧部署使用 `hg-test`，无需额外认领命名空间；旧自定义前缀请先按 +[元数据命名空间接入步骤](./hugegraph-helm-operations.md#metadata-namespace)核对，再执行升级。 ### 服务身份与图空间 diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index afb8f7b94c..67951d97cc 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -53,6 +53,14 @@ flowchart LR > set `vermeer.mode=cluster` and `vermeer.worker.replicas=3`. Both require the HStore/PD data path; the small HugeGraph preset provides it. > Top-level `mode: easy/strict` independently selects NodePort or ClusterIP HTTP entry and network policy defaults. > +> Keep the initialized `metadataCluster` (default `hg-test`): the Chart aligns Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER` for Schema reads. +> This is a PD metadata prefix, not a Raft name; changing it does not migrate an existing graph. Do not change it to `hg` to enable Vermeer. +> If loads fail with `Schema missing` or `no such vertex label`, check namespace alignment and the environment of running Store Pods first. +> Older custom prefixes require verification/adoption as described in [Helm operations](/docs/quickstart/hugegraph/hugegraph-helm-operations/#metadata-namespace). +> For first enablement on an older release, export/review `helm get values --all -o yaml` and upgrade with that file through `-f` without `--reuse-values`; +> the deployment guide gives the complete sequence. With `OnDelete`, Store Pods need the existing controlled update procedure to use changed environment. +> Replacing `emptyDir` Pods discards their data and is not a lossless migration. +> > Hubble receives the internal Master URL and service token automatically. A HugeGraph administrator can load/reload a graph, > run nine supported algorithms, inspect/cancel tasks, page through results and unload the compute copy. Results are not written back to graph properties. > The native Vermeer UI/API is available too, with separate administrator-token login. No Master failover or automatic task recovery is promised. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index b8901dd84d..f598cdc9e0 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -38,6 +38,29 @@ PD `/v1/ready` requires a Raft leader; `/v1/health` only confirms the listener. Server waits up to `server.storageWaitTimeoutSeconds` (default 300) before its application startup; adjust it for slow storage bootstrap. No local Helm rendering verifies live cluster reachability, volumes or JVM capacity. +### Preserve the metadata namespace {#metadata-namespace} + +`metadataCluster: hg-test` keeps the legacy Server PD metadata prefix and configures both Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER`. +It is not a Raft name or a metadata-migration option. Do not switch an initialized deployment to `hg` merely to enable Vermeer. +If Vermeer Store scans report `Schema missing` or `no such vertex label` while Server REST queries work, first compare this shared value +with the existing Server metadata namespace and the environment of each running Store Pod. + +Online upgrades reject a target value that conflicts with the recorded Server Deployment annotation or explicit `HG_SERVER_CLUSTER` value. +Standard legacy `hg-test` releases need no extra adoption action. If an older custom image used another prefix and the Chart cannot verify it, +inspect the existing Server logs/configuration first. Record that verified existing value on the Server Deployment, then set `metadataCluster` +to exactly the same value in the reviewed Helm values: + +```bash +kubectl -n hugegraph annotate deployment hugegraph-server \ + hugegraph.apache.org/metadata-cluster='' +``` + +Replace the placeholder only after verification. This records the namespace already in use; it does not copy or migrate PD keys. +Offline/GitOps rendering cannot inspect the running Deployment, so preserve the verified value explicitly. +With the cluster preset's `store.updateStrategy.type=OnDelete`, updating the StatefulSet template does not update running Pods. +Apply the existing [one-at-a-time Store procedure](#6-rolling-store-images-safely) before expecting the new environment to take effect. +Replacing a Pod backed by `emptyDir` discards its temporary data; such a rollout is not a lossless recovery or migration. + > [!DETAILS]- Optional engines: readiness, credentials and recovery > SeaTunnel and Vermeer stay disabled in both HugeGraph presets; enabling either adds separate entry credentials and network rules. > SeaTunnel HTTP/UI uses 8080 and Basic authentication; member/CLI 5801 is restricted to trusted release peers even in easy mode. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 87481071ad..dd1c09d0b8 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -174,6 +174,17 @@ A published Chart or a moving `latest` tag does not prove that the required appl > The [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) > covers matching builds, token retrieval, deployment credentials, storage and mode changes. > Hubble requires `hubble.mode=pd` for this native integration; API-only Vermeer remains usable with `hubble.enabled=false`. +> For first enablement on a pre-Vermeer release, export and review `helm get values --all -o yaml`, then supply that file with `-f` +> without `--reuse-values`, allowing the new Vermeer defaults to load. Preserve `metadataCluster`; see the deployment guide for the complete command. + +### PD metadata namespace {#metadata-namespace} + +Top-level `metadataCluster` defaults to `hg-test`, preserving the existing Server metadata prefix. +The Chart supplies the same value as Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER`, so Store scans resolve the Schema written by Server. +This prefix is independent of Raft names, service IDs and graph spaces. A new deployment can choose another identifier before initialization. +Changing the value afterward does not migrate metadata or graph data; keep the initialized Server value when enabling Vermeer. +Standard older releases using `hg-test` need no namespace-adoption step. For a custom legacy prefix, follow +[metadata namespace adoption](./hugegraph-helm-operations.md#metadata-namespace) before upgrading. ### Server service identity and graph space From 643baef3c25c6648ba5850c0c90251f6374208b8 Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 05:27:40 +0000 Subject: [PATCH 06/11] docs: keep native engines private and simple --- .../quickstart/computing/hugegraph-vermeer.md | 16 ++++--- .../hugegraph/hugegraph-helm-operations.md | 20 +++++--- .../quickstart/hugegraph/hugegraph-helm.md | 43 ++++++++++------- .../quickstart/computing/hugegraph-vermeer.md | 18 +++++--- .../hugegraph/hugegraph-helm-operations.md | 22 ++++++--- .../quickstart/hugegraph/hugegraph-helm.md | 46 ++++++++++++------- 6 files changed, 106 insertions(+), 59 deletions(-) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index 01f921b068..bd1b1e52f0 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -40,18 +40,18 @@ flowchart LR > [!DETAILS]- Helm：与 HugeGraph、Hubble 一起部署 Vermeer > HugeGraph Helm Chart 提供可选的原生 Vermeer 集成，两种 HugeGraph 拓扑预设都默认关闭。 -> 先在 `my-images.yaml` 选好匹配的 Hubble/Vermeer 构建，再从 HugeGraph 仓库根目录运行： +> 从 HugeGraph 仓库根目录开启 Vermeer，之后登录现有 Hubble 入口： > > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ -> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> -f helm/hugegraph/values-single.yaml \ > --set vermeer.enabled=true --set vermeer.mode=standalone \ > --wait --timeout 20m > ``` > > 单机为一个 Pod 内独立的 Master 和 Worker 容器；设置 `vermeer.mode=cluster` 与 `vermeer.worker.replicas=3`， > 则使用 1 个 Master Pod 和可调数量的 Worker Pod。两者都依赖 HStore/PD 数据链路，轻量 HugeGraph 预设已提供它。 -> 顶层 `mode: easy/strict` 独立选择 NodePort 或 ClusterIP HTTP 入口以及网络策略默认值。 +> 顶层 `mode: easy/strict` 独立选择 Server/Hubble 入口与完整网络隔离，原生引擎在两种模式下都保留为私有服务。 > > 保留已初始化的 `metadataCluster`，默认 `hg-test`；Chart 统一 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER` 供 Schema 读取。 > 这是 PD 元数据前缀，不是 Raft 名称；改变它不会迁移已有图，不要为了启用 Vermeer 将其改成 `hg`。 @@ -61,17 +61,21 @@ flowchart LR > `OnDelete` 需按既有受控流程更新 Store Pod，新环境才会生效；替换 `emptyDir` Pod 会丢弃其数据，不能视为无损迁移。 > > Hubble 自动获得 Master 内部地址与服务令牌。HugeGraph 管理员可以加载／重载图、运行九种支持算法、查看／取消任务、 -> 分页浏览结果并卸载计算副本；结果不会写回图属性。原生 Vermeer UI/API 也同时提供，使用独立管理员令牌登录。 +> 分页浏览结果并卸载计算副本；结果不会写回图属性。原生 Vermeer UI/API 始终为私有 ClusterIP，访问始终需要登录。 +> 按需管理使用经过授权的 port-forward，将 `-vermeer-admin` Secret 的 `password` 中独立 16 位密码 +> 粘贴到 **Admin credential**，无需用户名；登录获得 24 小时版本化会话 Cookie，Hubble 服务鉴权仍自动接入。 > 不承诺 Master 自动故障切换或运行中任务自动恢复。 > 镜像前提、凭据、端口和持久化见 [Helm 可选引擎](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) > 与 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 -> 不要仅凭现有 `latest` 标签假定镜像已包含新能力。 +> 镜像发布使用 [Vermeer 发布工作流](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml)。 > [!WARNING] > 生产环境必须启用 HugeGraph Server [认证与授权](/cn/docs/config/config-authentication/)、IP 白名单和最小权限授权，并保留 `audit-*.log` 审计记录。Server Auth 不会保护 Vermeer、PD 和 Store 的独立接口；这些 HTTP、gRPC 端口必须限制在可信网络及调用方范围内，Vermeer 对外入口需配置访问控制。 > -> Vermeer 的 `master.ini` 默认 `auth=none`，普通及管理 API 均未启用鉴权。本机快速上手只发布回环端口；远程访问前必须启用 `auth=token`，或通过受保护网络、网关将访问限制到可信调用方。 +> 上游手工配置 `master.ini` 仍默认 `auth=none`，下方手工 Docker 示例仅发布回环端口。这与本次 Helm 集成相互独立： +> Helm 始终使用 token 鉴权、私有原生 Service 与管理员密码，不能把手工未鉴权默认值当成 Helm 的便捷替代方案。 +> 手工保护部署应在远程访问前启用 `auth=token`，并按上游说明配置文件凭据。 下面两种 Docker 启动方式都需要先准备一个宿主机配置目录。请在 Vermeer 仓库根目录执行，将项目提供的 [`master.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/master.ini) 和 [`worker.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/worker.ini) 模板复制到该目录；挂载会覆盖镜像里的 `/go/bin/config`，所以不要把空目录或整个用户主目录挂进去： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 2862bc79e8..1e350201aa 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -60,13 +60,15 @@ kubectl -n hugegraph annotate deployment hugegraph-server \ > [!DETAILS]- 可选引擎：就绪、凭据和恢复 > SeaTunnel 和 Vermeer 在两种 HugeGraph 预设中都默认关闭，启用后增加独立入口凭据与网络规则。 -> SeaTunnel HTTP/UI 使用 8080 和 Basic 鉴权；成员／CLI 端口 5801 在 easy 下也限制为可信的同 release peers。 +> SeaTunnel HTTP/UI 使用 8080 和 Basic 鉴权，两种模式都将私有 HTTP／成员端口限制为必要的内部调用方。 > 常驻 hybrid 进程不代表 checkpoint 已通过 PVC 持久化。 > -> Vermeer Master HTTP/gRPC 为 6688/6689，Worker HTTP/gRPC 为 6788/6789；仅鉴权后的 Master HTTP 对外提供入口。 +> Vermeer Master HTTP/gRPC 为 6688/6689，Worker HTTP/gRPC 为 6788/6789，原生 UI/API 也始终保留为私有 ClusterIP。 > 单机为一个 Pod 中独立的 Master/Worker 容器和数据卷；集群默认为 1 个 Master 加 3 个 Worker Pod。 -> 保留的签名因子和自动生成的 Hubble 长期服务令牌，与 Server 登录和 PD 凭据相互独立。 -> 修改外部 Secret 后需滚动相关 Vermeer 工作负载及 Hubble，才能刷新进程凭据和服务令牌。 +> 两个引擎的原生入口始终需要登录。新管理员密码为 16 位，升级复用既有凭据，按需管理使用经过授权的 port-forward。 +> Vermeer 的 **Admin credential** 直接接受 `-vermeer-admin` Secret 的 `password`，无需用户名，登录获得 24 小时版本化会话 Cookie。 +> SeaTunnel 用户名仍为 `admin`。Hubble 服务鉴权自动接入，与人类管理密码独立，不需要用户获取令牌。 +> 更改外部 Vermeer 管理密码 Secret 只需重启 Master；内部服务签名因子轮换需重启 Master 与 Hubble，无需重启 Worker。 > > Master/Worker 监听器健康不代表当前空间已可计算。以服务凭据检查 `/api/v1/workers/availability`， > 再通过 Hubble 实测加载和已知算法结果；公共 Worker 池避免新空间需要手工分配。 @@ -74,7 +76,7 @@ kubectl -n hugegraph annotate deployment hugegraph-server \ > 切换拓扑或 Worker 数前停止新提交、完成／取消任务并卸载计算图，变更后检查可用性并重新加载。 > 单机和集群使用不同 Worker claim，模式切换不会迁移本地文件。 > -> 令牌获取、凭据来源、保留卷与升级步骤见 [Vermeer 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> 管理密码获取、保留卷与升级步骤见 [Vermeer 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) > 和 [SeaTunnel 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 ### Helm test 检查范围 {#helm-test-coverage} @@ -130,10 +132,11 @@ PD 会持久化分区设置，初始化后修改 chart 值不会覆盖已有元 ## 5 NetworkPolicy {#5-networkpolicy} -easy 模式及普通集群预设默认关闭，strict 模式默认开启；显式 `networkPolicy.enabled` 在任何模式都优先。 +基础服务的完整隔离在 easy 和普通集群预设下默认关闭，strict 下开启。 +SeaTunnel 和 Vermeer 的私有 ClusterIP、登录及原生 HTTP／RPC 入口限制始终生效，`networkPolicy.enabled=false` 也不例外。 集群网络插件必须支持策略执行，才有实际隔离效果。 生成策略允许组件间通信和 DNS，外部客户端、Ingress 控制器需要适当的 `networkPolicy..extraIngress`， -外部发现地址可能还需要 `extraEgress`。空列表合法但可能阻止外部访问；支持 Kubernetes 原生规则，包括允许全部的 `{}`，不要求额外来源确认。 +外部发现地址可能还需要 `extraEgress`。基础服务规则的空列表合法但可能阻止外部访问，并支持 Kubernetes 原生规则，包括允许全部的 `{}`。 按实际来源地址或 selector 配置，并考虑 NodePort SNAT 和控制器行为。 ```yaml @@ -157,6 +160,9 @@ networkPolicy: port: 8088 ``` +原生引擎的 ingress 只接受显式内部 Pod／namespace selector，拒绝 IP block 和允许全部的规则。 +上面的基础服务示例用于 Server，不用于对外暴露原生引擎；外部数据源可按需配置引擎 `extraEgress`，strict 进一步限制出站流量。 + ## 6 逐个升级 Store {#6-rolling-store-images-safely} 集群预设使用 `store.updateStrategy.type=OnDelete` 便于维护时控制逐个替换。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 66ff479193..1bb0de83ac 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -86,7 +86,8 @@ hugegraph-helm/ ``` 默认 `mode: easy`，Server 和 Hubble 自动分配 NodePort，PD 保持 ClusterIP。可以直接使用 HTTP，无需域名、证书或额外确认参数。 -`mode: strict` 默认将 Server/Hubble 和已启用可选组件的 HTTP 入口设为 ClusterIP，并开启 NetworkPolicy。两个模式都保留鉴权和持久化。 +`mode: strict` 默认将 Server/Hubble 设为 ClusterIP，并开启完整 NetworkPolicy 隔离。 +SeaTunnel 和 Vermeer 的原生 Service 在两种模式下始终为私有 ClusterIP，访问始终需要登录。两个模式都保留鉴权和持久化。 优先级是组件显式参数高于全局参数，全局参数高于模式默认值，显式 `false` 也会生效。 全局参数包括 `persistence.enabled` 和 `global.imageRegistry`，严格预设为 `values-strict.yaml`。 @@ -117,7 +118,7 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 `values-single.yaml` 和 `values-cluster.yaml` 都不会开启 SeaTunnel 或 Vermeer。 这两个预设选择 HugeGraph 的 HStore 拓扑；`seatunnel.mode` 和 `vermeer.mode` 分别选择可选引擎的拓扑， -顶层 `mode: easy/strict` 则独立控制 HTTP 入口与网络隔离。 +顶层 `mode: easy/strict` 则独立控制 Server/Hubble 的 HTTP 入口与完整网络隔离。 | 组件 | 默认值 | 开关 | |---|---|---| @@ -127,9 +128,7 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 将引擎开关设为 `true` 即可启用；`hubble.enabled=false` 切换为仅 API 部署。 -下面示例从 HugeGraph 仓库根目录安装源码 Chart。 -启用 Vermeer 前须确认 Hubble/Vermeer 镜像包含对应能力，并固定已验证的镜像引用； -已发布 Chart 或可变的 `latest` 标签本身不能证明应用改动已经包含在镜像中。 +下面示例从 HugeGraph 仓库根目录安装源码 Chart。使用 Vermeer 图计算只需开启开关并登录 Hubble，服务地址与凭据由 Chart 自动接入。 > [!DETAILS]- SeaTunnel：按需开启原生导入、导出和迁移 > ```bash @@ -140,32 +139,35 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > ``` > > 单机模式运行一个常驻 hybrid 成员；设置 `seatunnel.mode=cluster` 和 `seatunnel.replicas=2` 可运行多个成员。 -> 两种模式都有原生 UI/API，使用独立的 HTTP Basic 凭据。 -> HTTP 入口在 easy 下为 NodePort、strict 下为 ClusterIP；成员端口 5801 始终限制为可信的同 release peers。 +> 原生 UI/API 在两种模式下都保留为私有 ClusterIP，始终需要独立的 HTTP Basic 登录。 +> 新生成的管理员密码为 16 位，升级复用既有凭据；两种模式都将 HTTP／成员端口限制为必要的内部调用方。 +> 按需管理时使用经过授权的 port-forward，步骤见部署指南。 > Helm 准备引擎和示例，不自动建图或执行作业；checkpoint 使用临时本地文件。 > 访问、凭据、复制示例和恢复限制见 [SeaTunnel 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 > [!DETAILS]- Vermeer：按需开启图计算，自动接入 Hubble > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ -> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> -f helm/hugegraph/values-single.yaml \ > --set vermeer.enabled=true --set vermeer.mode=standalone \ > --wait --timeout 20m > ``` > -> 先在 `my-images.yaml` 中选择匹配的 Hubble/Vermeer 镜像。 > 单机模式使用一个 Pod，内含独立的 Master 和 Worker 原生进程容器，各自挂载数据卷。 > 设置 `vermeer.mode=cluster` 后为 1 个 Master Pod 加 `vermeer.worker.replicas` 个 Worker Pod，默认 3 个 Worker。 > 多 Worker 提供分布式计算；单 Master 不承诺自动故障切换。 > > 保持 Hubble 默认的 PD 模式，Chart 会自动提供 Master 内部地址和服务令牌，无需手工填写。 > 以 HugeGraph 管理员登录 Hubble，选择 HStore 图，加载／重载后运行九种支持算法之一， -> 查看／取消异步任务并分页浏览结果，结束后卸载计算副本。 +> 查看／取消异步任务并分页浏览结果。计算副本清理由既有 Hubble 管理员 API 完成，当前页面提供加载／重载，没有独立卸载按钮。 > 此流程不把结果写回 HugeGraph 属性；普通图读取用户不会因此获得直接扫描 Store 的权限。 > -> Vermeer 原生 UI/API 也同时提供：easy 下使用 NodePort，strict 下使用 ClusterIP，令牌登录与 Hubble 登录相互独立。 +> Vermeer 原生 UI/API 在两种模式下都保留为私有 ClusterIP。按需管理时， > 执行 `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` 后访问 `http://127.0.0.1:6688/`。 -> 匹配镜像、令牌获取、部署凭据、持久化和模式切换见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 +> 从 Secret `hugegraph-vermeer-admin` 的 `password` 键读取独立的 16 位管理员密码，粘贴到 **Admin credential** 输入框。 +> 登录后获得有效期 24 小时的版本化会话 Cookie；使用 Hubble 无需手工获取服务令牌。 +> 密码获取、持久化、模式切换与高级服务凭据见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 +> 镜像发布使用 [Vermeer 发布工作流](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml)。 > 原生联动要求 `hubble.mode=pd`；设置 `hubble.enabled=false` 时仍可通过原生入口使用 Vermeer。 > 对新增 Vermeer 之前的旧 release 首次启用时，先导出并审阅 `helm get values --all -o yaml`，再用 `-f` 传入， > 不加 `--reuse-values`，以便加载新 Vermeer 默认值。保留既有 `metadataCluster`，完整命令见部署指南。 @@ -283,10 +285,19 @@ GitOps 使用加密的固定值，或预先创建 Secret 并配置 `pd.auth.exis Hubble 默认开启，当前镜像的登录仍依赖 Server 鉴权。只使用 API 可以设置 `hubble.enabled=false`， 如需关闭 API 鉴权，再设置 `server.auth.enabled=false`。未使用的凭据配置可以留在 values 中。 -可选引擎启用后增加独立入口凭据：SeaTunnel 使用原生 HTTP Basic；Vermeer 使用保留的签名因子 Secret， -通过 `vermeer.auth.value` 或 `vermeer.auth.existingSecret/key` 配置，Hubble 会自动生成长期服务令牌。GitOps 需要保留稳定的凭据来源。 -Worker Schema 读取默认复用部署管理员凭据，也可通过 `vermeer.hugegraphCredentials.existingSecret/key` 指向现有用户的受保护用户名密码 JSON； -该用户需具备目标图的 Schema 权限，Chart 不会自动创建账户。 +可选引擎的原生入口始终需要登录，easy 模式也不例外。新安装生成独立的 16 位管理员密码： +SeaTunnel 使用 HTTP Basic，Vermeer 使用 `-vermeer-admin` Secret 与 **Admin credential** 登录，升级保留既有凭据。 +Vermeer 管理密码可通过 `vermeer.auth.admin.password` 或 `vermeer.auth.admin.existingSecret/key` 配置，仅 Master 读取。 +原生管理按需使用经过授权的 port-forward，Hubble 的服务凭据自动配置。 + +> [!DETAILS]- 高级：Vermeer 部署凭据与 GitOps +> GitOps 需保留稳定的管理员凭据和独立的内部服务身份。 +> 服务签名因子通过 `vermeer.auth.value` 或 `vermeer.auth.existingSecret/key` 配置，Hubble 自动生成服务令牌； +> 日常 Hubble 使用和原生密码登录都不需要手工获取该令牌。 +> 更改外部管理密码 Secret 只需重启 Master；服务签名因子轮换需重启 Master 与 Hubble，无需重启 Worker。 +> Worker Schema 读取默认复用部署管理员，也可通过 `vermeer.hugegraphCredentials.existingSecret/key` 指向现有用户的受保护用户名密码 JSON。 +> 该用户需具备目标图的 Schema 权限，Chart 不会自动创建账户。 + ## 5 升级和验证 diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index 67951d97cc..6755609084 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -40,18 +40,18 @@ flowchart LR > [!DETAILS]- Helm: deploy Vermeer together with HugeGraph and Hubble > The HugeGraph Helm Chart offers an optional native Vermeer integration. It is disabled by default in both HugeGraph topology presets. -> From the HugeGraph repository root, after selecting compatible Hubble/Vermeer builds in `my-images.yaml`: +> From the HugeGraph repository root, enable Vermeer and sign in to the existing Hubble entry: > > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ -> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> -f helm/hugegraph/values-single.yaml \ > --set vermeer.enabled=true --set vermeer.mode=standalone \ > --wait --timeout 20m > ``` > > Standalone uses one Pod with separate Master and Worker containers. Cluster mode uses one Master Pod plus configurable Worker Pods: > set `vermeer.mode=cluster` and `vermeer.worker.replicas=3`. Both require the HStore/PD data path; the small HugeGraph preset provides it. -> Top-level `mode: easy/strict` independently selects NodePort or ClusterIP HTTP entry and network policy defaults. +> Top-level `mode: easy/strict` independently selects Server/Hubble entry and full network isolation. Native engines stay private in both modes. > > Keep the initialized `metadataCluster` (default `hg-test`): the Chart aligns Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER` for Schema reads. > This is a PD metadata prefix, not a Raft name; changing it does not migrate an existing graph. Do not change it to `hg` to enable Vermeer. @@ -63,16 +63,22 @@ flowchart LR > > Hubble receives the internal Master URL and service token automatically. A HugeGraph administrator can load/reload a graph, > run nine supported algorithms, inspect/cancel tasks, page through results and unload the compute copy. Results are not written back to graph properties. -> The native Vermeer UI/API is available too, with separate administrator-token login. No Master failover or automatic task recovery is promised. +> The native UI/API remains a private ClusterIP Service and always requires login. Optional administration uses an authorized port-forward +> and the separate 16-character password in `-vermeer-admin`, key `password`. Paste it into **Admin credential**, with no username; +> login creates a 24-hour versioned session cookie. Hubble service authentication remains automatic. No Master failover or automatic task recovery is promised. > See [Helm optional engines](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and the > [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) -> for image prerequisites, credentials, ports and retained data. Do not assume an existing `latest` image contains the required new capabilities. +> for optional administration, retained data and advanced service credentials. Image publishing uses the +> [Vermeer publishing workflow](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml). > [!WARNING] > In production, enable [Server authentication and authorization](/docs/config/config-authentication/), an IP allowlist, and minimum permissions; retain `audit-*.log`. Server Auth does not protect independent Vermeer, PD, or Store APIs. Restrict these HTTP/gRPC ports to trusted networks and callers, and configure access controls at the Vermeer external entry point. > -> `master.ini` defaults to `auth=none`, disabling authentication for ordinary and administrative APIs. Local examples publish loopback only. Before remote access, enable `auth=token` or restrict callers through a protected network or gateway. +> Manual upstream `master.ini` defaults to `auth=none`; the manual Docker examples below publish loopback only. This is independent of the Helm integration, +> which always uses token authentication, a private native Service and an administrator password. +> Do not use the manual unauthenticated defaults as a Helm shortcut. +> For a protected manual deployment, enable `auth=token` and follow the upstream file-based credential instructions before remote access. Both Docker options need a host configuration directory. From the Vermeer repository root, copy the supplied [`master.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/master.ini) and [`worker.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/worker.ini) templates. The mount hides image configuration under `/go/bin/config`, so never mount an empty directory or your entire home directory there: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index f598cdc9e0..ec8ec34625 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -63,13 +63,16 @@ Replacing a Pod backed by `emptyDir` discards its temporary data; such a rollout > [!DETAILS]- Optional engines: readiness, credentials and recovery > SeaTunnel and Vermeer stay disabled in both HugeGraph presets; enabling either adds separate entry credentials and network rules. -> SeaTunnel HTTP/UI uses 8080 and Basic authentication; member/CLI 5801 is restricted to trusted release peers even in easy mode. +> SeaTunnel HTTP/UI uses 8080 and Basic authentication. Its private HTTP/member ports admit only required internal callers in both modes. > Its long-running hybrid process does not provide PVC-backed checkpoint recovery. > -> Vermeer Master HTTP/gRPC uses 6688/6689, and Worker HTTP/gRPC uses 6788/6789. Only authenticated Master HTTP is exposed. +> Vermeer Master HTTP/gRPC uses 6688/6689, and Worker HTTP/gRPC uses 6788/6789. Its native UI/API also remains private behind ClusterIP. > Standalone has one Pod with separate Master/Worker containers and data volumes; cluster has one Master plus three Worker Pods by default. -> Its kept signing factor and generated long-lived Hubble token are separate from Server login and PD credentials. -> Changing an external Secret requires rolling the dependent Vermeer workloads and Hubble so the token is regenerated. +> Both engines always require native login. New administrator passwords are 16 characters and upgrades retain existing credentials. +> Optional administration uses authorized port-forwarding; Vermeer **Admin credential** accepts the password from `-vermeer-admin`, +> key `password`, with no username required. Login creates a 24-hour versioned session cookie. SeaTunnel still uses username `admin`. +> Hubble service authentication is automatic and separate from human passwords; no token retrieval is needed. +> An external Vermeer administrator Secret change needs a Master restart only; internal service-factor rotation needs Master and Hubble, not Workers. > > Master/Worker listener health does not prove space-level compute readiness. Check `/api/v1/workers/availability` with the service credential, > then verify loading and a known algorithm result through Hubble. The common Worker pool avoids manual allocation for new spaces. @@ -79,7 +82,7 @@ Replacing a Pod backed by `emptyDir` discards its temporary data; such a rollout > > Follow the [Vermeer operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) > and [SeaTunnel operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) -> for token retrieval, credential sources, retained claims and exact upgrade commands. +> for administrator password retrieval, retained claims and exact upgrade commands. Raw service tokens are advanced internal integrations only. ### Helm test coverage @@ -139,11 +142,12 @@ before changing a live cluster; the chart does not migrate existing shard metada ## 5 NetworkPolicy -Easy mode, including the ordinary cluster preset, defaults policies off. Strict mode enables them; explicit `networkPolicy.enabled` wins in either mode. +Easy mode and the ordinary cluster preset leave full base-service isolation disabled by default; strict enables it. +SeaTunnel and Vermeer always keep private ClusterIP Services, login and native HTTP/RPC ingress restrictions, even with `networkPolicy.enabled=false`. The cluster network plugin must enforce NetworkPolicy for these resources to have an effect. The generated policies admit component traffic and DNS. External clients and Ingress controllers need suitable `networkPolicy..extraIngress` rules; external discovery addresses may need matching `extraEgress`. -An empty list is valid and can block external traffic. Native Kubernetes rules are accepted, including `{}` to allow all; +For base-service rules, an empty list can block outside traffic and native Kubernetes rules include `{}` to allow all; there is no separate source-acknowledgement gate. Use your actual source addresses/selectors, considering NodePort SNAT and controller behavior. ```yaml @@ -167,6 +171,10 @@ networkPolicy: port: 8088 ``` +Native engine ingress accepts explicit internal Pod/namespace selectors only; IP blocks and allow-all forms are rejected. +The base-service example above applies to Server, not native engine exposure. External data destinations can use engine `extraEgress`; +strict mode additionally enforces egress isolation. + ## 6 Rolling Store images safely Use `store.updateStrategy.type=OnDelete` for a controlled maintenance rollout, as the cluster preset does. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index dd1c09d0b8..7b37f72e69 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -90,7 +90,8 @@ hugegraph-helm/ ``` `mode: easy` is the default. Server and Hubble use automatic NodePorts; PD stays ClusterIP. HTTP works without a domain, certificate or acknowledgement. -`mode: strict` defaults Server/Hubble and enabled optional HTTP entries to ClusterIP and enables NetworkPolicy. +`mode: strict` defaults Server/Hubble to ClusterIP and enables full NetworkPolicy isolation. +SeaTunnel and Vermeer native Services stay private ClusterIP services and require login in both modes. Both modes keep authentication and persistence. Explicit component parameters take priority over global parameters, which take priority over mode defaults; explicit `false` remains an override. The global parameters are `persistence.enabled` and `global.imageRegistry`. Strict mode is also available through `values-strict.yaml`. @@ -122,7 +123,7 @@ the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields rem SeaTunnel and Vermeer remain disabled with both `values-single.yaml` and `values-cluster.yaml`. These presets select HugeGraph's HStore topology; `seatunnel.mode` and `vermeer.mode` select the optional engines' own topology. -Top-level `mode: easy/strict` separately controls HTTP entry and network isolation. +Top-level `mode: easy/strict` separately controls Server/Hubble HTTP entry and full network isolation. | Component | Default | Switch | |---|---|---| @@ -133,8 +134,7 @@ Top-level `mode: easy/strict` separately controls HTTP entry and network isolati Set an engine's switch to `true` to enable it. Set `hubble.enabled=false` for API-only access. The examples below use the source Chart from the HugeGraph repository root. -Vermeer and Hubble need compatible image builds; verify their capabilities and pin the tested references before installing. -A published Chart or a moving `latest` tag does not prove that the required application changes are already available. +For Vermeer computation, enable the switch and sign in to Hubble; service addresses and credentials are configured automatically. > [!DETAILS]- SeaTunnel: enable native import, export and migration > ```bash @@ -145,8 +145,9 @@ A published Chart or a moving `latest` tag does not prove that the required appl > ``` > > Standalone starts one long-running hybrid member. Set `seatunnel.mode=cluster` and `seatunnel.replicas=2` -> for multiple hybrid members. Both include the native UI/API, protected by separate HTTP Basic credentials. -> HTTP inherits NodePort in easy mode or ClusterIP in strict mode; member port 5801 stays restricted to trusted release peers. +> for multiple hybrid members. Native UI/API access remains private behind ClusterIP and always requires HTTP Basic login. +> New administrator passwords are 16 characters; upgrades reuse existing credentials. HTTP/member ports admit only required internal callers +> in both modes. For optional administration, use an authorized port-forward as described in the deployment guide. > Helm prepares the engine and examples; create graphs and submit jobs yourself. Checkpoints use temporary local files. > See the [SeaTunnel deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) > for access, credentials, copy examples and recovery limits. @@ -154,25 +155,28 @@ A published Chart or a moving `latest` tag does not prove that the required appl > [!DETAILS]- Vermeer: enable graph computation and automatic Hubble connection > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ -> -f helm/hugegraph/values-single.yaml -f my-images.yaml \ +> -f helm/hugegraph/values-single.yaml \ > --set vermeer.enabled=true --set vermeer.mode=standalone \ > --wait --timeout 20m > ``` > -> Select matching Hubble/Vermeer image references in `my-images.yaml` first. > Standalone uses one Pod with separate native Master and Worker containers and separate data volumes. > Set `vermeer.mode=cluster` for one Master Pod plus `vermeer.worker.replicas` Worker Pods (default 3). > Multiple Workers provide distributed computation; the single Master has no automatic failover guarantee. > > Keep Hubble in its default PD mode. The Chart supplies the internal Master URL and service token automatically. > Log in to Hubble as the HugeGraph administrator, select an HStore graph, load/reload it, run one of the nine supported algorithms, -> inspect/cancel the asynchronous task and page through results. Unload the compute copy when finished. +> inspect/cancel the asynchronous task and page through results. Compute-copy cleanup uses the existing Hubble administrator API; +> the current page has Load/Reload controls, not a separate Unload button. > This workflow does not write results into HugeGraph properties. Ordinary graph readers do not receive direct Store-scan privileges. > -> The native Vermeer UI/API is also exposed: easy uses NodePort, strict uses ClusterIP. Its administrator token login is separate from Hubble. -> Use `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` and open `http://127.0.0.1:6688/`. +> Native UI/API remains private behind ClusterIP in both modes. Optional administration uses +> `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` and `http://127.0.0.1:6688/`. +> Read the separate 16-character administrator password from Secret `hugegraph-vermeer-admin`, key `password`, +> and paste it into **Admin credential**. Login creates a 24-hour versioned session cookie. Hubble needs no manual service token. > The [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) -> covers matching builds, token retrieval, deployment credentials, storage and mode changes. +> covers password retrieval, storage, mode changes and advanced service credentials. Image publishing uses the +> [Vermeer publishing workflow](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml). > Hubble requires `hubble.mode=pd` for this native integration; API-only Vermeer remains usable with `hubble.enabled=false`. > For first enablement on a pre-Vermeer release, export and review `helm get values --all -o yaml`, then supply that file with `-f` > without `--reuse-values`, allowing the new Vermeer defaults to load. Preserve `metadataCluster`; see the deployment guide for the complete command. @@ -293,11 +297,19 @@ update the Secret/source to that same password, then restart the Server Deployme Hubble is enabled by default and its current login requires Server authentication. Set `hubble.enabled=false` for API-only access; optionally also set `server.auth.enabled=false` for an unauthenticated API. Inactive credential settings may remain in your values file. -Enabled optional engines add independent entry credentials. SeaTunnel uses native HTTP Basic authentication; -Vermeer uses a kept signing factor configured through `vermeer.auth.value` or `vermeer.auth.existingSecret/key`. -Hubble generates its long-lived Vermeer service token automatically from that factor. For GitOps, preserve stable credential sources. -Worker Schema reads reuse the deployment administrator credential unless `vermeer.hugegraphCredentials.existingSecret/key` supplies -a protected username/password JSON for an existing account with the required Schema permissions. No account is created automatically. +Enabled optional engines always require native login, including in easy mode. New installations generate separate 16-character +administrator passwords: SeaTunnel uses HTTP Basic, while Vermeer uses Secret `-vermeer-admin` and its **Admin credential** login. +Upgrades keep existing credentials. Vermeer password sources are `vermeer.auth.admin.password` or `vermeer.auth.admin.existingSecret/key`; +only Master reads that password. Native administration uses authorized port-forwarding, and Hubble service credentials are automatic. + +> [!DETAILS]- Advanced: Vermeer deployment credentials and GitOps +> For GitOps, preserve stable administrator credentials and the separate internal service identity. +> The service signing factor uses `vermeer.auth.value` or `vermeer.auth.existingSecret/key`; Hubble generates its service token automatically. +> Ordinary Hubble use and native password login do not require retrieving that token. +> Changing an external native administrator Secret needs a Master restart only. Service-factor rotation requires Master and Hubble, +> not Workers. Worker Schema reads reuse the deployment administrator unless `vermeer.hugegraphCredentials.existingSecret/key` +> supplies protected username/password JSON for an existing account with the required Schema permissions. No account is created automatically. + ## 5 Upgrade and verification From f3effa33aa34aac548dcb4aff34781bd66e1f5f7 Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 05:45:22 +0000 Subject: [PATCH 07/11] docs: pin published Vermeer image references --- .../docs/quickstart/computing/hugegraph-vermeer.md | 5 ++++- .../hugegraph/hugegraph-helm-operations.md | 5 ++++- .../cn/docs/quickstart/hugegraph/hugegraph-helm.md | 11 ++++++++--- .../docs/quickstart/computing/hugegraph-vermeer.md | 7 +++++-- .../hugegraph/hugegraph-helm-operations.md | 7 +++++-- .../en/docs/quickstart/hugegraph/hugegraph-helm.md | 13 +++++++++---- 6 files changed, 35 insertions(+), 13 deletions(-) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index bd1b1e52f0..852e15ebfd 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -67,7 +67,10 @@ flowchart LR > 不承诺 Master 自动故障切换或运行中任务自动恢复。 > 镜像前提、凭据、端口和持久化见 [Helm 可选引擎](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) > 与 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 -> 镜像发布使用 [Vermeer 发布工作流](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml)。 +> Chart 按经过验证的镜像索引 digest 固定 `hugegraph/vermeer:helm-2678ff91b56a`，由 +> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40639306743)基于源码 +> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241)发布。 +> 部署指南记录完整 digest 与自定义镜像覆盖流程。 > [!WARNING] diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 1e350201aa..76891346fc 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -25,7 +25,10 @@ kubectl get pv,storageclass 出现 `ImagePullBackOff` 时检查 Pod 事件、仓库连通性和拉取凭据。默认只需四个组件镜像，等待 Store/Helm test 复用已包含 curl 的组件镜像。 如显式覆盖 helper 镜像，该镜像也需要同步到内网仓库。 -启用 SeaTunnel 还需配置的 `apache/seatunnel` 镜像；启用 Vermeer 还需匹配的 `hugegraph/vermeer` 构建，Master、Worker 和令牌初始化共用它。 +启用 SeaTunnel 还需配置的 `apache/seatunnel` 镜像；启用 Vermeer 使用按 digest 固定的 `hugegraph/vermeer:helm-2678ff91b56a`， +Master、Worker 和令牌初始化共用它。[官方发布运行](https://github.com/hugegraph/actions/actions/runs/40639306743)记录源码与镜像 digest， +详见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 +自定义镜像覆盖还需同步更新 `vermeer.image.digest`，或显式清空以按标签选择；非空 digest 优先。 基础 local PV 示例不包含 Vermeer 卷：单机增加两个，集群增加一个 Master 卷及每 Worker 一个卷，默认增加四个。 ## 2 端口和健康检查 {#2-ports-and-health} diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index 1bb0de83ac..e7b73545ce 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -9,7 +9,8 @@ search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, 内网部 可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本，例如 `0.4.x` 的 Chart 可以部署 `1.8.x` 的服务。 > [!WARNING] -> 当前开发 Chart 使用 `latest` 镜像，适合测试。 +> 当前开发 Chart 的 HugeGraph 基础组件使用 `latest` 镜像，适合测试。 +> 可选 Vermeer 已固定为经过验证的已发布镜像及 digest，见[可选引擎](#optional-engines)。 > 对应 HugeGraph 服务正式发布后，生产环境请选择稳定 Chart，并检查其中的镜像版本。 > 镜像标签可能变化；需要固定镜像内容时，请配置各组件的 `image.digest`。 @@ -167,7 +168,10 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > 从 Secret `hugegraph-vermeer-admin` 的 `password` 键读取独立的 16 位管理员密码，粘贴到 **Admin credential** 输入框。 > 登录后获得有效期 24 小时的版本化会话 Cookie；使用 Hubble 无需手工获取服务令牌。 > 密码获取、持久化、模式切换与高级服务凭据见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 -> 镜像发布使用 [Vermeer 发布工作流](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml)。 +> Chart 将 `hugegraph/vermeer:helm-2678ff91b56a` 固定到镜像索引 digest +> `sha256:9ef623d93e4feddc345c6ce445109c4039b029be83090d0eca97aedeba981a9e`，由 +> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40639306743)基于源码 +> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241)发布。 > 原生联动要求 `hubble.mode=pd`；设置 `hubble.enabled=false` 时仍可通过原生入口使用 Vermeer。 > 对新增 Vermeer 之前的旧 release 首次启用时，先导出并审阅 `helm get values --all -o yaml`，再用 `-f` 传入， > 不加 `--reuse-values`，以便加载新 Vermeer 默认值。保留既有 `metadataCluster`，完整命令见部署指南。 @@ -210,8 +214,9 @@ GitOps 凭据、仅 API 部署以及无域名的 HTTP Ingress。 等待 PD 的 init container 复用 Store 镜像，Helm test 复用 Server 镜像。这两个镜像已包含 `curl`，无需额外 curl 镜像或启动时安装软件。 自定义镜像可以继续使用显式 `store.waitImage` 和 `server.waitImage` 覆盖。 -启用 SeaTunnel 时还需同步其配置的 `apache/seatunnel` 镜像，启用 Vermeer 时还需匹配的 `hugegraph/vermeer` 构建。 +启用 SeaTunnel 时还需同步其配置的 `apache/seatunnel` 镜像，启用 Vermeer 时使用上文固定的已发布构建。 Vermeer 的 Master、Worker 和服务令牌初始化复用同一镜像；所有已启用镜像及显式 helper 覆盖都应同步。 +使用自定义 Vermeer 镜像时，还需更新 `vermeer.image.digest`，或在按标签选择时显式清空；非空 digest 优先于标签。 ### 存储配置 diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index 6755609084..47534bef4f 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -68,8 +68,11 @@ flowchart LR > login creates a 24-hour versioned session cookie. Hubble service authentication remains automatic. No Master failover or automatic task recovery is promised. > See [Helm optional engines](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and the > [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) -> for optional administration, retained data and advanced service credentials. Image publishing uses the -> [Vermeer publishing workflow](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml). +> for optional administration, retained data and advanced service credentials. The Chart pins +> `hugegraph/vermeer:helm-2678ff91b56a` by verified image-index digest, published by the +> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40639306743) from source +> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241). +> The deployment guide records the digest and custom-image override procedure. > [!WARNING] diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index ec8ec34625..17f5718aa7 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -26,8 +26,11 @@ kubectl get pv,storageclass For `ImagePullBackOff`, inspect Pod events and registry access/credentials. The default image inventory contains four component images; Store wait and Helm test reuse existing component images with `curl` already installed. Explicit helper-image overrides must also be mirrored. -Enabled SeaTunnel adds its configured `apache/seatunnel` image; enabled Vermeer adds a compatible `hugegraph/vermeer` build, -reused by Master, Worker and token initialization. The base local-PV example omits Vermeer claims: standalone adds two, +Enabled SeaTunnel adds its configured `apache/seatunnel` image. Enabled Vermeer uses `hugegraph/vermeer:helm-2678ff91b56a`, pinned by digest +and reused by Master, Worker and token initialization. Its [official publishing run](https://github.com/hugegraph/actions/actions/runs/40639306743) +records the source and image digest; see the [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md). +Custom image overrides must also update `vermeer.image.digest`, or explicitly clear it to select by tag; digest takes priority. +The base local-PV example omits Vermeer claims: standalone adds two, while cluster adds one Master claim plus one per Worker (four additional claims by default). ## 2 Ports and health diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 7b37f72e69..1c86d96d2b 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -10,7 +10,8 @@ Install `hugegraph-helm` from GHCR or Docker Hub. Chart and HugeGraph versions a for example, a `0.4.x` Chart can deploy a `1.8.x` service. > [!WARNING] -> The current development Chart uses `latest` images and is intended for testing. +> The current development Chart uses `latest` images for the base HugeGraph components and is intended for testing. +> Optional Vermeer is pinned to a verified published image and digest; see [optional engines](#optional-engines). > For production, choose a stable Chart once the corresponding HugeGraph service has been released, and review its image versions. > Image tags can change; set each component's `image.digest` to keep using the same image content. @@ -175,8 +176,11 @@ For Vermeer computation, enable the switch and sign in to Hubble; service addres > Read the separate 16-character administrator password from Secret `hugegraph-vermeer-admin`, key `password`, > and paste it into **Admin credential**. Login creates a 24-hour versioned session cookie. Hubble needs no manual service token. > The [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) -> covers password retrieval, storage, mode changes and advanced service credentials. Image publishing uses the -> [Vermeer publishing workflow](https://github.com/hugegraph/actions/blob/master/.github/workflows/publish_latest_vermeer_image.yml). +> covers password retrieval, storage, mode changes and advanced service credentials. +> The Chart pins `hugegraph/vermeer:helm-2678ff91b56a` to image-index digest +> `sha256:9ef623d93e4feddc345c6ce445109c4039b029be83090d0eca97aedeba981a9e`, published by the +> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40639306743) from source +> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241). > Hubble requires `hubble.mode=pd` for this native integration; API-only Vermeer remains usable with `hubble.enabled=false`. > For first enablement on a pre-Vermeer release, export and review `helm get values --all -o yaml`, then supply that file with `-f` > without `--reuse-values`, allowing the new Vermeer defaults to load. Preserve `metadataCluster`; see the deployment guide for the complete command. @@ -220,8 +224,9 @@ The default mirror inventory is only `hugegraph/pd`, `hugegraph/store`, `hugegra Store's PD wait init container and the Helm test reuse Store and Server images respectively, which already contain `curl`. No separate curl image or runtime package installation is required. Explicit `store.waitImage` / `server.waitImage` overrides remain supported. -Enabled SeaTunnel additionally needs its configured `apache/seatunnel` image; enabled Vermeer needs its matching `hugegraph/vermeer` build. +Enabled SeaTunnel additionally needs its configured `apache/seatunnel` image; enabled Vermeer uses the published build pinned above. Vermeer reuses that image for Master, Worker and service-token initialization. Mirror every enabled image and explicit helper override. +For a custom Vermeer image, also update `vermeer.image.digest`, or explicitly clear it when selecting by tag; a nonempty digest takes priority. ### Storage configuration From 6b3e687a5a6c9027641f8309931d526f1e3505fb Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 06:36:09 +0000 Subject: [PATCH 08/11] docs: describe native admin passwords by deployment mode --- .../quickstart/computing/hugegraph-vermeer.md | 3 ++- .../hugegraph/hugegraph-helm-operations.md | 3 ++- .../docs/quickstart/hugegraph/hugegraph-helm.md | 11 +++++++---- .../quickstart/computing/hugegraph-vermeer.md | 6 ++++-- .../hugegraph/hugegraph-helm-operations.md | 3 ++- .../docs/quickstart/hugegraph/hugegraph-helm.md | 15 +++++++++------ 6 files changed, 26 insertions(+), 15 deletions(-) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index 852e15ebfd..6dac2eca45 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -62,7 +62,8 @@ flowchart LR > > Hubble 自动获得 Master 内部地址与服务令牌。HugeGraph 管理员可以加载／重载图、运行九种支持算法、查看／取消任务、 > 分页浏览结果并卸载计算副本；结果不会写回图属性。原生 Vermeer UI/API 始终为私有 ClusterIP，访问始终需要登录。 -> 按需管理使用经过授权的 port-forward，将 `-vermeer-admin` Secret 的 `password` 中独立 16 位密码 +> 按需管理使用经过授权的 port-forward，从 `-vermeer-admin` Secret 的 `password` 读取独立管理密码。 +> 新生成的密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位；升级和切换模式均保留既有密码，不自动轮换。 > 粘贴到 **Admin credential**，无需用户名；登录获得 24 小时版本化会话 Cookie，Hubble 服务鉴权仍自动接入。 > 不承诺 Master 自动故障切换或运行中任务自动恢复。 > 镜像前提、凭据、端口和持久化见 [Helm 可选引擎](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 76891346fc..19ed0a83b7 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -68,7 +68,8 @@ kubectl -n hugegraph annotate deployment hugegraph-server \ > > Vermeer Master HTTP/gRPC 为 6688/6689，Worker HTTP/gRPC 为 6788/6789，原生 UI/API 也始终保留为私有 ClusterIP。 > 单机为一个 Pod 中独立的 Master/Worker 容器和数据卷；集群默认为 1 个 Master 加 3 个 Worker Pod。 -> 两个引擎的原生入口始终需要登录。新管理员密码为 16 位，升级复用既有凭据，按需管理使用经过授权的 port-forward。 +> 两个引擎的原生入口始终需要登录。新生成的管理员密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位。 +> 升级复用既有密码，切换模式也不会自动轮换；按需管理使用经过授权的 port-forward。 > Vermeer 的 **Admin credential** 直接接受 `-vermeer-admin` Secret 的 `password`，无需用户名，登录获得 24 小时版本化会话 Cookie。 > SeaTunnel 用户名仍为 `admin`。Hubble 服务鉴权自动接入，与人类管理密码独立，不需要用户获取令牌。 > 更改外部 Vermeer 管理密码 Secret 只需重启 Master；内部服务签名因子轮换需重启 Master 与 Hubble，无需重启 Worker。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index e7b73545ce..ba1c7dd4ce 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -141,7 +141,8 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > > 单机模式运行一个常驻 hybrid 成员；设置 `seatunnel.mode=cluster` 和 `seatunnel.replicas=2` 可运行多个成员。 > 原生 UI/API 在两种模式下都保留为私有 ClusterIP，始终需要独立的 HTTP Basic 登录。 -> 新生成的管理员密码为 16 位，升级复用既有凭据；两种模式都将 HTTP／成员端口限制为必要的内部调用方。 +> 新生成的管理员密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位。 +> 升级复用既有密码，切换模式也不会自动轮换；两种模式都将 HTTP／成员端口限制为必要的内部调用方。 > 按需管理时使用经过授权的 port-forward，步骤见部署指南。 > Helm 准备引擎和示例，不自动建图或执行作业；checkpoint 使用临时本地文件。 > 访问、凭据、复制示例和恢复限制见 [SeaTunnel 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 @@ -165,7 +166,8 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > > Vermeer 原生 UI/API 在两种模式下都保留为私有 ClusterIP。按需管理时， > 执行 `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` 后访问 `http://127.0.0.1:6688/`。 -> 从 Secret `hugegraph-vermeer-admin` 的 `password` 键读取独立的 16 位管理员密码，粘贴到 **Admin credential** 输入框。 +> 从 Secret `hugegraph-vermeer-admin` 的 `password` 键读取独立的管理员密码，粘贴到 **Admin credential** 输入框。 +> 新生成的密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位；升级和切换模式均保留既有密码。 > 登录后获得有效期 24 小时的版本化会话 Cookie；使用 Hubble 无需手工获取服务令牌。 > 密码获取、持久化、模式切换与高级服务凭据见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 > Chart 将 `hugegraph/vermeer:helm-2678ff91b56a` 固定到镜像索引 digest @@ -290,8 +292,9 @@ GitOps 使用加密的固定值，或预先创建 Secret 并配置 `pd.auth.exis Hubble 默认开启，当前镜像的登录仍依赖 Server 鉴权。只使用 API 可以设置 `hubble.enabled=false`， 如需关闭 API 鉴权，再设置 `server.auth.enabled=false`。未使用的凭据配置可以留在 values 中。 -可选引擎的原生入口始终需要登录，easy 模式也不例外。新安装生成独立的 16 位管理员密码： -SeaTunnel 使用 HTTP Basic，Vermeer 使用 `-vermeer-admin` Secret 与 **Admin credential** 登录，升级保留既有凭据。 +可选引擎的原生入口始终需要登录，easy 模式也不例外。新生成的独立管理员密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位。 +SeaTunnel 使用 HTTP Basic，Vermeer 使用 `-vermeer-admin` Secret 与 **Admin credential** 登录。 +升级保留既有密码，切换模式也不会自动轮换。 Vermeer 管理密码可通过 `vermeer.auth.admin.password` 或 `vermeer.auth.admin.existingSecret/key` 配置，仅 Master 读取。 原生管理按需使用经过授权的 port-forward，Hubble 的服务凭据自动配置。 diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index 47534bef4f..9cfb18f601 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -64,8 +64,10 @@ flowchart LR > Hubble receives the internal Master URL and service token automatically. A HugeGraph administrator can load/reload a graph, > run nine supported algorithms, inspect/cancel tasks, page through results and unload the compute copy. Results are not written back to graph properties. > The native UI/API remains a private ClusterIP Service and always requires login. Optional administration uses an authorized port-forward -> and the separate 16-character password in `-vermeer-admin`, key `password`. Paste it into **Admin credential**, with no username; -> login creates a 24-hour versioned session cookie. Hubble service authentication remains automatic. No Master failover or automatic task recovery is promised. +> and the separate password in `-vermeer-admin`, key `password`. Newly generated passwords use +> 6 random alphanumeric characters in easy mode or 16 in strict mode. Upgrades, including mode changes, retain the existing password without automatic rotation. +> Paste it into **Admin credential**, with no username; login creates a 24-hour versioned session cookie. Hubble service authentication remains automatic. +> No Master failover or automatic task recovery is promised. > See [Helm optional engines](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and the > [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) > for optional administration, retained data and advanced service credentials. The Chart pins diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 17f5718aa7..a529bcd543 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -71,7 +71,8 @@ Replacing a Pod backed by `emptyDir` discards its temporary data; such a rollout > > Vermeer Master HTTP/gRPC uses 6688/6689, and Worker HTTP/gRPC uses 6788/6789. Its native UI/API also remains private behind ClusterIP. > Standalone has one Pod with separate Master/Worker containers and data volumes; cluster has one Master plus three Worker Pods by default. -> Both engines always require native login. New administrator passwords are 16 characters and upgrades retain existing credentials. +> Both engines always require native login. Newly generated administrator passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode. +> Upgrades retain existing passwords, including when changing mode; changing mode does not rotate them automatically. > Optional administration uses authorized port-forwarding; Vermeer **Admin credential** accepts the password from `-vermeer-admin`, > key `password`, with no username required. Login creates a 24-hour versioned session cookie. SeaTunnel still uses username `admin`. > Hubble service authentication is automatic and separate from human passwords; no token retrieval is needed. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 1c86d96d2b..426b9e785f 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -147,7 +147,8 @@ For Vermeer computation, enable the switch and sign in to Hubble; service addres > > Standalone starts one long-running hybrid member. Set `seatunnel.mode=cluster` and `seatunnel.replicas=2` > for multiple hybrid members. Native UI/API access remains private behind ClusterIP and always requires HTTP Basic login. -> New administrator passwords are 16 characters; upgrades reuse existing credentials. HTTP/member ports admit only required internal callers +> Newly generated administrator passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode. +> Upgrades, including mode changes, retain existing passwords without automatic rotation. HTTP/member ports admit only required internal callers > in both modes. For optional administration, use an authorized port-forward as described in the deployment guide. > Helm prepares the engine and examples; create graphs and submit jobs yourself. Checkpoints use temporary local files. > See the [SeaTunnel deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) @@ -173,8 +174,9 @@ For Vermeer computation, enable the switch and sign in to Hubble; service addres > > Native UI/API remains private behind ClusterIP in both modes. Optional administration uses > `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` and `http://127.0.0.1:6688/`. -> Read the separate 16-character administrator password from Secret `hugegraph-vermeer-admin`, key `password`, -> and paste it into **Admin credential**. Login creates a 24-hour versioned session cookie. Hubble needs no manual service token. +> Read the separate administrator password from Secret `hugegraph-vermeer-admin`, key `password`, and paste it into **Admin credential**. +> Newly generated passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode; upgrades and mode changes retain existing passwords. +> Login creates a 24-hour versioned session cookie. Hubble needs no manual service token. > The [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) > covers password retrieval, storage, mode changes and advanced service credentials. > The Chart pins `hugegraph/vermeer:helm-2678ff91b56a` to image-index digest @@ -302,9 +304,10 @@ update the Secret/source to that same password, then restart the Server Deployme Hubble is enabled by default and its current login requires Server authentication. Set `hubble.enabled=false` for API-only access; optionally also set `server.auth.enabled=false` for an unauthenticated API. Inactive credential settings may remain in your values file. -Enabled optional engines always require native login, including in easy mode. New installations generate separate 16-character -administrator passwords: SeaTunnel uses HTTP Basic, while Vermeer uses Secret `-vermeer-admin` and its **Admin credential** login. -Upgrades keep existing credentials. Vermeer password sources are `vermeer.auth.admin.password` or `vermeer.auth.admin.existingSecret/key`; +Enabled optional engines always require native login, including in easy mode. Newly generated administrator passwords use 6 random alphanumeric +characters in easy mode or 16 in strict mode. SeaTunnel uses HTTP Basic, while Vermeer uses Secret `-vermeer-admin` and its +**Admin credential** login. Upgrades retain existing passwords, including when changing mode; mode changes do not rotate them automatically. +Vermeer password sources are `vermeer.auth.admin.password` or `vermeer.auth.admin.existingSecret/key`; only Master reads that password. Native administration uses authorized port-forwarding, and Hubble service credentials are automatic. > [!DETAILS]- Advanced: Vermeer deployment credentials and GitOps From 7a3e2f5d7c8cb5df51f558db1b02ab43be5f2cb1 Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 07:48:40 +0000 Subject: [PATCH 09/11] docs: clarify ownership migration for reused PD and Store data --- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 3 +++ content/cn/docs/quickstart/hugegraph/hugegraph-pd.md | 3 +++ content/en/docs/quickstart/hugegraph/hugegraph-hstore.md | 3 +++ content/en/docs/quickstart/hugegraph/hugegraph-pd.md | 3 +++ 4 files changed, 12 insertions(+) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index f00f2bb539..919a3b1af9 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -110,6 +110,9 @@ set -a; . ./.env; set +a 单独运行当前主线构建的 Store 时，将示例地址换成 Store 与 PD 均可路由的实际地址： +下面的 `mkdir -p` 和非递归 `chown` 仅适用于新建空目录。复用旧 root 镜像写入的数据时，先停止 Store， +执行一次 `sudo chown -R 10001:10001 /path/to/storage`，再启动 UID 10001 镜像。 + ```bash # master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写 mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md index 11b4ae136e..1f444b53b5 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md @@ -81,6 +81,9 @@ docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local . 单独运行当前主线构建的 PD 时，先设置部署专用密钥，并把示例地址替换为容器可达的真实地址： +下面的 `mkdir -p` 和非递归 `chown` 仅适用于新建空目录。复用旧 root 镜像写入的数据时，先停止 PD， +执行一次 `sudo chown -R 10001:10001 /path/to/data`，再启动 UID 10001 镜像。 + ```bash export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)" # master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 708931b9e7..5d39d077ee 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -111,6 +111,9 @@ Multi-node service names are `pd0`–`pd2`, `store0`–`store2`, and `server0` To run master-built Store alone, replace example addresses with actual routable Store and PD addresses: +The `mkdir -p` and nonrecursive `chown` below are for a new empty directory. Before reusing data written by a root image, stop Store and run +`sudo chown -R 10001:10001 /path/to/storage` once, then start the UID 10001 image. + ```bash # Master-built images run as UID 10001; the host data directory must be writable by it mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md index 85d14103da..ce534da44f 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md @@ -82,6 +82,9 @@ docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local . To run master-built PD alone, first set a deployment-specific secret and replace example addresses with addresses reachable by the container: +The `mkdir -p` and nonrecursive `chown` below are for a new empty directory. Before reusing data written by a root image, stop PD and run +`sudo chown -R 10001:10001 /path/to/data` once, then start the UID 10001 image. + ```bash export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)" # Master-built images run as UID 10001; the host data directory must be writable by it From 387970df871031923fceb230126052aca6eb2dc5 Mon Sep 17 00:00:00 2001 From: orion Date: Wed, 28 Oct 2026 08:07:53 +0000 Subject: [PATCH 10/11] docs: fix deployment guide links and sync published Vermeer image Pin all eight Vermeer guide links to public Helm revision e0f6b071c31e645127226ee5c1217a4fb4196732. Replace native image source 2678ff91b56ae9501fbcdb0e1cf937144e508241 with official build 30b67d93e7d097374341cf46ee6a0703421512b1 from successful publishing run 40653109759 and its verified index digest. Link the merged ASF schema-copy examples in both Source guides and clarify the Chinese deployment credential wording. --- .../cn/docs/quickstart/computing/hugegraph-vermeer.md | 10 +++++----- .../quickstart/hugegraph/hugegraph-helm-operations.md | 8 ++++---- content/cn/docs/quickstart/hugegraph/hugegraph-helm.md | 10 +++++----- .../export-migration/hugegraph-seatunnel-source.md | 3 +++ .../en/docs/quickstart/computing/hugegraph-vermeer.md | 8 ++++---- .../quickstart/hugegraph/hugegraph-helm-operations.md | 9 +++++---- content/en/docs/quickstart/hugegraph/hugegraph-helm.md | 10 +++++----- .../export-migration/hugegraph-seatunnel-source.md | 3 +++ 8 files changed, 34 insertions(+), 27 deletions(-) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index 6dac2eca45..8fd5fc4929 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -14,7 +14,7 @@ Vermeer 是使用 Go 编写的高性能内存优先图计算框架，支持一 master 是负责通信、转发、汇总的节点，计算量和占用资源量较少。worker 是计算节点，用于存储图数据和运行计算任务，占用大量内存和 cpu。grpc 和 rest 模块分别负责内部通信和外部调用。 -启动时，程序先设置内置默认值，再读取工作目录下 `config/.ini` 的 `[default]` 节，最后由显式命令行参数覆盖对应配置；例如 `--env=master` 读取 `config/master.ini`。Docker 镜像把仓库中的配置复制到 `/go/bin/config/`，并以 `/go/bin/` 为工作目录。挂载宿主机目录到 `/go/bin/config` 会遮住镜像自带文件，因此该目录必须包含实际使用的 ini 文件。普通 INI 配置键不会自动映射环境变量。专门的部署凭据设置还支持 +启动时，程序先设置内置默认值，再读取工作目录下 `config/.ini` 的 `[default]` 节，最后由显式命令行参数覆盖对应配置；例如 `--env=master` 读取 `config/master.ini`。Docker 镜像把仓库中的配置复制到 `/go/bin/config/`，并以 `/go/bin/` 为工作目录。挂载宿主机目录到 `/go/bin/config` 会遮住镜像自带文件，因此该目录必须包含实际使用的 ini 文件。普通 INI 配置键不会自动映射环境变量。部署专用凭据设置还支持 `VERMEER_PD_PASSWORD_FILE`、`VERMEER_PD_PEERS`、`VERMEER_HUGEGRAPH_CREDENTIALS_FILE` 及文档中的签名因子／密码文件设置。 默认端口如下： @@ -67,10 +67,10 @@ flowchart LR > 粘贴到 **Admin credential**，无需用户名；登录获得 24 小时版本化会话 Cookie，Hubble 服务鉴权仍自动接入。 > 不承诺 Master 自动故障切换或运行中任务自动恢复。 > 镜像前提、凭据、端口和持久化见 [Helm 可选引擎](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) -> 与 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 -> Chart 按经过验证的镜像索引 digest 固定 `hugegraph/vermeer:helm-2678ff91b56a`，由 -> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40639306743)基于源码 -> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241)发布。 +> 与 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md)。 +> Chart 按经过验证的镜像索引 digest 固定 `hugegraph/vermeer:helm-30b67d93e7d0`，由 +> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40653109759)基于源码 +> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1)发布。 > 部署指南记录完整 digest 与自定义镜像覆盖流程。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 19ed0a83b7..3f547a6aab 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -25,9 +25,9 @@ kubectl get pv,storageclass 出现 `ImagePullBackOff` 时检查 Pod 事件、仓库连通性和拉取凭据。默认只需四个组件镜像，等待 Store/Helm test 复用已包含 curl 的组件镜像。 如显式覆盖 helper 镜像，该镜像也需要同步到内网仓库。 -启用 SeaTunnel 还需配置的 `apache/seatunnel` 镜像；启用 Vermeer 使用按 digest 固定的 `hugegraph/vermeer:helm-2678ff91b56a`， -Master、Worker 和令牌初始化共用它。[官方发布运行](https://github.com/hugegraph/actions/actions/runs/40639306743)记录源码与镜像 digest， -详见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 +启用 SeaTunnel 还需配置的 `apache/seatunnel` 镜像；启用 Vermeer 使用按 digest 固定的 `hugegraph/vermeer:helm-30b67d93e7d0`， +Master、Worker 和令牌初始化共用它。[官方发布运行](https://github.com/hugegraph/actions/actions/runs/40653109759)记录源码与镜像 digest， +详见 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md)。 自定义镜像覆盖还需同步更新 `vermeer.image.digest`，或显式清空以按标签选择；非空 digest 优先。 基础 local PV 示例不包含 Vermeer 卷：单机增加两个，集群增加一个 Master 卷及每 Worker 一个卷，默认增加四个。 @@ -80,7 +80,7 @@ kubectl -n hugegraph annotate deployment hugegraph-server \ > 切换拓扑或 Worker 数前停止新提交、完成／取消任务并卸载计算图，变更后检查可用性并重新加载。 > 单机和集群使用不同 Worker claim，模式切换不会迁移本地文件。 > -> 管理密码获取、保留卷与升级步骤见 [Vermeer 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> 管理密码获取、保留卷与升级步骤见 [Vermeer 运维指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) > 和 [SeaTunnel 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 ### Helm test 检查范围 {#helm-test-coverage} diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index ba1c7dd4ce..f80f4bbf1c 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -169,11 +169,11 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > 从 Secret `hugegraph-vermeer-admin` 的 `password` 键读取独立的管理员密码，粘贴到 **Admin credential** 输入框。 > 新生成的密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位；升级和切换模式均保留既有密码。 > 登录后获得有效期 24 小时的版本化会话 Cookie；使用 Hubble 无需手工获取服务令牌。 -> 密码获取、持久化、模式切换与高级服务凭据见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 -> Chart 将 `hugegraph/vermeer:helm-2678ff91b56a` 固定到镜像索引 digest -> `sha256:9ef623d93e4feddc345c6ce445109c4039b029be83090d0eca97aedeba981a9e`，由 -> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40639306743)基于源码 -> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241)发布。 +> 密码获取、持久化、模式切换与高级服务凭据见 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md)。 +> Chart 将 `hugegraph/vermeer:helm-30b67d93e7d0` 固定到镜像索引 digest +> `sha256:f9b69ef134069b432de1c9964374d7fdbfa53245d1fe7dcbce1e75b82b69dc9e`，由 +> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40653109759)基于源码 +> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1)发布。 > 原生联动要求 `hubble.mode=pd`；设置 `hubble.enabled=false` 时仍可通过原生入口使用 Vermeer。 > 对新增 Vermeer 之前的旧 release 首次启用时，先导出并审阅 `helm get values --all -o yaml`，再用 `-f` 传入， > 不加 `--reuse-values`，以便加载新 Vermeer 默认值。保留既有 `metadataCluster`，完整命令见部署指南。 diff --git a/content/cn/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md b/content/cn/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md index b528728072..e9b24e0fab 100644 --- a/content/cn/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md +++ b/content/cn/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md @@ -19,6 +19,9 @@ SeaTunnel 3.0+ 提供 HugeGraph Source，支持图模型自动发现和多标签 这两个任务只迁移指定标签和属性，不会完整复制源图的索引、TTL 等全部 Schema 配置。运行期间应暂停源图写入，避免两个任务读到不同时间的数据；完成后核对顶点、边数量及抽样属性。 +需要保留普通边标签的 Schema ID 和索引定义时，可参考 Helm Chart 中的 +[Schema 复制示例](https://github.com/apache/hugegraph/tree/96ce802a25672f8b7b0d08c49e68db694231f5e4/helm/hugegraph/examples/seatunnel/clone)。 + [![跨图迁移时重建主键可能改变顶点 ID；使用 CUSTOMIZE_STRING 保留原 ID，确保边端点匹配](/cn/docs/images/seatunnel/seatunnel-preserve-ids-zh.png)](/cn/docs/images/seatunnel/seatunnel-preserve-ids-zh.png) ### 1.1 先迁移顶点 diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index 9cfb18f601..00092559c5 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -69,11 +69,11 @@ flowchart LR > Paste it into **Admin credential**, with no username; login creates a 24-hour versioned session cookie. Hubble service authentication remains automatic. > No Master failover or automatic task recovery is promised. > See [Helm optional engines](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and the -> [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> [Vermeer deployment guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) > for optional administration, retained data and advanced service credentials. The Chart pins -> `hugegraph/vermeer:helm-2678ff91b56a` by verified image-index digest, published by the -> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40639306743) from source -> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241). +> `hugegraph/vermeer:helm-30b67d93e7d0` by verified image-index digest, published by the +> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40653109759) from source +> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1). > The deployment guide records the digest and custom-image override procedure. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index a529bcd543..760b07da49 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -26,9 +26,10 @@ kubectl get pv,storageclass For `ImagePullBackOff`, inspect Pod events and registry access/credentials. The default image inventory contains four component images; Store wait and Helm test reuse existing component images with `curl` already installed. Explicit helper-image overrides must also be mirrored. -Enabled SeaTunnel adds its configured `apache/seatunnel` image. Enabled Vermeer uses `hugegraph/vermeer:helm-2678ff91b56a`, pinned by digest -and reused by Master, Worker and token initialization. Its [official publishing run](https://github.com/hugegraph/actions/actions/runs/40639306743) -records the source and image digest; see the [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md). +Enabled SeaTunnel adds its configured `apache/seatunnel` image. Enabled Vermeer uses `hugegraph/vermeer:helm-30b67d93e7d0`, pinned by digest +and reused by Master, Worker and token initialization. Its [official publishing run](https://github.com/hugegraph/actions/actions/runs/40653109759) +records the source and image digest; see the +[Vermeer deployment guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md). Custom image overrides must also update `vermeer.image.digest`, or explicitly clear it to select by tag; digest takes priority. The base local-PV example omits Vermeer claims: standalone adds two, while cluster adds one Master claim plus one per Worker (four additional claims by default). @@ -84,7 +85,7 @@ Replacing a Pod backed by `emptyDir` discards its temporary data; such a rollout > Stop submissions, finish/cancel tasks and unload compute graphs before topology/Worker-count changes; inspect availability and reload afterward. > Standalone and cluster use different Worker claims, so changing modes does not migrate local files. > -> Follow the [Vermeer operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> Follow the [Vermeer operations guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) > and [SeaTunnel operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) > for administrator password retrieval, retained claims and exact upgrade commands. Raw service tokens are advanced internal integrations only. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 426b9e785f..0f1f5dfbf2 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -177,12 +177,12 @@ For Vermeer computation, enable the switch and sign in to Hubble; service addres > Read the separate administrator password from Secret `hugegraph-vermeer-admin`, key `password`, and paste it into **Admin credential**. > Newly generated passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode; upgrades and mode changes retain existing passwords. > Login creates a 24-hour versioned session cookie. Hubble needs no manual service token. -> The [Vermeer deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) +> The [Vermeer deployment guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) > covers password retrieval, storage, mode changes and advanced service credentials. -> The Chart pins `hugegraph/vermeer:helm-2678ff91b56a` to image-index digest -> `sha256:9ef623d93e4feddc345c6ce445109c4039b029be83090d0eca97aedeba981a9e`, published by the -> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40639306743) from source -> [`2678ff91b56a`](https://github.com/hugegraph/hugegraph-computer/commit/2678ff91b56ae9501fbcdb0e1cf937144e508241). +> The Chart pins `hugegraph/vermeer:helm-30b67d93e7d0` to image-index digest +> `sha256:f9b69ef134069b432de1c9964374d7fdbfa53245d1fe7dcbce1e75b82b69dc9e`, published by the +> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40653109759) from source +> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1). > Hubble requires `hubble.mode=pd` for this native integration; API-only Vermeer remains usable with `hubble.enabled=false`. > For first enablement on a pre-Vermeer release, export and review `helm get values --all -o yaml`, then supply that file with `-f` > without `--reuse-values`, allowing the new Vermeer defaults to load. Preserve `metadataCluster`; see the deployment guide for the complete command. diff --git a/content/en/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md b/content/en/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md index 7b5437ac89..b4768bcd2f 100644 --- a/content/en/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md +++ b/content/en/docs/quickstart/toolchain/export-migration/hugegraph-seatunnel-source.md @@ -20,6 +20,9 @@ The following example migrates `person` vertices and `knows` edges from a source These two jobs migrate only the selected labels and properties. They do not copy every source schema setting, such as indexes and TTLs. Pause writes to the source graph during the migration so both jobs read a consistent point in time. Afterward, compare vertex and edge counts and sample properties. +To retain schema IDs and indexes for ordinary edge labels, see the Chart's +[schema-copy examples](https://github.com/apache/hugegraph/tree/96ce802a25672f8b7b0d08c49e68db694231f5e4/helm/hugegraph/examples/seatunnel/clone). + [![Regenerating a primary key can change 1:marko to 2:marko; CUSTOMIZE_STRING preserves the original ID so edge endpoints still resolve](/docs/images/seatunnel/seatunnel-preserve-ids-en.png)](/docs/images/seatunnel/seatunnel-preserve-ids-en.png) ### 1.1 Migrate vertices first From ebdb7b523522d2f3d254b3a6febfaf1f32f780cb Mon Sep 17 00:00:00 2001 From: imbajin Date: Wed, 28 Oct 2026 16:40:43 +0800 Subject: [PATCH 11/11] docs(helm): refine Vermeer & optional engines guide with filetree and clear context --- .../quickstart/computing/hugegraph-vermeer.md | 50 ++++++------ .../hugegraph/hugegraph-helm-operations.md | 46 +++-------- .../quickstart/hugegraph/hugegraph-helm.md | 77 +++++++----------- .../quickstart/computing/hugegraph-vermeer.md | 56 ++++++------- .../hugegraph/hugegraph-helm-operations.md | 47 +++-------- .../quickstart/hugegraph/hugegraph-helm.md | 79 +++++++------------ 6 files changed, 126 insertions(+), 229 deletions(-) diff --git a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md index 8fd5fc4929..c8f42ad10e 100644 --- a/content/cn/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/cn/docs/quickstart/computing/hugegraph-vermeer.md @@ -39,8 +39,8 @@ flowchart LR ### 1.2 运行方法 > [!DETAILS]- Helm：与 HugeGraph、Hubble 一起部署 Vermeer -> HugeGraph Helm Chart 提供可选的原生 Vermeer 集成，两种 HugeGraph 拓扑预设都默认关闭。 -> 从 HugeGraph 仓库根目录开启 Vermeer，之后登录现有 Hubble 入口： +> HugeGraph Helm Chart 支持一键拉起原生 Vermeer 内存图计算引擎，默认保持关闭。 +> 在 HugeGraph 仓库根目录下，开启 Vermeer 并启动： > > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ @@ -49,37 +49,33 @@ flowchart LR > --wait --timeout 20m > ``` > -> 单机为一个 Pod 内独立的 Master 和 Worker 容器；设置 `vermeer.mode=cluster` 与 `vermeer.worker.replicas=3`， -> 则使用 1 个 Master Pod 和可调数量的 Worker Pod。两者都依赖 HStore/PD 数据链路，轻量 HugeGraph 预设已提供它。 -> 顶层 `mode: easy/strict` 独立选择 Server/Hubble 入口与完整网络隔离，原生引擎在两种模式下都保留为私有服务。 +> ```filetree {wrap=true title="Vermeer 核心文件与配置结构"} +> helm/hugegraph/ +> examples/ +> values-vermeer-standalone.yaml # 单机预设（单个 Pod 同时运行 Master 与 Worker 容器） +> values-vermeer-cluster.yaml # 集群预设（独立 Master Pod + 多 Worker Pods 分布式计算） +> templates/ +> vermeer-master.yaml # Master 调度节点编排 +> vermeer-worker.yaml # Worker 内存计算节点编排 +> vermeer-auth-secret.yaml # 管理员密码与 Hubble 内部调用服务令牌 +> docs/ +> vermeer.md # Vermeer 算法调用、参数映射与运维指引 +> ``` > -> 保留已初始化的 `metadataCluster`，默认 `hg-test`；Chart 统一 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER` 供 Schema 读取。 -> 这是 PD 元数据前缀，不是 Raft 名称；改变它不会迁移已有图，不要为了启用 Vermeer 将其改成 `hg`。 -> 加载报 `Schema missing` 或 `no such vertex label` 时，先检查命名空间和运行中 Store Pod 的环境是否对齐。 -> 旧自定义前缀先按 [Helm 运维](/cn/docs/quickstart/hugegraph/hugegraph-helm-operations/#metadata-namespace)核对并记录既有值。 -> 旧 release 首次启用先导出／审阅 `helm get values --all -o yaml`，再用 `-f` 传入，升级时不加 `--reuse-values`，完整流程见部署指南。 -> `OnDelete` 需按既有受控流程更新 Store Pod，新环境才会生效；替换 `emptyDir` Pod 会丢弃其数据，不能视为无损迁移。 +> **架构与运行模式**： +> - **单机模式（standalone）**：Master 与 Worker 运行在同一个 Pod 中，开销小，适合小规模图计算测试。 +> - **集群模式（cluster）**：设 `vermeer.mode=cluster` 与 `vermeer.worker.replicas=3`，提供独立的 Master 协调节点与多个分布式 Worker 计算节点。 +> - **图服务协同**：Master 通过 gRPC 向 PD 查询分区信息，Worker 直连 Store 扫描图数据切片；Hubble 会自动注入 Master 地址与通信令牌，在可视化界面中一键加载图并执行 15+ 种图算法。 > -> Hubble 自动获得 Master 内部地址与服务令牌。HugeGraph 管理员可以加载／重载图、运行九种支持算法、查看／取消任务、 -> 分页浏览结果并卸载计算副本；结果不会写回图属性。原生 Vermeer UI/API 始终为私有 ClusterIP，访问始终需要登录。 -> 按需管理使用经过授权的 port-forward，从 `-vermeer-admin` Secret 的 `password` 读取独立管理密码。 -> 新生成的密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位；升级和切换模式均保留既有密码，不自动轮换。 -> 粘贴到 **Admin credential**，无需用户名；登录获得 24 小时版本化会话 Cookie，Hubble 服务鉴权仍自动接入。 -> 不承诺 Master 自动故障切换或运行中任务自动恢复。 -> 镜像前提、凭据、端口和持久化见 [Helm 可选引擎](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) -> 与 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md)。 -> Chart 按经过验证的镜像索引 digest 固定 `hugegraph/vermeer:helm-30b67d93e7d0`，由 -> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40653109759)基于源码 -> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1)发布。 -> 部署指南记录完整 digest 与自定义镜像覆盖流程。 - +> **核心注意事项**： +> 1. **保持元数据命名空间一致**：保留 Chart 默认的 `metadataCluster: hg-test`。该值统一了 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER`，确保 Schema 正确读取；切勿随意修改该值，以免计算加载时报 `Schema missing`。 +> 2. **访问原生 Web 控制台**：原生 UI 默认以私有 ClusterIP 运行。如需直连管理，可通过 `kubectl port-forward svc/-vermeer-master 6688:6688` 转发，并在 **Admin credential** 处填入 `-vermeer-admin` Secret 中的 `password`（无需用户名），登录后获得 24 小时有效会话。 +> 3. 详细镜像固定策略、持久卷配置及运维命令可参考 [Helm 可选引擎指南](/cn/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) 与 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 > [!WARNING] > 生产环境必须启用 HugeGraph Server [认证与授权](/cn/docs/config/config-authentication/)、IP 白名单和最小权限授权，并保留 `audit-*.log` 审计记录。Server Auth 不会保护 Vermeer、PD 和 Store 的独立接口；这些 HTTP、gRPC 端口必须限制在可信网络及调用方范围内，Vermeer 对外入口需配置访问控制。 > -> 上游手工配置 `master.ini` 仍默认 `auth=none`，下方手工 Docker 示例仅发布回环端口。这与本次 Helm 集成相互独立： -> Helm 始终使用 token 鉴权、私有原生 Service 与管理员密码，不能把手工未鉴权默认值当成 Helm 的便捷替代方案。 -> 手工保护部署应在远程访问前启用 `auth=token`，并按上游说明配置文件凭据。 +> 独立手动部署时，默认 `master.ini` 配置为 `auth=none`，下方 Docker 示例仅发布至回环地址；若需远程访问，务必在配置文件中启用 `auth=token`。Helm 部署则已默认开启 Token 鉴权与私有 Service 隔离。 下面两种 Docker 启动方式都需要先准备一个宿主机配置目录。请在 Vermeer 仓库根目录执行，将项目提供的 [`master.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/master.ini) 和 [`worker.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/worker.ini) 模板复制到该目录；挂载会覆盖镜像里的 `/go/bin/config`，所以不要把空目录或整个用户主目录挂进去： diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 3f547a6aab..62efeaab9d 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -41,47 +41,23 @@ Server 等待存储的默认上限为 300 秒，可以用 `server.storageWaitTim ### 保留元数据命名空间 {#metadata-namespace} -`metadataCluster: hg-test` 保留旧 Server 的 PD 元数据前缀，并统一配置 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER`。 -它不是 Raft 名称，也不是元数据迁移开关；不要为了启用 Vermeer 把已初始化部署切换成 `hg`。 -若 Server REST 查询正常，而 Vermeer 扫描 Store 报 `Schema missing` 或 `no such vertex label`， -先核对共享值、既有 Server 元数据命名空间，以及每个运行中 Store Pod 的环境是否一致。 +`metadataCluster: hg-test` 用于声明 Server 和 Store 访问 PD 时的元数据前缀（注入至 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER`）。 +它并非 Raft 分组名，修改该值不会自动迁移历史元数据。**切勿**为了启用 Vermeer 将已有集群的前缀随意变更。若遇到 Server 查询正常但 Vermeer 扫描 Store 报 `Schema missing` 或 `no such vertex label`，应优先核查各组件的元数据前缀是否完全一致。 -在线升级会拒绝与 Server Deployment 记录的 annotation 或显式 `HG_SERVER_CLUSTER` 冲突的目标值。 -标准旧 `hg-test` 部署无需额外认领操作。若旧自定义镜像用了其他前缀且 Chart 无法确认， -先读取既有 Server 日志／配置，确认实际值，再在 Server Deployment 记录该值，并在审阅后的 Helm values 中将 `metadataCluster` 设为同一值： +若历史自建环境使用了非默认前缀，升级前需在 Server Deployment 显式标注确认： ```bash kubectl -n hugegraph annotate deployment hugegraph-server \ - hugegraph.apache.org/metadata-cluster='<核实过的既有命名空间>' + hugegraph.apache.org/metadata-cluster='<已核准的历史前缀>' ``` -只在完成核对后替换占位符；annotation 记录原本使用的命名空间，不复制或迁移 PD key。 -离线／GitOps 渲染无法检查在线 Deployment，应显式保留核实后的值。 -集群预设的 `store.updateStrategy.type=OnDelete` 不会因模板更新而替换正在运行的 Pod， -须按[逐个更新 Store 的既有流程](#6-rolling-store-images-safely)更新 Pod，新环境才会生效。 -替换使用 `emptyDir` 的 Pod 会丢弃其临时数据，这种滚动操作不能视为无损恢复或迁移。 - -> [!DETAILS]- 可选引擎：就绪、凭据和恢复 -> SeaTunnel 和 Vermeer 在两种 HugeGraph 预设中都默认关闭，启用后增加独立入口凭据与网络规则。 -> SeaTunnel HTTP/UI 使用 8080 和 Basic 鉴权，两种模式都将私有 HTTP／成员端口限制为必要的内部调用方。 -> 常驻 hybrid 进程不代表 checkpoint 已通过 PVC 持久化。 -> -> Vermeer Master HTTP/gRPC 为 6688/6689，Worker HTTP/gRPC 为 6788/6789，原生 UI/API 也始终保留为私有 ClusterIP。 -> 单机为一个 Pod 中独立的 Master/Worker 容器和数据卷；集群默认为 1 个 Master 加 3 个 Worker Pod。 -> 两个引擎的原生入口始终需要登录。新生成的管理员密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位。 -> 升级复用既有密码，切换模式也不会自动轮换；按需管理使用经过授权的 port-forward。 -> Vermeer 的 **Admin credential** 直接接受 `-vermeer-admin` Secret 的 `password`，无需用户名，登录获得 24 小时版本化会话 Cookie。 -> SeaTunnel 用户名仍为 `admin`。Hubble 服务鉴权自动接入，与人类管理密码独立，不需要用户获取令牌。 -> 更改外部 Vermeer 管理密码 Secret 只需重启 Master；内部服务签名因子轮换需重启 Master 与 Hubble，无需重启 Worker。 -> -> Master/Worker 监听器健康不代表当前空间已可计算。以服务凭据检查 `/api/v1/workers/availability`， -> 再通过 Hubble 实测加载和已知算法结果；公共 Worker 池避免新空间需要手工分配。 -> 持久化元数据不保证内存图、结果缓存或运行中任务自动恢复。 -> 切换拓扑或 Worker 数前停止新提交、完成／取消任务并卸载计算图，变更后检查可用性并重新加载。 -> 单机和集群使用不同 Worker claim，模式切换不会迁移本地文件。 -> -> 管理密码获取、保留卷与升级步骤见 [Vermeer 运维指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) -> 和 [SeaTunnel 运维指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 +并在 values 中将 `metadataCluster` 设为同一值。对于采用 `store.updateStrategy.type=OnDelete` 策略的 Store 节点，需按[受控滚动升级流程](#6-rolling-store-images-safely)逐个重建 Pod，新配置方可生效。 + +> [!DETAILS]- 可选引擎运维：探针、凭据与拓扑切换 +> - **端口与健康状态**：SeaTunnel HTTP/UI 端口为 `8080`；Vermeer Master HTTP/gRPC 为 `6688/6689`，Worker 为 `6788/6789`。两款引擎的原生接口在两种模式下均保持私有 ClusterIP。 +> - **密码与会话**：初次部署生成的管理密码在 easy 模式下为 6 位字符，strict 模式下为 16 位；后续升级与模式切换均自动保留既有凭据。Vermeer 原生控制台直接在 **Admin credential** 填入 `-vermeer-admin` Secret 的 `password` 即可登录；Hubble 内部服务凭据已自动注入。 +> - **拓扑与副本切换**：修改 `seatunnel.mode` 或 `vermeer.mode` 前，请确保所有计算与导入批任务已结束并卸载内存图副本。单机与集群使用独立的数据卷声明，拓扑切换不会自动迁移本地文件。 +> - 完整恢复指引与进阶参数详见 [Vermeer 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) 与 [SeaTunnel 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 ### Helm test 检查范围 {#helm-test-coverage} diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md index f80f4bbf1c..a27dc870cf 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md @@ -117,21 +117,17 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 ### 可选引擎：默认关闭 {#optional-engines} -`values-single.yaml` 和 `values-cluster.yaml` 都不会开启 SeaTunnel 或 Vermeer。 -这两个预设选择 HugeGraph 的 HStore 拓扑；`seatunnel.mode` 和 `vermeer.mode` 分别选择可选引擎的拓扑， -顶层 `mode: easy/strict` 则独立控制 Server/Hubble 的 HTTP 入口与完整网络隔离。 +Chart 默认仅部署核心图服务（PD + Store + Server + Hubble）。针对数据集成与超大规模内存图计算场景，Chart 提供了 SeaTunnel 与 Vermeer 两款原生可选引擎，默认均保持关闭： -| 组件 | 默认值 | 开关 | -|---|---|---| -| Hubble | `true` | `hubble.enabled` | -| SeaTunnel | `false` | `seatunnel.enabled` | -| Vermeer | `false` | `vermeer.enabled` | - -将引擎开关设为 `true` 即可启用；`hubble.enabled=false` 切换为仅 API 部署。 +| 可选引擎 | 默认状态 | 核心用途 | 运行模式 (`*.mode`) | 访问控制 | +|---|---|---|---|---| +| **Hubble** | 开启 (`true`) | 图数据可视化、多图空间与任务监控 | 单副本 Deployment | 跟随全局 `mode`（NodePort 或 ClusterIP） | +| **SeaTunnel** | 关闭 (`false`) | 异构数据源批流导入与跨图整库迁移 | `standalone` / `cluster` | 私有 ClusterIP（HTTP Basic 鉴权） | +| **Vermeer** | 关闭 (`false`) | 内存优先的高性能分布式图计算算法 | `standalone` / `cluster` | 私有 ClusterIP（Token 鉴权，Hubble 自动集成） | -下面示例从 HugeGraph 仓库根目录安装源码 Chart。使用 Vermeer 图计算只需开启开关并登录 Hubble，服务地址与凭据由 Chart 自动接入。 +在 values 中将对应引擎的 `enabled` 设为 `true` 即可启用。两款引擎的原生接口均保留为私有 ClusterIP，管理密码与 Server 独立生成。 -> [!DETAILS]- SeaTunnel：按需开启原生导入、导出和迁移 +> [!DETAILS]- SeaTunnel：按需开启原生数据导入、导出与迁移 > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ > -f helm/hugegraph/values-single.yaml \ @@ -139,15 +135,11 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > --wait --timeout 30m > ``` > -> 单机模式运行一个常驻 hybrid 成员；设置 `seatunnel.mode=cluster` 和 `seatunnel.replicas=2` 可运行多个成员。 -> 原生 UI/API 在两种模式下都保留为私有 ClusterIP，始终需要独立的 HTTP Basic 登录。 -> 新生成的管理员密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位。 -> 升级复用既有密码，切换模式也不会自动轮换；两种模式都将 HTTP／成员端口限制为必要的内部调用方。 -> 按需管理时使用经过授权的 port-forward，步骤见部署指南。 -> Helm 准备引擎和示例，不自动建图或执行作业；checkpoint 使用临时本地文件。 -> 访问、凭据、复制示例和恢复限制见 [SeaTunnel 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 - -> [!DETAILS]- Vermeer：按需开启图计算，自动接入 Hubble +> - **运行模式**：`standalone` 启动 1 个 Hybrid 节点（轻量测试）；`cluster` 模式启动多个同构节点（高并发批处理）。 +> - **访问与凭据**：Web 控制台使用独立 HTTP Basic 认证（默认用户 `admin`），密码保存在 `hugegraph-seatunnel-auth` Secret 中。端口 `5801` 仅供集群内部通信，严禁对外暴露。 +> - 完整作业配置、内置示例验证及跨图迁移流程见 [SeaTunnel 部署章节](#6-start-seatunnel) 或 [SeaTunnel 部署指南](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md)。 + +> [!DETAILS]- Vermeer：按需开启内存图计算，自动接入 Hubble > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ > -f helm/hugegraph/values-single.yaml \ @@ -155,37 +147,26 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据 > --wait --timeout 20m > ``` > -> 单机模式使用一个 Pod，内含独立的 Master 和 Worker 原生进程容器，各自挂载数据卷。 -> 设置 `vermeer.mode=cluster` 后为 1 个 Master Pod 加 `vermeer.worker.replicas` 个 Worker Pod，默认 3 个 Worker。 -> 多 Worker 提供分布式计算；单 Master 不承诺自动故障切换。 -> -> 保持 Hubble 默认的 PD 模式，Chart 会自动提供 Master 内部地址和服务令牌，无需手工填写。 -> 以 HugeGraph 管理员登录 Hubble，选择 HStore 图，加载／重载后运行九种支持算法之一， -> 查看／取消异步任务并分页浏览结果。计算副本清理由既有 Hubble 管理员 API 完成，当前页面提供加载／重载，没有独立卸载按钮。 -> 此流程不把结果写回 HugeGraph 属性；普通图读取用户不会因此获得直接扫描 Store 的权限。 +> ```text +> helm/hugegraph/ +> examples/ +> values-vermeer-standalone.yaml # 单机预设（单个 Pod 同时包含 Master 与 Worker） +> values-vermeer-cluster.yaml # 集群预设（1 个 Master Pod + 3 个 Worker Pods） +> docs/ +> vermeer.md # Vermeer 算法调用、参数映射与进阶运维手册 +> ``` > -> Vermeer 原生 UI/API 在两种模式下都保留为私有 ClusterIP。按需管理时， -> 执行 `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` 后访问 `http://127.0.0.1:6688/`。 -> 从 Secret `hugegraph-vermeer-admin` 的 `password` 键读取独立的管理员密码，粘贴到 **Admin credential** 输入框。 -> 新生成的密码在 easy 模式下为 6 位随机字母数字，strict 模式下为 16 位；升级和切换模式均保留既有密码。 -> 登录后获得有效期 24 小时的版本化会话 Cookie；使用 Hubble 无需手工获取服务令牌。 -> 密码获取、持久化、模式切换与高级服务凭据见 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md)。 -> Chart 将 `hugegraph/vermeer:helm-30b67d93e7d0` 固定到镜像索引 digest -> `sha256:f9b69ef134069b432de1c9964374d7fdbfa53245d1fe7dcbce1e75b82b69dc9e`，由 -> [官方工作流运行](https://github.com/hugegraph/actions/actions/runs/40653109759)基于源码 -> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1)发布。 -> 原生联动要求 `hubble.mode=pd`；设置 `hubble.enabled=false` 时仍可通过原生入口使用 Vermeer。 -> 对新增 Vermeer 之前的旧 release 首次启用时，先导出并审阅 `helm get values --all -o yaml`，再用 `-f` 传入， -> 不加 `--reuse-values`，以便加载新 Vermeer 默认值。保留既有 `metadataCluster`，完整命令见部署指南。 +> - **运行模式**：`standalone` 单机模式在同一个 Pod 中运行 Master 协调与 Worker 计算容器；`cluster` 模式提供独立的 Master Pod 与可水平扩展的 Worker Pod 集群（默认 3 副本）。 +> - **Hubble 一键集成**：Hubble 会自动注入 Master 内部 Service 地址与访问令牌。管理员在 Hubble 控制台即可直接触发 15+ 种图算法，计算结果保留在内存副本中，不污染原图属性。 +> - **原生控制台直连**：原生 UI 默认以私有 ClusterIP 运行，可通过 `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` 转发，并在 **Admin credential** 输入框中填入 `-vermeer-admin` Secret 的 `password` 登录。 +> - 镜像固定策略与进阶凭据管理见 [Vermeer 部署指南](https://github.com/hugegraph/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md)。 ### PD 元数据命名空间 {#metadata-namespace} -顶层 `metadataCluster` 默认为 `hg-test`，保留既有 Server 元数据前缀。 -Chart 将同一值注入 Server 的 `HG_SERVER_CLUSTER` 和 Store 的 `PD_CLUSTER`，让 Store 扫描读取到 Server 写入的 Schema。 -该前缀独立于 Raft 名称、服务 ID 和图空间；新部署可在初始化前选择其他标识符。 -初始化后改变该值不会迁移元数据或图数据，启用 Vermeer 时应保留原 Server 的值。 -标准旧部署使用 `hg-test`，无需额外认领命名空间；旧自定义前缀请先按 -[元数据命名空间接入步骤](./hugegraph-helm-operations.md#metadata-namespace)核对，再执行升级。 +顶层参数 `metadataCluster`（默认 `hg-test`）定义了 PD 中元数据的集群前缀。Chart 会将该值同步注入 Server 的 `HG_SERVER_CLUSTER` 与 Store 的 `PD_CLUSTER`，使得 Store 在接收 Vermeer 扫描请求时能准确定位 Server 写入的 Schema。 + +> [!IMPORTANT] +> `metadataCluster` 是元数据存储的前缀空间，而非 Raft 分组名。修改该值**不会**自动迁移已有图数据。开启 Vermeer 时必须保留原有集群的前缀值；若加载图时遇到 `Schema missing` 或 `no such vertex label`，请优先检查各组件的元数据前缀是否一致。自定义前缀的核验流程请参考 [元数据命名空间运维指引](./hugegraph-helm-operations.md#metadata-namespace)。 ### 服务身份与图空间 diff --git a/content/en/docs/quickstart/computing/hugegraph-vermeer.md b/content/en/docs/quickstart/computing/hugegraph-vermeer.md index 00092559c5..4abb496940 100644 --- a/content/en/docs/quickstart/computing/hugegraph-vermeer.md +++ b/content/en/docs/quickstart/computing/hugegraph-vermeer.md @@ -38,9 +38,9 @@ flowchart LR ### 1.2 Running Vermeer -> [!DETAILS]- Helm: deploy Vermeer together with HugeGraph and Hubble -> The HugeGraph Helm Chart offers an optional native Vermeer integration. It is disabled by default in both HugeGraph topology presets. -> From the HugeGraph repository root, enable Vermeer and sign in to the existing Hubble entry: +> [!DETAILS]- Helm: Deploy Vermeer with HugeGraph and Hubble +> The HugeGraph Helm Chart supports deploying the native Vermeer in-memory graph computing engine, disabled by default. +> From the HugeGraph repository root, enable Vermeer with: > > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ @@ -49,41 +49,33 @@ flowchart LR > --wait --timeout 20m > ``` > -> Standalone uses one Pod with separate Master and Worker containers. Cluster mode uses one Master Pod plus configurable Worker Pods: -> set `vermeer.mode=cluster` and `vermeer.worker.replicas=3`. Both require the HStore/PD data path; the small HugeGraph preset provides it. -> Top-level `mode: easy/strict` independently selects Server/Hubble entry and full network isolation. Native engines stay private in both modes. +> ```filetree {wrap=true title="Vermeer Core Files and Layout"} +> helm/hugegraph/ +> examples/ +> values-vermeer-standalone.yaml # Standalone preset (Master and Worker run in a single Pod) +> values-vermeer-cluster.yaml # Cluster preset (dedicated Master Pod + distributed Worker Pods) +> templates/ +> vermeer-master.yaml # Master scheduling and coordination workload +> vermeer-worker.yaml # Worker in-memory computing workload +> vermeer-auth-secret.yaml # Admin credentials and Hubble internal service tokens +> docs/ +> vermeer.md # Advanced algorithm parameters, API mapping and operations +> ``` > -> Keep the initialized `metadataCluster` (default `hg-test`): the Chart aligns Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER` for Schema reads. -> This is a PD metadata prefix, not a Raft name; changing it does not migrate an existing graph. Do not change it to `hg` to enable Vermeer. -> If loads fail with `Schema missing` or `no such vertex label`, check namespace alignment and the environment of running Store Pods first. -> Older custom prefixes require verification/adoption as described in [Helm operations](/docs/quickstart/hugegraph/hugegraph-helm-operations/#metadata-namespace). -> For first enablement on an older release, export/review `helm get values --all -o yaml` and upgrade with that file through `-f` without `--reuse-values`; -> the deployment guide gives the complete sequence. With `OnDelete`, Store Pods need the existing controlled update procedure to use changed environment. -> Replacing `emptyDir` Pods discards their data and is not a lossless migration. +> **Architecture & Topologies**: +> - **Standalone Mode (`standalone`)**: Master and Worker run as distinct containers in the same Pod with minimal overhead, suitable for local exploration and small-scale testing. +> - **Cluster Mode (`cluster`)**: Set `vermeer.mode=cluster` and `vermeer.worker.replicas=3` to provision a dedicated Master coordinator Pod and multiple distributed Worker computing Pods. +> - **Graph Service Integration**: Master queries PD via gRPC for partition topology, while Workers scan graph slices directly from Store via gRPC. Hubble automatically injects the Master URL and communication token, allowing users to load graphs and execute 15+ graph algorithms directly from the UI. > -> Hubble receives the internal Master URL and service token automatically. A HugeGraph administrator can load/reload a graph, -> run nine supported algorithms, inspect/cancel tasks, page through results and unload the compute copy. Results are not written back to graph properties. -> The native UI/API remains a private ClusterIP Service and always requires login. Optional administration uses an authorized port-forward -> and the separate password in `-vermeer-admin`, key `password`. Newly generated passwords use -> 6 random alphanumeric characters in easy mode or 16 in strict mode. Upgrades, including mode changes, retain the existing password without automatic rotation. -> Paste it into **Admin credential**, with no username; login creates a 24-hour versioned session cookie. Hubble service authentication remains automatic. -> No Master failover or automatic task recovery is promised. -> See [Helm optional engines](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and the -> [Vermeer deployment guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) -> for optional administration, retained data and advanced service credentials. The Chart pins -> `hugegraph/vermeer:helm-30b67d93e7d0` by verified image-index digest, published by the -> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40653109759) from source -> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1). -> The deployment guide records the digest and custom-image override procedure. - +> **Key Operational Considerations**: +> 1. **Preserve Metadata Namespace**: Retain the Chart default `metadataCluster: hg-test`. This key synchronizes Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER` so that Store can properly resolve schemas. Do not arbitrarily change this value on existing clusters to avoid `Schema missing` errors during load tasks. +> 2. **Access Native Web Dashboard**: The native UI runs as a private ClusterIP Service. Use `kubectl port-forward svc/-vermeer-master 6688:6688` to access it locally, and log in by entering the password from the `-vermeer-admin` Secret directly into **Admin credential** (no username required), which grants a 24-hour versioned session. +> 3. For image pinning, persistent volume sizing, and recovery procedures, refer to the [Helm Optional Engines Guide](/docs/quickstart/hugegraph/hugegraph-helm/#optional-engines) and [Vermeer Deployment Guide](https://github.com/hugegraph/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md). > [!WARNING] > In production, enable [Server authentication and authorization](/docs/config/config-authentication/), an IP allowlist, and minimum permissions; retain `audit-*.log`. Server Auth does not protect independent Vermeer, PD, or Store APIs. Restrict these HTTP/gRPC ports to trusted networks and callers, and configure access controls at the Vermeer external entry point. > -> Manual upstream `master.ini` defaults to `auth=none`; the manual Docker examples below publish loopback only. This is independent of the Helm integration, -> which always uses token authentication, a private native Service and an administrator password. -> Do not use the manual unauthenticated defaults as a Helm shortcut. -> For a protected manual deployment, enable `auth=token` and follow the upstream file-based credential instructions before remote access. +> Manual standalone deployments default to `auth=none` in `master.ini`, and the Docker examples below publish to loopback only. When deploying manually for remote access, always enable `auth=token`. The Helm deployment enables token authentication and private ClusterIP isolation by default. Both Docker options need a host configuration directory. From the Vermeer repository root, copy the supplied [`master.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/master.ini) and [`worker.ini`](https://github.com/apache/hugegraph-computer/blob/master/vermeer/config/worker.ini) templates. The mount hides image configuration under `/go/bin/config`, so never mount an empty directory or your entire home directory there: diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md index 760b07da49..dc10c1488e 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm-operations.md @@ -44,50 +44,23 @@ No local Helm rendering verifies live cluster reachability, volumes or JVM capac ### Preserve the metadata namespace {#metadata-namespace} -`metadataCluster: hg-test` keeps the legacy Server PD metadata prefix and configures both Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER`. -It is not a Raft name or a metadata-migration option. Do not switch an initialized deployment to `hg` merely to enable Vermeer. -If Vermeer Store scans report `Schema missing` or `no such vertex label` while Server REST queries work, first compare this shared value -with the existing Server metadata namespace and the environment of each running Store Pod. +`metadataCluster: hg-test` sets the PD metadata namespace prefix (injected into Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER`). +It is not a Raft group name; changing it will not automatically migrate existing metadata. **Never** arbitrarily change this prefix on an initialized cluster to enable Vermeer. If Server REST queries succeed but Vermeer scanning Store fails with `Schema missing` or `no such vertex label`, check that the namespace prefix matches across all components. -Online upgrades reject a target value that conflicts with the recorded Server Deployment annotation or explicit `HG_SERVER_CLUSTER` value. -Standard legacy `hg-test` releases need no extra adoption action. If an older custom image used another prefix and the Chart cannot verify it, -inspect the existing Server logs/configuration first. Record that verified existing value on the Server Deployment, then set `metadataCluster` -to exactly the same value in the reviewed Helm values: +If a legacy environment used a custom prefix, record it explicitly on the Server Deployment before upgrading: ```bash kubectl -n hugegraph annotate deployment hugegraph-server \ hugegraph.apache.org/metadata-cluster='' ``` -Replace the placeholder only after verification. This records the namespace already in use; it does not copy or migrate PD keys. -Offline/GitOps rendering cannot inspect the running Deployment, so preserve the verified value explicitly. -With the cluster preset's `store.updateStrategy.type=OnDelete`, updating the StatefulSet template does not update running Pods. -Apply the existing [one-at-a-time Store procedure](#6-rolling-store-images-safely) before expecting the new environment to take effect. -Replacing a Pod backed by `emptyDir` discards its temporary data; such a rollout is not a lossless recovery or migration. - -> [!DETAILS]- Optional engines: readiness, credentials and recovery -> SeaTunnel and Vermeer stay disabled in both HugeGraph presets; enabling either adds separate entry credentials and network rules. -> SeaTunnel HTTP/UI uses 8080 and Basic authentication. Its private HTTP/member ports admit only required internal callers in both modes. -> Its long-running hybrid process does not provide PVC-backed checkpoint recovery. -> -> Vermeer Master HTTP/gRPC uses 6688/6689, and Worker HTTP/gRPC uses 6788/6789. Its native UI/API also remains private behind ClusterIP. -> Standalone has one Pod with separate Master/Worker containers and data volumes; cluster has one Master plus three Worker Pods by default. -> Both engines always require native login. Newly generated administrator passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode. -> Upgrades retain existing passwords, including when changing mode; changing mode does not rotate them automatically. -> Optional administration uses authorized port-forwarding; Vermeer **Admin credential** accepts the password from `-vermeer-admin`, -> key `password`, with no username required. Login creates a 24-hour versioned session cookie. SeaTunnel still uses username `admin`. -> Hubble service authentication is automatic and separate from human passwords; no token retrieval is needed. -> An external Vermeer administrator Secret change needs a Master restart only; internal service-factor rotation needs Master and Hubble, not Workers. -> -> Master/Worker listener health does not prove space-level compute readiness. Check `/api/v1/workers/availability` with the service credential, -> then verify loading and a known algorithm result through Hubble. The common Worker pool avoids manual allocation for new spaces. -> Persistent metadata does not restore in-memory graphs, result caches or running jobs automatically. -> Stop submissions, finish/cancel tasks and unload compute graphs before topology/Worker-count changes; inspect availability and reload afterward. -> Standalone and cluster use different Worker claims, so changing modes does not migrate local files. -> -> Follow the [Vermeer operations guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) -> and [SeaTunnel operations guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) -> for administrator password retrieval, retained claims and exact upgrade commands. Raw service tokens are advanced internal integrations only. +and ensure `metadataCluster` matches this value in your values file. For Store nodes using `store.updateStrategy.type=OnDelete`, follow the [rolling upgrade procedure](#6-rolling-store-images-safely) to recreate Pods one by one so the new settings take effect. + +> [!DETAILS]- Optional Engines Operations: Probes, Credentials, and Topology Switching +> - **Ports & Health**: SeaTunnel HTTP/UI runs on `8080`; Vermeer Master HTTP/gRPC listens on `6688/6689`, and Worker on `6788/6789`. Both engines stay behind private ClusterIP in both modes. +> - **Credentials & Sessions**: Generated admin passwords use 6 characters in easy mode or 16 in strict mode, retained across upgrades and mode changes. In Vermeer native UI, enter the password from Secret `-vermeer-admin` into **Admin credential**; Hubble internal service tokens are auto-wired. +> - **Topology Changes**: Ensure active computations and batch ingestion jobs are complete and in-memory graphs are unloaded before changing `seatunnel.mode` or `vermeer.mode`. Standalone and cluster use separate PVC claims, so mode changes do not migrate local files. +> - See the [Vermeer Guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md) and [SeaTunnel Guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) for full recovery and configuration details. ### Helm test coverage diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md index 0f1f5dfbf2..49e566f8dc 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md @@ -122,22 +122,17 @@ the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields rem ### Optional engines: disabled by default {#optional-engines} -SeaTunnel and Vermeer remain disabled with both `values-single.yaml` and `values-cluster.yaml`. -These presets select HugeGraph's HStore topology; `seatunnel.mode` and `vermeer.mode` select the optional engines' own topology. -Top-level `mode: easy/strict` separately controls Server/Hubble HTTP entry and full network isolation. +By default, the Chart provisions only the core graph services (PD + Store + Server + Hubble). For data migration and distributed memory graph computing, the Chart offers SeaTunnel and Vermeer as native optional engines, both disabled by default: -| Component | Default | Switch | -|---|---|---| -| Hubble | `true` | `hubble.enabled` | -| SeaTunnel | `false` | `seatunnel.enabled` | -| Vermeer | `false` | `vermeer.enabled` | - -Set an engine's switch to `true` to enable it. Set `hubble.enabled=false` for API-only access. +| Engine | Default | Purpose | Topologies (`*.mode`) | Access & Security | +|---|---|---|---|---| +| **Hubble** | Enabled (`true`) | Graph visualization, multi-graphspace management & metrics | Single-replica Deployment | Follows global `mode` (NodePort or ClusterIP) | +| **SeaTunnel** | Disabled (`false`) | Heterogeneous data ingestion & full graph migration | `standalone` / `cluster` | Private ClusterIP (HTTP Basic auth) | +| **Vermeer** | Disabled (`false`) | Memory-first high-performance distributed graph algorithms | `standalone` / `cluster` | Private ClusterIP (Token auth, auto-wired to Hubble) | -The examples below use the source Chart from the HugeGraph repository root. -For Vermeer computation, enable the switch and sign in to Hubble; service addresses and credentials are configured automatically. +Enable either engine by setting its `enabled` key to `true` in values. Both engines maintain private ClusterIP services, and their administrative passwords are generated independently from Server. -> [!DETAILS]- SeaTunnel: enable native import, export and migration +> [!DETAILS]- SeaTunnel: On-demand Data Import, Export, and Migration > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ > -f helm/hugegraph/values-single.yaml \ @@ -145,16 +140,11 @@ For Vermeer computation, enable the switch and sign in to Hubble; service addres > --wait --timeout 30m > ``` > -> Standalone starts one long-running hybrid member. Set `seatunnel.mode=cluster` and `seatunnel.replicas=2` -> for multiple hybrid members. Native UI/API access remains private behind ClusterIP and always requires HTTP Basic login. -> Newly generated administrator passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode. -> Upgrades, including mode changes, retain existing passwords without automatic rotation. HTTP/member ports admit only required internal callers -> in both modes. For optional administration, use an authorized port-forward as described in the deployment guide. -> Helm prepares the engine and examples; create graphs and submit jobs yourself. Checkpoints use temporary local files. -> See the [SeaTunnel deployment guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) -> for access, credentials, copy examples and recovery limits. - -> [!DETAILS]- Vermeer: enable graph computation and automatic Hubble connection +> - **Topologies**: `standalone` runs 1 Hybrid node for lightweight testing; `cluster` runs multiple homogeneous nodes for high-throughput batch jobs. +> - **Authentication**: Web dashboard uses independent HTTP Basic auth (default `admin`), stored in the `hugegraph-seatunnel-auth` Secret. Port `5801` is strictly for cluster internal communication. +> - See the [SeaTunnel Deployment Section](#6-start-seatunnel) or [SeaTunnel Guide](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/seatunnel.md) for full job configs and migration steps. + +> [!DETAILS]- Vermeer: In-Memory Graph Computing Integrated with Hubble > ```bash > helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \ > -f helm/hugegraph/values-single.yaml \ @@ -162,37 +152,26 @@ For Vermeer computation, enable the switch and sign in to Hubble; service addres > --wait --timeout 20m > ``` > -> Standalone uses one Pod with separate native Master and Worker containers and separate data volumes. -> Set `vermeer.mode=cluster` for one Master Pod plus `vermeer.worker.replicas` Worker Pods (default 3). -> Multiple Workers provide distributed computation; the single Master has no automatic failover guarantee. -> -> Keep Hubble in its default PD mode. The Chart supplies the internal Master URL and service token automatically. -> Log in to Hubble as the HugeGraph administrator, select an HStore graph, load/reload it, run one of the nine supported algorithms, -> inspect/cancel the asynchronous task and page through results. Compute-copy cleanup uses the existing Hubble administrator API; -> the current page has Load/Reload controls, not a separate Unload button. -> This workflow does not write results into HugeGraph properties. Ordinary graph readers do not receive direct Store-scan privileges. +> ```text +> helm/hugegraph/ +> examples/ +> values-vermeer-standalone.yaml # Standalone preset (Master and Worker combined in one Pod) +> values-vermeer-cluster.yaml # Cluster preset (1 dedicated Master Pod + 3 distributed Worker Pods) +> docs/ +> vermeer.md # Advanced algorithm parameters, API mapping and operations +> ``` > -> Native UI/API remains private behind ClusterIP in both modes. Optional administration uses -> `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` and `http://127.0.0.1:6688/`. -> Read the separate administrator password from Secret `hugegraph-vermeer-admin`, key `password`, and paste it into **Admin credential**. -> Newly generated passwords use 6 random alphanumeric characters in easy mode or 16 in strict mode; upgrades and mode changes retain existing passwords. -> Login creates a 24-hour versioned session cookie. Hubble needs no manual service token. -> The [Vermeer deployment guide](https://github.com/hugegraph/hugegraph/blob/e0f6b071c31e645127226ee5c1217a4fb4196732/helm/hugegraph/docs/vermeer.md) -> covers password retrieval, storage, mode changes and advanced service credentials. -> The Chart pins `hugegraph/vermeer:helm-30b67d93e7d0` to image-index digest -> `sha256:f9b69ef134069b432de1c9964374d7fdbfa53245d1fe7dcbce1e75b82b69dc9e`, published by the -> [official workflow run](https://github.com/hugegraph/actions/actions/runs/40653109759) from source -> [`30b67d93e7d0`](https://github.com/hugegraph/hugegraph-computer/commit/30b67d93e7d097374341cf46ee6a0703421512b1). -> Hubble requires `hubble.mode=pd` for this native integration; API-only Vermeer remains usable with `hubble.enabled=false`. -> For first enablement on a pre-Vermeer release, export and review `helm get values --all -o yaml`, then supply that file with `-f` -> without `--reuse-values`, allowing the new Vermeer defaults to load. Preserve `metadataCluster`; see the deployment guide for the complete command. +> - **Topologies**: `standalone` runs Master and Worker in one Pod; `cluster` provides a separate Master coordinator Pod and scalable Worker computing Pods (default 3 replicas). +> - **Hubble Integration**: Hubble automatically acquires the internal Master Service URL and service tokens. Operators can trigger 15+ graph algorithms directly from Hubble without manual token configuration. +> - **Native Dashboard Access**: Forward the private Service via `kubectl -n hugegraph port-forward svc/hugegraph-vermeer-master 6688:6688` and sign in with the password from Secret `-vermeer-admin` under **Admin credential**. +> - For image pinning and credentials management, see the [Vermeer Deployment Guide](https://github.com/hugegraph/hugegraph/blob/master/helm/hugegraph/docs/vermeer.md). ### PD metadata namespace {#metadata-namespace} -Top-level `metadataCluster` defaults to `hg-test`, preserving the existing Server metadata prefix. -The Chart supplies the same value as Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER`, so Store scans resolve the Schema written by Server. -This prefix is independent of Raft names, service IDs and graph spaces. A new deployment can choose another identifier before initialization. -Changing the value afterward does not migrate metadata or graph data; keep the initialized Server value when enabling Vermeer. +The top-level `metadataCluster` parameter (default `hg-test`) specifies the PD metadata cluster prefix. The Chart injects this value into Server `HG_SERVER_CLUSTER` and Store `PD_CLUSTER`, ensuring Store correctly locates the Schema initialized by Server when processing Vermeer graph scans. + +> [!IMPORTANT] +> `metadataCluster` is a metadata namespace prefix, not a Raft group name. Modifying it **does not** automatically migrate existing graph data. Always preserve the original cluster prefix when enabling Vermeer; if graph load tasks fail with `Schema missing` or `no such vertex label`, check that the namespace prefix matches across all components. Refer to the [Metadata Namespace Operations Guide](./hugegraph-helm-operations.md#metadata-namespace) for details. Standard older releases using `hg-test` need no namespace-adoption step. For a custom legacy prefix, follow [metadata namespace adoption](./hugegraph-helm-operations.md#metadata-namespace) before upgrading.