From dc8c55a8a2c08a4c53e058ae57009cfe734245f3 Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Mon, 13 Jun 2022 11:33:00 -0700 Subject: [PATCH] docusaurus initial (#444) * docusaurus initial * docusaurus progress * incr * values to doc * automate * remove generated doc --- .github/workflows/docusaurus.yml | 3 +- README.md | 86 ------------ charts/tezos/values.yaml | 212 ++++++++++++++++------------- docs/.gitignore | 4 + docs/00-helm-chart.md | 3 + docs/04-other-helm-charts.md | 9 ++ docs/Prerequisites.md | 86 ++++++++++++ docs/Private-Node.md | 61 +++++++++ docs/Private_Chain.md | 224 +++++++++++++++++++++++++++++++ docs/README.md | 19 +++ docs/Tezos-RPC-Service.md | 41 ++++++ docs/docusaurus.config.js | 3 +- docs/index.md | 34 ++++- docs/package-lock.json | 2 +- docs/package.json | 2 +- docs/sidebars.js | 37 ++--- docs/values_to_doc.sh | 30 +++++ 17 files changed, 652 insertions(+), 204 deletions(-) create mode 100644 docs/00-helm-chart.md create mode 100644 docs/04-other-helm-charts.md create mode 100644 docs/Prerequisites.md create mode 100644 docs/Private-Node.md create mode 100644 docs/Private_Chain.md create mode 100644 docs/README.md create mode 100644 docs/Tezos-RPC-Service.md create mode 100644 docs/values_to_doc.sh diff --git a/.github/workflows/docusaurus.yml b/.github/workflows/docusaurus.yml index 971e8f9fb..037a864bd 100644 --- a/.github/workflows/docusaurus.yml +++ b/.github/workflows/docusaurus.yml @@ -26,6 +26,7 @@ jobs: - name: Build Docusaurus website run: | cd docs + ./values_to_doc.sh npm install npm run build - name: Deploy to GitHub Pages @@ -35,4 +36,4 @@ jobs: target_branch: gh-pages build_dir: docs/build env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index 81aa506e9..7df2d829c 100644 --- a/README.md +++ b/README.md @@ -37,92 +37,6 @@ Follow the prerequisites step first. Then you can jump to either [joining mainne NOTE: You do not need to clone this repository! All necessary components will be installed. -## Prerequisites - -- python3 (>=3.7) -- [docker](https://docs.docker.com/get-docker/) -- [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/) -- [minikube](https://minikube.sigs.k8s.io/docs/) -- [helm](https://helm.sh/) -- A [ZeroTier](https://www.zerotier.com/) network with api access token - -## Installing prerequisites - -This section varies depending on OS. - -### Mac - -- Install [Docker Desktop](https://docs.docker.com/docker-for-mac/install/). - -- Start Docker Desktop and follow the setup instructions. Note: You may quit Docker after it has finished setting up. It is not required that Docker Desktop is running for you to run a Tezos chain. - -- Install [homebrew](https://brew.sh/): - - ```shell - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" - ``` - -- Install other prerequisites: - ```shell - brew install python3 kubectl minikube helm - ``` - -### Arch Linux - -```shell -pacman -Syu && pacman -S docker python3 minikube kubectl kubectx helm -``` - -### Other Operating Systems - -Please see the respective pages for installation instructions: - -- [python3](https://www.python.org/downloads/) -- [docker](https://docs.docker.com/get-docker/) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) -- [helm](https://helm.sh/docs/intro/install/) - -## Configuring Minikube - -It is suggested to deploy minikube as a virtual machine. This requires a virtual machine [driver](https://minikube.sigs.k8s.io/docs/drivers/). - -### Mac - -Requires the [hyperkit](https://minikube.sigs.k8s.io/docs/drivers/hyperkit/) driver. This comes already bundled together with Docker Desktop. - -Make hyperkit the default minikube driver: - -```shell -minikube config set driver hyperkit -``` - -(Note: We do not use Docker itself as the minikube driver due to an [issue](https://github.com/kubernetes/minikube/issues/7332) regarding the minikube ingress addon that is required by [rpc-auth](./rpc-auth/README.md)) - -### Other Operating Systems - -If in the next step minikube does not start correctly, you may need to configure a different driver for it. Please see the minikube docs [here](https://minikube.sigs.k8s.io/docs/drivers/) for more information. - -## Starting Minikube - -```shell -minikube start -``` - -Configure your shell environment to use minikube’s Docker daemon: - -```shell -eval $(minikube docker-env) -``` - -This allows you to run Docker commands inside of minikube. For example: `docker images` to view the images that minikube has. - -If you want to unset your shell from using minikube's docker daemon: - -```shell -eval $(minikube docker-env -u) -``` - ## Tezos k8s Helm Chart To add the Tezos k8s Helm chart to your local Helm chart repo, run: diff --git a/charts/tezos/values.yaml b/charts/tezos/values.yaml index c007f9b17..ddd36eb6b 100644 --- a/charts/tezos/values.yaml +++ b/charts/tezos/values.yaml @@ -30,14 +30,18 @@ chain_initiator_job: # account is not explicitly set below. bootstrap_mutez: "4000000000000" -# # ACCOUNTS +# # Accounts # -# When running bakers for a public net, you must provide your own secret keys. -# For non public networks you can change this setting to true, and deterministic -# keys will be generated for your nodes automatically. If a genesis block hash -# is not provided, that will also be generated. This is helpful for spinning up -# local testnets. -should_generate_unsafe_deterministic_data: false +# The `accounts` object of values.yaml defines Tezos accounts used in the chart. +# By default no account is configured: +accounts: {} +# +# `accounts` is a map where keys are account aliases and values are maps of +# fields `key`, `is_bootstrap_baker_account`, `bootstrap_balance` and `signer_url`. +# +# The key field can be set to a public or private key. For a bootstrap baker, +# it must be set to a private key. The key type will be recognized automatically, +# and the pod will fail if the key type is unexpected. # # - Public chains: Accounts do not get `is_bootstrap_baker_account` and # `bootstrap_balance` fields. @@ -48,104 +52,117 @@ should_generate_unsafe_deterministic_data: false # node but they will not be bootstrap accounts. If you don't set a bootstrap # balance, it will default to the `bootstrap_mutez` field above. # -# The key field can be set to a public or private key. For a bootstrap baker, -# it must be set to a private key. The key type will be recognized automatically, -# and the pod will fail if the key type is unexpected. +# Example: # -accounts: {} +# ``` +# accounts: # baker0: # key: edsk... # is_bootstrap_baker_account: true # bootstrap_balance: "50000000000000" - +# # baker1: # key: edpk... # is_bootstrap_baker_account: false # bootstrap_balance: "4000000000000" - -## A public key account can contain a url to a remote signer that signs with the -## corresponding secret key. You shouldn't need to set this if you're deploying -## a tezos-k8s chart's signer into the same namespace. See the `signers` values -## field below in the file to define remote signers. -# baker3: +# ``` +# +# A public key account can contain a url to a remote signer that signs with the +# corresponding secret key. You shouldn't need to set this if you're deploying +# a tezos-k8s chart's signer into the same namespace. See the `signers` values +# field below in the file to define remote signers. +# ``` +# baker2: # key: edpk... # is_bootstrap_baker_account: false # bootstrap_balance: "4000000000000" -# signer_url: http://..:6732 - +# signer_url: http://[POD-NAME].[SERVICE-NAME].[NAMESPACE]:6732 +# ``` +# # NOTE - signer_url must be URL to external remote signer without anything extra # in the path, such as the public key hash. +# +# When running bakers for a public net, you must provide your own secret keys. +# For non public networks you can change the +# `should_generate_unsafe_deterministic_data` setting to true, and deterministic +# keys will be generated for your nodes automatically. If a genesis block hash +# is not provided, that will also be generated. This is helpful for spinning up +# local testnets. +should_generate_unsafe_deterministic_data: false +# # End Accounts -## NODES -## -## "nodes" is a dictionary where each key/value pair defines a statefulset and a -## number of instances thereof. The name (key) defines the name of the -## statefulset and will be the base of the pod names. The instances are defined -## as a list because their names are simply -N appended to the statefulsetname. -## Said names are typically kebab case. -## -## https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/ -## -## Params at the statefulset level: -## - "config": The "config" property should mimic the structure of a node's -## config.json. Run `tezos-node config --help` for more info. -## If present at the statefulset level, it overrides it in -## node_globals. -## - "env": a dictionary of containers mapped to a dictionary of env -## vars. The container name "all" will apply the env vars to -## all containers. The most specific wins. Find the names of -## the containers by examining an installed environment, or by -## looking at charts/tezos/templates/nodes.yaml. Please note -## that we truncate the protocol from the container name for -## bakers and accusers, so "baker-011-pthangz2" is configured -## using just "baker". -## - "storage_size": the size of the PV -## - "images": Optional specification of images to use for the tezos node and -## baker. Options are "octez" with a tezos/tezos image or -## "tezedge" with a tezedge/tezedge image. If no images are provided, -## the containers will default to the images defined in the "images" -## field up above. -## - "runs": A list of containers to run. A tezos node implementation is required. -## Options being "octez_node" or "tezedge_node". Other optional -## containers are "accuser", "baker", "logger", and "metrics". -## - "local_storage": use local storage instead of a volume. The storage will be -## wiped when the node restarts for any reason. Useful when -## faster IO is desired. Defaults to false. -## - "labels": https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ -## NOTE: the labels appType, node_class, and baking_node are set -## automatically for you. -## - "node_selector": Specify a kubernetes node selector in 'key: value' format -## for your tezos nodes. -## - "readiness_probe": Attach a probe to the node. The probe checks whether -## the most recent block is recent enough. If not, the -## services will be unreachable. Defaults to True. -## True is good for RPC nodes, private nodes, and -## self-contained private chains. -## Recommended to set to False when bootstrapping a new -## chain with external bakers, such as a new test chain. -## Otherwise, the chain may become unreachable externally -## while waiting for other nodes to come online. -## - "instances": a list of nodes to fire up, each is a dictionary defining: -## - "bake_using_account": Account name that should be used for baking. -## - "bake_using_accounts": List of account names that should be used for baking. -## - "config": Same as the outer statefulset level "config". It overrides the -## statefulset level. -## - "is_bootstrap_node": Is this node a bootstrap peer. -## - "identity": An optional map containing a pre-generated Tezos node -## identity. This is useful for local storage nodes which would -## need to generate an identity at every boot. The identity file -## will be created at /var/tezos/node/data/identity.json. -## Required fields are "peer_id", "public_key", "secret_key", -## and "proof_of_work_timestamp". -## -## Defaults are filled in for most of the above values. You can also provide -## global defaults for all nodes via a node_globals: section which is also -## a dictionary. Currently, two keys are defined: "config" and "env". These -## operate in the same way as the section in "nodes" going by the same name. -## -## Example config: -## +# # Nodes +# +# Use `nodes` to configure the Tezos nodes running in your chart. +# +# `nodes` is a dictionary where each key/value pair defines a statefulset and a +# number of instances thereof. The name (key) defines the name of the +# statefulset and will be the base of the pod names. The instances are defined +# as a list because their names are simply -N appended to the statefulsetname. +# Said names are typically kebab case. # +# https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/ +# +# Params at the statefulset level: +# - "config": The "config" property should mimic the structure of a node's +# config.json. Run `tezos-node config --help` for more info. +# If present at the statefulset level, it overrides it in +# node_globals. +# - "env": a dictionary of containers mapped to a dictionary of env +# vars. The container name "all" will apply the env vars to +# all containers. The most specific wins. Find the names of +# the containers by examining an installed environment, or by +# looking at charts/tezos/templates/nodes.yaml. Please note +# that we truncate the protocol from the container name for +# bakers and accusers, so "baker-011-pthangz2" is configured +# using just "baker". +# - "storage_size": the size of the PV +# - "images": Optional specification of images to use for the tezos node and +# baker. Options are "octez" with a tezos/tezos image or +# "tezedge" with a tezedge/tezedge image. If no images are provided, +# the containers will default to the images defined in the "images" +# field up above. +# - "runs": A list of containers to run. A tezos node implementation is required. +# Options being "octez_node" or "tezedge_node". Other optional +# containers are "accuser", "baker", "logger", and "metrics". +# - "local_storage": use local storage instead of a volume. The storage will be +# wiped when the node restarts for any reason. Useful when +# faster IO is desired. Defaults to false. +# - "labels": https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ +# NOTE: the labels appType, node_class, and baking_node are set +# automatically for you. +# - "node_selector": Specify a kubernetes node selector in 'key: value' format +# for your tezos nodes. +# - "readiness_probe": Attach a probe to the node. The probe checks whether +# the most recent block is recent enough. If not, the +# services will be unreachable. Defaults to True. +# True is good for RPC nodes, private nodes, and +# self-contained private chains. +# Recommended to set to False when bootstrapping a new +# chain with external bakers, such as a new test chain. +# Otherwise, the chain may become unreachable externally +# while waiting for other nodes to come online. +# - "instances": a list of nodes to fire up, each is a dictionary defining: +# - "bake_using_account": Account name that should be used for baking. +# - "bake_using_accounts": List of account names that should be used for baking. +# - "config": Same as the outer statefulset level "config". It overrides the +# statefulset level. +# - "is_bootstrap_node": Is this node a bootstrap peer. +# - "identity": An optional map containing a pre-generated Tezos node +# identity. This is useful for local storage nodes which would +# need to generate an identity at every boot. The identity file +# will be created at /var/tezos/node/data/identity.json. +# Required fields are "peer_id", "public_key", "secret_key", +# and "proof_of_work_timestamp". +# +# Defaults are filled in for most of the above values. You can also provide +# global defaults for all nodes via a node_globals: section which is also +# a dictionary. Currently, two keys are defined: "config" and "env". These +# operate in the same way as the section in "nodes" going by the same name. +# +# Example config: +# +# ``` # node_globals: # config: # shell: @@ -202,15 +219,12 @@ accounts: {} # instances: # - {} # - {} - +# ``` +# The default configuration is: node_globals: env: {} - nodes: rolling-node: -# labels: -# rpc_node: "true" -# peer_node: "true" storage_size: 100Gi runs: - octez_node @@ -219,6 +233,7 @@ nodes: config: shell: history_mode: rolling +# End nodes ## Configuration for K8s Service resources. Configuring the labels selector of a ## service will result in the service forwarding traffic only to pods that have @@ -230,12 +245,21 @@ services: selector: # rpc_node: "true" +# # Signers +# # Define remote signers. Bakers automatically use signers in their namespace # that are configured to sign for the accounts they are baking for. +# +# By default no signer is configured: signers: {} +# Here is an example of octez signer config. When set, the +# ``` +# signers: # tezos-signer-0: # sign_for_accounts: # - baker0 +# ``` +# End Signers ## Where full and rolling history mode nodes will get their Tezos snapshots from. full_snapshot_url: https://mainnet.xtz-shots.io/full diff --git a/docs/.gitignore b/docs/.gitignore index b2d6de306..5ea5d4468 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -18,3 +18,7 @@ npm-debug.log* yarn-debug.log* yarn-error.log* + +01-Tezos-Nodes.md +02-Tezos-Accounts.md +03-Tezos-Signers.md diff --git a/docs/00-helm-chart.md b/docs/00-helm-chart.md new file mode 100644 index 000000000..f6c5f3b3d --- /dev/null +++ b/docs/00-helm-chart.md @@ -0,0 +1,3 @@ +# Helm charts + +Tezos-k8s is deployed as a helm chart. The [values.yaml](https://github.com/oxheadalpha/tezos-k8s/blob/master/charts/tezos/values.yaml) file offers rich configuration options to customize your Tezos setup on Kubernetes. diff --git a/docs/04-other-helm-charts.md b/docs/04-other-helm-charts.md new file mode 100644 index 000000000..0b140c71b --- /dev/null +++ b/docs/04-other-helm-charts.md @@ -0,0 +1,9 @@ +# Other Helm charts + +The Tezos-k8s project also maintains several other helm charts: + +* **pyrometer**: a chart to deploy the [Pyrometer Tezos monitoring tool](https://gitlab.com/tezos-kiln/pyrometer) +* **rpc-auth**: a vending-machine to dispense Tezos RPC access +* **tezos-faucet**: a faucet to dispense pre-activated accounts (backend only) +* **snapshotEngine**: an utility to generate Tezos snapshots from running nodes, using Kubernetes CSI driver +* **tezos-reward-distributor**: a chart to deploy [TRD](https://tezos-reward-distributor-organization.github.io/tezos-reward-distributor/) diff --git a/docs/Prerequisites.md b/docs/Prerequisites.md new file mode 100644 index 000000000..1f44b5e82 --- /dev/null +++ b/docs/Prerequisites.md @@ -0,0 +1,86 @@ +## Prerequisites + +- python3 (>=3.7) +- [docker](https://docs.docker.com/get-docker/) +- [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/) +- [minikube](https://minikube.sigs.k8s.io/docs/) +- [helm](https://helm.sh/) +- A [ZeroTier](https://www.zerotier.com/) network with api access token + +## Installing prerequisites + +This section varies depending on OS. + +### Mac + +- Install [Docker Desktop](https://docs.docker.com/docker-for-mac/install/). + +- Start Docker Desktop and follow the setup instructions. Note: You may quit Docker after it has finished setting up. It is not required that Docker Desktop is running for you to run a Tezos chain. + +- Install [homebrew](https://brew.sh/): + + ```shell + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" + ``` + +- Install other prerequisites: + ```shell + brew install python3 kubectl minikube helm + ``` + +### Arch Linux + +```shell +pacman -Syu && pacman -S docker python3 minikube kubectl kubectx helm +``` + +### Other Operating Systems + +Please see the respective pages for installation instructions: + +- [python3](https://www.python.org/downloads/) +- [docker](https://docs.docker.com/get-docker/) +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) +- [minikube](https://minikube.sigs.k8s.io/docs/start/) +- [helm](https://helm.sh/docs/intro/install/) + +## Configuring Minikube + +It is suggested to deploy minikube as a virtual machine. This requires a virtual machine [driver](https://minikube.sigs.k8s.io/docs/drivers/). + +### Mac + +Requires the [hyperkit](https://minikube.sigs.k8s.io/docs/drivers/hyperkit/) driver. This comes already bundled together with Docker Desktop. + +Make hyperkit the default minikube driver: + +```shell +minikube config set driver hyperkit +``` + +(Note: We do not use Docker itself as the minikube driver due to an [issue](https://github.com/kubernetes/minikube/issues/7332) regarding the minikube ingress addon that is required by rpc-auth.) + +### Other Operating Systems + +If in the next step minikube does not start correctly, you may need to configure a different driver for it. Please see the minikube docs [here](https://minikube.sigs.k8s.io/docs/drivers/) for more information. + +## Starting Minikube + +```shell +minikube start +``` + +Configure your shell environment to use minikube’s Docker daemon: + +```shell +eval $(minikube docker-env) +``` + +This allows you to run Docker commands inside of minikube. For example: `docker images` to view the images that minikube has. + +If you want to unset your shell from using minikube's docker daemon: + +```shell +eval $(minikube docker-env -u) +``` + diff --git a/docs/Private-Node.md b/docs/Private-Node.md new file mode 100644 index 000000000..ee39afba4 --- /dev/null +++ b/docs/Private-Node.md @@ -0,0 +1,61 @@ +# Public network node +Connecting to a public net is easy! + +(See [here](https://tezos.gitlab.io/user/history_modes.html) for info on snapshots and node history modes) + +Simply run the following to spin up a rolling history node: + +```shell +helm install tezos-mainnet oxheadalpha/tezos-chain \ +--namespace oxheadalpha --create-namespace +``` + +Running this results in: + +- Creating a Helm [release](https://helm.sh/docs/intro/using_helm/#three-big-concepts) named tezos-mainnet for 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 oxheadalpha namespace with some status information using `kubectl`. + +```shell +kubectl -n oxheadalpha get pods -l appType=tezos-node +``` + +You can monitor (and follow using the `-f` flag) the logs of the snapshot downloader/import container: + +```shell +kubectl logs -n oxheadalpha statefulset/rolling-node -c snapshot-downloader -f +``` + +You can view logs for your node using the following command: + +```shell +kubectl -n oxheadalpha logs -l appType=tezos-node -c tezos-node -f --prefix +``` + +IMPORTANT: + +- 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 + ❯ 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 + ``` + diff --git a/docs/Private_Chain.md b/docs/Private_Chain.md new file mode 100644 index 000000000..c8e598f53 --- /dev/null +++ b/docs/Private_Chain.md @@ -0,0 +1,224 @@ +# Creating a Private Blockchain + +## Zerotier + +Zerotier is a VPN service that the Tezos nodes in your cluster will use to communicate with each other. + +Create a ZeroTier network: + +- Go to https://my.zerotier.com +- Login with credentials or create a new account +- Go to https://my.zerotier.com/account to create a new API access token +- Under `API Access Tokens > New Token`, give a name to your access token and generate it by clicking on the "generate" button. Save the generated access token, e.g. `yEflQt726fjXuSUyQ73WqXvAFoijXkLt` on your computer. +- Go to https://my.zerotier.com/network +- Create a new network by clicking on the "Create a Network" + button. Save the 16 character generated network + id, e.g. `1c33c1ced02a5eee` on your computer. + +Set Zerotier environment variables in order to access the network id and access token values with later commands: + +```shell +export ZT_TOKEN=yEflQt726fjXuSUyQ73WqXvAFoijXkLt +export ZT_NET=1c33c1ced02a5eee +``` + +## mkchain + +mkchain is a python script that generates Helm values, which Helm then uses to create your Tezos chain on k8s. + +Follow _just_ the Install mkchain step in `./mkchain/README.md`. See there for more info on how you can customize your chain. + +Set as an environment variable the name you would like to give to your chain: + +```shell +export CHAIN_NAME=my-chain +``` + +NOTE: k8s will throw an error when deploying if your chain name format does not match certain requirements. From k8s: `DNS-1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')` + +Set [unbuffered IO](https://docs.python.org/3.6/using/cmdline.html#envvar-PYTHONUNBUFFERED) for python: + +```shell +export PYTHONUNBUFFERED=x +``` + +## Start your private 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 oxheadalpha/tezos-chain \ +--values ./${CHAIN_NAME}_values.yaml \ +--namespace oxheadalpha --create-namespace +``` + +Your kubernetes cluster will now be running a series of jobs to +perform the following tasks: + +- get a zerotier ip +- generate a node identity +- create a baker account +- generate a genesis block for your chain +- start the bootstrap-node baker to bake/validate the chain +- activate the protocol +- bake the first block + +You can find your node in the oxheadalpha namespace with some status information using kubectl. + +```shell +kubectl -n oxheadalpha get pods -l appType=tezos-node +``` + +You can view (and follow using the `-f` flag) logs for your node using the following command: + +```shell +kubectl -n oxheadalpha logs -l appType=tezos-node -c tezos-node -f --prefix +``` + +Congratulations! You now have an operational Tezos based permissioned +chain running one node. + +## Adding nodes within the cluster + +You can spin up a number of regular peer nodes that don't bake in your cluster by passing `--number-of-nodes N` to `mkchain`. Pass this along with your previously used flags (`--zerotier-network` and `--zerotier-token`). You can use this to both scale up and down. + +Or if you previously spun up the chain using `mkchain`, you may adjust +your setup to an arbitrary number of nodes by updating the "nodes" +section in the values yaml file. + +nodes is a dictionary where each key value pair defines a statefulset +and a number of instances thereof. The name (key) defines the name of +the statefulset and will be the base of the pod names. The name must be +DNS compliant or you will get odd errors. The instances are defined as a +list because their names are simply `-N` appended to the statefulsetname. +Said names are traditionally kebab case. + +At the statefulset level, the following parameters are allowed: + + - storage_size: the size of the PV + - runs: a list of containers to run, e.g. "baker", "tezedge" + - instances: a list of nodes to fire up, each is a dictionary + defining: + - `bake_using_account`: The name of the account that should be used + for baking. + - `is_bootstrap_node`: Is this node a bootstrap peer. + - config: The `config` property should mimic the structure + of a node's config.json. + Run `tezos-node config --help` for more info. + +defaults are filled in for most values. + +Each statefulset can run either Nomadic Lab's `tezos-node` or TezEdge's +`tezedge` node. Either can support all of the other containers. If you +specify `tezedge` as one of the containers to run, then it will be run +in preference to `tezos-node`. + +E.g.: + +``` +nodes: + baking-node: + storage_size: 15Gi + runs: + - baker + - logger + instances: + - bake_using_account: baker0 + is_bootstrap_node: true + config: + shell: + history_mode: rolling + full-node: + instances: + - {} + - {} + tezedge-full-node: + runs: + - baker + - logger + - tezedge + instances: + - {} + - {} + - {} +``` + +This will run the following nodes: + - `baking-node-0` + - `full-node-0` + - `full-node-1` + - `tezedge-full-node-0` + - `tezedge-full-node-1` + - `tezedge-full-node-2` + +`baking-node-0` will run baker and logger containers +and will be the only bootstrap node. `full-node-*` are just nodes +with no extras. `tezedge-full-node-*` will be tezedge nodes running baker +and logger containers. + +To upgrade your Helm release run: + +```shell +helm upgrade $CHAIN_NAME oxheadalpha/tezos-chain \ +--values ./${CHAIN_NAME}_values.yaml \ +--namespace oxheadalpha +``` + +The nodes will start up and establish peer-to-peer connections in a full mesh topology. + +List all of your running nodes: `kubectl -n oxheadalpha get pods -l appType=tezos-node` + +## Adding external nodes to the cluster + +External nodes to your local cluster can be added to your network by sharing a yaml file +generated by the `mkchain` command. + +The file is located at: `/${CHAIN_NAME}_invite_values.yaml` + +Send this file to the recipients you want to invite. + +### On the computer of the joining node + +The member needs to: + +1. Follow the [prerequisite installation instructions](#installing-prerequisites) +2. [Start minikube](#start-minikube) + +Then run: + +```shell +helm repo add oxheadalpha https://oxheadalpha.github.io/tezos-helm-charts + +helm install $CHAIN_NAME oxheadalpha/tezos-chain \ +--values \ +--namespace oxheadalpha --create-namespace +``` + +At this point additional nodes will be added in a full mesh +topology. + +Congratulations! You now have a multi-node Tezos based permissioned chain. + +On each computer, run this command to check that the nodes have matching heads by comparing their hashes (it may take a minute for the nodes to sync up): + +```shell +kubectl get pod -n oxheadalpha -l appType=tezos-node -o name | +while read line; + do kubectl -n oxheadalpha exec $line -c tezos-node -- /usr/local/bin/tezos-client rpc get /chains/main/blocks/head/hash; +done +``` + + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..64d41e72f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# Tezos-k8s documentation + +Hosted at https://tezos-k8s.xyz + +The documentation is built from static markdown files in the `docs` directory as well as some generated documentation from `charts/tezos/values.yaml`. + +To generate the files: + +``` +cd docs/ +./values_to_doc.sh +``` + +To render locally: + +``` +npm install +./node_modules/.bin/docusaurus serve --build +``` diff --git a/docs/Tezos-RPC-Service.md b/docs/Tezos-RPC-Service.md new file mode 100644 index 000000000..35a135592 --- /dev/null +++ b/docs/Tezos-RPC-Service.md @@ -0,0 +1,41 @@ +## RPC Authentication + +You can optionally spin up an RPC authentication backend allowing trusted users to make RPC requests to your cluster. + +Follow the steps at `rpc-auth/README.md`. + +# Using a custom Tezos build + +Create a clone of the `[tezos](https://gitlab.com/tezos/tezos)` +repository. [Set up your development environment as usual](https://tezos.gitlab.io/introduction/howtoget.html#setting-up-the-development-environment-from-scratch). Then run: + +```shell +eval $(minikube docker-env) +make docker-image +``` + +This will create a docker image called `tezos:latest` and install it +into the minikube environment. + +Or, if you prefer, you can build the image using: +```shell +./scripts/create_docker_image.sh +``` + +This will create an image with a name like `tezos/tezos:v13-rc1`. +Then you install it thus: +```shell +docker image save | ( eval $(minikube docker-env); docker image load ) +``` + +Either way, inside `$CHAIN_NAME_values.yaml`, change the `images` section to: + +```yaml +images: + octez: +``` + +where image is `tezos:latest` or whatever. + +Then install the chart as above. + diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 0fef4504d..9a7757aa7 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -23,6 +23,7 @@ const config = { ({ docs: { routeBasePath: '/', // Serve the docs at the site's root + sidebarPath: require.resolve('./sidebars.js'), path: '.', include: ['*.md'] }, @@ -38,7 +39,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ navbar: { - title: 'Home', + title: 'Tezos-k8s', logo: { alt: 'Oxhead Alpha Logo', src: 'img/logo.svg', diff --git a/docs/index.md b/docs/index.md index ab03b243e..9ac35a9e6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,35 @@ # Overview -Tezos K8s is a collection of Helm charts and container images that can be used to deploy a Tezos node and other tools on a Kubernetes cluster. +![Tezos](./static/img/tezos-black.svg)![Kubernetes](./static/img/kubernetes.svg) -We plan on moving our documentation to this site, but for now please visit https://github.com/oxheadalpha/tezos-k8s for more information. +Tezos-k8s is a collection of Helm charts and container images that can be used to deploy [Tezos](https://tezos.com) blockchain infrastructure on a Kubernetes cluster. -![Kubernetes](./static/img/kubernetes.svg)![Tezos](./static/img/tezos-black.svg) +Use it to deploy: + +* a Tezos node +* a Tezos RPC service +* a Tezos baker (coming soon) +* a Tezos private chain + +on your laptop or in a cloud platform such as AWS, Digitalocean or GCP. + +Tezos-k8s is actively maintained by the team at [Oxhead Alpha](https://oxheadalpha.com), a Tezos core development company. + +## Quick start + +To deploy a Tezos mainnet node: + +1. Add the Oxhead Alpha Helm chart repository to your local Helm installation: + +``` +helm repo add oxheadalpha https://oxheadalpha.github.io/tezos-helm-charts/ +``` + +2. Install a Tezos node: + +``` +helm install tezos-mainnet oxheadalpha/tezos-chain \ +--namespace oxheadalpha --create-namespace +``` + +k8s will spin up an [Octez](https://tezos.gitlab.io/) node which will download and import a Tezos [mainnet tarball](https://tezos.gitlab.io/). This will take a few minutes. diff --git a/docs/package-lock.json b/docs/package-lock.json index b35c51444..10eb46f91 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -9,7 +9,7 @@ "version": "0.0.0", "dependencies": { "@docusaurus/core": "2.0.0-beta.18", - "@docusaurus/preset-classic": "2.0.0-beta.18", + "@docusaurus/preset-classic": "^2.0.0-beta.18", "@mdx-js/react": "^1.6.22", "clsx": "^1.1.1", "prism-react-renderer": "^1.3.1", diff --git a/docs/package.json b/docs/package.json index 58e416211..8a2be7c7b 100644 --- a/docs/package.json +++ b/docs/package.json @@ -16,7 +16,7 @@ }, "dependencies": { "@docusaurus/core": "2.0.0-beta.18", - "@docusaurus/preset-classic": "2.0.0-beta.18", + "@docusaurus/preset-classic": "^2.0.0-beta.18", "@mdx-js/react": "^1.6.22", "clsx": "^1.1.1", "prism-react-renderer": "^1.3.1", diff --git a/docs/sidebars.js b/docs/sidebars.js index fd342f2cd..930ab1e76 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,31 +1,34 @@ -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ - // @ts-check /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], // But you can create a sidebar manually - /* - tutorialSidebar: [ + tezosK8sSidebar: [ + 'index', + { + type: 'category', + label: 'Common use cases', + collapsed: false, + items: [ + 'Private-Node', + 'Private_Chain', + 'Tezos-RPC-Service'] + }, { type: 'category', - label: 'Tutorial', - items: ['hello'], + label: 'Tezos-k8s helm chart', + collapsed: false, + items: ['helm-chart', + 'Prerequisites', + 'Tezos-Accounts', + 'Tezos-Nodes', + 'Tezos-Signers', + ], }, + 'other-helm-charts' ], - */ }; module.exports = sidebars; diff --git a/docs/values_to_doc.sh b/docs/values_to_doc.sh new file mode 100644 index 000000000..9a981071d --- /dev/null +++ b/docs/values_to_doc.sh @@ -0,0 +1,30 @@ +#!/bin/sh + +extract_markdown() { + uncommented=false + while IFS= read -r line; do + if [[ $line =~ ^# ]]; then + if [[ "$uncommented" == "true" ]]; then + echo '```' + fi + uncommented=false + echo "$line" | sed -e 's/^# //' | sed -e 's/^#$//' + else + if [[ "$uncommented" == "false" ]]; then + echo '```' + fi + uncommented=true + echo "$line" + fi + done <<< $1 + if [[ "$uncommented" == "true" ]]; then + echo '```' + fi +} + +lines=$(cat ../charts/tezos/values.yaml | awk '/# Nodes/,/End nodes/' | head -n -1) +extract_markdown "$lines" > 01-Tezos-Nodes.md +lines=$(cat ../charts/tezos/values.yaml | awk '/# Accounts/,/End Accounts/' | head -n -1) +extract_markdown "$lines" > 02-Tezos-Accounts.md +lines=$(cat ../charts/tezos/values.yaml | awk '/# Signers/,/End Signers/' | head -n -1) +extract_markdown "$lines" > 03-Tezos-Signers.md