From 7e53c1beec5725630f4a9c4c211d41d6196b06cc Mon Sep 17 00:00:00 2001 From: Aryeh Harris Date: Fri, 26 Mar 2021 17:56:55 -0400 Subject: [PATCH] Mkchain readme updates (#174) * mkchain doc updates plus some other small doc updates * Add table of contents in each README * Clearer text regarding disk size * Update readme as per PR review comments --- DEVELOPMENT.md | 13 ++++- README.md | 128 +++++++++++++++++++++++++-------------------- mkchain/README.md | 30 +++++++---- rpc-auth/README.md | 5 ++ 4 files changed, 108 insertions(+), 68 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 4363681f5..8013f63c2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,3 +1,12 @@ +- [Prerequisites](#prerequisites) +- [Using devspace](#using-devspace) + - [Notes](#notes) +- [Helm Charts](#helm-charts) + - [Creating Charts](#creating-charts) + - [Notes](#notes-1) +- [Creating Docker Images](#creating-docker-images) +- [Releases](#releases) + # Helm Chart Development ## Prerequisites @@ -32,7 +41,7 @@ - Run `devspace dev --var CHAIN_NAME=$CHAIN_NAME` (you can leave out the `--var` flag if you used `export CHAIN_NAME=my-chain`). -- You may add the `rpc-auth` devspace [profile](https://devspace.sh/cli/docs/configuration/profiles/basics) by using the `-p rpc-auth` flag in the `devspace dev` command. This tells devspace deploy `rpc-auth` and to redeploy it if its files change. You can also pass another `--var` flag for `rpc-auth` like so: `--var FLASK_ENV=`. Devpsace defaults it to `development`. Running with `development` will allow the the python server to hot reload on file changes. Devspace does not need to restart the pod on file changes as the python server file is [synced](https://devspace.sh/cli/docs/configuration/development/file-synchronization) to the container. +- You may add the `rpc-auth` devspace [profile](https://devspace.sh/cli/docs/configuration/profiles/basics) by using the `-p rpc-auth` flag in the `devspace dev` command. This tells devspace deploy `rpc-auth` and to redeploy it if its files change. You can also pass another `--var` flag for `rpc-auth` like so: `--var FLASK_ENV=`. Devpsace defaults it to `development`. Running with `development` will allow the python server to hot reload on file changes. Devspace does not need to restart the pod on file changes as the python server file is [synced](https://devspace.sh/cli/docs/configuration/development/file-synchronization) to the container. Devspace will now do a few things: @@ -74,7 +83,7 @@ If you use `helm install|upgrade` (instead of devspace) for local charts, make s # Creating Docker Images -Currently, we are placing all docker images in the the root level directory. The name of the folder is treated as the name of the image being created. +Currently, we are placing all docker images in the root level directory. The name of the folder is treated as the name of the image being created. Here is an example of the flow for creating new images and how they are published to Docker Hub via the CI: diff --git a/README.md b/README.md index 6ef60c945..b1f122f7c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,26 @@ +- [Prerequisites](#prerequisites) +- [Installing prerequisites](#installing-prerequisites) + - [Mac](#mac) + - [Arch Linux](#arch-linux) + - [Other Operating Systems](#other-operating-systems) +- [Configuring Minikube](#configuring-minikube) + - [Mac](#mac-1) + - [Other Operating Systems](#other-operating-systems-1) +- [Starting Minikube](#starting-minikube) +- [Tezos k8s Helm Chart](#tezos-k8s-helm-chart) +- [Joining Mainnet](#joining-mainnet) + - [Spinning Up a Regular Peer Node](#spinning-up-a-regular-peer-node) +- [Creating a Private Blockchain](#creating-a-private-blockchain) + - [Zerotier](#zerotier) + - [mkchain](#mkchain) + - [Start your private chain](#start-your-private-chain) + - [Adding nodes within the cluster](#adding-nodes-within-the-cluster) + - [Adding external nodes to the cluster](#adding-external-nodes-to-the-cluster) + - [On the computer of the joining node](#on-the-computer-of-the-joining-node) + - [RPC Authentication](#rpc-authentication) +- [Notes](#notes) +- [Development](#development) + # Tezos k8s This README walks you through: @@ -107,17 +130,31 @@ helm repo add tqtezos https://tqtezos.github.io/tezos-helm-charts # Joining Mainnet +## Spinning Up a Regular Peer Node + Connecting to a public net is easy! -Run: +(See [here](https://tezos.gitlab.io/user/history_modes.html) for info on snapshots and node history modes) + +If you'd like to spin up a node that runs with history mode rolling, all you need to do is run: ```shell helm install tezos-mainnet tqtezos/tezos-chain \ --namespace tqtezos --create-namespace ``` -- This creates a Helm [release](https://helm.sh/docs/intro/using_helm/#three-big-concepts) named tezos-mainnet in your k8s cluster. -- k8s will spin up one regular (i.e. non-baking node) which will download and import a mainnet [rolling snapshot](https://tezos.gitlab.io/user/history_modes.html). This will take a few minutes. +If you'd like to spin up a node with history mode full, run: + +```shell +helm install tezos-mainnet tqtezos/tezos-chain \ +--namespace tqtezos --create-namespace \ +--set nodes.regular.tezos-node-0.config.shell.history_mode=full +``` + +Running either of these commands results in: + +- Creating a Helm [release](https://helm.sh/docs/intro/using_helm/#three-big-concepts) named tezos-mainnet in your k8s cluster. +- k8s will spin up one regular (i.e. non-baking node) which will download and import a mainnet snapshot. This will take a few minutes. - Once the snapshot step is done, your node will be bootstrapped and syncing with mainnet! You can find your node in the tqtezos namespace with some status information using `kubectl`. @@ -138,63 +175,31 @@ You can view logs for your node using the following command: kubectl -n tqtezos logs -l appType=tezos -c tezos-node -f --prefix ``` -## Spinning Up a Baker - -In the previous sections you spun one mainnet regular peer node. Here is how you add an additional mainnet baker node. - -- Create a yaml file named `baker.yaml`. -- In this file you should copy and paste the yaml below. - - ```yaml - accounts: - tqtezos_baker_0: - key: edsk... - type: secret - - nodes: - baking: - tezos-baking-node-0: - bake_using_account: tqtezos_baker_0 - config: - shell: - history_mode: rolling - ``` - -- Notice the `accounts.tqezos_baker_0.key` field above. You should replace that value with your own secret key you want to bake with. The key should begin with prefix `edsk`. -- If you'd like, in the `nodes` section of the yaml, you can replace the `history_mode` with either `archive` or `full`. If you use `full`, a `full` snapshot will be downloaded and imported to the node. +IMPORTANT: -- Run: +- Although spinning up a mainnet baker is possible, we do not recommend running a mainnet baker at this point in time. Secret keys should be handled via an HSM that should remain online, and the keys should be passed through a k8s secret to k8s. This functionality still needs to be implemented. +- You should be aware of `minikube` VM's allocated memory. Especially if you use `minikube` for other applications. It may run out of virtual memory say due to having large docker images. Being that snapshots are relatively large and increasing in size as the blockchain grows, when downloading one, you can potentially run out of disk space. The snapshot is deleted after import. According to `minikube start --help`, default allocated space is 20000mb. You can modify this via the `--disk-size` flag. To view the memory usage of the VM, you can ssh into `minikube`. ```shell - helm upgrade tezos-mainnet tqtezos/tezos-chain \ - --namespace tqtezos \ - --values + ❯ minikube ssh + _ _ + _ _ ( ) ( ) + ___ ___ (_) ___ (_)| |/') _ _ | |_ __ + /' _ ` _ `\| |/' _ `\| || , < ( ) ( )| '_`\ /'__`\ + | ( ) ( ) || || ( ) || || |\`\ | (_) || |_) )( ___/ + (_) (_) (_)(_)(_) (_)(_)(_) (_)`\___/'(_,__/'`\____) + + $ df -h + Filesystem Size Used Avail Use% Mounted on + tmpfs 5.2G 593M 4.6G 12% / + devtmpfs 2.8G 0 2.8G 0% /dev + tmpfs 2.9G 0 2.9G 0% /dev/shm + tmpfs 2.9G 50M 2.8G 2% /run + tmpfs 2.9G 0 2.9G 0% /sys/fs/cgroup + tmpfs 2.9G 8.0K 2.9G 1% /tmp + /dev/vda1 17G 12G 4.2G 74% /mnt/vda1 ``` -After the snapshot has been downloaded and imported you should have a baker up and running that is syncing with mainnet! Run the the `kubectl` commands mentioned in the above section to view status and logs of your node. - -IMPORTANT: Especially if you use `minikube` for other applications or have a lot of docker images, you should be aware of `minikube's` virtual machine's allocated memory. Being that snapshots are relatively large and increasing in size as the blockchain grows, you can potentially run out of disk space. According to `minikube start --help`, default allocated space is 20000mb. You can modify this via the `--disk-size` flag. To view the memory usage of the VM, you can ssh into `minikube`. - -```shell -❯ minikube ssh - _ _ - _ _ ( ) ( ) - ___ ___ (_) ___ (_)| |/') _ _ | |_ __ -/' _ ` _ `\| |/' _ `\| || , < ( ) ( )| '_`\ /'__`\ -| ( ) ( ) || || ( ) || || |\`\ | (_) || |_) )( ___/ -(_) (_) (_)(_)(_) (_)(_)(_) (_)`\___/'(_,__/'`\____) - -$ df -h -Filesystem Size Used Avail Use% Mounted on -tmpfs 5.2G 593M 4.6G 12% / -devtmpfs 2.8G 0 2.8G 0% /dev -tmpfs 2.9G 0 2.9G 0% /dev/shm -tmpfs 2.9G 50M 2.8G 2% /run -tmpfs 2.9G 0 2.9G 0% /sys/fs/cgroup -tmpfs 2.9G 8.0K 2.9G 1% /tmp -/dev/vda1 17G 12G 4.2G 74% /mnt/vda1 -``` - # Creating a Private Blockchain ## Zerotier @@ -241,11 +246,22 @@ export PYTHONUNBUFFERED=x ## Start your private chain -Run the following commands to create the Helm values, and create a Helm release that will start your chain. +Run `mkchain` to create your Helm values ```shell mkchain $CHAIN_NAME --zerotier-network $ZT_NET --zerotier-token $ZT_TOKEN +``` + +This will create two files: + +1. `./${CHAIN_NAME}_values.yaml` +2. `./${CHAIN_NAME}_invite_values.yaml` +The former is what you will use to create your chain, and the latter is for invitees to join your chain. + +Create a Helm release that will start your chain: + +```shell helm install $CHAIN_NAME tqtezos/tezos-chain \ --values ./${CHAIN_NAME}_values.yaml \ --namespace tqtezos --create-namespace diff --git a/mkchain/README.md b/mkchain/README.md index 1c5e0e0c2..73cc0acc8 100644 --- a/mkchain/README.md +++ b/mkchain/README.md @@ -1,3 +1,8 @@ +- [Install mkchain](#install-mkchain) +- [Generate Helm Values](#generate-helm-values) + - [mkchain parameters](#mkchain-parameters) +- [Create Tezos Chain](#create-tezos-chain) + # mkchain Helper program to generate values for the Tezos chain Helm chart @@ -43,7 +48,9 @@ To generate these values run: mkchain $CHAIN_NAME ``` -This command will create two yaml files in your current working directory. `<$CHAIN_NAME>_values.yaml` and `<$CHAIN_NAME>_invite_values.yaml`. +This command will create a yaml file in your current working directory: `<$CHAIN_NAME>_values.yaml` + +If you configure your chain to run over a Zerotier VPN, mkchain will create an additional file for invitees to join your network: `<$CHAIN_NAME>_invite_values.yaml`. ### mkchain parameters @@ -53,15 +60,18 @@ You can explicitly specify some values by: - directly modifying the values yaml file generated by `mkchain` - passing arguments to [helm install](https://helm.sh/docs/helm/helm_install/) or [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) commands using the `--set` flag, which will selectively override the current yaml values -| YAML Key | mkchain argument | Description | Default | -| -------------------------------- | ------------------ | --------------------------------------------------------------------------- | ---------------------- | -| bootstrap_peer | --bootstrap-peer | Peer ip to connect to | | -| images.tezos | --docker-image | Version of the Tezos docker image | tezos/tezos:v8-release | -| number_of_nodes | --number-of-nodes | Number of non-baking nodes in the cluster | 1 | -| number_of_bakers | --number-of-bakers | Number of baking nodes in the cluster | 1 | -| rpc_auth | --rpc-auth | Whether or not an [RPC auth](../rpc-auth/README.md) backend will be spun up | False | -| zerotier_config.zerotier_network | --zerotier-network | Zerotier network id for external chain access | | -| zerotier_config.zerotier_token | --zerotier-token | Zerotier token for external chain access | | +| YAML Key | mkchain argument | Description | Default | +| -------------------------------- | ------------------------ | --------------------------------------------------------------------------- | ---------------------- | +| | -h | mkchain help message | | +| | -v | mkchain version | | +| | --number-of-bakers | Number of baking nodes in the cluster | 1 | +| | --number-of-nodes | Number of non-baking nodes in the cluster | 0 | +| bootstrap_peers | --bootstrap-peers | Peer ips to connect to | [] | +| expected_proof_of_work | --expected-proof-of-work | Node identity generation difficulty | 0 | +| images.tezos | --tezos-docker-image | Version of the Tezos docker image to run | tezos/tezos:v8-release | +| rpc_auth | --rpc-auth | Whether or not an [RPC auth](../rpc-auth/README.md) backend will be spun up | False | +| zerotier_config.zerotier_network | --zerotier-network | Zerotier network id for external chain access | | +| zerotier_config.zerotier_token | --zerotier-token | Zerotier token for external chain access | | ## Create Tezos Chain diff --git a/rpc-auth/README.md b/rpc-auth/README.md index 04b317ad5..b14b8862c 100644 --- a/rpc-auth/README.md +++ b/rpc-auth/README.md @@ -1,3 +1,8 @@ +- [Deploy RPC Auth Backend](#deploy-rpc-auth-backend) +- [Client Authentication](#client-authentication) + - [Prerequisites](#prerequisites) +- [Authentication flow](#authentication-flow) + # Tezos RPC Authentication `rpc-auth` provides a mechanism where a user authenticates themselves and will receive a secret url that they then use to make RPC calls.