EOSIO Helm Tutorial

Overview

This tutorial demonstrates how to install and use Helm charts for local EOSIO deployment using Kubernetes and Docker Desktop. The tutorial is divided into three parts: Installation, Basic Usage, and EOSIO Helm Repositories. The concepts will be illustrated within the context of a single EOSIO node being deployed via Kubernetes and hosted within an EOSIO docker image.

Before You Begin

Part 1: Installation

Perform the following steps to install EOSIO Helm Charts for local deployment:

  1. Clone the EOSIO Help Charts github repository:
git clone https://github.com/EOSIO/eosio.helm.git
Cloning into 'eosio.helm'...
remote: Enumerating objects: 204, done.
remote: Counting objects: 100% (204/204), done.
remote: Compressing objects: 100% (88/88), done.
remote: Total 204 (delta 109), reused 203 (delta 109), pack-reused 0
Receiving objects: 100% (204/204), 44.24 KiB | 1.11 MiB/s, done.
Resolving deltas: 100% (109/109), done.
  1. Navigate to the project directory eosio.helm:
cd eosio.helm
ls -l
-rw-r--r--   1 username  groupname   839 Apr  7 15:22 artifacthub-repo.yml
drwxr-xr-x  10 username  groupname   320 Apr  7 15:23 eosio
drwxr-xr-x   5 username  groupname   160 Apr  7 15:22 eosio-common
drwxr-xr-x   8 username  groupname   256 Apr  7 15:23 eosio-nodeos
-rw-r--r--   1 username  groupname  2767 Apr  7 15:22 CONTRIBUTING.md
-rw-r--r--   1 username  groupname  5614 Apr  7 15:22 IMPORTANT.md
-rw-r--r--   1 username  groupname  1119 Apr  7 15:22 LICENSE
-rw-r--r--   1 username  groupname  3330 Apr  7 15:22 README.md
  1. Perform helm dependency update to cache the subchart metadata:
./eosio/scripts/helm-dependency-update.sh
~/Work/eosio.helm/eosio-common ~/Work/eosio.helm
~/Work/eosio.helm
~/Work/eosio.helm/eosio-nodeos ~/Work/eosio.helm
Saving 1 charts
Deleting outdated charts
~/Work/eosio.helm
~/Work/eosio.helm/eosio ~/Work/eosio.helm
Saving 1 charts
Deleting outdated charts
~/Work/eosio.helm
  1. Configure Kubernetes context to use local namespace:
kubectl config set-context --current --namespace=local
Context "docker-desktop" modified.
  1. Install the EOSIO Helm chart itself:
helm upgrade --install eosio eosio -f eosio/local.yaml -f eosio/nodeos_config.yaml
Release "eosio" does not exist. Installing it now.
NAME: eosio
LAST DEPLOYED: Wed Apr 07 15:24:01 2021
NAMESPACE: local
STATUS: deployed
REVISION: 1
TEST SUITE: None

Note that two values files are specified in the helm upgrade command. The first one, eosio/local.yaml, is the Docker Desktop configuration. The second one, eosio/nodeos_config.yaml, contains the default nodeos configuration options (note that the EOSIO node is set up as a single producing node).

Part 2: Basic Usage

Perform any of the following steps to use the EOSIO Helm chart:

  • Now that the EOSIO node has been deployed, you can check its status by listing the current Kubernetes components:
kubectl get pods
NAME                   READY    STATUS    RESTARTS   AGE
eosio-local-nodeos-0   0/1      Running   0          7s

Note that the node is still initializing. A few seconds later it is fully deployed:

kubectl get pods
NAME                   READY    STATUS    RESTARTS   AGE
eosio-local-nodeos-0   1/1      Running   0          17s
  • You can also query the logs generated by the running EOSIO node instance:
kubectl logs eosio-local-nodeos-0
...
info  2021-04-07T15:24:01.391 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/get_table_by_scope
info  2021-04-07T15:24:01.391 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/get_table_rows
info  2021-04-07T15:24:01.391 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/get_transaction_id
info  2021-04-07T15:24:01.391 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/push_block
info  2021-04-07T15:24:01.391 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/push_transaction
info  2021-04-07T15:24:01.391 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/push_transactions
info  2021-04-07T15:24:01.392 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/send_transaction
info  2021-04-07T15:24:01.392 nodeos    http_plugin.cpp:983        add_handler      ] add api url: /v1/chain/
info  2021-04-07T15:24:01.392 nodeos    producer_plugin.cpp:932    plugin_startup   ] producer plugin:  plugin_startup() begin
info  2021-04-07T15:24:01.392 nodeos    producer_plugin.cpp:957    plugin_startup   ] Launching block production for 1 producers at 2021-04-07T15:17:23.392.
info  2021-04-07T15:24:01.392 nodeos    producer_plugin.cpp:968    plugin_startup   ] producer plugin:  plugin_startup() end
...
  • You can also list all deployed Helm chart releases for the default namespace:
helm list
NAME    NAMESPACE        REVISION        UPDATED                                 STATUS      CHART         APP VERSION
eosio   local            1               2021-04-07 15:24:01.58271 -0500 EST     deployed    eosio-0.1.0   0.1.0

Note that the only chart release deployed is eosio within the local namespace and launched using the chart eosio-0.1.0.

  • To cleanup a deployed release, just perform helm uninstall by specifying the release name eosio:
helm uninstall eosio
release "eosio" uninstalled

This might take a few seconds to complete. To check the status you can list the Kubernetes components again:

kubectl get pods
NAME                   READY    STATUS        RESTARTS   AGE
eosio-local-nodeos-0   1/1      Terminating   0          55s

Note that for a full cleanup you also need to remove the state generated by the EOSIO node. To that end, first list all Kubernetes persistent artefacts:

kubectl get persistentvolumeclaims
NAME                       STATUS    VOLUME                                      CAPACITY   ACCESS MODES    STORAGECLASS    AGE
pvc-eosio-local-nodeos-0   Bound     pvc-dcb06ae4-0bed-41f5-ae55-51beb204c97f    100Gi      RWO             hostpath        71s

Then, delete the actual artefact by specifying the persistent volume claim (pcv) by name pvc-eosio-local-nodeos-0:

kubectl delete persistentvolumeclaims pvc-eosio-local-nodeos-0
persistentvolumeclaim "pvc-eosio-local-nodeos-0" deleted
Note

If you want to retain the EOSIO node state in between launches and cleanups, then do not perform the last step since it will destroy the state stored within the EOSIO persistent volume.

Part 3: EOSIO Helm Repos

You can create, add, and remove chart repositories locally or to a remote endpoint. A helm repository is where you can collect and share charts remotely, similar to the Linux DPKG, APT, or RPM package managers, but for Kubernetes packages.

Perform any of the following steps to manage EOSIO Helm repositories:

  • To list all Helm repositories (local or remote):
helm repo list
Error: no repositories to show
  • To add the eosio repository to the list:
helm repo add eosio [URL]
"eosio" has been added to your repositories
Note

Note that you can specify a remote URL endpoint as well if you have previously configured it to host a Helm repository. For more information on Helm repositories, refer to the Helm Chart Repository Guide.

You can check that the eosio repository was indeed added to the list:

helm repo list
NAME    URL
eosio   localhost:8080
  • To pull a specific chart from the repository:
helm pull eosio/eosio --untar
ls -l
total 0
drwxr-xr-x 10 username groupname 320 Apr 07 15:26 eosio

The above command will retrieve the eosio chart from the eosio repository, unpackage it, and place it under the eosio folder (chart name by default).

Now that the chart has been retrieved, you can navigate to the eosio chart folder, install it following the steps from Part 1: Installation, and use it following the steps from Part 2: Basic Usage:

cd eosio

Summary

This tutorial showcased how to install an EOSIO Helm chart. It also explained how to use it within the context of a deployed single EOSIO node. Finally, it demonstrated how to create an EOSIO Helm repository for sharing EOSIO Helm charts.