Deploy with Solo Provisioner (Recommended)
Overview
This guide walks you through deploying a Hiero Block Node on a Google Cloud Platform (GCP) virtual machine using Solo Provisioner (formerly Solo Weaver). Solo Provisioner handles VM provisioning, Kubernetes setup, and Block Node Helm chart installation in a single flow.
GCP is used as the worked example. The same flow applies on other cloud providers — substitute the equivalent VM-creation and SSH steps for your provider.
Prerequisites
Before you begin, ensure you have:
Access to a cloud provider account (such as Google Cloud, AWS, or Azure) with permissions to create and manage VM instances.
The
gcloudCLI installed and authenticated (if using Google Cloud).
Step-by-Step Guide
Step 1: Create a Google Cloud VM
Open the Google Cloud Console.
In the project switcher at the top of the page, confirm the project you want to use is selected. To create a new project, click the project switcher and choose New project.
From the Welcome page's Quick access panel (or the navigation menu, ☰), open Compute Engine, then click Create instance.
Select a machine type appropriate for your Block Node profile. Solo Provisioner's preflight check measures physical CPU cores (not vCPUs), and the
localprofile requires a minimum of 3 physical cores. The recommendations below account for that:For a
localprofile (testing or learning): Choosee2-standard-8or larger (4 physical cores, 8 vCPUs, 32 GB RAM).For
previewnetortestnet: Select a machine with at least ~16 vCPUs (for example,e2-standard-16) and adequate RAM (≥ 32 GB) for non-mainnet block volume.For
mainnet(Tier 1): Solo Provisioner on a single GCP VM is generally not the right deployment shape for production Tier 1. See Block Node Hardware Specifications for the canonical hardware target, and follow the Bare Metal Single Node Kubernetes Deployment guide as the recommended path.
Solo Provisioner GCP VM configuration
Set the region and zone (defaults are fine unless you have a preference).
For the boot disk, select Debian GNU/Linux 12 (bookworm), which Solo Provisioner is tested against. Other current Debian and Ubuntu LTS releases are also supported. Avoid relying on the cloud provider's default image, since the default may change over time.
Leave other instance settings at defaults for a standard deployment.
Click Create to launch the VM.
Wait until the instance status is Running before proceeding.
Step 2: Install Solo Provisioner
The install script in this section downloads the correct Solo Provisioner binary for your VM's architecture automatically. You don't need to download anything manually. For air-gapped environments or other advanced cases, see Manual install (advanced) at the end of this section.
All
solo-provisionercommands except-h(help) and-v(version) must be run withsudo. Running other commands withoutsudoproduces permission errors against the state files under/opt/solo/weaver/.
In the Google Cloud Console, open your VM's details page. You can also reach the SSH menu from the Compute Engine > VM instances list.
Select the down arrow next to SSH, then choose View gcloud command.
Copy the suggested
gcloud compute sshcommand displayed.On your local machine, run the command in a terminal. It will look similar to:
Expected output:
On first connection,
gcloudmay generate an SSH key pair and prompt for a passphrase. On subsequent connections, key generation is skipped. Either way, the session ends at a Debian shell prompt similar to:
Install the tool using the official script:
Expected output: the script fetches the latest release, verifies the checksum, runs the binary's
installsubcommand (which creates theweaverservice account), and prints the help summary. The load-bearing lines confirming success look like:The script then prints the binary's help summary (the same output as
solo-provisioner -h). The exactLatest releasevalue, asset IDs, and timestamps will reflect whatever's current when you run.
Verify that Solo Provisioner is installed correctly by running the version check:
Expected output:
The exact
versionvalue will match whichever release the install script downloaded.
Manual install (advanced)
If you prefer not to use the install script — for example, in an air-gapped environment — download the binary directly from the official Solo Provisioner releases page:
solo-provisioner-linux-amd64for x86_64 VMssolo-provisioner-linux-arm64for ARM-based VMs
The GitHub Releases UI labels these as solo-provisioner (linux/amd64) and solo-provisioner (linux/arm64), but the underlying filenames use the dash-separated form.
Transfer the binary to your VM, then make it executable and run its install subcommand:
Then continue from the version-check step above.
Step 3: Install the Block Node
The block node install command performs the full install in one pass: it creates the weaver service account if it doesn't already exist, runs system preflight checks, installs and configures Kubernetes components, installs MetalLB for load balancing, and deploys the Block Node Helm chart into the cluster. The whole flow takes several minutes.
Run the install command with
sudoand the desired profile (local,previewnet,testnet,mainnet, orperfnet):Replace
<profile>with one of:local,testnet,previewnet,mainnet, orperfnet.By default the install runs interactively and prompts for namespace, Helm release name, chart version, retention thresholds, storage paths, and plugin preset. Pressing Enter at each prompt accepts the default value shown. The defaults are appropriate for an initial deployment on a single VM:
To skip the prompts and accept all defaults, append
--non-interactive:
On a successful run you will see a Completed successfully summary along with the paths to the setup report and provisioner log under /opt/solo/weaver/logs/.
Additional Options
Custom Helm values:
--values <path-to-values.yaml>Custom configuration:
--config <path-to-config.yaml>Example
config.yaml:
The chart version shown reflects the default bundled with the current Solo Provisioner release. Check the hiero-block-node releases page to confirm the latest available version before deploying.
The legacy
block node setupsubcommand is deprecated. Useblock node installfor all Solo Provisioner v0.3.0+ deployments. See Solo Provisioner v0.3.0 release notes.
Step 4: Verify the Block Node Deployment
After completing the setup, confirm that your Block Node is deployed and running by checking the Kubernetes cluster:
Verify with
kubectl(recommended)From the VM (where Solo Provisioner configured Kubernetes access), list all pods:
Look for Block Node pods. Ensure they show
Runningstatus and all containers are ready (e.g.,1/1or2/2).
Verify with K9s (optional):
If you prefer a text-based Kubernetes dashboard:
Ensure Install
k9sis available on your VM or on a machine that can reach the cluster.To Inspect pods, namespaces, and logs. Run:
To list pods across all namespaces, press 0:

To list instances in all namespaces, press o:

Confirm the Block Node
StatefulSet/Podsare healthy.
If the pods are running and healthy, your Block Node is successfully installed and running on the Google Cloud VM.
Step 5: Test Block Node Accessibility with grpcurl
Install grpcurl:
Download and extract the latest protobuf files from the official release:
Determine the protobuf version directory. The previous
wgetstep downloads an archive namedblock-node-protobuf-<VERSION>.tgzand extracts it into ablock-node-protobuf-<VERSION>directory. Use the same<VERSION>string in the next command. Inspect the working directory if you are unsure:Call the
serverStatusendpoint to verify the node is accessible:<BLOCK_NODE_IP>depends on where you are runninggrpcurl:From inside the VM (most common, since
gcloud compute sshputs you on the VM): use the VM's internal IP (hostname -Ireturns it) or the Kubernetes service IP fromkubectl get svc -n block-node.localhostdoes not work because the Block Node is published on the cluster service network, not the host loopback.From outside the VM: use the VM's external IP from the GCP VM details page. By default, GCP firewall rules block all inbound traffic except SSH (port 22). To reach the Block Node from outside, add a firewall rule allowing TCP on the gRPC port (default
40840) to the VM's network tag.
<GRPC_PORT>is the gRPC service port exposed by your Block Node. The default is40840(seeserver.portin configuration.md).
Review the output for status information confirming the node is running and serving requests.
Expected output:
Note: The value
18446744073709551615means the node has not stored any blocks yet. After the node finishes syncing, these fields will show real block numbers.
Step 6: Deprovisioning and Shutdown
If you need to permanently remove a Block Node deployment (for decommissioning, upgrades, or migration):
Test environments: Delete the VM from the Compute Engine page in Google Cloud Console to remove all associated resources.
Production nodes: Follow organizational and project-specific procedures for graceful shutdown, backup, and ongoing monitoring to avoid service interruption or data loss.
Troubleshooting
See below for common errors, causes, and solutions during Block Node setup:
Error: “Profile not set”
Cause: The
Block Node installcommand was run without specifying a profile.Fix: Re-run with a valid profile, for example:
Error: “solo-provisioner must be run with superuser privileges”
Cause: The
block node install -pcommand was run withoutsudo.Fix: Add
sudobefore your command:
Error: “CPU does not meet Block Node (Local) requirements (minimum 3 cores)” or “Insufficient memory”
Cause: The VM machine type does not meet the minimum physical CPU core count for the selected profile. Solo Provisioner counts physical cores, not vCPUs, so
e2-standard-2(1 core) ande2-standard-4(2 cores) both fail thelocalprofile preflight.Fix:
Delete your current VM.
Create a new VM with at least the minimum core count:
e2-standard-8(4 cores) for thelocalprofile,e2-standard-16or larger fortestnetandpreviewnet, and follow the Block Node Hardware Specifications formainnet.Repeat the installation steps.
Last updated