You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hugegraph.apache.org by ji...@apache.org on 2026/10/16 16:43:11 UTC
(hugegraph-doc) branch master updated: docs: explain Helm OCI installation (#533)
This is an automated email from the ASF dual-hosted git repository.
imbajin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git
The following commit(s) were added to refs/heads/master by this push:
new bb039de98 docs: explain Helm OCI installation (#533)
bb039de98 is described below
commit bb039de9898a5f8f06a29bb733b956570f1874d5
Author: imbajin <ji...@apache.org>
AuthorDate: Sat Oct 17 00:43:06 2026 +0800
docs: explain Helm OCI installation (#533)
The Helm quickstart currently starts with a source checkout. It now installs a published Chart from GHCR or Docker Hub, with matching English and Chinese instructions. Trials follow the latest version with --devel; a short tip explains how to pin a version for production or reproducible installs.
---
.../cn/docs/quickstart/hugegraph/hugegraph-helm.md | 106 ++++++++++++++++----
.../en/docs/quickstart/hugegraph/hugegraph-helm.md | 111 +++++++++++++++++----
static/images/helm-oci-install-cn.png | Bin 0 -> 1525095 bytes
static/images/helm-oci-install.png | Bin 0 -> 1199762 bytes
4 files changed, 175 insertions(+), 42 deletions(-)
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index 80540bfdb..a7ae6ee91 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -2,13 +2,22 @@
title: "使用 Helm 部署 HugeGraph"
linkTitle: "Helm 部署"
weight: 4
-search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble, 内网部署]
+search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, 内网部署, OCI, GHCR, Artifact Hub]
---
-本文对应 HugeGraph 开发分支的 chart。发布镜像完成前标签仍为 `latest`，实际部署请固定自己的镜像版本。
-需要 Helm 3 和 Kubernetes 1.23 或更高版本。常用命令和参数见
-[chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md)，生命周期操作见
-[运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md)。
+本文适用于 HugeGraph **1.8.0 及以后版本**，需要支持 OCI 的 Helm **3.8+** 和 Kubernetes (K8s) **1.23+**。
+可从 GHCR 或 Docker Hub 安装 `hugegraph-helm`。Chart 与 HugeGraph 服务分别维护版本，例如 `0.2.x` 的 Chart 可以部署 `1.8.x` 的服务。
+
+> [!WARNING]
+> 当前开发 Chart 使用 `latest` 镜像，适合测试。
+> 对应 HugeGraph 服务正式发布后，生产环境请选择稳定 Chart，并检查其中的镜像版本。
+> 镜像标签可能变化；需要固定镜像内容时，请配置各组件的 `image.digest`。
+
+[Artifact Hub](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) 方便查找 Chart、查看版本和安装说明，实际安装包仍从 GHCR 或 Docker Hub 下载。
+参数和源码开发方式见 [chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md)，
+生命周期操作见 [运维参考](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md)。
+
+
## 1 安装
@@ -18,26 +27,47 @@ search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble, 内网部署]
> - **存储依赖**：需要集群具备默认动态 StorageClass 或预先匹配的静态 local PV，共需 7 个持久卷（3 个 10 GiB PD 卷、3 个 50 GiB Store 卷、1 个 1 GiB Hubble 卷）。
> - **内存考量**：保留镜像内 JVM 内存自动推导；按需调整 resource requests/limits，确保宿主机给 9 个图服务 JVM 与 Hubble 提供足够内存。
-```bash
-git clone https://github.com/apache/hugegraph.git
-cd hugegraph
+选择一个下载源即可，公共 CI 推荐 GHCR。本地轻量测试可直接使用单节点预设。
+
+> [!TIP]
+> `--devel` 按版本号选择最新 Chart，包含开发版和稳定版，不限于某个版本系列。
+> 生产部署或需要复现时，将 `--devel` 换成 `--version <已发布版本>`，固定你选定的版本。
+
+```bash {tab="GHCR（推荐）"}
+CHART=oci://ghcr.io/hugegraph/hugegraph-helm
+kubectl config current-context
+kubectl get nodes
+kubectl get storageclass
+helm install hugegraph "$CHART" --devel -n hugegraph \
+ --create-namespace --wait --timeout 15m
+```
+
+```bash {tab="Docker Hub"}
+CHART=oci://registry-1.docker.io/hugegraph/hugegraph-helm
kubectl config current-context
kubectl get nodes
kubectl get storageclass
-# 默认标准集群安装（3 PD + 3 Store + 3 Server + 1 Hubble，需 7 个 PV）：
-helm install hugegraph ./helm/hugegraph -n hugegraph \
+helm install hugegraph "$CHART" --devel -n hugegraph \
--create-namespace --wait --timeout 15m
+```
-# 本地测试 / 单节点轻量环境（Minikube、Kind 等，仅各 1 副本且关闭反亲和）：
-# helm install hugegraph ./helm/hugegraph -n hugegraph \
-# -f ./helm/hugegraph/values-single.yaml \
-# --create-namespace --wait --timeout 10m
+```bash {tab="单节点试用"}
+# 适合本地 Minikube/Kind 等轻量测试；直接安装本次下载的 Chart
+CHART=oci://ghcr.io/hugegraph/hugegraph-helm
+helm pull "$CHART" --devel --untar
+helm install hugegraph ./hugegraph-helm -n hugegraph \
+ -f ./hugegraph-helm/values-single.yaml \
+ --create-namespace --wait --timeout 10m
```
+单节点试用预设替代默认安装，将各组件设为 1 副本并放宽调度限制，适合资源受限环境。
+
## 2 模式和访问入口
+解压后目录为 `hugegraph-helm/`，源码目录仍为 `helm/hugegraph/`。
+
```filetree {.hg-filetree-notes title="HugeGraph Helm 核心文件与结构"}
-helm/hugegraph/
+hugegraph-helm/
Chart.yaml # Chart 元数据与版本定义
values.yaml # 默认配置（easy 模式：3 PD + 3 Store + 3 Server + 1 Hubble，NodePort 入口）
values-single.yaml # 单节点预设（本地 Minikube/Kind 测试，1 副本且关闭反亲和与 PDB）
@@ -87,7 +117,7 @@ NodePort 省略或设为 `0` 时自动分配，固定端口由 Kubernetes 根据
默认 `server.serviceId` 与 `server.graphSpace` 均为 `DEFAULT`。如需将 Server 注册到指定的业务服务名或图空间，可通过 values 指定：
```bash
-helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \
+helm upgrade --install hugegraph "$CHART" --devel -n hugegraph \
--set-string server.serviceId=analytics \
--set-string server.graphSpace=team_a \
--set-string server.testGraphAlias=team_a-demo
@@ -106,6 +136,39 @@ GitOps 凭据、仅 API 部署以及无域名的 HTTP Ingress。
等待 PD 的 init container 复用 Store 镜像，Helm test 复用 Server 镜像。这两个镜像已包含 `curl`，无需额外 curl 镜像或启动时安装软件。
自定义镜像可以继续使用显式 `store.waitImage` 和 `server.waitImage` 覆盖。
+### 离线安装和私库
+
+先选择最新版本，再按该版本下载 Chart，将 `.tgz` 搬入内网。可以直接安装，也可以接入已有的 OCI 或 HTTP 私库。
+
+```bash
+CHART=oci://ghcr.io/hugegraph/hugegraph-helm
+CHART_VERSION=$(helm show chart "$CHART" --devel | sed -n 's/^version: //p')
+helm pull "$CHART" --version "$CHART_VERSION"
+```
+
+```bash {tab="直接安装"}
+helm install hugegraph "./hugegraph-helm-${CHART_VERSION}.tgz" -n hugegraph \
+ --create-namespace --wait --timeout 15m
+```
+
+```bash {tab="OCI 私库"}
+helm registry login registry.example.com
+helm push "./hugegraph-helm-${CHART_VERSION}.tgz" oci://registry.example.com/charts
+helm install hugegraph oci://registry.example.com/charts/hugegraph-helm \
+ --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m
+```
+
+```bash {tab="HTTP 私库"}
+# 按私库的上传方式接收同一个 .tgz，并更新 index.yaml。
+# 自建静态 HTTP 源可用 helm repo index 生成索引；helm push 只适用于 OCI。
+helm repo add hugegraph-internal https://charts.example.com
+helm repo update hugegraph-internal
+helm install hugegraph hugegraph-internal/hugegraph-helm \
+ --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m
+```
+
+私库地址请替换为实际地址。Chart 包不包含容器镜像；完整离线部署还需搬运配置引用的所有容器镜像，并覆盖镜像地址。
+
`storageClassName` 为空时继承集群默认 StorageClass，`"-"` 表示显式不使用 StorageClass。
local PV 需要预建宿主机目录、匹配容量、`nodeAffinity` 和 `kubernetes.io/no-provisioner` StorageClass。
`WaitForFirstConsumer` 根据 Pod 调度约束绑定，创建资源前请查看七个卷的完整例子。
@@ -132,16 +195,17 @@ Hubble 默认开启，当前镜像的登录仍依赖 Server 鉴权。只使用 A
## 5 升级和验证
-使用 Helm 原生值复用保留旧部署的 UI、入口、存储和凭据设置。
+使用 Helm 原生值复用保留已有部署的 UI、入口、存储和凭据设置。
```bash
helm get values hugegraph -n hugegraph --all
-helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \
- --wait --timeout 15m
+# 测试环境继续跟随最新版本；生产升级请改用 --version 指定已审阅的稳定版本。
+helm upgrade hugegraph "$CHART" --devel -n hugegraph \
+ --reuse-values --wait --timeout 15m
helm test hugegraph -n hugegraph --logs --timeout 5m
```
-旧值中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。
+已有配置中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。
要采用新的默认值，先审阅已有配置，再使用 `--reset-values` 和保留镜像、凭据、存储、拓扑设置的配置文件。
PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。
@@ -149,5 +213,5 @@ PD 成员、持久存储和共享凭据变更需要按生命周期说明协调
未指定的启动探针阈值按存储等待加 150 秒推导；显式探针不会被改写，但预算必须覆盖存储等待和至少 120 秒 Server 启动时间。
矛盾预算会在渲染时报出对应参数。这个等待超时不是 JVM 内存配置。
-Kubernetes Ready 和 `helm test` 不代表 UI 登录已经验证。安装或恢复后还应测试新登录及图查询。
+默认 `helm test` hook 检查连接和读取。安装或恢复后，还应重新登录 UI，并验证应用实际使用的读写查询。
调度、NetworkPolicy、滚动升级和恢复见 [Kubernetes 运维](./hugegraph-helm-operations.md)。
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index b61ad5fd1..65d93c02e 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -2,13 +2,24 @@
title: "Deploy HugeGraph with Helm"
linkTitle: "Helm Deployment"
weight: 4
-search_keywords: [HugeGraph Helm, Kubernetes, NodePort, Hubble]
+search_keywords: [HugeGraph Helm, Kubernetes, K8s, NodePort, Hubble, OCI, GHCR, Artifact Hub]
---
-This guide follows the chart in the HugeGraph development branch. Image tags remain `latest` until release images are published;
-pin images for your installation. The chart requires Helm 3 and Kubernetes 1.23 or later.
-Start with the [chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md) for common commands and settings.
-Advanced lifecycle procedures are in the [operations reference](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md).
+This guide covers HugeGraph **1.8.0 and later**, using Helm **3.8+** 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.
+
+> [!WARNING]
+> The current development Chart uses `latest` images and is intended for testing.
+> 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.
+
+[Artifact Hub](https://artifacthub.io/packages/helm/hugegraph-helm/hugegraph-helm) helps you find the Chart, browse versions and read installation instructions.
+The packages themselves are downloaded from GHCR or Docker Hub.
+See the [chart README](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/README.md) for settings and source-based development,
+and the [operations reference](https://github.com/apache/hugegraph/blob/master/helm/hugegraph/docs/operations.md) for lifecycle procedures.
+
+
## 1 Install
@@ -20,26 +31,47 @@ Advanced lifecycle procedures are in the [operations reference](https://github.c
> - **Memory Sizing**: Retains container JVM memory auto-calculation; configure resource requests/limits to allocate sufficient physical memory
> for the 9 JVMs and Hubble.
-```bash
-git clone https://github.com/apache/hugegraph.git
-cd hugegraph
+Choose either registry; GHCR is recommended for public CI. For local lightweight testing, use the single-node preset.
+
+> [!TIP]
+> `--devel` selects the highest Chart version, including development and stable versions, without limiting the version series.
+> For production or reproducible installations, replace `--devel` with `--version <published-version>` to pin your chosen version.
+
+```bash {tab="GHCR (recommended)"}
+CHART=oci://ghcr.io/hugegraph/hugegraph-helm
+kubectl config current-context
+kubectl get nodes
+kubectl get storageclass
+helm install hugegraph "$CHART" --devel -n hugegraph \
+ --create-namespace --wait --timeout 15m
+```
+
+```bash {tab="Docker Hub"}
+CHART=oci://registry-1.docker.io/hugegraph/hugegraph-helm
kubectl config current-context
kubectl get nodes
kubectl get storageclass
-# Standard cluster deployment (3 PD + 3 Store + 3 Server + 1 Hubble; requires 7 PVs):
-helm install hugegraph ./helm/hugegraph -n hugegraph \
+helm install hugegraph "$CHART" --devel -n hugegraph \
--create-namespace --wait --timeout 15m
+```
-# Local testing or single-node environments (Minikube, Kind; 1 replica and no anti-affinity):
-# helm install hugegraph ./helm/hugegraph -n hugegraph \
-# -f ./helm/hugegraph/values-single.yaml \
-# --create-namespace --wait --timeout 10m
+```bash {tab="Single-node trial"}
+# For local testing (Minikube, Kind): install the Chart downloaded below
+CHART=oci://ghcr.io/hugegraph/hugegraph-helm
+helm pull "$CHART" --devel --untar
+helm install hugegraph ./hugegraph-helm -n hugegraph \
+ -f ./hugegraph-helm/values-single.yaml \
+ --create-namespace --wait --timeout 10m
```
+The single-node preset replaces the default installation with one replica per component and relaxed scheduling constraints.
+
## 2 Modes and entry points
+The extracted package is rooted at `hugegraph-helm/`; the source directory remains `helm/hugegraph/`.
+
```filetree {.hg-filetree-notes title="HugeGraph Helm Chart Layout"}
-helm/hugegraph/
+hugegraph-helm/
Chart.yaml # Chart metadata and version definitions
values.yaml # Default values (easy mode: 3 PD + 3 Store + 3 Server + 1 Hubble, NodePort)
values-single.yaml # Single-node preset (local Minikube/Kind testing with 1 replica and no anti-affinity)
@@ -89,7 +121,7 @@ the chart does not force `30000–32767`. Legacy HTTP acknowledgement fields rem
Both `server.serviceId` and `server.graphSpace` default to `DEFAULT`. To register the Server with a specific service name or graph space in PD:
```bash
-helm upgrade --install hugegraph ./helm/hugegraph -n hugegraph \
+helm upgrade --install hugegraph "$CHART" --devel -n hugegraph \
--set-string server.serviceId=analytics \
--set-string server.graphSpace=team_a \
--set-string server.testGraphAlias=team_a-demo
@@ -108,6 +140,41 @@ 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.
+### Offline installation and internal repositories
+
+Select the latest version, download that Chart and move the `.tgz` into your network.
+Install it directly or upload it to an existing OCI or HTTP repository.
+
+```bash
+CHART=oci://ghcr.io/hugegraph/hugegraph-helm
+CHART_VERSION=$(helm show chart "$CHART" --devel | sed -n 's/^version: //p')
+helm pull "$CHART" --version "$CHART_VERSION"
+```
+
+```bash {tab="Install archive"}
+helm install hugegraph "./hugegraph-helm-${CHART_VERSION}.tgz" -n hugegraph \
+ --create-namespace --wait --timeout 15m
+```
+
+```bash {tab="Internal OCI"}
+helm registry login registry.example.com
+helm push "./hugegraph-helm-${CHART_VERSION}.tgz" oci://registry.example.com/charts
+helm install hugegraph oci://registry.example.com/charts/hugegraph-helm \
+ --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m
+```
+
+```bash {tab="Internal HTTP"}
+# Upload the same .tgz using your repository's upload mechanism and update index.yaml.
+# For a static HTTP repository, use helm repo index. Native helm push only supports OCI.
+helm repo add hugegraph-internal https://charts.example.com
+helm repo update hugegraph-internal
+helm install hugegraph hugegraph-internal/hugegraph-helm \
+ --version "$CHART_VERSION" -n hugegraph --create-namespace --wait --timeout 15m
+```
+
+Replace the example registry addresses with your own.
+The archive contains no container images: mirror all configured container images separately, then override their addresses.
+
For storage, empty `storageClassName` inherits the cluster default, while `"-"` explicitly selects no StorageClass.
Local PVs require prepared host directories, matching capacities, `nodeAffinity` and a `kubernetes.io/no-provisioner` StorageClass;
`WaitForFirstConsumer` binds with the Pod's scheduling constraints. See the complete seven-volume example before creating resources.
@@ -134,16 +201,17 @@ optionally also set `server.auth.enabled=false` for an unauthenticated API. Inac
## 5 Upgrade and verification
-Use native Helm value reuse to preserve an old release's UI, entry, storage and credentials:
+Use native Helm value reuse to preserve an existing deployment's UI, entry, storage and credentials:
```bash
helm get values hugegraph -n hugegraph --all
-helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \
- --wait --timeout 15m
+# Follow the latest version for testing; use --version with a reviewed stable version for production.
+helm upgrade hugegraph "$CHART" --devel -n hugegraph \
+ --reuse-values --wait --timeout 15m
helm test hugegraph -n hugegraph --logs --timeout 5m
```
-Older explicit helper images also remain under `--reuse-values`; add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images.
+Existing explicit helper images also remain under `--reuse-values`; add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images.
Adopt new defaults deliberately with `--reset-values` and a reviewed file retaining your image, credential, storage and topology settings.
Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference.
@@ -151,5 +219,6 @@ Do not treat PD membership, storage or credential changes as ordinary independen
from that wait plus 150 seconds; an explicit threshold is preserved and must cover the storage wait plus at least 120 seconds of Server startup.
A contradictory budget fails rendering with the relevant parameter names. Storage wait timeout is not a JVM memory setting.
-Kubernetes readiness and `helm test` do not prove fresh UI login. Test login and graph queries after install/recovery.
+The default `helm test` hook checks connectivity and reads. After installation or recovery, also test a new UI login and your application's
+read/write queries.
For scheduling, NetworkPolicy, rolling updates and recovery, see [Kubernetes operations](./hugegraph-helm-operations.md).
diff --git a/static/images/helm-oci-install-cn.png b/static/images/helm-oci-install-cn.png
new file mode 100644
index 000000000..17c08d23a
Binary files /dev/null and b/static/images/helm-oci-install-cn.png differ
diff --git a/static/images/helm-oci-install.png b/static/images/helm-oci-install.png
new file mode 100644
index 000000000..c74c555fe
Binary files /dev/null and b/static/images/helm-oci-install.png differ