feat(helm): add HStore deployment chart

.github/workflows/helm-chart-ci.yml

@@ -0,0 +1,202 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+name: "Helm Chart CI"
+
+on:
+  push:
+    branches: [ master, 'release-*' ]
+    paths: [ 'helm/**', '.github/workflows/helm-chart-ci.yml' ]
+  pull_request:
+    paths: [ 'helm/**', '.github/workflows/helm-chart-ci.yml' ]
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-render:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      # azure/setup-helm is not on the ASF-approved actions allowlist, which
+      # fails the workflow at startup; install the pinned release directly.
+      - name: install helm
+        run: |
+          curl -fsSL https://get.helm.sh/helm-v3.16.2-linux-amd64.tar.gz | tar -xz -C /tmp
+          sudo install -m 0755 /tmp/linux-amd64/helm /usr/local/bin/helm
+          helm version
+
+      - name: helm lint
+        run: |
+          helm lint helm/hugegraph
+          helm lint helm/hugegraph -f helm/hugegraph/values-single.yaml
+          helm lint helm/hugegraph -f helm/hugegraph/values-cluster.yaml
+
+      - name: helm template
+        run: |
+          for preset in "" "-f helm/hugegraph/values-single.yaml" "-f helm/hugegraph/values-cluster.yaml"; do
+            # shellcheck disable=SC2086 # $preset intentionally splits into flags
+            helm template ci helm/hugegraph $preset > /dev/null
+          done
+          # Positive coverage for every hubble wrapper branch: pd mode with
+          # auth, direct mode with a custom port, and a TLS-less ingress with
+          # the explicit opt-in.
+          helm template ci helm/hugegraph \
+            --set hubble.enabled=true \
+            --set server.auth.enabled=true \
+            --set server.auth.admin.existingSecret=ci-auth > /dev/null
+          helm template ci helm/hugegraph \
+            --set hubble.enabled=true \
+            --set hubble.allowWithoutServerAuth=true \
+            --set hubble.mode=direct \
+            --set hubble.port=9090 \
+            --set hubble.persistence.enabled=true \
+            --set hubble.ingress.enabled=true \
+            --set hubble.ingress.allowPlainHttp=true > /dev/null
+          # PD sharding knobs rendered as -D system properties, including
+          # the values-file shape where the count arrives as a numeric string
+          helm template ci helm/hugegraph \
+            --set pd.partition.defaultShardCount=3 \
+            --set pd.partition.storeMaxShardCount=12 > /dev/null
+          helm template ci helm/hugegraph \
+            --set-string pd.partition.defaultShardCount=3 > /dev/null
+          # The derived shard count must land in the PD JAVA_OPTS verbatim:
+          # 3 on the default topology, 1 on the single-node preset
+          helm template ci helm/hugegraph \
+            | grep -qF 'value: "-Dpartition.default-shard-count=3"'
+          helm template ci helm/hugegraph -f helm/hugegraph/values-single.yaml \
+            | grep -qF 'value: "-Dpartition.default-shard-count=1"'
+          # The stock distributed install must put every Server replica on
+          # the shared PD graph catalog, even without Hubble. Auth is on by
+          # default, so the chart-managed admin Secret must render too.
+          DEFAULT=$(helm template ci helm/hugegraph)
+          grep -qF "printf 'usePD=true\\n'" <<<"$DEFAULT"
+          grep -qF "printf 'pd.peers=%s\\n' \"\${HG_SERVER_PD_PEERS}\"" \
+            <<<"$DEFAULT"
+          grep -qF 'value: "ci-hugegraph-pd-0.ci-hugegraph-pd.default.svc:8686,ci-hugegraph-pd-1.ci-hugegraph-pd.default.svc:8686,ci-hugegraph-pd-2.ci-hugegraph-pd.default.svc:8686"' \
+            <<<"$DEFAULT"
+          grep -qE '^kind: Secret$' <<<"$DEFAULT"
+          grep -qF 'name: ci-admin' <<<"$DEFAULT"
+          grep -qF 'name: ci-auth-token' <<<"$DEFAULT"
+
+      - name: reject invalid values
+        run: |
+          # Each case must fail to render; the schema and helpers are the
+          # contract. `! cmd` alone is NOT enforced under `set -e` (errexit
+          # ignores inverted commands), so every case checks explicitly.
+          must_fail() {
+            if helm template ci helm/hugegraph "$@" >/dev/null 2>&1; then
+              echo "expected render failure for: $*" >&2
+              exit 1
+            fi
+          }
+          must_fail --set pd.replicas=100
+          must_fail --set pd.pdb.minAvailable=3
+          must_fail --set server.hpa.enabled=true
+          must_fail \
+            --set server.hpa.enabled=true \
+            --set server.hpa.minReplicas=2 \
+            --set server.resources.requests.cpu=100m \
+            --set server.pdb.enabled=true \
+            --set server.pdb.minAvailable=2
+          must_fail --set server.auth.enabled=true --set server.auth.admin.autoGenerate=false --set server.auth.token.autoGenerate=false
+          # Auth defaults to on, so Hubble alone is valid; refuse Hubble only
+          # when authentication is explicitly disabled.
+          must_fail --set hubble.enabled=true --set server.auth.enabled=false
+          A=(--set hubble.enabled=true --set hubble.allowWithoutServerAuth=true)
+          must_fail "${A[@]}" --set hubble.port=0
+          must_fail "${A[@]}" \
+            --set hubble.persistence.enabled=true \
+            --set hubble.persistence.size=""
+          must_fail "${A[@]}" --set hubble.service.nodePort=30080
+          must_fail "${A[@]}" --set hubble.mode=bogus
+          must_fail "${A[@]}" --set hubble.image.tag=""
+          must_fail "${A[@]}" --set hubble.ingress.enabled=true
+          must_fail --set server.ingress.enabled=true \
+            --set server.ingress.allowPlainHttp=true
+          # PD PDB must keep the Raft majority: floor(replicas/2)+1
+          must_fail --set pd.replicas=5 --set pd.pdb.minAvailable=2
+          must_fail --set pd.replicas=4 --set pd.pdb.minAvailable=2
+          helm template ci helm/hugegraph \
+            --set pd.replicas=5 --set pd.pdb.minAvailable=3 > /dev/null
+          helm template ci helm/hugegraph \
+            --set pd.replicas=5 --set pd.pdb.minAvailable=4 > /dev/null
+          # PD sharding knobs: empty or a positive integer; an explicit
+          # shard count must be odd and stay within the store count
+          must_fail --set pd.partition.defaultShardCount=0
+          must_fail --set pd.partition.defaultShardCount=-1
+          must_fail --set-string pd.partition.defaultShardCount=abc
+          must_fail --set pd.partition.defaultShardCount=2
+          must_fail --set pd.partition.defaultShardCount=5
+          must_fail --set pd.partition.storeMaxShardCount=0
+          # extraEnv must not override chart-managed variables
+          must_fail --set 'server.extraEnv[0].name=HG_SERVER_INIT_STORE_ENABLED' \
+            --set 'server.extraEnv[0].value=true'
+          must_fail --set 'pd.extraEnv[0].name=HG_PD_RAFT_PEERS_LIST' \
+            --set 'pd.extraEnv[0].value=x'
+          must_fail --set 'store.extraEnv[0].name=HG_STORE_PD_ADDRESS' \
+            --set 'store.extraEnv[0].value=x'
+          # JAVA_OPTIONS is reserved: a preset value makes the start scripts
+          # skip auto heap sizing and drop the chart's JAVA_OPTS entirely
+          must_fail --set 'pd.extraEnv[0].name=JAVA_OPTIONS' \
+            --set 'pd.extraEnv[0].value=-Xmx1g'
+
+      - name: kubeconform
+        shell: bash
+        run: |
+          set -o pipefail
+          curl -sSLo /tmp/kc.tar.gz https://github.com/yannh/kubeconform/releases/download/v0.6.7/kubeconform-linux-amd64.tar.gz
+          tar -xzf /tmp/kc.tar.gz -C /tmp
+          for preset in "" "-f helm/hugegraph/values-single.yaml" "-f helm/hugegraph/values-cluster.yaml"; do
+            # shellcheck disable=SC2086 # $preset intentionally splits into flags
+            helm template ci helm/hugegraph $preset | /tmp/kubeconform -strict -summary -kubernetes-version 1.23.0
+          done
+          helm template ci helm/hugegraph \
+            --set hubble.enabled=true \
+            --set hubble.allowWithoutServerAuth=true \
+            --set hubble.mode=direct \
+            --set hubble.port=9090 \
+            --set hubble.persistence.enabled=true \
+            --set hubble.ingress.enabled=true \
+            --set hubble.ingress.allowPlainHttp=true \
+            | /tmp/kubeconform -strict -summary -kubernetes-version 1.23.0
+          helm template ci helm/hugegraph \
+            --set hubble.enabled=true \
+            --set server.auth.enabled=true \
+            --set server.auth.admin.existingSecret=ci-auth \
+            | /tmp/kubeconform -strict -summary -kubernetes-version 1.23.0
+          helm template ci helm/hugegraph \
+            --set pd.partition.defaultShardCount=3 \
+            --set pd.partition.storeMaxShardCount=12 \
+            | /tmp/kubeconform -strict -summary -kubernetes-version 1.23.0
+
+      - name: legacy --reuse-values compatibility
+        run: |
+          # A release created before a field existed must still render. This has
+          # regressed five times, so it is guarded here rather than by review.
+          # `-f` is NOT equivalent: it merges over the new defaults, whereas
+          # --reuse-values discards them, so the fixture must become values.yaml.
+          cp -R helm/hugegraph /tmp/legacy
+          cp helm/hugegraph/testdata/values-pre-hardening.yaml /tmp/legacy/values.yaml
+          helm template legacy /tmp/legacy > /dev/null
+          helm template legacy /tmp/legacy --is-upgrade > /dev/null
+
+      - name: helm package
+        run: helm package helm/hugegraph -d /tmp/chart

README.md

@@ -207,9 +207,16 @@ For advanced Docker configurations, see:
 >
 > **Version Tags**: Use release tags (e.g., `1.7.0`) for stable deployments. The `latest` tag should only be used for testing or development.
 
+### Option 2: Kubernetes with Helm
+
+The HStore Helm chart deploys HugeGraph PD, Store, and Server as a distributed
+Kubernetes cluster. See the [chart documentation](helm/hugegraph/README.md) for
+single-node and highly available presets, configuration, and
+upgrade guidance.
+
 
 <details>
-<summary><b>Option 2: Download Binary Package</b></summary>
+<summary><b>Option 3: Download Binary Package</b></summary>
 
 Download pre-built packages from the [Download Page](https://hugegraph.apache.org/docs/download/download/):
 
@@ -242,7 +249,7 @@ For detailed instructions, see the [Binary Installation Guide](https://hugegraph
 </details>
 
 <details>
-<summary><b>Option 3: Build from Source</b></summary>
+<summary><b>Option 4: Build from Source</b></summary>
 
 Build from source for development or customization:
 

helm/hugegraph/.helmignore

@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Patterns to ignore when building packages.
+.DS_Store
+.git/
+.gitignore
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+.idea/
+.vscode/
+
+# Contributor tooling, if present in a working tree. Never ship it.
+scripts/
+testdata/
+
+# Never package a chart archive inside a chart.
+*.tgz

helm/hugegraph/Chart.yaml

@@ -0,0 +1,36 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+apiVersion: v2
+name: hugegraph
+description: Helm chart for Apache HugeGraph HStore cluster (PD + Store + Server)
+type: application
+version: 0.1.1
+appVersion: "latest"
+kubeVersion: ">=1.23.0-0"
+keywords:
+  - hugegraph
+  - graph
+  - hstore
+  - raft
+home: https://hugegraph.apache.org/
+sources:
+  - https://github.com/apache/hugegraph
+maintainers:
+  - name: HugeGraph Community
+    url: https://hugegraph.apache.org/
+    email: dev@hugegraph.apache.org