tmpnet

package
v1.18.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2025 License: BSD-3-Clause Imports: 83 Imported by: 0

README

tmpnet - temporary network orchestration

This package implements a simple orchestrator for the node nodes of a temporary network. Configuration is stored on disk, and nodes run as independent processes whose process details are also written to disk. Using the filesystem to store configuration and process details allows for the tmpnetctl cli and e2e test fixture to orchestrate the same temporary networks without the use of an rpc daemon.

What's in a name?

The name of this package was originally testnet and its cli was testnetctl. This name was chosen in ignorance that testnet commonly refers to a persistent blockchain network used for testing.

To avoid confusion, the name was changed to tmpnet and its cli tmpnetctl. tmpnet is short for temporary network since the networks it deploys are likely to live for a limited duration in support of the development and testing of node and its related repositories.

Package details

The functionality in this package is grouped by logical purpose into the following non-test files:

Filename Types Purpose
defaults.go Defines common default configuration
flags.go FlagsMap Simplifies configuration of node flags
genesis.go Creates test genesis
network.go Network Orchestrates and configures temporary networks
network_config.go Network Reads and writes network configuration
node.go Node Orchestrates and configures nodes
node_config.go Node Reads and writes node configuration
node_process.go NodeProcess Orchestrates node processes
subnet.go Subnet Orchestrates subnets
utils.go Defines shared utility functions

Usage

Via tmpnetctl

A temporary network can be managed by the tmpnetctl cli tool:

# From the root of the node repo

# Build the tmpnetctl binary
$ ./scripts/build_tmpnetctl.sh

# Start a new network. Possible to specify the number of nodes (> 1) with --node-count.
$ ./build/tmpnetctl start-network --node-path=/path/to/node
...
Started network /home/me/.tmpnet/networks/20240306-152305.924531 (UUID: abaab590-b375-44f6-9ca5-f8a6dc061725)

Configure tmpnetctl to target this network by default with one of the following statements:
 - source /home/me/.tmpnet/networks/20240306-152305.924531/network.env
 - export TMPNET_NETWORK_DIR=/home/me/.tmpnet/networks/20240306-152305.924531
 - export TMPNET_NETWORK_DIR=/home/me/.tmpnet/networks/latest

# Stop the network
$ ./build/tmpnetctl stop-network --network-dir=/path/to/network

Note the export of the path ending in latest. This is a symlink that is set to the last network created by tmpnetctl start-network. Setting the TMPNET_NETWORK_DIR env var to this symlink ensures that tmpnetctl commands target the most recently deployed temporary network.

Deprecated usage with e2e suite

tmpnetctl was previously used to create temporary networks for use across multiple e2e test runs. As the usage of temporary networks has expanded to require subnets, that usage has been supplanted by the --reuse-network flag defined for the e2e suite. It was easier to support defining subnet configuration in the e2e suite in code than to extend a cli tool like tmpnetctl to support similar capabilities.

Via code

A temporary network can be managed in code:

network := &tmpnet.Network{                   // Configure non-default values for the new network
    DefaultFlags: tmpnet.FlagsMap{
        config.LogLevelKey: "INFO",           // Change one of the network's defaults
    },
    Nodes: tmpnet.NewNodesOrPanic(5),           // Number of initial validating nodes
    Subnets: []*tmpnet.Subnet{                // Subnets to create on the new network once it is running
        {
            Name: "xsvm-a",                   // User-defined name used to reference subnet in code and on disk
            Chains: []*tmpnet.Chain{
                {
                    VMName: "xsvm",           // Name of the VM the chain will run, will be used to derive the name of the VM binary
                    Genesis: <genesis bytes>, // Genesis bytes used to initialize the custom chain
                    PreFundedKey: <key>,      // (Optional) A private key that is funded in the genesis bytes
                },
            },
            ValidatorIDs: <node ids>,         // The IDs of nodes that validate the subnet
        },
    },
}

_ := tmpnet.BootstrapNewNetwork(          // Bootstrap the network
    ctx,                                  // Context used to limit duration of waiting for network health
    ginkgo.GinkgoWriter,                  // Writer to report progress of initialization
    network,
    "",                                   // Empty string uses the default network path (~/tmpnet/networks)
    "/path/to/node",               // The path to the binary that nodes will execute
    "/path/to/plugins",                   // The path nodes will use for plugin binaries (suggested value ~/.node/plugins)
)

uris := network.GetNodeURIs()

// Use URIs to interact with the network

// Stop all nodes in the network
network.Stop(context.Background())

Networking configuration

By default, nodes in a temporary network will be started with staking and API ports set to 0 to ensure that ports will be dynamically chosen. The tmpnet fixture discovers the ports used by a given node by reading the [base-data-dir]/process.json file written by node on node start. The use of dynamic ports supports testing with many temporary networks without having to manually select compatible port ranges.

Configuration on disk

A temporary network relies on configuration written to disk in the following structure:

HOME
└── .tmpnet                                              // Root path for the temporary network fixture
    ├── prometheus                                       // Working directory for a metrics-scraping prometheus instance
    │   └── file_sd_configs                              // Directory containing file-based service discovery config for prometheus
    ├── promtail                                         // Working directory for a log-collecting promtail instance
    │   └── file_sd_configs                              // Directory containing file-based service discovery config for promtail
    └── networks                                         // Default parent directory for temporary networks
        └── 20240306-152305.924531                       // The timestamp of creation is the name of a network's directory
            ├── NodeID-37E8UK3x2YFsHE3RdALmfWcppcZ1eTuj9 // The ID of a node is the name of its data dir
            │   ├── chainData
            │   │   └── ...
            │   ├── config.json                          // Node runtime configuration
            │   ├── db
            │   │   └── ...
            │   ├── flags.json                           // Node flags
            │   ├── logs
            │   │   └── ...
            │   ├── plugins
            │   │   └── ...
            │   └── process.json                         // Node process details (PID, API URI, staking address)
            ├── chains
            │   ├── C
            │   │   └── config.json                      // C-Chain config for all nodes
            │   └── raZ51bwfepaSaZ1MNSRNYNs3ZPfj...U7pa3
            │       └── config.json                      // Custom chain configuration for all nodes
            ├── config.json                              // Common configuration (including defaults and pre-funded keys)
            ├── genesis.json                             // Genesis for all nodes
            ├── network.env                              // Sets network dir env var to simplify network usage
            └── subnets                                  // Directory containing subnet config for both node and tmpnet
                ├── subnet-a.json                        // tmpnet configuration for subnet-a and its chain(s)
                ├── subnet-b.json                        // tmpnet configuration for subnet-b and its chain(s)
                └── 2jRbWtaonb2RP8DEM5DBsd7o2o8d...RqNs9 // The ID of a subnet is the name of its configuration dir
                    └── config.json                      // node configuration for subnet
Common networking configuration

Network configuration such as default flags (e.g. --log-level=), runtime defaults (e.g. node path) and pre-funded private keys are stored at [network-dir]/config.json. A given default will only be applied to a new node on its addition to the network if the node does not explicitly set a given value.

Genesis

The genesis file is stored at [network-dir]/genesis.json and referenced by default by all nodes in the network. The genesis file content will be generated with reasonable defaults if not supplied. Each node in the network can override the default by setting an explicit value for --genesis-file or --genesis-file-content.

Chain configuration

The chain configuration for a temporary network is stored at [network-dir]/chains/[chain alias or ID]/config.json and referenced by all nodes in the network. The C-Chain config will be generated with reasonable defaults if not supplied. X-Chain and P-Chain will use implicit defaults. The configuration for custom chains can be provided with subnet configuration and will be writen to the appropriate path.

Each node in the network can override network-level chain configuration by setting --chain-config-dir to an explicit value and ensuring that configuration files for all chains exist at [custom-chain-config-dir]/[chain alias or ID]/config.json.

Network env

A shell script that sets the TMPNET_NETWORK_DIR env var to the path of the network is stored at [network-dir]/network.env. Sourcing this file (i.e. source network.env) in a shell will configure ginkgo e2e and the tmpnetctl cli to target the network path specified in the env var.

Set TMPNET_ROOT_DIR to specify the root directory in which to create the configuration directory of new networks (e.g. $TMPNET_ROOT_DIR/[network-dir]). The default root directory is ~/.tmpdir/networks. Configuring the root directory is only relevant when creating new networks as the path of existing networks will already have been set.

Node configuration

The data dir for a node is set by default to [network-path]/[node-id]. A node can be configured to use a non-default path by explicitly setting the --data-dir flag.

Runtime config

The details required to configure a node's execution are written to [network-path]/[node-id]/config.json. This file contains the runtime-specific details like the path of the node binary to start the node with.

Flags

All flags used to configure a node are written to [network-path]/[node-id]/flags.json so that a node can be configured with only a single argument: --config-file=/path/to/flags.json. This simplifies node launch and ensures all parameters used to launch a node can be modified by editing the config file.

Process details

The process details of a node are written by node to [base-data-dir]/process.json. The file contains the PID of the node process, the URI of the node's API, and the address other nodes can use to bootstrap themselves (aka staking address).

Monitoring

Monitoring is an essential part of understanding the workings of a distributed system such as node. The tmpnet fixture enables collection of logs and metrics from temporary networks to a monitoring stack (prometheus+loki+grafana) to enable results to be analyzed and shared.

Example usage
# Start prometheus to collect metrics
PROMETHEUS_ID=<id> PROMETHEUS_PASSWORD=<password> ./scripts/run_prometheus.sh

# Start promtail to collect logs
LOKI_ID=<id> LOKI_PASSWORD=<password> ./scripts/run_promtail.sh

# Network start emits link to grafana displaying collected logs and metrics
./build/tmpnetctl start-network
Metrics collection

When a node is started, configuration enabling collection of metrics from the node is written to ~/.tmpnet/prometheus/file_sd_configs/[network uuid]-[node id].json.

The scripts/run_prometheus.sh script starts prometheus in agent mode configured to scrape metrics from configured nodes and forward the metrics to a persistent prometheus instance. The script requires that the PROMETHEUS_ID and PROMETHEUS_PASSWORD env vars be set. By default the prometheus instance at https://prometheus-experimental.lux-dev.network will be targeted and this can be overridden via the PROMETHEUS_URL env var.

Log collection

Nodes log are stored at ~/.tmpnet/networks/[network id]/[node id]/logs by default, and can optionally be forwarded to loki with promtail.

When a node is started, promtail configuration enabling collection of logs for the node is written to ~/.tmpnet/promtail/file_sd_configs/[network uuid]-[node id].json.

The scripts/run_promtail.sh script starts promtail configured to collect logs from configured nodes and forward the results to loki. The script requires that the LOKI_ID and LOKI_PASSWORD env vars be set. By default the loki instance at https://loki-experimental.lux-dev.network will be targeted and this can be overridden via the LOKI_URL env var.

Labels

The logs and metrics collected for temporary networks will have the following labels applied:

  • network_uuid
    • uniquely identifies a network across hosts
  • node_id
  • is_ephemeral_node
    • 'ephemeral' nodes are expected to run for only a fraction of the life of a network
  • network_owner
    • an arbitrary string that can be used to differentiate results when a CI job runs more than one network

When a network runs as part of a github CI job, the following additional labels will be applied:

  • gh_repo
  • gh_workflow
  • gh_run_id
  • gh_run_number
  • gh_run_attempt
  • gh_job_id

These labels are sourced from Github Actions' github context as per https://docs.github.com/en/actions/learn-github-actions/contexts#github-context.

Viewing
Local networks

When a network is started with tmpnet, a link to the default grafana instance will be emitted. The dashboards will only be populated if prometheus and promtail are running locally (as per previous sections) to collect metrics and logs.

CI

Collection of logs and metrics is enabled for CI jobs that use tmpnet. Each job will execute a step titled Notify of metrics availability that emits a link to grafana parametized to show results for the job. Additional links to grafana parametized to show results for individual network will appear in the logs displaying the start of those networks.

Documentation

Index

Constants

View Source 
const (
	DefaultNodeCount      = 2 // Minimum required to ensure connectivity-based health checks will pass
	DefaultFundedKeyCount = 50

	DefaultGasLimit = uint64(100_000_000) // Gas limit is arbitrary

	// Arbitrarily large amount of LUX to fund keys on the X-Chain for testing
	DefaultFundedKeyXChainAmount = 30 * units.MegaLux

	// A short min stake duration enables testing of staking logic.
	DefaultMinStakeDuration = time.Second

	// RootNetworkDirEnvName is the environment variable for the root network directory
	RootNetworkDirEnvName = "TMPNET_ROOT_DIR"
)
View Source 
const (
	// Interval appropriate for network operations that should be
	// retried periodically but not too often.
	DefaultPollingInterval = 500 * time.Millisecond

	// Validator start time must be a minimum of SyncBound from the
	// current time for validator addition to succeed, and adding 20
	// seconds provides a buffer in case of any delay in processing.
	DefaultValidatorStartTimeDiff = executor.SyncBound + 20*time.Second

	DefaultNetworkTimeout = 2 * time.Minute

	// Arbitrary number of pre-funded keys to create by default
	DefaultPreFundedKeyCount = 50
)
View Source 
const (
	// Constants defining the names of shell variables whose value can
	// configure network orchestration.
	NetworkDirEnvName = "TMPNET_NETWORK_DIR"
	RootDirEnvName    = "TMPNET_ROOT_DIR"

	// eth address: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
	HardHatKeyStr = "56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027"
)
View Source 
const (
	AvalancheGoPathEnvName = "LUXD_PATH"
)
View Source 
const (
	DefaultNodeTickerInterval = 50 * time.Millisecond
)
View Source 
const (
	LuxNodePathEnvName = "LUXD_PATH"
)
View Source 
const (

	// 2GB is the minimum size of a PersistentVolumeClaim used for a node's data directory:
	// - A value greater than 1GB must be used
	//   - A node will report unhealthy if it detects less than 1GiB available
	// - EBS volume sizes are in GB
	//   - The minimum number greater than 1GB is 2GB
	MinimumVolumeSizeGB = 2
)
View Source 
const (

	// Use a delay slightly longer than the scrape interval to ensure a final scrape before shutdown
	NetworkShutdownDelay = prometheusScrapeInterval + 2*time.Second
)

Variables

View Source 
var (
	ErrNotRunning = errors.New("not running")

	// MetricsAvailableMessage is the message logged when metrics are available
	MetricsAvailableMessage = "Metrics available"
)
View Source 
var (
	AvalancheGoPluginDirEnvName = config.EnvVarName(config.EnvPrefix, config.PluginDirKey)
)
View Source 
var (
	// Arbitrarily large amount of LUX (10^12) to fund keys on the C-Chain for testing
	DefaultFundedKeyCChainAmount = new(big.Int).Exp(big.NewInt(10), big.NewInt(30), nil)
)
View Source 
var DefaultKubeRuntimeConfig = &KubeRuntimeConfig{
	Namespace:    "default",
	VolumeSizeGB: 10,
	Image:        "luxfi/luxd:latest",
}
View Source 
var (
	// Key expected to be funded for net-evm hardhat testing
	// TODO(marun) Remove when net-evm configures the genesis with this key.
	HardhatKey *secp256k1.PrivateKey
)

Functions

func BootstrapNewNetwork 

func BootstrapNewNetwork(
	ctx context.Context,
	w io.Writer,
	network *Network,
	rootNetworkDir string,
	luxNodeExecPath string,
	pluginDir string,
) error

func CheckLogsExist 

func CheckLogsExist(ctx context.Context, log log.Logger, networkUUID string) error

CheckLogsExist checks if logs exist for the given network. If no network UUID is provided, an attempt will be made to derive selectors from env vars (GH_*) identifying a github actions run.

func CheckMetricsExist 

func CheckMetricsExist(ctx context.Context, log log.Logger, networkUUID string) error

CheckMetricsExist checks if metrics exist for the given network. Github labels are also used as filters if provided as env vars (GH_*).

func CheckNodeHealth 

func CheckNodeHealth(ctx context.Context, uri string) (*health.APIReply, error)

CheckNodeHealth checks if a node is healthy

func DefaultChainConfigs 

func DefaultChainConfigs() map[string]FlagsMap

A set of chain configurations appropriate for testing.

func DefaultJSONMarshal 

func DefaultJSONMarshal(v interface{}) ([]byte, error)

Marshal to json with default prefix and indent.

func DefaultPodFlags 

func DefaultPodFlags(networkName string, dataDir string) map[string]string

DefaultPodFlags defines common flags for luxd nodes running in a pod.

func EnvVarName added in v1.11.14 

func EnvVarName(prefix, key string) string

EnvVarName returns the environment variable name for a given prefix and key

func GetClientConfig 

func GetClientConfig(log log.Logger, path string, context string) (*restclient.Config, error)

GetClientConfig replicates the behavior of clientcmd.BuildConfigFromFlags with zap logging and support for an optional config context. If path is not provided, use of in-cluster config will be attempted.

func GetClientset 

func GetClientset(log log.Logger, path string, context string) (*kubernetes.Clientset, error)

GetClientset returns a kubernetes clientset for the provided kubeconfig path and context.

func GetEnvWithDefault 

func GetEnvWithDefault(key, defaultValue string) string

GetEnvWithDefault gets an environment variable with a default value

func GetEthAddress added in v1.1.11 

func GetEthAddress(key *secp256k1.PrivateKey) common.Address

GetEthAddress converts a secp256k1 private key to an Ethereum address (exported version)

func GetGitHubLabels 

func GetGitHubLabels() map[string]string

func GetNodeWebsocketURIs 

func GetNodeWebsocketURIs(nodes []*Node, blockchainID ids.ID) ([]string, error)

GetNodeWebsocketURIs returns websocket URIs for nodes (stub)

func GetPrometheusServiceDiscoveryDir 

func GetPrometheusServiceDiscoveryDir() (string, error)

GetPrometheusServiceDiscoveryDir returns the path for prometheus file-based service discovery configuration.

func GetReusableNetworkPathForOwner 

func GetReusableNetworkPathForOwner(owner string) (string, error)

Retrieves the path to a reusable network path for the given owner.

func IsRunningInCluster 

func IsRunningInCluster() bool

IsRunningInCluster detects if this code is running inside a Kubernetes cluster by checking for the presence of the service account token that's automatically mounted in every pod.

func MetricsLinkForNetwork 

func MetricsLinkForNetwork(networkUUID, startTime, endTime string) string

MetricsLinkForNetwork returns a metrics link for the given network UUID and time range

func NewNodeStatefulSet 

func NewNodeStatefulSet(
	name string,
	generateName bool,
	imageName string,
	containerName string,
	volumeName string,
	volumeSize string,
	volumeMountPath string,
	flags FlagsMap,
	labels map[string]string,
) *appsv1.StatefulSet

NewNodeStatefulSet returns a statefulset for an luxd node.

func NewPrivateKeys 

func NewPrivateKeys(keyCount int) ([]*secp256k1.PrivateKey, error)

Helper simplifying creation of a set of private keys

func NewTestGenesis 

func NewTestGenesis(
	networkID uint32,
	xChainBalances XChainBalanceMap,
	cChainBalances core.GenesisAlloc,
	validatorIDs []ids.NodeID,
) (*genesis.UnparsedConfig, error)

Create a genesis struct valid for bootstrapping a test network. Note that many of the genesis fields (e.g. reward addresses) are randomly generated or hard-coded.

func NewTestGenesisWithFunds added in v1.1.11 

func NewTestGenesisWithFunds(
	networkID uint32,
	nodes []*Node,
	keysToFund []*secp256k1.PrivateKey,
) (*genesis.UnparsedConfig, error)

Create a genesis struct valid for bootstrapping a test network. Note that many of the genesis fields (e.g. reward addresses) are randomly generated or hard-coded.

func NodesToIDs 

func NodesToIDs(nodes ...*Node) []ids.NodeID

func RestartNetwork 

func RestartNetwork(ctx context.Context, w io.Writer, dir string) error

Restarts the nodes of the network configured in the provided directory.

func StartPrometheus 

func StartPrometheus(ctx context.Context, log log.Logger) error

StartPrometheus ensures prometheus is running to collect metrics from local nodes.

func StartPromtail 

func StartPromtail(ctx context.Context, log log.Logger) error

StartPromtail ensures promtail is running to collect logs from local nodes.

func StopLogsCollector 

func StopLogsCollector(ctx context.Context, log log.Logger) error

StopLogsCollector ensures promtail is not running.

func StopMetricsCollector 

func StopMetricsCollector(ctx context.Context, log log.Logger) error

StopMetricsCollector ensures prometheus is not running.

func StopNetwork 

func StopNetwork(ctx context.Context, dir string) error

Stops the nodes of the network configured in the provided directory.

func WaitForHealthy added in v1.1.11 

func WaitForHealthy(ctx context.Context, node *Node) error

WaitForHealthy blocks until Node.IsHealthy returns true or an error (including context timeout) is observed.

func WaitForNodeHealthy 

func WaitForNodeHealthy(
	ctx context.Context,
	log log.Logger,
	kubeconfig *restclient.Config,
	namespace string,
	podName string,
	healthCheckInterval time.Duration,
	out io.Writer,
	outErr io.Writer,
) (ids.NodeID, error)

WaitForNodeHealthy waits for the node running in the specified pod to report healthy.

func WaitForPodCondition 

func WaitForPodCondition(ctx context.Context, clientset *kubernetes.Clientset, namespace string, podName string, conditionType corev1.PodConditionType) error

WaitForPodCondition watches the specified pod until the status includes the specified condition.

func WaitForPodStatus 

func WaitForPodStatus(
	ctx context.Context,
	clientset *kubernetes.Clientset,
	namespace string,
	name string,
	acceptable func(*corev1.PodStatus) bool,
) error

WaitForPodStatus watches the specified pod until the status is deemed acceptable by the provided test function.

func WaitForPromtailReadiness 

func WaitForPromtailReadiness(ctx context.Context, log log.Logger) error

WaitForPromtailReadiness waits until prometheus is ready. It can only succeed after one or more nodes have written their service discovery configuration.

func WritePrometheusSDConfig 

func WritePrometheusSDConfig(name string, sdConfig SDConfig, withGitHubLabels bool) (string, error)

WritePrometheusSDConfig writes the SDConfig with the provided name to the location expected by the prometheus instance start by tmpnet.

If withGitHubLabels is true, checks env vars for GitHub-specific labels and adds them as labels if present before writing the SDConfig.

Returns the path to the written configuration file.

Types

type Chain 

type Chain struct {
	// Set statically
	VMID    ids.ID
	Config  string
	Genesis []byte

	// Set at runtime
	ChainID      ids.ID
	PreFundedKey *secp256k1.PrivateKey
}

func (*Chain) WriteConfig added in v1.1.11 

func (c *Chain) WriteConfig(chainDir string) error

Write the chain configuration to the specified directory.

type FlagsMap 

type FlagsMap map[string]string

Defines a mapping of flag keys to values intended to be supplied to an invocation of an AvalancheGo node.

func DefaultTestFlags added in v1.1.11 

func DefaultTestFlags() FlagsMap

Flags appropriate for networks used for all types of testing.

func DefaultTmpnetFlags 

func DefaultTmpnetFlags() FlagsMap

Flags appropriate for tmpnet networks.

func ReadFlagsMap 

func ReadFlagsMap(path string, description string) (FlagsMap, error)

Utility function simplifying construction of a FlagsMap from a file.

func (FlagsMap) GetStringVal added in v1.1.11 

func (f FlagsMap) GetStringVal(key string) (string, error)

GetStringVal simplifies retrieving a map value as a string.

func (FlagsMap) SetDefault 

func (f FlagsMap) SetDefault(key string, value string)

SetDefault ensures the effectiveness of a flag override by only setting a value supplied whose key is not already explicitly set.

func (FlagsMap) SetDefaults 

func (f FlagsMap) SetDefaults(defaults FlagsMap)

SetDefaults ensures the effectiveness of flag overrides by only setting values supplied in the defaults map that are not already explicitly set.

func (FlagsMap) Write 

func (f FlagsMap) Write(path string, description string) error

Write simplifies writing a FlagsMap to the provided path. The description is used in error messages.

type KubeRuntime 

type KubeRuntime struct {
	// contains filtered or unexported fields
}

func (*KubeRuntime) GetAccessibleStakingAddress added in v1.11.14 

func (p *KubeRuntime) GetAccessibleStakingAddress(ctx context.Context) (netip.AddrPort, func(), error)

GetAccessibleStakingAddress retrieves a StakingAddress for the node intended to be accessible from this process until the provided cancel function is called.

func (*KubeRuntime) GetAccessibleURI added in v1.11.14 

func (p *KubeRuntime) GetAccessibleURI() string

GetAccessibleURI retrieves a URI for the node accessible from where this process is running. If the process is running inside a kube cluster, the node and the process will be assumed to be running in the same kube cluster and the node's URI be used. If the process is running outside of a kube cluster, a URI accessible from outside of the cluster will be used.

func (*KubeRuntime) InitiateStop 

func (p *KubeRuntime) InitiateStop(ctx context.Context) error

Stop the Pod by setting the replicas to zero on the StatefulSet.

func (*KubeRuntime) IsHealthy 

func (p *KubeRuntime) IsHealthy(ctx context.Context) (bool, error)

IsHealthy checks if the node is running and healthy.

func (*KubeRuntime) Restart 

func (p *KubeRuntime) Restart(ctx context.Context) error

Restarts the node. Does not wait for readiness or health.

func (*KubeRuntime) Start 

func (p *KubeRuntime) Start(ctx context.Context) error

Start the node as a Kubernetes StatefulSet.

func (*KubeRuntime) WaitForStopped 

func (p *KubeRuntime) WaitForStopped(ctx context.Context) error

Waits for the node process to stop. TODO(marun) Consider using a watch instead

type KubeRuntimeConfig 

type KubeRuntimeConfig struct {
	// Path to the kubeconfig file identifying the target cluster
	ConfigPath string `json:"configPath,omitempty"`
	// The context of the kubeconfig file to use
	ConfigContext string `json:"configContext,omitempty"`
	// Namespace in the target cluster in which resources will be
	// created. For simplicity all nodes are assumed to be deployed to
	// the same namespace to ensure network connectivity.
	Namespace string `json:"namespace,omitempty"`
	// The docker image to run for the node
	Image string `json:"image,omitempty"`
	// Size in gigabytes of the PersistentVolumeClaim  to allocate for the node
	VolumeSizeGB uint `json:"volumeSizeGB,omitempty"`
	// Whether to schedule each Luxd node to a dedicated Kubernetes node
	UseExclusiveScheduling bool `json:"useExclusiveScheduling,omitempty"`
	// Label key to use for exclusive scheduling for node selection and toleration
	SchedulingLabelKey string `json:"schedulingLabelKey,omitempty"`
	// Label value to use for exclusive scheduling for node selection and toleration
	SchedulingLabelValue string `json:"schedulingLabelValue,omitempty"`
	// Host for ingress rules (e.g., "localhost:30791" for kind, "tmpnet.example.com" for EKS)
	IngressHost string `json:"ingressHost,omitempty"`
	// TLS secret name for ingress (empty for HTTP, populated for HTTPS)
	IngressSecret string `json:"ingressSecret,omitempty"`
}

type Net added in v1.17.2 

type Net struct {
	// A unique string that can be used to refer to the net across different temporary
	// networks (since the NetID will be different every time the net is created)
	Name string

	Config FlagsMap

	// The ID of the transaction that created the subnet
	NetID ids.ID

	// The private key that owns the subnet
	OwningKey *secp256k1.PrivateKey

	// IDs of the nodes responsible for validating the subnet
	ValidatorIDs []ids.NodeID

	Chains []*Chain
}

type Network 

type Network struct {
	// Uniquely identifies the temporary network for metrics
	// collection. Distinct from node's concept of network ID
	// since the utility of special network ID values (e.g. to trigger
	// specific fork behavior in a given network) precludes requiring
	// unique network ID values across all temporary networks.
	UUID string

	// A string identifying the entity that started or maintains this
	// network. Useful for differentiating between networks when a
	// given CI job uses multiple networks.
	Owner string

	// Path where network configuration and data is stored
	Dir string

	// Id of the network. If zero, must be set in Genesis.
	NetworkID uint32

	// Genesis for the network. If nil, NetworkID must be non-zero
	Genesis *genesis.UnparsedConfig

	// Configuration for primary network chains (P, X, C)
	// TODO(marun) Rename to PrimaryChainConfigs
	ChainConfigs map[string]FlagsMap

	// Default configuration to use when creating new nodes
	DefaultFlags         FlagsMap
	DefaultRuntimeConfig NodeRuntimeConfig

	// Keys pre-funded in the genesis on both the X-Chain and the C-Chain
	PreFundedKeys []*secp256k1.PrivateKey

	// Nodes that constitute the network
	Nodes []*Node

	// Subnets that have been enabled on the network
	Subnets []*Subnet
}

Collects the configuration for running a temporary node network

func LocalNetworkOrPanic 

func LocalNetworkOrPanic() *Network

func NewDefaultNetwork 

func NewDefaultNetwork(owner string) *Network

func ReadNetwork 

func ReadNetwork(dir string) (*Network, error)

Reads a network from the provided directory.

func (*Network) Bootstrap 

func (n *Network) Bootstrap(ctx context.Context, w io.Writer) error

Start the network for the first time

func (*Network) Create 

func (n *Network) Create(rootDir string) error

Creates the network on disk, generating its genesis and configuring its nodes in the process.

func (*Network) CreateNets added in v1.17.2 

func (n *Network) CreateNets(ctx context.Context, w io.Writer, apiURI string, restartRequired bool) error

Ensure that each net on the network is created. If restartRequired is false, node restart to pick up configuration changes becomes the responsibility of the caller.

func (*Network) EnsureDefaultConfig 

func (n *Network) EnsureDefaultConfig(w io.Writer, luxNodePath string, pluginDir string) error

Initializes a new network with default configuration.

func (*Network) EnsureNodeConfig 

func (n *Network) EnsureNodeConfig(node *Node) error

Ensures the provided node has the configuration it needs to start. If the data dir is not set, it will be defaulted to [nodeParentDir]/[node ID]. For a not-yet-created network, no action will be taken. TODO(marun) Reword or refactor to account for the differing behavior pre- vs post-start

func (*Network) EnvFileContents 

func (n *Network) EnvFileContents() string

func (*Network) EnvFilePath 

func (n *Network) EnvFilePath() string

func (*Network) GetMonitoringLabels 

func (n *Network) GetMonitoringLabels() map[string]string

GetMonitoringLabels returns monitoring labels for the network (stub)

func (*Network) GetNodeURIs 

func (n *Network) GetNodeURIs() []NodeURI

func (*Network) GetSubnet 

func (n *Network) GetSubnet(name string) *Net

func (*Network) GetURIForNodeID added in v1.1.11 

func (n *Network) GetURIForNodeID(nodeID ids.NodeID) (string, error)

func (*Network) Read 

func (n *Network) Read() error

Read network and node configuration from disk.

func (*Network) Restart 

func (n *Network) Restart(ctx context.Context, w io.Writer) error

Restarts all non-ephemeral nodes in the network.

func (*Network) RestartNode added in v1.1.11 

func (n *Network) RestartNode(ctx context.Context, w io.Writer, node *Node) error

Restart a single node.

func (*Network) StartNode 

func (n *Network) StartNode(ctx context.Context, w io.Writer, node *Node) error

Starts the provided node after configuring it for the network.

func (*Network) StartNodes 

func (n *Network) StartNodes(ctx context.Context, w io.Writer, nodesToStart ...*Node) error

Starts the specified nodes

func (*Network) Stop 

func (n *Network) Stop(ctx context.Context) error

Stops all nodes in the network.

func (*Network) TrackedSubnetsForNode 

func (n *Network) TrackedSubnetsForNode(nodeID ids.NodeID) string

TrackedSubnetsForNode returns the net IDs for the given node

func (*Network) Write 

func (n *Network) Write() error

Write network configuration to disk.

type NetworkConfig added in v1.1.11 

type NetworkConfig struct {
	Genesis      *genesis.UnparsedConfig
	CChainConfig FlagsMap
	DefaultFlags FlagsMap
	FundedKeys   []*secp256k1.PrivateKey
}

NetworkConfig defines configuration shared or common to all nodes in a given network.

func (*NetworkConfig) EnsureGenesis added in v1.1.11 

func (c *NetworkConfig) EnsureGenesis(networkID uint32, validatorIDs []ids.NodeID) error

Ensure genesis is generated if not already present.

type Node 

type Node struct {
	// Uniquely identifies the network the node is part of to enable monitoring.
	NetworkUUID string

	// Identify the entity associated with this network. This is
	// intended to be used to label metrics to enable filtering
	// results for a test run between the primary/shared network used
	// by the majority of tests and private networks used by
	// individual tests.
	NetworkOwner string

	// Set by EnsureNodeID which is also called when the node is read.
	NodeID ids.NodeID

	// Flags that will be supplied to the node at startup
	Flags FlagsMap

	// An ephemeral node is not expected to be a persistent member of the network and
	// should therefore not be used as for bootstrapping purposes.
	IsEphemeral bool

	// The configuration used to initialize the node runtime.
	RuntimeConfig *NodeRuntimeConfig

	// Runtime state, intended to be set by NodeRuntime
	URI            string
	StakingAddress string
	// contains filtered or unexported fields
}

Node supports configuring and running a node participating in a temporary network.

func NewEphemeralNode 

func NewEphemeralNode(flags FlagsMap) *Node

Initializes an ephemeral node using the provided config flags

func NewNode 

func NewNode(dataDir string) *Node

Initializes a new node with only the data dir set

func NewNodesOrPanic 

func NewNodesOrPanic(count int) []*Node

Initializes the specified number of nodes.

func ReadNode added in v1.1.11 

func ReadNode(dataDir string) (*Node, error)

Reads a node's configuration from the specified directory.

func ReadNodes added in v1.1.11 

func ReadNodes(networkDir string, includeEphemeral bool) ([]*Node, error)

Reads nodes from the specified network directory.

func (*Node) EnsureBLSSigningKey 

func (n *Node) EnsureBLSSigningKey() error

Ensures a BLS signing key is generated if not already present.

func (*Node) EnsureKeys 

func (n *Node) EnsureKeys() error

Ensures staking and signing keys are generated if not already present and that the node ID (derived from the staking keypair) is set.

func (*Node) EnsureNodeID 

func (n *Node) EnsureNodeID() error

Derives the node ID. Requires that a tls keypair is present.

func (*Node) EnsureStakingKeypair 

func (n *Node) EnsureStakingKeypair() error

Ensures a staking keypair is generated if not already present.

func (*Node) GetDataDir added in v1.1.11 

func (n *Node) GetDataDir() string

func (*Node) GetProofOfPossession 

func (n *Node) GetProofOfPossession() (*signer.ProofOfPossession, error)

Derives the nodes proof-of-possession. Requires the node to have a BLS signing key.

func (*Node) InitiateStop 

func (n *Node) InitiateStop(ctx context.Context) error

func (*Node) IsHealthy 

func (n *Node) IsHealthy(ctx context.Context) (bool, error)

func (*Node) Read 

func (n *Node) Read() error

func (*Node) SaveAPIPort added in v1.1.11 

func (n *Node) SaveAPIPort() error

Saves the currently allocated API port to the node's configuration for use across restarts. Reusing the port ensures consistent labeling of metrics.

func (*Node) SaveMetricsSnapshot 

func (n *Node) SaveMetricsSnapshot(ctx context.Context) error

Writes the current state of the metrics endpoint to disk

func (*Node) SetNetworkingConfig added in v1.1.11 

func (n *Node) SetNetworkingConfig(bootstrapIDs []string, bootstrapIPs []string)

Sets networking configuration for the node. Convenience method for setting networking flags.

func (*Node) Start 

func (n *Node) Start(w io.Writer) error

func (*Node) Stop 

func (n *Node) Stop(ctx context.Context) error

Initiates node shutdown and waits for the node to stop.

func (*Node) WaitForStopped 

func (n *Node) WaitForStopped(ctx context.Context) error

func (*Node) Write 

func (n *Node) Write() error

type NodeConfig added in v1.1.11 

type NodeConfig struct {
	NodeID ids.NodeID
	Flags  FlagsMap
}

NodeConfig defines configuration for an luxd node.

func NewNodeConfig added in v1.1.11 

func NewNodeConfig() *NodeConfig

func (*NodeConfig) EnsureBLSSigningKey added in v1.1.11 

func (nc *NodeConfig) EnsureBLSSigningKey() error

Ensures a BLS signing key is generated if not already present.

func (*NodeConfig) EnsureKeys added in v1.1.11 

func (nc *NodeConfig) EnsureKeys() error

Ensures staking and signing keys are generated if not already present and that the node ID (derived from the staking keypair) is set.

func (*NodeConfig) EnsureNodeID added in v1.1.11 

func (nc *NodeConfig) EnsureNodeID() error

Attempt to derive the node ID from the node configuration.

func (*NodeConfig) EnsureStakingKeypair added in v1.1.11 

func (nc *NodeConfig) EnsureStakingKeypair() error

Ensures a staking keypair is generated if not already present.

func (*NodeConfig) SetNetworkingConfigDefaults added in v1.1.11 

func (nc *NodeConfig) SetNetworkingConfigDefaults(
	httpPort uint16,
	stakingPort uint16,
	bootstrapIDs []string,
	bootstrapIPs []string,
)

Convenience method for setting networking flags.

type NodeProcess added in v1.1.11 

type NodeProcess struct {
	// contains filtered or unexported fields
}

Defines local-specific node configuration. Supports setting default and node-specific values.

func (*NodeProcess) InitiateStop added in v1.1.11 

func (p *NodeProcess) InitiateStop() error

Signals the node process to stop.

func (*NodeProcess) IsHealthy added in v1.1.11 

func (p *NodeProcess) IsHealthy(ctx context.Context) (bool, error)

func (*NodeProcess) Start added in v1.1.11 

func (p *NodeProcess) Start(w io.Writer) error

Start waits for the process context to be written which indicates that the node will be accepting connections on its staking port. The network will start faster with this synchronization due to the avoidance of exponential backoff if a node tries to connect to a beacon that is not ready.

func (*NodeProcess) WaitForStopped added in v1.1.11 

func (p *NodeProcess) WaitForStopped(ctx context.Context) error

Waits for the node process to stop.

type NodeRuntime 

type NodeRuntime interface {
	Start(w io.Writer) error
	InitiateStop() error
	WaitForStopped(ctx context.Context) error
	IsHealthy(ctx context.Context) (bool, error)
	// contains filtered or unexported methods
}

NodeRuntime defines the methods required to support running a node.

type NodeRuntimeConfig 

type NodeRuntimeConfig struct {
	LuxNodePath string
	Process     *ProcessRuntimeConfig `json:"process,omitempty"`
	Kube        *KubeRuntimeConfig    `json:"kube,omitempty"`
}

Configuration required to configure a node runtime.

type NodeURI 

type NodeURI struct {
	NodeID ids.NodeID
	URI    string
}

NodeURI associates a node ID with its API URI.

func GetNodeURIs 

func GetNodeURIs(nodes []*Node) []NodeURI

type ProcessRuntime 

type ProcessRuntime struct {
	// contains filtered or unexported fields
}

Defines local-specific node configuration. Supports setting default and node-specific values.

func (*ProcessRuntime) GetAccessibleStakingAddress added in v1.18.2 

func (p *ProcessRuntime) GetAccessibleStakingAddress(_ context.Context) (netip.AddrPort, func(), error)

func (*ProcessRuntime) GetAccessibleURI added in v1.18.2 

func (p *ProcessRuntime) GetAccessibleURI() string

GetAccessibleURI returns the URI that can be used to access the node's API.

func (*ProcessRuntime) InitiateStop 

func (p *ProcessRuntime) InitiateStop(_ context.Context) error

Signals the node process to stop.

func (*ProcessRuntime) IsHealthy 

func (p *ProcessRuntime) IsHealthy(ctx context.Context) (bool, error)

func (*ProcessRuntime) Restart 

func (p *ProcessRuntime) Restart(ctx context.Context) error

Restarts the node

func (*ProcessRuntime) Start 

func (p *ProcessRuntime) Start(ctx context.Context) error

Start waits for the process context to be written which indicates that the node will be accepting connections on its staking port. The network will start faster with this synchronization due to the avoidance of exponential backoff if a node tries to connect to a beacon that is not ready.

func (*ProcessRuntime) WaitForStopped 

func (p *ProcessRuntime) WaitForStopped(ctx context.Context) error

Waits for the node process to stop.

type ProcessRuntimeConfig 

type ProcessRuntimeConfig struct {
	AvalancheGoPath   string `json:"avalancheGoPath,omitempty"`
	PluginDir         string `json:"pluginDir,omitempty"`
	ReuseDynamicPorts bool   `json:"reuseDynamicPorts,omitempty"`
}

type SDConfig 

type SDConfig struct {
	Targets []string          `json:"targets"`
	Labels  map[string]string `json:"labels"`
}

SDConfig represents a Prometheus service discovery config entry.

file_sd_config docs: https://metrics.io/docs/prometheus/latest/configuration/configuration/#file_sd_config

type Subnet 

type Subnet = Net

Subnet is an alias for Net to maintain backward compatibility

func (*Subnet) AddValidators 

func (s *Subnet) AddValidators(ctx context.Context, w io.Writer, apiURI string, nodes ...*Node) error

Add validators to the subnet

func (*Subnet) Create 

func (s *Subnet) Create(ctx context.Context, uri string) error

Issues the net creation transaction and retains the result. The URI of a node is required to issue the transaction.

func (*Subnet) CreateChains 

func (s *Subnet) CreateChains(ctx context.Context, w io.Writer, uri string) error

func (*Subnet) GetWallet 

func (s *Subnet) GetWallet(ctx context.Context, uri string) (primary.Wallet, error)

Retrieves a wallet configured for use with the subnet

func (*Subnet) HasChainConfig 

func (s *Subnet) HasChainConfig() bool

HasChainConfig indicates whether at least one of the subnet's chains have explicit configuration. This can be used to determine whether validator restart is required after chain creation to ensure that chains are configured correctly.

func (*Subnet) Write 

func (s *Subnet) Write(subnetDir string, chainDir string) error

Write the net configuration to disk

type XChainBalanceMap 

type XChainBalanceMap map[ids.ShortID]uint64

Helper type to simplify configuring X-Chain genesis balances

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.