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
- Get familiar with Docker Desktop.
- Become acquainted with Kubernetes.
- Familiarize with Helm, the Kubernetes package manager.
- Read the EOSIO Helm Charts tool guide.
-
Install the following software on your local system:
- Install Docker Desktop: Docker Official: Desktop
- Install Kubernetes command-line tool (kubectl): Kubernetes Official: Install and Set Up Kubectl
- Install Helm: Helm Official: Installing Helm
Part 1: Installation
Perform the following steps to install EOSIO Helm Charts for local deployment:
- 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.
- 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
- 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
- Configure Kubernetes context to use
local
namespace:
kubectl config set-context --current --namespace=local
Context "docker-desktop" modified.
- 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 nameeosio
:
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
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
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.