From 1ff2271e454a5ed36e05dcc3863d072dc4e3d482 Mon Sep 17 00:00:00 2001 From: Pranali Deshmukh Date: Thu, 6 Nov 2025 17:58:30 +0200 Subject: [PATCH 1/4] docs: update Helm chart README for Hiero Block Node installation and configuration This update revises the Helm chart README for the Hiero Block Node to provide clearer installation guidance and improved troubleshooting instructions. Signed-off-by: Pranali Deshmukh --- charts/block-node-server/README.md | 161 +++++++++++++++++++++++------ 1 file changed, 130 insertions(+), 31 deletions(-) diff --git a/charts/block-node-server/README.md b/charts/block-node-server/README.md index 8980ef235..8747b32e7 100644 --- a/charts/block-node-server/README.md +++ b/charts/block-node-server/README.md @@ -4,61 +4,84 @@ Installs the Hiero Block Node on a Kubernetes cluster. ## Prerequisites -- Helm 3+ -- Kubernetes 1.29+ +* [Helm 3+](https://helm.sh/docs/intro/install/) +* [Kubernetes 1.29+](https://kubernetes.io/releases/) -For Development and Test environment is recommended to use minikube with the following command (if want to deploy the kube-prometheus-stack for metrics visualization): +## Development and Test Environment Setup +For development and test environments, it is recommended to use [minikube](https://minikube.sigs.k8s.io/docs/start/). + +### Basic minikube setup ```bash -minikube delete && minikube start --kubernetes-version=v1.23.0 --memory=8g --bootstrapper=kubeadm --extra-config=kubelet.authentication-token-webhook=true --extra-config=kubelet.authorization-mode=Webhook --extra-config=scheduler.bind-address=0.0.0.0 --extra-config=controller-manager.bind-address=0.0.0.0 +minikube delete && minikube start --kubernetes-version=v1.29.0 ``` -Set environment variables that will be used for the remainder of the document: -Replacing the values with the appropriate values for your environment: bn-release is short for block-node-release, but you can name you release as you wish. And use the version that you want to install. +### minikube setup with monitoring support +If you want to deploy the `kube-prometheus-stack` for metrics visualization: ```bash -export RELEASE="bn-release" -export VERSION="0.23.0-SNAPSHOT" +minikube delete && minikube start \ + --kubernetes-version=v1.29.0 \ + --memory=8g \ + --bootstrapper=kubeadm \ + --extra-config=kubelet.authentication-token-webhook=true \ + --extra-config=kubelet.authorization-mode=Webhook \ + --extra-config=scheduler.bind-address=0.0.0.0 \ + --extra-config=controller-manager.bind-address=0.0.0.0 ``` -## Template - -To generate the K8 manifest files without installing the chart, you need to clone this repo and navigate to `/charts` folder. +## Configuration +Set environment variables that will be used throughout this guide. Replace the values with appropriate values for your environment: ```bash -helm template --name-template bn-release block-node-server/ --dry-run --output-dir out +export RELEASE="bn-release" # bn-release is short for block-node-release +export VERSION="0.23.0-SNAPSHOT" ``` +## Installation Options -## Install using a published chart +### Option 1: Template (without installing) -To pull the packaged chart from the public repo: +To generate Kubernetes manifest files without installing the chart: +1. Clone this repository +2. Navigate to the `/charts` folder +3. Run the following command: ```bash -helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart --version "${VERSION}" +helm template --name-template bn-release block-node-server/ --dry-run --output-dir out ``` -To install the chart with default values: +### Option 2: Install using a published chart +#### Pull the packaged chart ```bash -helm install "${RELEASE}" block-node-server/charts/block-node-server-$VERSION.tgz +helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" ``` -To install the chart with custom values: +#### Install with default values +```bash +helm install "${RELEASE}" block-node-server-$VERSION.tgz +``` +#### Install with custom values ```bash -helm install "${RELEASE}" block-node-server/charts/block-node-server-$VERSION.tgz -f +helm install "${RELEASE}" block-node-server-$VERSION.tgz -f ``` -*Note:* If using the chart directly after cloning the github repo, there is no need to add the repo. and install can be directly. -Assuming you are at the root folder of the repo. +### Option 3: Install directly from cloned repository + +*Note:* There is no need to add the repo, If using the chart directly after cloning the GitHub repository. Assuming you are at the root folder of the repository: +1. Build dependencies: ```bash helm dependency build charts/block-node-server +``` +2. Install the chart: +```bash helm install "${RELEASE}" charts/block-node-server -f ``` -## Configure +## Custom Configuration There are several ways to configure the Hiero Block Node. The following is the most common and recommended way to configure the Hiero Block Node. @@ -115,10 +138,34 @@ promtail: enabled: false ``` -## Using +## Post-Installation Follow the `NOTES` instructions after installing the chart to perform `port-forward` to the Hiero Block Node and be able to use it. +## Upgrade + +To upgrade the chart to a new version: + +1. Set the new version: +```bash + export VERSION="" +``` + +2. Pull the new chart version: +```bash + helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" +``` + +3. Save your current configuration: +```bash + helm get values "${RELEASE}" > user-values.yaml +``` + +4. Upgrade the release: +```bash + helm upgrade "${RELEASE}" block-node-server-$VERSION.tgz -f user-values.yaml +``` + ## Uninstall To uninstall the chart: @@ -126,16 +173,68 @@ To uninstall the chart: ```bash helm uninstall "${RELEASE}" ``` +This will remove all Kubernetes resources associated with the release. -## Upgrade -To upgrade the chart: +## Troubleshooting + +This section covers common issues you may encounter when working with the Hiero Block Node Helm chart. + +### Chart Dependencies Missing + +**When running:** +```bash +helm template --name-template bn-release block-node-server/ --dry-run --output-dir out +``` + +**Error:** +``` +Error: An error occurred while checking for chart dependencies. You may need to run `helm dependency build` to fetch missing dependencies: found in Chart.yaml, but missing in charts/ directory: kube-prometheus-stack, loki, promtail +Error: Chart.yaml file is missing +``` + +**Solution:** + +Before running the template command, build the chart dependencies: +```bash +helm dependency build charts/block-node-server +``` + +This will download all required chart dependencies to the `charts/` directory. + +--- + +### Chart Version Not Found in Registry + +**When running:** +```bash +helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart --version "${VERSION}" +``` + +**Error:** +``` +Error: failed to perform "fetchReference" on source: ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart:0.22.8-SNAPSHOT: not found +``` + +or +``` +Error: failed to perform "fetchReference" on source: ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart:0.21.2: not found +``` + +**Cause:** + +The specified chart version does not exist in the registry, or the OCI registry path has changed. + +**Solution:** + +1. Use the correct OCI registry path: +```bash + helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" +``` + +2. Verify the chart version exists by checking the [releases page](https://github.com/hiero-ledger/hiero-block-node/releases) +3. Confirm your `VERSION` environment variable is set to a valid release: ```bash -# update the helm repo -helm repo update -# save current user supplied values -helm get values "${RELEASE}" > user-values.yaml -# upgrade the chart -helm upgrade "${RELEASE}" hiero-block-node/block-node-server -f user-values.yaml + echo $VERSION ``` From cf151e9652327ac1f6d8fcd7058098672d14b30c Mon Sep 17 00:00:00 2001 From: Pranali Deshmukh Date: Fri, 7 Nov 2025 18:44:19 +0200 Subject: [PATCH 2/4] Update charts/block-node-server/README.md Co-authored-by: Nana Essilfie-Conduah <56320167+Nana-EC@users.noreply.github.com> Signed-off-by: Pranali Deshmukh --- charts/block-node-server/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/block-node-server/README.md b/charts/block-node-server/README.md index 8747b32e7..0d7366254 100644 --- a/charts/block-node-server/README.md +++ b/charts/block-node-server/README.md @@ -223,7 +223,7 @@ Error: failed to perform "fetchReference" on source: ghcr.io/hiero-ledger/hiero- **Cause:** -The specified chart version does not exist in the registry, or the OCI registry path has changed. +The specified chart version or name does not exist in the registry, or the OCI registry path has changed. **Solution:** From c95624efd56f503c1c482e84e2e694e85b419838 Mon Sep 17 00:00:00 2001 From: Pranali Deshmukh Date: Mon, 17 Nov 2025 19:50:59 +0200 Subject: [PATCH 3/4] docs: update upgrade section to support OCI registry and local chart methods Add separate sections for local charts and OCI registry based upgrade paths. Signed-off-by: Pranali Deshmukh --- charts/block-node-server/README.md | 33 +++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/charts/block-node-server/README.md b/charts/block-node-server/README.md index 0d7366254..3660fb1c9 100644 --- a/charts/block-node-server/README.md +++ b/charts/block-node-server/README.md @@ -144,28 +144,51 @@ Follow the `NOTES` instructions after installing the chart to perform `port-forw ## Upgrade -To upgrade the chart to a new version: +### Upgrade using a published chart (OCI registry) + +To upgrade the chart to a new version from the OCI registry: 1. Set the new version: ```bash export VERSION="" ``` -2. Pull the new chart version: +2. Save your current configuration: ```bash - helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" + helm get values "${RELEASE}" > user-values.yaml ``` -3. Save your current configuration: +3. Upgrade the release directly from OCI registry: +```bash + helm upgrade "${RELEASE}" oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" -f user-values.yaml +``` + +### Upgrade using a local chart + +To upgrade the chart from a local `.tgz` file or cloned repository: + +1. If using a downloaded `.tgz` file, ensure you have the new version locally. If using a cloned repository, pull the latest changes: +```bash + git pull origin main + helm dependency build charts/block-node-server +``` + +2. Save your current configuration: ```bash helm get values "${RELEASE}" > user-values.yaml ``` -4. Upgrade the release: +3. Upgrade the release from local chart: ```bash + # If using a .tgz file: helm upgrade "${RELEASE}" block-node-server-$VERSION.tgz -f user-values.yaml + + # If using cloned repository: + helm upgrade "${RELEASE}" charts/block-node-server -f user-values.yaml ``` + + ## Uninstall To uninstall the chart: From 9cc805edd29d84764ab5efd45ce70dc2962b188a Mon Sep 17 00:00:00 2001 From: Pranali Deshmukh Date: Tue, 18 Nov 2025 15:21:35 +0530 Subject: [PATCH 4/4] docs(README): Fix StyleCheck CI Gate check. Signed-off-by: Pranali Deshmukh --- charts/block-node-server/README.md | 53 +++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/charts/block-node-server/README.md b/charts/block-node-server/README.md index 6511b4b88..37f1e6bc4 100644 --- a/charts/block-node-server/README.md +++ b/charts/block-node-server/README.md @@ -12,6 +12,7 @@ Installs the Hiero Block Node on a Kubernetes cluster. For development and test environments, it is recommended to use [minikube](https://minikube.sigs.k8s.io/docs/start/). ### Basic minikube setup + ```bash minikube delete && minikube start --kubernetes-version=v1.29.0 ``` @@ -19,6 +20,7 @@ minikube delete && minikube start --kubernetes-version=v1.29.0 ### minikube setup with monitoring support If you want to deploy the `kube-prometheus-stack` for metrics visualization: + ```bash minikube delete && minikube start \ --kubernetes-version=v1.29.0 \ @@ -33,10 +35,12 @@ minikube delete && minikube start \ ## Configuration Set environment variables that will be used throughout this guide. Replace the values with appropriate values for your environment: + ```bash export RELEASE="bn-release" # bn-release is short for block-node-release export VERSION="0.24.0-SNAPSHOT" ``` + ## Installation Options ### Option 1: Template (without installing) @@ -46,6 +50,7 @@ To generate Kubernetes manifest files without installing the chart: 1. Clone this repository 2. Navigate to the `/charts` folder 3. Run the following command: + ```bash helm template --name-template bn-release block-node-server/ --dry-run --output-dir out ``` @@ -53,16 +58,19 @@ helm template --name-template bn-release block-node-server/ --dry-run --output-d ### Option 2: Install using a published chart #### Pull the packaged chart + ```bash helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" ``` #### Install with default values + ```bash helm install "${RELEASE}" block-node-server-$VERSION.tgz ``` #### Install with custom values + ```bash helm install "${RELEASE}" block-node-server-$VERSION.tgz -f ``` @@ -72,11 +80,13 @@ helm install "${RELEASE}" block-node-server-$VERSION.tgz -f ``` @@ -149,18 +159,21 @@ Follow the `NOTES` instructions after installing the chart to perform `port-forw To upgrade the chart to a new version from the OCI registry: 1. Set the new version: + ```bash - export VERSION="" +export VERSION="" ``` 2. Save your current configuration: + ```bash - helm get values "${RELEASE}" > user-values.yaml +helm get values "${RELEASE}" > user-values.yaml ``` 3. Upgrade the release directly from OCI registry: + ```bash - helm upgrade "${RELEASE}" oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" -f user-values.yaml +helm upgrade "${RELEASE}" oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" -f user-values.yaml ``` ### Upgrade using a local chart @@ -168,27 +181,27 @@ To upgrade the chart to a new version from the OCI registry: To upgrade the chart from a local `.tgz` file or cloned repository: 1. If using a downloaded `.tgz` file, ensure you have the new version locally. If using a cloned repository, pull the latest changes: + ```bash - git pull origin main - helm dependency build charts/block-node-server +git pull origin main +helm dependency build charts/block-node-server ``` 2. Save your current configuration: + ```bash - helm get values "${RELEASE}" > user-values.yaml +helm get values "${RELEASE}" > user-values.yaml ``` 3. Upgrade the release from local chart: + ```bash - # If using a .tgz file: - helm upgrade "${RELEASE}" block-node-server-$VERSION.tgz -f user-values.yaml - - # If using cloned repository: - helm upgrade "${RELEASE}" charts/block-node-server -f user-values.yaml +# If using a .tgz file: +helm upgrade "${RELEASE}" block-node-server-$VERSION.tgz -f user-values.yaml +# If using cloned repository: +helm upgrade "${RELEASE}" charts/block-node-server -f user-values.yaml ``` - - ## Uninstall To uninstall the chart: @@ -196,8 +209,8 @@ To uninstall the chart: ```bash helm uninstall "${RELEASE}" ``` -This will remove all Kubernetes resources associated with the release. +This will remove all Kubernetes resources associated with the release. ## Troubleshooting @@ -206,11 +219,13 @@ This section covers common issues you may encounter when working with the Hiero ### Chart Dependencies Missing **When running:** + ```bash helm template --name-template bn-release block-node-server/ --dry-run --output-dir out ``` **Error:** + ``` Error: An error occurred while checking for chart dependencies. You may need to run `helm dependency build` to fetch missing dependencies: found in Chart.yaml, but missing in charts/ directory: kube-prometheus-stack, loki, promtail Error: Chart.yaml file is missing @@ -219,6 +234,7 @@ Error: Chart.yaml file is missing **Solution:** Before running the template command, build the chart dependencies: + ```bash helm dependency build charts/block-node-server ``` @@ -230,16 +246,19 @@ This will download all required chart dependencies to the `charts/` directory. ### Chart Version Not Found in Registry **When running:** + ```bash helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart --version "${VERSION}" ``` **Error:** + ``` Error: failed to perform "fetchReference" on source: ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart:0.22.8-SNAPSHOT: not found ``` or + ``` Error: failed to perform "fetchReference" on source: ghcr.io/hiero-ledger/hiero-block-node/block-node-helm-chart:0.21.2: not found ``` @@ -251,13 +270,15 @@ The specified chart version or name does not exist in the registry, or the OCI r **Solution:** 1. Use the correct OCI registry path: + ```bash - helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" +helm pull oci://ghcr.io/hiero-ledger/hiero-block-node/block-node-server --version "${VERSION}" ``` 2. Verify the chart version exists by checking the [releases page](https://github.com/hiero-ledger/hiero-block-node/releases) 3. Confirm your `VERSION` environment variable is set to a valid release: + ```bash - echo $VERSION +echo $VERSION ```