We've extended Kubernetes with Node custom resource which can be used to create Filecoin nodes across different filecoin networks like Mainnet or calibration using lotus client from a given spec.

Here's an example of a Filecoin node that syncs calibration chain:

apiVersion: filecoin.kotal.io/v1alpha1
kind: Node
metadata:
  name: calibration-node
spec:
  network: calibration

For all the fields associated with the Node API resource:

kubectl explain node --api-version filecoin.kotal.io/v1alpha1
kubectl explain node.spec --api-version filecoin.kotal.io/v1alpha1

Full filecoin node reference is documented here.

You can support us by donating Eth or any token to our ENS address farghaly.eth or directly to the following Ethereum address:

Thank you!

Polkadot is a sharded protocol that enables blockchain networks to operate together seamlessly. Polkadot is a 100% open-source project created to enable a decentralized web and better society.

We've extended Kubernetes with Node custom resource which can be used to Polkadot, Kusama, Rococo, and substrate-based chains from the given spec.

Node

Node is Polkadot node using client, connecting to and syncing a specific chain, and optionally validating blocks.

For all the fields associated with the Node API resource:

Full polkadot node reference is documented .

IPFS is a distributed system for storing and accessing files, websites, applications, and data.

We've extended Kubernetes with Peer and ClusterPeer custom resources which can be used to deploy IPFS peers, swarms, and clusters from the given spec.

Peer

Peer is an ipfs peer running go-ipfs client and connecting to the public ipfs swarm or a private swarm secured by swarm key. Here's an example of a very basic ipfs peer connecting to the public ipfs swarm.

For all the fields associated with the Peer API resource:

Full ipfs peer reference is documented .

ClusterPeer

ClusterPeer is an ipfs cluster peer running ipfs-cluster-service client, connecting to ipfs peer and optional bootstrap cluster peer(s). ClusterPeers provide data orchestration across a swarm of IPFS daemons by allocating, replicating and tracking a global pinset distributed among multiple peers. Here's an example of cluster peer connecting to ipfs peer.

For all the fields associated with the ClusterPeer API resource:

Full ipfs cluster peer reference is documented .

We've extended Kubernetes with Node custom resource which can be used to deploy Bitcoin nodes from the given spec.

Node

Node is Bitcoin node using client, connecting to and syncing a specific chain.

For all the fields associated with the Node API resource:

Full Bitcoin node reference is documented .

Kotal is an open source alternative to centralized API gateway, Node as a service, and Staking service providers. Like Infura in Ethereum ecosystem, Onfinality in Polkadot ecosystem, and Hiro in Stacks ecosystem.

Kotal is multi-client, protocol-agnostic, and cloud-agnostic Blockchain Kubernetes Operator that makes it easy to deploy highly-available self-managing self-healing blockchain infrastructure on any cloud.

Kotal has been tested on Amazon Web Service, Google Cloud Platform, Microsoft Azure, DigitalOcean, Alibab Cloud, Tencent cloud 🤯.

What can I do with Kotal ?

• Deploy nodes across 10 Blockchain protocols (Aptos, Bitcoin, Chainkstack, Ethereum, Filecoin, IPFS, NEAR, Polkadot, Stacks)

• Upgrade and Downgrade node client software

• Load validator keys and start producing blocks

• Manage storage and resources (CPU & Memory) allocated to the node

• Manage Secrets (private keys, passwords, tokens, certificates)

• Monitor resources utilization

• Fetch real time logs

• Create TLS-secure API endpoints

• View API endpoints usage

• Create workspaces of nodes and resources

• Invite members to workspaces and assign roles

Create rinkeby.yaml manifest that describes an Ethereum node which uses go-ethereum client, connecting to rinkeby network, and enabling JSON-RPC server:

apiVersion: ethereum.kotal.io/v1alpha1
kind: Node
metadata:
  name: rinkeby-geth-node
spec:
  network: rinkeby
  client: geth
  rpc: true

Deploy the node using kubectl:

kubectl apply -f rinkeby.yaml

Within a couple of seconds, the node will be up and running. You can get the node using:

kubectl get nodes.ethereum

It will return an output similar to the following:

NAME                 CLIENT   Network   Consensus
rinkeby-geth-node    geth     rinkeby   poa

Kotal will create all the necessary pods, volumes, services for the node. Get the pods by:

kubectl get pods

It will return an output similar to the following:

NAME                     READY   STATUS    RESTARTS   AGE
rinkeby-geth-node-0      1/1     Running   0          1m

Finally delete the node by:

kubectl delete -f rinkeby.yaml

Congratulations!

We've extended Kubernetes with Node custom resource which can be used to deploy Chainlink nodes from the given spec.

apiVersion: chainlink.kotal.io/v1alpha1
kind: Node
metadata:
  name: my-node
spec:
  # your node spec goes here

Using Chainlink Node custom resource, you can describe any chainlink node, connect to EVM chain node, add jobs and satisfy requests, and Kotal will create all the necessary Kubernetes resources like pods, persistent volumes, services, configmaps, and secrets for you.

If you want to get all the deployted chainlink Node(s):

kubectl get nodes.chainlink

Which will report node name, client, Ethereum chain ID, and Link contract address.

If you want to get all the fields associated with chainlink Node:

kubectl explain nodes --api-version chainlink.kotal.io/v1alpha1

For a comprehensive reference on Chainlink Node, check our chainlink reference

We've extended Kubernetes with Node custom resource which can be used to deploy Ethereum nodes from the given spec.

Using Ethereum Node custom resource, you can describe any public or private network node you want, and Kotal will create all the necessary Kubernetes resources like pods, persistent volumes, services, configmaps, and secrets for you.

If you want to get all the deployted ethereum Node(s):

Which will report node name, client, network, and consensus.

If you want to get all the fields associated with ethereum Node:

For a comprehensive reference on Ethereum Node, check our

Multi-client Support

Kotal supports the following Ethereum 1 clients:

We've extended Kubernetes with BeaconNode and Validator custom resources which can be used to deploy Ethereum 2.0 beacon nodes and validator clients from the given spec.

Beacon Node

BeaconNode is Ethereum 2.0 beacon node -optionally- connecting to Ethereum 1 endpoint and syncing the beacon chain.

Here's an example of ConsenSys Teku beacon node BeaconNode syncing mainnet beacon chain, connecting to Ethereum 1 JSON RPC endpoint, enabling REST API server which is listening at port 8888:

For all the fields associated with the BeaconNode API resource:

Full beacon node reference is documented .

Validator Client

Validator is Ethereum 2.0 validator client connecting to beacon node endpoint and validating blocks using the loaded keystores.

Here's an example of ConsenSys Teku validator client connecting to beacon node endpoint, validating pyrmont blocks using 1 loaded validator keystore from its secret:

For all the fields associated with the Validator API resource:

Full validator client reference is documented .

Multi-client Support

Kotal supports the following Ethereum 2.0 beacon node and validator clients:

• by ConsenSys.

• by Sigma Prime.

• by Prysmatic Labs.

• by Status.im.

Setting validator or beacon node client is as simple as changing the spec.client to the desired client.

We've extended Kubernetes with Node custom resource which can be used to deploy NEAR nodes from the given spec.

Node

Node is NEAR node using client, connecting to and syncing a specific chain, and optionally validating blocks.

For all the fields associated with the Node API resource:

Full NEAR node reference is documented .

Staking is the act of depositing 32 ETH to activate validator software. As a validator you’ll be responsible for storing data, processing transactions, and adding new blocks to the blockchain. This will keep Ethereum secure for everyone and earn you new ETH in the process. This process, known as proof-of-stake, is being introduced by the Beacon Chain. source

Deploy Validator Client

apiVersion: ethereum2.kotal.io/v1alpha1
kind: Validator
metadata:
  name: teku-validator
spec:
  client: teku
  network: pyrmont
  beaconEndpoints:
    - http://teku-beacon-node:9999
  graffiti: Validated by Kotal
  keystores:
    - secretName: my-validator

In this validator client, we're using ConsenSys Teku Ethereum 2.0 client client: teku, validating pyrmont network blockchain network: pyrmont, connecting to beacon node endpoint using beaconEndpoints: ..., setting the graffiti text to include in the propsed blocks graffiti: validated by Kotal, and loading a validator keystore using keystores: ... from a kubernetes secret called my-validator.

Let's deploy the validator client:

kubectl apply -f validator.yaml

Kotal operator will notice your teku-validator and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum 2.0 Validator using:

kubectl get validators

It will return an output similar to the following:

NAME             CLIENT   NETWORK   AGE
teku-validator   teku     pyrmont   1m

Fetch Validator Logs

Get the pods created for the validator client:

kubectl get pods

It will return an output similar to the following:

NAME                 READY   STATUS    RESTARTS   AGE
teku-validator-0     1/1     Running   0          1m

Get the logs of the running validator pod:

kubectl logs -f teku-validator-0

You'll get an output similar to the following:

...
21:21:30.668 INFO  - Storing validator data in: /opt/teku/kotal-data/validator
21:21:30.751 INFO  - Loading 1 validator keys...
21:21:31.759 INFO  - Loaded 1 Validators: 83dbb18
...

Finally delete the validator client:

kubectl delete validator teku-validator

Kubernetes garbage collector will delete all the resources that has been created by Kotal Ethereum 2.0 Validator controller.

Deploy RPC Node

The following manifest describes a NEAR node that syncs NEAR mainnet network: mainnet, enables HTTP JSON-RPC server rpc: true and uses NEAR Core client:

apiVersion: near.kotal.io/v1alpha1
kind: Node
metadata:
  name: near-node
spec:
  network: mainnet
  rpc: true

Apply near.yaml manifest:

kubectl apply -f near.yaml

Kotal operator will notice your near-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed NEAR Node using:

kubectl get nodes.near

It will return an output similar to the following:

NAME         NETWORK    CLIENT      VALIDATOR
near-node    mainnet    nearcore    fasle

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

kubectl get pods

It will return an output similar to the following:

NAME              READY   STATUS    RESTARTS   AGE
near-node-0       1/1     Running   0          1m

Get the logs of the running node:

kubectl logs -f near-node-0

It will return node logs similar to the following:

Apr 07 12:18:33.280  INFO neard: Version: 1.23.1, Build: 1.23.0-9-gc0551c84b-modified, Latest Protocol: 50
Apr 07 12:18:33.287  INFO near: Did not find "/home/near/kotal-data/data" path, will be creating new store database
Apr 07 12:18:33.806  INFO stats: Server listening at ed25519:[email protected]:24567
Apr 07 12:18:43.816  INFO stats: # 9820210 Downloading headers 0.00% (53203932)   5/3/40 peers ⬇ 7.2kiB/s ⬆ 0.4kiB/s 0.00 bps 0 gas/s CPU: 0%, Mem: 0 B
Apr 07 12:18:53.819  INFO stats: # 9820210 Downloading headers 0.00% (53203933)   5/3/40 peers ⬇ 7.2kiB/s ⬆ 0.5kiB/s 0.00 bps 0 gas/s CPU: 10%, Mem: 134.4 MiB
Apr 07 12:19:03.787  INFO stats: # 9820210 Downloading headers 0.00% (53203933)   5/3/40 peers ⬇ 7.2kiB/s ⬆ 0.5kiB/s 0.00 bps 0 gas/s CPU: 24%, Mem: 165.9 MiB
Apr 07 12:19:13.790  INFO stats: # 9820210 Downloading headers 0.00% (53203933)   5/3/40 peers ⬇ 7.2kiB/s ⬆ 0.5kiB/s 0.00 bps 0 gas/s CPU: 9%, Mem: 175.0 MiB
...

Call JSON-RPC Method

By default, NEAR node JSON-RPC server port is 3030, which can be changed using rpcPort.

Forward localhost:3030 calls to the node pod:

kubectl port-forward near-node-0 3030

In another terminal window call status JSON-RPC method to get the general status of our node (sync status, nearcore node version, protocol version) and the current set of validators:

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "status"}' 0.0.0.0:3030

You will get JSON result similar to the following:

{
  "jsonrpc": "2.0",
  "result": {
    "version": {
      "version": "1.23.1",
      "build": "1.23.0-9-gc0551c84b-modified"
    },
    "chain_id": "mainnet",
    "protocol_version": 29,
    "latest_protocol_version": 50,
    "rpc_addr": "0.0.0.0:3030",
    "validators": [
      {
        "account_id": "nfvalidator2.near",
        "is_slashed": false
      },
      {
        "account_id": "nfvalidator1.near",
        "is_slashed": false
      },
      {
        "account_id": "nfvalidator4.near",
        "is_slashed": false
      },
      {
        "account_id": "nfvalidator3.near",
        "is_slashed": false
      }
    ],
    "sync_info": {
      "latest_block_hash": "EPnLgE7iEq9s7yTkos96M3cWymH5avBAPm3qx3NXqR8H",
      "latest_block_height": 9820210,
      "latest_state_root": "5o1trt9N9YgDL4xeY33z9adS5Ub3jMmuyQpWM7UHowrq",
      "latest_block_time": "2020-07-21T16:55:51.591948Z",
      "syncing": true,
      "earliest_block_hash": "EPnLgE7iEq9s7yTkos96M3cWymH5avBAPm3qx3NXqR8H",
      "earliest_block_height": 9820210,
      "earliest_block_time": "2020-07-21T16:55:51.591948Z"
    },
    "validator_account_id": "validator"
  },
  "id": 53
}

Finally you can delete the node by:

kubectl delete -f near.yaml

Kubernetes garbage collector will delete all the resources that has been created by Kotal NEAR Node controller.

Deploy Rinkeby Node

Rinkeby is a Proof of Authority public Ethereum test network, used by developers to test their dApps.

The following manifest describes an Ethereum node that joins rinkeby network network: rinkeby, and uses Hyperledger Besu client client: besu:

Apply rinkeby.yaml manifest:

Kotal operator will notice your rinkeby-besu-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed Ethereum Node using:

It will return an output similar to the following:

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Get the logs of the running node:

Call JSON-RPC Method

Let's update our node by enabling JSON-RPC HTTP server:

Apply the new version of rinkeby.yaml:

Forward localhost:8545 calls to the node pod:

In another terminal window call eth_syncing JSON-RPC method

You will get JSON result similar to the following:

Finally you can delete the node by:

Kubernetes garbage collector will delete all the resources that has been created by Kotal Ethereum Node controller.

Generate JSON-RPC password secret

Bitcoin nodes that enable JSON-RPC server are required to use basic authentication while calling JSON-RPC methods.

Apply rpc-user-password.yaml to create the password secret:

Deploy Bitcoin RPC Node

The following manifest describes a Bitcoin node that syncs Bitcoin mainnet network: mainnet, enables HTTP JSON-RPC server rpc: true, defines JSON-RPC user credentials rpcUsers: ... and uses client:

Apply bitcoin.yaml manifest:

Kotal operator will notice your bitcoin-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed Bitcoin Node using:

It will return an output similar to the following:

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Get the logs of the running node:

It will return node logs similar to the following:

Call JSON-RPC Method

By default, Bitcoin node JSON-RPC server port is 8332, which can be changed using rpcPort.

Forward localhost:8332 calls to the node pod:

In another terminal window call getblockhash JSON-RPC method to get the genesis block hash:

You will get JSON result similar to the following:

Finally you can delete the node by:

Kubernetes garbage collector will delete all the resources that has been created by Bitcoin Node controller.

The Beacon Chain is the coordination mechanism of the new network, responsible for creating new blocks, making sure those new blocks are valid, and rewarding validators with ETH for keeping the network secure.

Deploy Beacon Node

In this beacon node, we're using ConsenSys Teku Ethereum 2.0 client client: teku, and syncing the pyrmont network beacon chain network: pyrmont. We also enable REST API server rest: true at port 8888 restPort: 8888. We're connecting to Ethereum 1 endpoint eth1Endpoints: .... Check Ethereum on how to deploy an Ethereum node.

Let's deploy the beacon node:

Kotal operator will notice your teku-beacon-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum 2.0 BeaconNode using:

It will return an output similar to the following:

Fetch Beacon Node Logs

Get the pods created for the beacon node:

It will return an output similar to the following:

Get the logs of the running beacon node:

Call /eth/v1/beacon/genesis REST API

Get the service created for the beacon node:

It will return an output similar to the following:

Forward the localhost:8888 calls to the beacon node

In another terminal window, send REST API call to get chain genesis details:

You'll get a result similar to the following:

Finally delete the beacon node:

Kubernetes garbage collector will delete all the resources that has been created by Kotal Ethereum 2.0 BeaconNode controller.

Deploy Polkadot Node

The following manifest describes a Polkadot node that syncs Polkadot relay chain network: polkadot, enables HTTP JSON-RPC server rpc: true on custom port rpcPort: 8888, and uses Parity Polkadot client:

apiVersion: polkadot.kotal.io/v1alpha1
kind: Node
metadata:
  name: polkadot-node
spec:
  network: polkadot
  rpc: true
  rpcPort: 8888

Apply polkadot.yaml manifest:

kubectl apply -f polkadot.yaml

Kotal operator will notice your polkadot-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed Polkadot Node using:

kubectl get nodes.polkadot

It will return an output similar to the following:

NAME             NETWORK     VALIDATOR
polkadot-node    polkadot    fasle

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

kubectl get pods

It will return an output similar to the following:

NAME                  READY   STATUS    RESTARTS   AGE
polkadot-node-0       1/1     Running   0          1m

Get the logs of the running node:

kubectl logs -f polkadot-node-0

It will return node logs similar to the following:

2021-10-17 22:15:12 Parity Polkadot
2021-10-17 22:15:12 ✌️  version 0.9.11-bfd38ed62-x86_64-linux-gnu
2021-10-17 22:15:12 ❤️  by Parity Technologies <[email protected]>, 2017-2021
2021-10-17 22:15:12 📋 Chain specification: Polkadot
2021-10-17 22:15:12 🏷 Node name: polkadot-node
2021-10-17 22:15:12 👤 Role: FULL
2021-10-17 22:15:12 💾 Database: RocksDb at /polkadot/kotal-data/chains/polkadot/db/full
2021-10-17 22:15:12 ⛓  Native runtime: polkadot-9110 (parity-polkadot-0.tx8.au0)
2021-10-17 22:15:12 🔨 Initializing Genesis block/state (state: 0x29d0…4e17, header-hash: 0x91b1…90c3)
2021-10-17 22:15:12 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.
2021-10-17 22:15:13 ⏱  Loaded block-time = 6s from block 0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3
2021-10-17 22:15:13 👶 Creating empty BABE epoch changes on what appears to be first startup.
2021-10-17 22:15:13 🏷 Local node identity is: 12D3KooWRo3vvfgPdsJ44tXu1Y2GeFNmC9ror2HsdJjvSjEcfZdw
2021-10-17 22:15:13 📦 Highest known block at #0
2021-10-17 22:15:13 Listening for new connections on 127.0.0.1:9944.
2021-10-17 22:15:13 🔍 Discovered new external address for our node: /ip4/102.189.29.174/tcp/30333/ws/p2p/12D3KooWRo3vvfgPdsJ44tXu1Y2GeFNmC9ror2HsdJjvSjEcfZdw
2021-10-17 22:15:18 ⚙️  Syncing, target=#7304424 (1 peers), best: #64 (0x4983…1114), finalized #0 (0x91b1…90c3), ⬇ 37.0kiB/s ⬆ 17.6kiB/s

Call JSON-RPC Method

Forward localhost:8888 calls to the node pod because rpcPort: 8888:

kubectl port-forward polkadot-node-0 8888

In another terminal window call eth_getBlock JSON-RPC method to get the latest synced block:

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "chain_getBlock", "params": []}' 0.0.0.0:8888

You will get JSON result similar to the following:

{
  "jsonrpc": "2.0",
  "result": {
    "block": {
      "extrinsics": [
        "0x280403000be06ab2527201",
        "0x14040a00912e",
        "0x1004140000"
      ],
      "header": {
        "digest": {
          "logs": [
            "0x0642414245b501030000000042eacc0f00000000f414617b1dbce8671e029af90ae45c4b51d2f8d77d7876ae5f19dd42b7cb213775f40642dc2d86dd0a16169008e2d8735c849d7113da468be33b1c85819310024daffbee165156a2c17919fdc592754960a5587b6affc81f3e9c260364da2200",
            "0x054241424501019243678a110c1271c784ba9abaf03e08ae635ea766ce953853bfb1e3c0f70b5c95907240de74e57aa379c8428cd9933f097e32f9ef82caf261277ba4dc573b8b"
          ]
        },
        "extrinsicsRoot": "0xd9c14a96f36005ef6487ff56cb4722ff64afa3535cb1464c988767084094566c",
        "number": "0xba7",
        "parentHash": "0xcfb74aa6750036482897f63806191b3b14447186e45f69c43fcb72e02b57871f",
        "stateRoot": "0x5116aa11f10b1b1ce7c05ea85de08238b7db4c2c485bc88a9167e3b0a153368b"
      }
    },
    "justifications": null
  },
  "id": 1
}

Finally you can delete the node by:

kubectl delete -f polkadot.yaml

node.polkadot.kotal.io "polkadot-node" deleted

Kubernetes garbage collector will delete all the resources that has been created by Kotal Polkadot Node controller.

Deploy Peer

apiVersion: ipfs.kotal.io/v1alpha1
kind: Peer
metadata:
  name: simple-peer
spec: {}

This is a simple ipfs peer that joins the public ipfs swarm, and will starts with the all default settings that's similar to running ipfs init then ipfs daemon on your machine.

Let's deploy the peer:

kubectl apply -f peer.yaml

Kotal operator will notice your simple-peer and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

kubectl get peers

It will return an output similar to the following:

NAME          CLIENT
simple-peer   go-ipfs

Fetch Peer Logs

Get the pods created for the peer:

kubectl get pods

It will return an output similar to the following:

NAME            READY   STATUS    RESTARTS   AGE
simple-peer-0   1/1     Running   0          5m

Check the logs of the running peer:

kubectl logs -f simple-peer-0

You'll get output similar to the following:

Initializing daemon...
go-ipfs version: 0.8.0-ce693d7
Repo version: 11
System version: amd64/linux
Golang version: go1.14.4
Swarm listening on /ip4/10.244.0.6/tcp/4001
Swarm listening on /ip4/10.244.0.6/udp/4001/quic
Swarm listening on /ip4/127.0.0.1/tcp/4001
Swarm listening on /ip4/127.0.0.1/udp/4001/quic
Swarm listening on /ip6/::1/tcp/4001
Swarm listening on /ip6/::1/udp/4001/quic
Swarm listening on /p2p-circuit
Swarm announcing /ip4/10.244.0.6/tcp/4001
Swarm announcing /ip4/10.244.0.6/udp/4001/quic
Swarm announcing /ip4/127.0.0.1/tcp/4001
Swarm announcing /ip4/127.0.0.1/udp/4001/quic
Swarm announcing /ip6/::1/tcp/4001
Swarm announcing /ip6/::1/udp/4001/quic
API server listening on /ip4/0.0.0.0/tcp/5001
WebUI: http://0.0.0.0:5001/webui
Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080
Daemon is ready

Your peer is up and running and ready to receive api calls.

Read file Using IPFS HTTP API

Let's forward localhost:5001 calls to simple-peer:5001

kubectl port-forward simple-peer-0 5001

In another terminal window, send http api call using cURL:

curl -X POST "http://127.0.0.1:5001/api/v0/cat?arg=QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/readme"

You'll get the following output:

Hello and Welcome to IPFS!

██╗██████╗ ███████╗███████╗
██║██╔══██╗██╔════╝██╔════╝
██║██████╔╝█████╗  ███████╗
██║██╔═══╝ ██╔══╝  ╚════██║
██║██║     ██║     ███████║
╚═╝╚═╝     ╚═╝     ╚══════╝

If you're seeing this, you have successfully installed
IPFS and are now interfacing with the ipfs merkledag!

 -------------------------------------------------------
| Warning:                                              |
|   This is alpha software. Use at your own discretion! |
|   Much is missing or lacking polish. There are bugs.  |
|   Not yet secure. Read the security notes for more.   |
 -------------------------------------------------------

Check out some of the other files in this directory:

  ./about
  ./help
  ./quick-start     <-- usage examples
  ./readme          <-- this file
  ./security-notes

You can also view ipfs webui by visiting http://0.0.0.0:5001/webui

Finally, delete the ipfs peer:

kubectl delete -f peer.yaml

Kubernetes garbage collector will delete all the resources that has been created by Kotal IPFS Peer controller.

Stacks node requires a Bitcoin node to connect to on the back-end for Proof of Transfer. You can deploy a Bitcoin node using Kotal operator like we did in this guide. In this tutorial, we will be using Bitcoin node hosted by Stacks Foundation.

Bitcoin node JSON-RPC user password

Let's store Stacks Foundation Bitcoin node JSON-RPC password in a Kubernetes secret to be used by our node:

apiVersion: v1
kind: Secret
metadata:
  name: bitcoin-node-rpc-password
stringData:
  password: blockstacksystem

Apply bitcoin-node-rpc-password.yaml to create the password secret:

kubectl apply -f bitcoin-node-rpc-password.yaml

Deploy Stacks RPC Node

The following manifest describes a Stacks node that syncs Stacks mainnet network: mainnet, and connects to the bitcoin node using configurations in bitcoinNode: ... for Proof of Transfer:

apiVersion: stacks.kotal.io/v1alpha1
kind: Node
metadata:
  name: stacks-node
spec:
  network: mainnet
  bitcoinNode:
    endpoint: bitcoin.blockstack.com
    rpcPort: 8332
    p2pPort: 8333
    rpcUsername: blockstack
    rpcPasswordSecretName: bitcoin-node-rpc-password

Apply stacks.yaml manifest:

kubectl apply -f stacks.yaml

Kotal operator will notice your stacks-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed Stacks Node using:

kubectl get nodes.stacks

It will return an output similar to the following:

NAME            NETWORK    CLIENT    MINER
stacks-node     mainnet    stacks    false

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

kubectl get pods

It will return an output similar to the following:

NAME             READY   STATUS    RESTARTS   AGE
stacks-node-0    1/1     Running   0          1m

Get the logs of the running node:

kubectl logs -f stacks-node-0

It will return node logs similar to the following:

INFO [1649597250.010714] [testnet/stacks-node/src/main.rs:113] [main] Loading config at path /home/stacks/kotal-config/config.toml
INFO [1649597250.599067] [testnet/stacks-node/src/run_loop/neon.rs:341] [main] Start syncing Bitcoin headers, feel free to grab a cup of coffee, this can take a while
INFO [1649597251.949664] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 0.3% (2000 out of 731268)
INFO [1649597253.010039] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 0.5% (4000 out of 731268)
INFO [1649597254.019798] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 0.8% (6000 out of 731268)
INFO [1649597254.992070] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.1% (8000 out of 731268)
INFO [1649597256.214756] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.4% (10000 out of 731268)
INFO [1649597257.276950] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.6% (12000 out of 731268)
INFO [1649597258.383248] [src/burnchains/bitcoin/spv.rs:923] [main] Syncing Bitcoin headers: 1.9% (14000 out of 731268)
...

Call JSON-RPC Method

By default, Stacks node JSON-RPC server port is 20443, which can be changed using rpcPort.

Forward localhost:20443 calls to the node pod:

kubectl port-forward bitcoin-node-0 20443

curl: (52) Empty reply from server

In another terminal window call info JSON-RPC method to retrieve information about the Core API including the server version:

curl localhost:20443/v2/info

You will get JSON result similar to the following:

{
  "peer_version": 402653189,
  "pox_consensus": "9bed78c9f02d2ba5a5950fe88c4746436b47c730",
  "burn_block_height": 666051,
  "stable_pox_consensus": "0000000000000000000000000000000000000000",
  "stable_burn_block_height": 666050,
  "server_version": "stacks-node No Version Info (No Branch Info:No Commit Info, release build, linux [x86_64])",
  "network_id": 1,
  "parent_network_id": 3652501241,
  "stacks_tip_height": 0,
  "stacks_tip": "0000000000000000000000000000000000000000000000000000000000000000",
  "stacks_tip_consensus_hash": "0000000000000000000000000000000000000000",
  "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
  "unanchored_tip": null,
  "unanchored_seq": null,
  "exit_at_block_height": null
}

Finally you can delete the node by:

kubectl delete -f stacks.yaml

Kubernetes garbage collector will delete all the resources that has been created by Stacks Node controller.

Deploy Private Network Node

Let's describe an Ethereum Node that uses a custom genesis block to join a private Proof of Authority network using Clique consensus configuration in the genesis block.

In this node, we're using Hyperledger besu client client: besu, enabling JSON-RPC server rpc: true so we can query number of peers later in this tutorial, and we're loading the node private key from Kubernetes secretd called besu-clique-nodekey.

The node private key will give the node a unique identity and node URL, and will allow the node to generate blocks, because the address 0xbAa5f05af4A67A467cEcA89085f162aFb4206Aaa that's corresponding to the node private key is in the initial block signers.

We're defining a genesis block that uses the value 4444 as network and chain identifier, and we start the chain with 3 signers as defined by spec.genesis.clique.signers.

This node private key secret can be created by:

Let's deploy the node:

Kotal operator will notice your besu-clique-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum Node using:

It will return an output similar to the following:

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Get the logs of the running node:

Deploy a Second Node

Let's deploy another go-ethereum node, and connect it to the previous node in our private proof of authority network.

In this node, we're using go-ethereum client client: geth, starting the PoA consensus engine miner: true, setting the second address in the genesis signers list spec.genesis.clique.signers as the coinbase coinbase: "0xc1381ED43B327e3C7A1ADb21285f1e9cB82Bc00d", and loading the signer account private key and password from kubernetes secrets privateKeySecretName: ... and passwordSecretName: .... We're connecting to the first node using staticNodes option which accepts Node name or enode url.

You can create the private key and password secrets using:

Deploy the second node using:

Kotal operator will notice your second geth-clique-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum Nodes using:

It will return an output similar to the following:

Call JSON-RPC Method net_peerCount

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Forward localhost:8545 calls to the node pod:

In another terminal window call net_peerCount JSON-RPC method

You will get JSON result similar to the following:

Homework

Deploy a third node that uses Nethermind client, and signing blocks using the third key in the signers list spec.genesis.clique.signers. Nethermind client is similar to geth, you will import signer account private key and password from kubernetes secrets, and use the same genesis as the other nodes.

Finally you can delete all the nodes by:

Kubernetes garbage collector will delete all the resources that has been created by Kotal Ethereum Node controller.

Deploy Private Network Node

Let's describe an Ethereum Node that uses a custom genesis block to join a private Proof of Work network using Ethash consensus configuration in the genesis block.

In this node, we're using Hyperledger besu client client: besu, enabling JSON-RPC server rpc: true so we can query number of peers later in this tutorial, turning on Proof of Work mining miner: true, setting the address that will collect block reward using coinbase, and we're loading the node private key from Kubernetes secretd called besu-ethash-nodekey, this is the private from which the coinbase address is derived.

We're defining a genesis block that uses the value 4444 as network and chain identifier, and used ethash proof of work consensus engine.

This node private key secret can be created by:

Let's deploy the node:

Kotal operator will notice your besu-ethash-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum Node using:

It will return an output similar to the following:

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Get the logs of the running node:

Deploy a Second Node

Let's deploy another go-ethereum node, and connect it to the previous node in our private proof of work network.

In this node, we're using go-ethereum client client: geth, turning on Proof of Work mining miner: true, setting the address that will collect block reward using coinbase, and loading the miner account private key and password from kubernetes secrets privateKeySecretName: ... and passwordSecretName: .... We're connecting to the first node using staticNodes option which accepts Node name or enode url.

You can create the private key and password secrets using:

Deploy the second node using:

Kotal operator will notice your second geth-ethash-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum Nodes using:

It will return an output similar to the following:

Call JSON-RPC Method net_peerCount

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Forward localhost:8545 calls to the node pod:

In another terminal window call net_peerCount JSON-RPC method

You will get JSON result similar to the following:

Homework

Deploy a third node that uses Nethermind client, and use the third private key and address from the table above. Nethermind client is similar to geth, you will import signer account private key and password from kubernetes secrets, and use the same genesis as the other nodes.

Finally you can delete all the nodes by:

Kubernetes garbage collector will delete all the resources that has been created by Kotal Ethereum Node controller.

Requirements

• Kubernetes cluster

• Cert Manager

Kubernetes cluster

For development and testing purposes we recommend using kind (Kubernetes in Docker), it's an easy way to create and tear down kubernetes clusters in seconds. For staging and production purposes you can use any public cloud kubernetes as a service like Amazon EKS, Azure AKS or Google GKE.

kind installation guide can be found here.

Cert Manager

Cert Manager is a native Kubernetes certificate management controller. It can help with issuing certificates from a variety of sources, such as Let’s Encrypt, HashiCorp Vault, a simple signing key pair, or self-signed. It will ensure certificates are valid and up to date, and attempt to renew certificates at a configured time before expiry.

Kotal webhook component uses cert-manager for issuing certificates to default and validate your Blockchain resources such as nodes, beacon nodes, ipfs peers ... etc.

cert-manager installation guide can be found here.

Install kotal

The latest version of Kotal operator v0.3.0 can be installed into your Kubernetes cluster simply by:

kubectl apply -f https://github.com/kotalco/kotal/releases/download/v0.3.0/kotal.yaml

network

network is NEAR network to join and sync. Possible values are mainnet, testnet, and betanet.

network is immutable, it can't be changed after node is created.

nodePrivateKeySecretName

nodePrivateKeySecretName is Kubernetes secret name holding node Ed25519 private key in data field key, from which node public key is generated, and p2p messages are signed.

validatorSecretName

validatorSecretName is Kubernetes secret name holding node Ed25519 validator key in data field key.

minPeers

minPeers is the minimum number of peers to start syncing/producing blocks.

archive

archive keeps old blocks in the storage.

p2pPort

p2pPort is p2p protocol tcp port.

p2pHost

p2pHost is p2p host address.

rpc

rpc enables JSON-RPC server.

rpcPort

rpcPort is JSON-RPC server listening port.

rpcHost

rpcHost is JSON-RPC server listening host address.

prometheusPort

prometheusPort is Prometheus exporter port.

prometheusHost

prometheusHost is Prometheus exporter host address.

telemetryURL

telemetryURL is Telemetry service URL.

bootnodes

bootnodes is a list of boot nodes to bootstrap network from

resources

resources allocates compute and storage resources to the node.

memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1), 1500m, 2, and 4.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

storageClass field is immutable, it cannot be changed after creation.

network

network is Bitcoin network to join and sync. Possible values are mainnet and testnet.

network is immutable, can't be changed after node is created.

p2pPort

p2pPort is p2p communications port.

p2pHost

p2pHost is p2p communications host.

rpc

rpc enables JSON-RPC server.

rpcPort

rpcPort is JSON-RPC server port.

rpcHost

rpcHost is JSON-RPC server host.

rpcUsers

rpcUsers is a list of JSON-RPC users credentials:

wallet

wallet loads local wallet and enables wallet RPC calls.

txIndex

txIndex maintains a full transaction index.

resources

resources allocates compute and storage resources to the node.

memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1), 1500m, 2, and 4.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

storageClass field is immutable, it cannot be changed after creation.

IPFS Cluster provides data orchestration across a swarm of IPFS daemons by allocating, replicating and tracking a global pinset distributed among multiple peers. Source

Prerequisites

Before we start, you need to:

Step 1 - Deploy IPFS Peer

Deploy an ipfs peer Peer because it's required by ClusterPeer. Check our Deploy IPFS Peer tutorial.

Step 2 - Generate Cluster Secret

Create a cluster secret which secures access to the cluster:

CLUSTER_SECRET=$(openssl rand -hex 32)
kubectl create secret generic cluster-secret --from-literal=secret=$CLUSTER_SECRET

Step 3 - Generate ID and Private Key

Create cluster peer ID and private key using ipfs-key

ipfs-key -type ed25519 | base64

It will return an output similar to the following:

Generating a 2048 bit ed25519 key...
Success!
ID for generated key: 12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq
CAESQOH/DvUJmeJ9z6m3wAStpkrlBwJQxIyNSK0YGf0EI5ZRGpwsWxl4wmgReqmHl8LQjTC2iPM0QbYAjeY3Z63AFnI=

Step 4 - Deploy Private Key Secret

create Kubernetes secret from the generated private key in step(3) above.

CLUSTER_PEER_PRIVATEKEY=CAESQOH/DvUJmeJ9z6m3wAStpkrlBwJQxIyNSK0YGf0EI5ZRGpwsWxl4wmgReqmHl8LQjTC2iPM0QbYAjeY3Z63AFnI=
kubectl create secret generic cluster-peer-privatekey --from-literal=key=$CLUSTER_PEER_PRIVATEKEY

Deploying First Cluster Peer

Now we're ready to deploy the cluster peer and connect it to the peer we've deployed in step(1)

apiVersion: ipfs.kotal.io/v1alpha1
kind: ClusterPeer
metadata:
  Name: cluster-peer
spec:
  consensus: crdt
  # from step(3)
  id: "12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq"
  # from step(4)
  privateKeySecretName: cluster-peer-privatekey
  # from step(1)
  peerEndpoint: /dns4/peer-sample/tcp/5001
  # from step(2)
  clusterSecretName: cluster-secret

Let's deploy cluster peer manifest file:

kubectl apply -f cluster-peer.yaml

Kotal operator will notice your cluster-peer and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed IPFS ClusterPeer using:

kubectl get clusterpeers

It will return an output similar to the following:

NAME           CLIENT                 CONSENSUS
cluster-peer   ipfs-cluster-service   crdt

Fetch Cluster Peer Logs

Get the pods created for our cluster peer:

kubectl get pods

It will return an output similar to the following:

NAME             READY   STATUS    RESTARTS   AGE
cluster-peer-0   1/1     Running   0          2m

Check the logs of the running cluster peer:

kubectl logs -f cluster-peer-0

It will return an output similar to the following:

2021-04-30T00:31:24.109Z	INFO	service	ipfs-cluster-service/daemon.go:46	Initializing. For verbose output run with "-l debug". Please wait...
2021-04-30T00:31:24.133Z	INFO	cluster	ipfs-cluster/cluster.go:136	IPFS Cluster v0.13.2+git812c8e3631d4d6771a6e04112e12cd7726e23f7a listening on:

        /ip4/10.244.0.8/tcp/9096/p2p/12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq
        /ip4/127.0.0.1/tcp/9096/p2p/12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq

2021-04-30T00:31:24.134Z	INFO	ipfsproxy	ipfsproxy/ipfsproxy.go:320	IPFS Proxy: /ip4/127.0.0.1/tcp/9095 -> /ip4/127.0.0.1/tcp/5001
2021-04-30T00:31:24.134Z	INFO	restapi	rest/restapi.go:521	REST API (HTTP): /ip4/127.0.0.1/tcp/9094
2021-04-30T00:31:24.134Z	INFO	crdt	[email protected]/crdt.go:278	crdt Datastore created. Number of heads: 0. Current max-height: 0
2021-04-30T00:31:24.136Z	INFO	cluster	ipfs-cluster/cluster.go:651	Cluster Peers (without including ourselves):
2021-04-30T00:31:24.136Z	INFO	cluster	ipfs-cluster/cluster.go:653	    - No other peers
2021-04-30T00:31:24.136Z	INFO	cluster	ipfs-cluster/cluster.go:666	** IPFS Cluster is READY **

As you can see from the logs that our cluster peer is up and running as indicated by the healthy logs IPFS Cluster is READY.

Update Cluster Pinset

Let's add some content to the pinset by executing commands inside cluster peer container:

$ kubectl exec -it cluster-peer-0 -- sh
# now we're inside cluster-peer container

$ echo "kotal simplifies Blockchain DevOps" > kotal.txt

# add kotal.txt to the pinset
$ ipfs-cluster-ctl add kotal.txt
added QmUiwYtz1VxeryVCpTLWqrbeUi9HyGH4AnpSG6BrmdMhzL kotal.txt

# leave cluster-peer container
$ exit

Let's fetch the pinset of the ipfs peer by executing commands inside peer -created in step(1)- container:

$ kubectl exec -it peer-sample-0 -- sh
# now we're inside peer-sample container

# List objects pinned to local storage
$ ipfs pin ls
QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn recursive
QmUiwYtz1VxeryVCpTLWqrbeUi9HyGH4AnpSG6BrmdMhzL recursive

$ ipfs cat QmUiwYtz1VxeryVCpTLWqrbeUi9HyGH4AnpSG6BrmdMhzL
kotal simplifies Blockchain DevOps

# leave ipfs peer container
$ exit

As you can see, content pinned by the cluster peer, has been added to the pinset of the ipfs peer and available in its local storage.

Deploying Second Cluster Peer

The only prerequisite to the second cluster peer is to:

Step 1 - Deploy IPFS Peer

Deploy an ipfs peer Peer, and name it peer-sample-two. Check our Deploy IPFS Peer tutorial.

We will reuse cluster secret that was generated in step(2) during deploying first cluster peer above.

apiVersion: ipfs.kotal.io/v1alpha1
kind: ClusterPeer
metadata:
  Name: cluster-peer-two
spec:
  # from step(1)
  peerEndpoint: /dns4/peer-sample-twp/tcp/5001
  # generated during deploying first cluster peer in step(2)
  clusterSecretName: cluster-secret
  # first cluster peer listening address
  bootstrapPeers:
    - /ip4/cluster-peer/tcp/9096/p2p/12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq

Deploying this cluster manifest will deploy a cluster peer that connects to the first cluster peer and will connect to its own ipfs peer peer-sample-two instance.

kubectl apply -f cluster-peer-two.yaml

You can fetch the deployed cluster peers by:

kubectl get clusterpeers

It will return an output similar to the following:

NAME               CLIENT                 CONSENSUS
cluster-peer       ipfs-cluster-service   crdt
cluster-peer-two   ipfs-cluster-service   crdt

Fetch Second Cluster Peer Logs

Get the pods created by our cluster peer:

kubectl get pods

It will return an output similar to the following:

NAME                 READY   STATUS    RESTARTS   AGE
cluster-peer-0       1/1     Running   0          10m
cluster-peer-two-0   1/1     Running   0          2m

Check the logs of cluster peer two:

kubectl logs -f cluster-peer-two-0

It will return an output similar to the following:

2021-05-01T19:17:12.043Z	INFO	service	ipfs-cluster-service/daemon.go:46	Initializing. For verbose output run with "-l debug". Please wait...
2021-05-01T19:17:12.352Z	INFO	cluster	ipfs-cluster/cluster.go:136	IPFS Cluster v0.13.2+git812c8e3631d4d6771a6e04112e12cd7726e23f7a listening on:

        /ip4/10.244.0.35/tcp/9096/p2p/12D3KooWGVZek7gdarvj7gePvnV9x8ekSeSdruYojgj5dmU466Wv
        /ip4/127.0.0.1/tcp/9096/p2p/12D3KooWGVZek7gdarvj7gePvnV9x8ekSeSdruYojgj5dmU466Wv


2021-05-01T19:17:12.441Z	INFO	restapi	rest/restapi.go:521	REST API (HTTP): /ip4/127.0.0.1/tcp/9094
2021-05-01T19:17:12.441Z	INFO	ipfsproxy	ipfsproxy/ipfsproxy.go:320	IPFS Proxy: /ip4/127.0.0.1/tcp/9095 -> /ip4/127.0.0.1/tcp/5001
2021-05-01T19:17:12.441Z	INFO	service	ipfs-cluster-service/daemon.go:218	Bootstrapping to /dns4/cluster-peer/tcp/9096/p2p/12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq
2021-05-01T19:17:12.442Z	INFO	crdt	[email protected]/crdt.go:278	crdt Datastore created. Number of heads: 0. Current max-height: 0
2021-05-01T19:17:12.442Z	INFO	crdt	crdt/consensus.go:277	'trust all' mode enabled. Any peer in the cluster can modify the pinset.
2021-05-01T19:17:12.447Z	INFO	cluster	ipfs-cluster/cluster.go:651	Cluster Peers (without including ourselves):
2021-05-01T19:17:12.447Z	INFO	cluster	ipfs-cluster/cluster.go:653	    - No other peers
2021-05-01T19:17:12.448Z	INFO	cluster	ipfs-cluster/cluster.go:666	** IPFS Cluster is READY **
2021-05-01T19:17:12.551Z	INFO	cluster	ipfs-cluster/cluster.go:1020	12D3KooWGVZek7gdarvj7gePvnV9x8ekSeSdruYojgj5dmU466Wv: joined 12D3KooWBcEtY8GH4mNkri9kM3haeWhEXtQV7mi81ErWrqLYGuiq's cluster

As you can see cluster peer two is up and running as indicated by the healthy logs and IPFS Cluster is READY.

Cluster peer two has joined the first cluster peer as indicated by the highlighted log line joined 12D...uiq's cluster

Finally, delete all peers and cluster peers:

kubectl delete peers --all
kubectl delete clusterpeers --all

Kubernetes garbage collector will delete all the resources that has been created by Kotal IPFS Peer and ClusterPeer controllers.

ethereumChainId

ethereumChainId is ethereum chain id.

linkContractAddress

linkContractAddress is Link contract address.

ethereumWsEndpoint

ethereumWsEndpoint is Ethereum node's WebSocket server endpoint.

ethereumHttpEndpoints

ethereumHttpEndpoints is array of Ethereum HTTP endpoints used for heavy requests and as fallback in case of Ethereum node bug or failure.

databaseURL

databaseURL is Postgres database connection URL.

keystorePasswordSecretName

keystorePasswordSecretName is k8s secret name that holds keystore (wallet) password in data field called password.

apiCredentials

apiCredentials is the credetials used to access Chainlink node UI:

corsDomains

corsDomains is a list of domains from which to accept cross origin requests.

certSecretName

certSecretName is k8s secret name that holds TLS private key in tls.key data field and TLS certificate in tls.crt data field.

apiPort

apiPort is the port used for node API and GUI.

tlsPort

tlsPort is the port used for HTTPS connections.

p2pPort

p2pPort is the port used for p2p communcations.

secureCookies

secureCookies enables secure cookies for authentication.

logging

logging is logging verbosity level. Possible values are debug, info, warn, error, and panic.

resources

resources allocates compute and storage resources to the node.

memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1), 1500m, 2, and 4.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

storageClass field is immutable, it cannot be changed after creation.

network

network is Stacks network to join and sync. Possible values are mainnet and testnet.

network is immutable, can't be changed after node is created.

rpcPort

rpcPort is JSON-RPC server port.

rpcHost

rpcHost is JSON-RPC server host.

p2pPort

p2pPort is p2p bind port.

p2pHost

p2pHost is p2p bind host.

bitcoinNode

bitcoinNode is Bitcoin node details for Stacks node to connect and query:

miner

miner enables mining.

seedPrivateKeySecretName

seedPrivateKeySecretName is Kubernetes secret name holding seed private key used for mining.

mineMicroblocks

mineMicroblocks enables mining Stacks micro blocks.

nodePrivateKeySecretName

nodePrivateKeySecretName is Kubernetes secret name holding node private key.

resources

resources allocates compute and storage resources to the node.

memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1), 1500m, 2, and 4.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

storageClass field is immutable, it cannot be changed after creation.

Stacks node requires a Bitcoin node to connect to on the back-end for . You can deploy a Bitcoin node using Kotal operator like we did in this . In this tutorial, we will be using Bitcoin node hosted by Stacks Foundation.

Generating Miner Private Key

Generate Key chain using tool. Stacks CLI can be installed using:

Generate key chain using:

It will return an output similar to the following

Store privateKey from the output above into a Kubernetes secret in data field called key:

Bitcoin node JSON-RPC user password

Let's store Stacks Foundation Bitcoin node JSON-RPC password in a Kubernetes secret to be used by our node:

Apply bitcoin-node-rpc-password.yaml to create the password secret:

Deploy Stacks Miner Node

The following manifest describes a Stacks node that syncs Stacks mainnet network: mainnet, and connects to the bitcoin node using configurations in bitcoinNode: ... for Proof of Transfer, and loading miner private key using seedPrivateKeySecretName:

Apply stacks.yaml manifest:

Kotal operator will notice your stacks-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed Stacks Node using:

It will return an output similar to the following:

Note Miner is true in the previous output 🔥

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Get the logs of the running node:

It will return node logs similar to the following:

Finally you can delete the node by:

Kubernetes garbage collector will delete all the resources that has been created by Stacks Node controller.

We've extended Kubernetes with Node custom resource which can be used to deploy Stacks rpc and miner nodes from the given spec.

Node

Node is Stacks node using client, connecting to and syncing a specific chain, optionally mining or exposing JSON-RPC server to be used by clients.

For all the fields associated with the Node API resource:

Full Stacks node reference is documented .

In this tutorial, we will learn how to deploy a NEAR validator node, and load a validator key into it.

Generate Validator Key

Generate validator account using NEAR CLI tool. Which can be installed using:

npm install -g near-cli

near generate-key validator

An ed25519 private key will be generated and saved in current user home directory under .near-credentials/testnet

cat ~/.near-credentials/testnet/validator.json

It will return an output similar to the following

{
  "account_id": "validator",
  "public_key": "ed25519:CdTBLXMmu9gzoCbNKdUnej1tJNMz5tzRjJF2a9DwAgUr",
  "private_key": "ed25519:4k83DwbSpD3zzai4ZPdeRJcfXttU3Uq68mWWhni6ra2RKnG3jyVKEZyP14gDJZ9W1oqFujpAkidoNrYY4TLqijsG"
}

Generate Secret for Validator Private Key

Create a Kubernetes secret from the generated private key in the previous step:

kubectl create secret generic validator-key  --from-file=key=$HOME/.near-credentials/testnet/validator.json

Deploy NEAR Validator Node

The following manifest describes a NEAR node that syncs NEAR testnet network: testnet, enables HTTP JSON-RPC server rpc: true, loads validator key from the Kubernetes secret that we've created in the previous step, and uses NEAR Core client:

apiVersion: near.kotal.io/v1alpha1
kind: Node
metadata:
  name: near-node
spec:
  network: testnet
  validatorSecretName: validator-key
  rpc: true

Apply near.yaml manifest:

kubectl apply -f near.yaml

Kotal operator will notice your near-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets neccessary.

You can fetch the deployed NEAR Node using:

kubectl get nodes.near

It will return an output similar to the following:

NAME         NETWORK    CLIENT      VALIDATOR
near-node    testnet    nearcore    true

Note that validator is true in the prevous output 😇

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

kubectl get pods

It will return an output similar to the following:

NAME              READY   STATUS    RESTARTS   AGE
near-node-0       1/1     Running   0          1m

Get the logs of the running node:

kubectl logs -f near-node-0

It will return node logs similar to the following:

Apr 08 12:24:09.930  INFO neard: Version: 1.23.1, Build: 1.23.0-9-gc0551c84b-modified, Latest Protocol: 50
Apr 08 12:24:09.937  INFO near: Did not find "/home/near/kotal-data/data" path, will be creating new store database
Apr 08 12:24:10.438  INFO stats: Server listening at ed25519:[email protected]:24567
Apr 08 12:24:20.444  INFO stats: # 9820210 Downloading headers 0.00% (53273496)   5/3/40 peers ⬇ 0.7kiB/s ⬆ 0.2kiB/s 0.00 bps 0 gas/s CPU: 0%, Mem: 0 B
Apr 08 12:24:30.447  INFO stats: # 9820210 Downloading headers 0.00% (53273498)   5/3/40 peers ⬇ 0.7kiB/s ⬆ 0.2kiB/s 0.00 bps 0 gas/s CPU: 4%, Mem: 78.4 MiB
Apr 08 12:24:40.417  INFO stats: # 9820210 Downloading headers 0.00% (53273497)   5/3/40 peers ⬇ 0.7kiB/s ⬆ 0.2kiB/s 0.00 bps 0 gas/s CPU: 10%, Mem: 99.6 MiB
...

Finally you can delete the node by:

kubectl delete -f near.yaml

Kubernetes garbage collector will delete all the resources that has been created by Kotal NEAR Node controller.

Further Reading

1. Deploy NEAR stacking pool

2. Staking on NEAR

3. Upgradable staking pool

4. NEAR validator bootcamp

Deploy Node

apiVersion: filecoin.kotal.io/v1alpha1
kind: Node
metadata:
  name: calibration-node
spec:
  network: calibration

This is a simple filecoin Node that joins calibration test network.

Let's deploy the node:

kubectl apply -f calibration.yaml

Kotal operator will notice your calibration-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

kubectl get peers

It will return an output similar to the following:

NAME                NETWORK        CLIENT
calibration-node    calibration    lotus

Fetch Node Logs

Get the pods created for the node:

kubectl get pods

It will return an output similar to the following:

NAME                  READY   STATUS    RESTARTS   AGE
calibration-node-0    1/1     Running   0          5m

Check the logs of the running node:

kubectl logs -f calibration-node-0

Finally you can delete the filecoin node and all its resources by

kubectl delete -f calibration.yaml

and kubernetes garbage collector will delete all resources created by the node controller.

Peer

initProfiles

initProfiles is al list of initial ipfs configuration profile.

initialProfiles available values are server, randomports, default-datastore, local-discovery, test, default-networking, flatfs, badgerds, and lowpower.

initProfiles can't be updated (immutable).

profiles

profiles is the list of configuration profiles to apply after peer initialization.

profiles available values are server, randomports, default-datastore, local-discovery, test, default-networking, flatfs, badgerds, and lowpower.

apiHost

apiHost is API server host.

apiPort

apiPort is API server port.

gatewayHost

gatewayHost is local ipfs gateway host.

gatewayPort

gatewayPort is API server port.

routing

routing is the content routing mechanism.

routing available values are none, dht, dhtclient, dhtserver.

swarmKeySecretName

swarmKeySecretName is the kubernetes secret name that's holding the swarm key in a key called secret.

kubectl create secret generic swarm-key --from-literal=secret=$w@rmk3y

resources

resources allocates compute and storage resources to the peer.

resources object has the following fields:

Memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1 core), 1500m which is 1.5 core, 2 cores, and 4 cores.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

storageClass field is immutable, it cannot be changed after creation.

ClusterPeer

id

id is cluster peer id derived from private key.

id is required if privateKeySecretName is provided.

id can be generated using ipfs-key tool.

ipfs-key -type ed25519 | base64

It will return an output similar to the following:

Generating a 2048 bit ed25519 key...
Success!
ID for generated key: 12D3KooWT2bqgwZPxHthAGBV9Ut8ZLraz1LARtB7vG3mF26Mtof1
CAESQLepaunFGa/PI0oNS3plrbVSInqab/X/U1laEDe2V2cL/7kbF9H6x3xBiwpbVnYT/jDA8EhAznXALlbwzEsuKaw=

privateKeySecretName

privateKeySecretName is the name of the k8s secret holding base64 cluster peer privatekey in a key called key.

privateKeySecretName is required if id is provided.

privateKeySecretName can be generated using ipfs-key tool.

ipfs-key -type ed25519 | base64

It will return an output similar to the following:

Generating a 2048 bit ed25519 key...
Success!
ID for generated key: 12D3KooWT2bqgwZPxHthAGBV9Ut8ZLraz1LARtB7vG3mF26Mtof1
CAESQLepaunFGa/PI0oNS3plrbVSInqab/X/U1laEDe2V2cL/7kbF9H6x3xBiwpbVnYT/jDA8EhAznXALlbwzEsuKaw=

trustedPeers

trustedPeers is a list of peer IDs that can manage the cluster pinset in crdt consensus clusters.

trustedPeers is ignored in raft consensus clusters.

trustedPeers default value is * which is trust all peers.

bootstrapPeers

bootstrapPeers is a list of peers to connect to on startup.

consensus

consensus is the cluster consensus algorithm.

peerEndpoint

peerEndpoint id ipfs peer http API endpoint.

peerEndpoint is required for the cluster peer to function correctly.

clusterSecretName

clusterSecretName is the k8s secret name holding 32-bit hex-encoded (without 0x) cluster secret in a key called secret.

clusterSecretName can be generated using openssl tool:

CLUSTER_SECRET=$(openssl rand -hex 32)
kubectl create secret generic cluster-secret --from-literal=secret=$CLUSTER_SECRET

resources

resources allocates compute and storage resources to the peer.

resources object has the following fields:

Memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1 core), 1500m which is 1.5 core, 2 cores, and 4 cores.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

Deploy Private Network Node

Let's describe an Ethereum Node that uses a custom genesis block to join a private Proof of Authority network using ibft2 consensus configuration in the genesis block.

In this node, we're using Hyperledger besu client client: besu, enabling JSON-RPC server rpc: true so we can query number of peers later in this tutorial, and we're loading the node private key from Kubernetes secretd called besu-ibft2-nodekey.

The node private key will give the node a unique identity and node URL, and will allow the node to generate blocks, because the address 0xbAa5f05af4A67A467cEcA89085f162aFb4206Aaa that's corresponding to the node private key is in the initial block validators.

We're defining a genesis block that uses the value 4444 as network and chain identifier, and we start the chain with 3 validators as defined by spec.genesis.ibft2.validators.

This node private key secret can be created by:

Let's deploy the node:

Kotal operator will notice your besu-ibft2-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum Node using:

It will return an output similar to the following:

Fetch Node Logs

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Get the logs of the running node:

Deploy a Second Node

Let's deploy another go-ethereum node, and connect it to the previous node in our private proof of authority network.

In this node, we're using go-ethereum client client: geth, starting the PoA consensus engine miner: true, setting the second address in the genesis validators list spec.genesis.ibft2.validators as the coinbase coinbase: "0xc1381ED43B327e3C7A1ADb21285f1e9cB82Bc00d", and loading the validator account private key and password from kubernetes secrets privateKeySecretName: ... and passwordSecretName: .... We're connecting to the first node using staticNodes option which accepts Node name or enode url.

You can create the private key and password secrets using:

Deploy the second node using:

Kotal operator will notice your second geth-ibft2-node and will create all the necessary pods, persistent volumes, services, configmaps, and secrets.

You can fetch the deployed Ethereum Nodes using:

It will return an output similar to the following:

Call JSON-RPC Method net_peerCount

Get the pods that has been created by Kotal for the node:

It will return an output similar to the following:

Forward localhost:8545 calls to the node pod:

In another terminal window call net_peerCount JSON-RPC method

You will get JSON result similar to the following:

Homework

Deploy a third node that uses Nethermind client, and signing blocks using the third key in the validators list spec.genesis.ibft2.validators. Nethermind client is similar to geth, you will import validator account private key and password from kubernetes secrets, and use the same genesis as the other nodes.

Finally you can delete all the nodes by:

Kubernetes garbage collector will delete all the resources that has been created by Kotal Ethereum Node controller.

network

network is the network this node should join and sync its blockchain data.

network possible values are mainnet, and calibration.

api

api enables API server.

apiPort

apiPort is API server listening port.

apiHost

apiHost is API server host.

apiRequestTimeout

apiRequestTimeout is API request timeout in seconds.

disableMetadataLog

disableMetadataLog disables metadata logging.

p2pPort

p2pPort is p2p port.

p2pHost

p2pHost is p2p host.

ipfsPeerEndpoint

ipfsPeerEndpoint ipfs peer endpoint.

ipfsOnlineMode

ipfsOnlineMode sets sets ipfs online mode.

ipfsForRetrieval

ipfsForRetrieval uses ipfs for retrieval.

resources

resources allocates compute and storage resources to the node.

memory and storage requests and limits must use the pattern ^[1-9][0-9]*[KMGTPE]i$ for example 1500Mi, 30Gi, and 1Ti.

cpu requests and limits must use the pattern ^[1-9][0-9]*m?$ for example 1000m (which is equal to 1), 1500m, 2, and 4.

cpuLimit can't be less than cpu.

memoryLimit can't be less than or equal to memory.

storageClass field is immutable, it cannot be changed after creation.