Node

Kotal extended Kubernetes with Node custom resource in the ethereum.kotal.io/v1alpha1 group version.

apiVersion: ethereum.kotal.io/v1alpha1
kind: Node
metadata:
name: mainnet-node
spec:
client: geth
join: mainnet
rpc: true
SyntaxTypeDescriptionDefault
idnumberNetwork id used for p2p communcations between network nodes
joinstringPublic network name to join, like mainnet, rinkeby, and goerli
consensusstringNetwork consensus algorithm name, like poa, pow, and ibft2
highlyAvailablebooleanEthereum nodes will be scheduled on different kubernetes nodesfalse
topologyKeystringkubernetes node label key used to distribute ethereum nodestopology.kubernetes.io/zone
genesisobjectGenesis block configuration
bootnodebooleannode is bootnodefalse
bootnodesarrayethereum node URLS for p2p discovery bootstrap
clientstringethereum client powering the nodebesu
coinbasestringethereum account to which mining rewards are paid
corsDomainsarraydomains from which to accept cross origin requests (browser enforced)*
graphqlbooleanenable GraphQL serverfalse
graphqlPortnumberGraphQL server listening port8547
hostsarrayhostnames to whitelist for RPC access (server enforced)*
importobjectethereum account to import for geth node
loggingstringnode logging verbosity levelinfo
minerbooleannode is mining or signing blocks ?false
namestringnode name
nodekeystringnode private key
p2pPortstringnode p2p port30303
resourcesobjectnode compute and storage resources to alloacte
rpcbooleanenable HTTP RPC serverfalse
rpcPortnumberHTTP RPC server listening port8545
rpcAPIarrayservices to enableweb3, eth, and net
staticNodesarrayset of trusted ethereum nodes to maintain connection to
syncModestringblockchain synchronization modefast in public, full in private
wsbooleanenable web socket serverfalse
wsPortnumberweb socket server listening port8546
wsAPIarrayservices to enableweb3, eth, and net

id#

note

If the node is created by a Network controller, the network .spec.id will be used, and node .spec.id will be ignored.

id is the network id used for p2p communications between network nodes in private networks.

id is required in private networks.

id can't be provided while joining a public network.

id can't be updated (immutable).

join#

note

If the node is created by a Network controller, the network .spec.join will be used, and node .spec.join will be ignored.

join is the public network name to join, like rinkeby.

join can't be provided in private networks.

join can't be updated (immutable).

consensus#

note

If the node is created by a Network controller, the network .spec.consensus will be used, and node .spec.consensus will be ignored.

consensus is the network consensus algorithm name, like ibft2.

consensus is required in private networks.

consensus possible values are poa, pow or ibft2.

consensus can't be updated (immutable).

highly available#

note

If the node is created by a Network controller, the network .spec.highlyAvailable will be used, and node .spec.highlyAvailable will be ignored.

highlyAvailable controls if Ethereum nodes will be scheduled on different Kubernetes nodes.

topology key#

note

If the node is created by a Network controller, the network .spec.topologyKey will be used, and node .spec.topologyKey will be ignored.

topologyKey is Kubernetes node label key used to distribute ethereum nodes pods on different kubernetes nodes.

genesis#

note

If the node is created by a Network controller, the network .spec.genesis will be used, and node .spec.genesis will be ignored.

genesis is the genesis block configuration.

genesis block is required in private networks.

genesis can't be updated (immutable).

For extensive details, check genesis reference.

bootnode#

bootnode marks the node as a boot node.

The first node in the spec.nodes list must be a bootnode with bootnode: true

Bootnodes must use node private key, check nodekey.

bootnodes#

bootnodes is ethereum node URLs for p2p network discovery bootstrap.

warning

Each Ethereum clients has hardcoded bootnodes for public main and test networks. bootnodes will override these bootnodes.

client#

client is the Ethereum client name powering the node.

client possible values are besu, geth or parity.

Client geth or parity can't be used if network consensus is ibft2.

Client geth or parity can't be used in fixed difficulty proof of work networks, where spec.consensus is pow and spec.genesis.ethash.fixedDifficulty is not null.

coinbase#

coinbase is ethereum account to which mining rewards are paid.

coinbase is required if the node is mining miner: true.

corsDomains#

corsDomains is a list of domains from which to accept cross-origin requests (browser enforced).

Default value * will be used if HTTP RPC server is enabled rpc: true or web socket server is enabled ws: true or graphQL server is enabled graphql: true.

graphql#

graphql enables the GraphQL server.

note
  • Parity (OpenEthereum) client doesn't support GraphQL.
  • Geth (Go-Ethereum) GraphQL server can be used only if RPC is enabled as of geth v1.9.19 release

graphqlPort#

graphqlPort GraphQL server listening port.

The default value 8547 will be used if the graphQL server is enabled graphql: true.

hosts#

hosts is a list of host names to whitelist for RPC access (server enforced).

import#

import is the ethereum account to import. Only for nodes running with geth or parity clients.

During account creation, it will be encrypted with the password, and during import it will be unlocked using the same password.

๐Ÿ Nodes that import accounts can't enable HTTP RPC server, web socket server, or GraphQL server to prevent funds drainage if exposed to the internet.

Account must be imported if the node is running with geth or parity clients wants to be a signer in proof of authority clique network.

SyntaxTypeDescription
privatekeystringaccount private key in hexadecimal
passwordstringencryption secret

logging#

logging is Ethereum node logging verbosity level.

logging possible values are off, fatal, error, warn, debug, info, trace and all.

Different clients support different logging vrbosity levels as shown in the following table:

Logging/ClientHyperledger BesuGo EthereumParity (OpenEthereum)
offโœ”๏ธโœ”๏ธโŒ
fatalโœ”๏ธโŒโŒ
errorโœ”๏ธโœ”๏ธโœ”๏ธ
warnโœ”๏ธโœ”๏ธโœ”๏ธ
debugโœ”๏ธโœ”๏ธโœ”๏ธ
infoโœ”๏ธโœ”๏ธโœ”๏ธ
traceโœ”๏ธโŒโœ”๏ธ
allโœ”๏ธโœ”๏ธโŒ

miner#

miner enables node mining or signing blocks.

note

Parity (OpenEthereum) client doesn't support PoW mining.

name#

name is the node name.

name is required.

name can't be updated (immutable).

nodekey#

nodekey is the node private key.

nodekey is required if the node is a boot node bootnode: true, or if besu node with client: besu is a signer in proof of authority clique network or validator in ibft2 network.

p2pPort#

p2pPort is node p2p port for communication (TCP) and discovery (UDP).

resources#

resources allocates compute and storage resources to the node.

SyntaxTypeDescriptionDefault
cpustringnumber of cpu cores this node requires2 in private, 4 in public
cpuLimitstringnumber of cpu cores this node is limited to3 in private, 6 in public
memorystringmemory this node requires4Gi in private, 8Gi in public
memoryLimitstringmemory this node is limited to8Gi in private, 16Gi in public
storagestringdisk space this node requires100Gi in private, 6Ti in mainnet with full sync, 750Gi in mainnet wit fast sync, 25Gi in public test networks
storageClassstringNode volume storage classCluster's default storage class will be used as defined by cluster admin or cloud provider

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

cpu requests and limits must have 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 memory.

rpc#

rpc enables the HTTP RPC server.

rpcPort#

rpcPort is the HTTP RPC server listening port.

Default value 8545 will be used if the HTTP RPC server is enabled with rpc: true.

rpcAPI#

rpcAPI is a list of RPC services to enable.

Default value ["web3", "eth", "net] will be used if HTTP RPC server is enabeld with rpc: true.

staticNodes#

staticNodes is a set of trusted ethereum nodes to maintain connection to

info

Static nodes are exempt from maximum peer and remote connection limits. Ethereum clients periodically initiating a connection to any unconnected static node.

syncMode#

syncMode is Blockchain synchronization mode.

syncMode possible values are light, full or fast.

๐Ÿ Nodes that run with client: besu doesn't support light sync mode.

ws#

ws enables the web socket server.

wsPort#

wsPort is the web socket server listening port.

The default value 8546 is used if the web socket server is enabled with ws: true.

wsAPI#

wsAPI is a list of rpc services to enable.

the default value ["web3", "eth", "net] will be used if the web socket server is enabeld with ws: true.