client

package
v0.1.10 Latest Latest
Warning

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

Go to latest
Published: May 26, 2025 License: Apache-2.0 Imports: 7 Imported by: 0

README

RMB Client Documentation

Package Overview

The client package provides a simple RMB interface to work with nodes.


Requirements

  1. Message Bus (msgbusd): A msgbusd instance must be running on the node. This client uses RMB to send messages and receive responses.
  2. ED25519 Key Pair: A valid ed25519 key pair is required. This key is used to sign deployments and must match the key configured for the local twin on substrate.

Simple Deployment Example

Step 1: Create an RMB Client
cl, err := rmb.Default()
if err != nil {
    panic(err)
}
Step 2: Create a Node Client
node := client.NewNodeClient(NodeTwinID, cl)
Step 3: Define Your Deployment Object
dl := gridtypes.Deployment{
    Version: Version,
    TwinID:  Twin, // LocalTwin,
    // This contract ID must match the one on substrate
    Workloads: []gridtypes.Workload{
        network(), // Network workload definition
        zmount(),  // Zmount workload definition
        publicip(), // Public IP definition
        zmachine(), // Zmachine definition
    },
    SignatureRequirement: gridtypes.SignatureRequirement{
        WeightRequired: 1,
        Requests: []gridtypes.SignatureRequest{
            {
                TwinID: Twin,
                Weight: 1,
            },
        },
    },
}
Step 4: Compute Deployment Hash
hash, err := dl.ChallengeHash()
if err != nil {
    panic("failed to create hash")
}
fmt.Printf("Hash: %x\n", hash)
Step 5: Deploy the Contract
dl.ContractID = 11 // Contract ID from substrate
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

err = node.DeploymentDeploy(ctx, dl)
if err != nil {
    panic(err)
}

Node Client Methods

Deployment Management
Deployment Deploy

Sends the deployment to the node for processing.

func (n *NodeClient) DeploymentDeploy(ctx context.Context, dl gridtypes.Deployment) error
Deployment Update

Updates a given deployment.

Deployment must be a valid update for a deployment that has been already created via DeploymentDeploy

func (n *NodeClient) DeploymentUpdate(ctx context.Context, dl gridtypes.Deployment) error
Deployment Get

Gets a deployment via contract ID

func (n *NodeClient) DeploymentGet(ctx context.Context, contractID uint64) (gridtypes.Deployment, error)
Deployment List

List all deployments on the node for a twin.

func (n *NodeClient) DeploymentList(ctx context.Context) ([]gridtypes.Deployment, error)
Deployment Changes

Get changes to a deployment by contract ID.

func (n *NodeClient) DeploymentChanges(ctx context.Context, contractID uint64) ([]gridtypes.Workload, error)
Deployment Delete

Delete a deployment.

func (n *NodeClient) DeploymentDelete(ctx context.Context, contractID uint64) error

Node Statistics
Get Counters

Gets node statistics, including total and available cpu, memory, storage, etc...

func (n *NodeClient) Counters(ctx context.Context) (Counters, error)
Pools

Returns the statistics of separate pools

func (n *NodeClient) Pools(ctx context.Context) ([]pkg.PoolMetrics, error)

GPU Management
List GPUs

Gets a list of GPUs on the node.

func (n *NodeClient) GPUs(ctx context.Context) ([]GPU, error)

Networking
List WireGuard Ports

List return a list of all "taken" ports on the node.

func (n *NodeClient) NetworkListWGPorts(ctx context.Context) ([]uint16, error)
Check Public IPv6 Availability

Check if the node has a public IP of version 6 address.

func (n *NodeClient) HasPublicIPv6(ctx context.Context) (bool, error)
List Interfaces

Retrieve all interfaces on the node.

func (n *NodeClient) NetworkListInterfaces(ctx context.Context) (map[string][]net.IP, error)
List Public IPs

List taken public IPs on the node

func (n *NodeClient) NetworkListPublicIPs(ctx context.Context) ([]string, error)
List Private IPs

Retrieve all private IPs reserved for a network.

func (n *NodeClient) NetworkListPrivateIPs(ctx context.Context, networkName string) ([]string, error)
Get Public Network Configuration

Retuns the current public network configuration for the node.

func (n *NodeClient) NetworkGetPublicConfig(ctx context.Context) (pkg.PublicConfig, error)

System Information
Get System Version

Returns the system version.

func (n *NodeClient) SystemVersion(ctx context.Context) (Version, error)
Get Node Features

Gets features of the node (This can be used to indicate if the node is of version 3 or 4).

func (n *NodeClient) SystemGetNodeFeatures(ctx context.Context) ([]pkg.NodeFeature, error)
Get System DMI

Returns DMI information for the node.

func (n *NodeClient) SystemDMI(ctx context.Context) (dmi.DMI, error)
Get Hypervisor Information

Gets the name of the hypervisor used on the node

func (n *NodeClient) SystemHypervisor(ctx context.Context) (string, error)
Run Diagnostics

Runs diagnostics on the system.

func (n *NodeClient) SystemDiagnostics(ctx context.Context) (diagnostics.Diagnostics, error)

Calls requires admin privileges
List All Physical Interfaces

List all physical devices on a node

func (n *NodeClient) NetworkListAllInterfaces(ctx context.Context) (map[string]Interface, error)
Set Public Exit Device

Set which physical interface to use as the exit device.

func (n *NodeClient) NetworkSetPublicExitDevice(ctx context.Context, iface string) error
Get Public Exit Device

Get the current dual NIC setup of the node.

func (n *NodeClient) NetworkGetPublicExitDevice(ctx context.Context) (ExitDevice, error)

Structs and Types

NodeClient

Represents the node client.

type NodeClient struct {
    nodeTwin uint32
    bus      rmb.Client
}
Version

Represents system version information.

type Version struct {
    ZOS   string `json:"zos"`
    ZInit string `json:"zinit"`
}
Interface

Represents network interface information.

type Interface struct {
    IPs []string `json:"ips"`
    Mac string   `json:"mac"`
}
ExitDevice

Represents exit device configuration.

type ExitDevice struct {
    IsSingle       bool   `json:"is_single"`
    IsDual         bool   `json:"is_dual"`
    AsDualInterface string `json:"dual_interface"`
}
Counters

Represents node statistics.

type Counters struct {
    Total  gridtypes.Capacity `json:"total"`
    Used   gridtypes.Capacity `json:"used"`
    System gridtypes.Capacity `json:"system"`
    Users  UsersCounters      `json:"users"`
}
UsersCounters

Represents deployment and workload statistics.

type UsersCounters struct {
    Deployments int `json:"deployments"`
    Workloads   int `json:"workloads"`
}
GPU

Represents GPU information.

type GPU struct {
    ID       string `json:"id"`
    Vendor   string `json:"vendor"`
    Device   string `json:"device"`
    Contract uint64 `json:"contract"`
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Counters

type Counters struct {
	// Total system capacity
	Total gridtypes.Capacity `json:"total"`
	// Used capacity this include user + system resources
	Used gridtypes.Capacity `json:"used"`
	// System resource reserved by zos
	System gridtypes.Capacity `json:"system"`
	// Users statistics by zos
	Users UsersCounters `json:"users"`
}

Counters (statistics) of the node

type ExitDevice

type ExitDevice struct {
	// IsSingle is set to true if br-pub
	// is connected to zos bridge
	IsSingle bool `json:"is_single"`
	// IsDual is set to true if br-pub is
	// connected to a physical nic
	IsDual bool `json:"is_dual"`
	// AsDualInterface is set to the physical
	// interface name if IsDual is true
	AsDualInterface string `json:"dual_interface"`
}

type GPU

type GPU struct {
	ID       string `json:"id"`
	Vendor   string `json:"vendor"`
	Device   string `json:"device"`
	Contract uint64 `json:"contract"`
}

GPU information

type Interface

type Interface struct {
	IPs []string `json:"ips"`
	Mac string   `json:"mac"`
}

type NodeClient

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

NodeClient struct

func NewNodeClient

func NewNodeClient(nodeTwin uint32, bus rmb.Client) *NodeClient

NewNodeClient creates a new node RMB client. This client then can be used to communicate with the node over RMB.

func (*NodeClient) Counters

func (n *NodeClient) Counters(ctx context.Context) (counters Counters, err error)

Counters returns some node statistics. Including total and available cpu, memory, storage, etc...

func (*NodeClient) DeploymentChanges

func (n *NodeClient) DeploymentChanges(ctx context.Context, contractID uint64) (changes []gridtypes.Workload, err error)

DeploymentChanges gets changes to deployment via contract ID

func (*NodeClient) DeploymentDelete

func (n *NodeClient) DeploymentDelete(ctx context.Context, contractID uint64) error

DeploymentDelete deletes a deployment, the node will make sure to decomission all deployments and set all workloads to deleted. A call to Get after delete is valid

func (*NodeClient) DeploymentDeploy

func (n *NodeClient) DeploymentDeploy(ctx context.Context, dl gridtypes.Deployment) error

DeploymentDeploy sends the deployment to the node for processing.

func (*NodeClient) DeploymentGet

func (n *NodeClient) DeploymentGet(ctx context.Context, contractID uint64) (dl gridtypes.Deployment, err error)

DeploymentGet gets a deployment via contract ID

func (*NodeClient) DeploymentList

func (n *NodeClient) DeploymentList(ctx context.Context) (dls []gridtypes.Deployment, err error)

DeploymentList gets all deployments for a twin

func (*NodeClient) DeploymentUpdate

func (n *NodeClient) DeploymentUpdate(ctx context.Context, dl gridtypes.Deployment) error

DeploymentUpdate update the given deployment. deployment must be a valid update for a deployment that has been already created via DeploymentDeploy

func (*NodeClient) GPUs

func (n *NodeClient) GPUs(ctx context.Context) (gpus []GPU, err error)

func (*NodeClient) GetVmLogs added in v0.1.3

func (n *NodeClient) GetVmLogs(ctx context.Context, path string) (string, error)

NetworkListPublicIPs list taken public IPs on the node

func (*NodeClient) HasPublicIPv6

func (n *NodeClient) HasPublicIPv6(ctx context.Context) (bool, error)

func (*NodeClient) NetworkGetPublicConfig

func (n *NodeClient) NetworkGetPublicConfig(ctx context.Context) (cfg pkg.PublicConfig, err error)

NetworkGetPublicConfig returns the current public node network configuration. A node with a public config can be used as an access node for wireguard.

func (*NodeClient) NetworkGetPublicExitDevice

func (n *NodeClient) NetworkGetPublicExitDevice(ctx context.Context) (exit ExitDevice, err error)

NetworkGetPublicExitDevice gets the current dual nic setup of the node.

func (*NodeClient) NetworkListAllInterfaces

func (n *NodeClient) NetworkListAllInterfaces(ctx context.Context) (result map[string]Interface, err error)

NetworkListAllInterfaces return all physical devices on a node

func (*NodeClient) NetworkListInterfaces

func (n *NodeClient) NetworkListInterfaces(ctx context.Context) (result map[string][]net.IP, err error)

func (*NodeClient) NetworkListPrivateIPs

func (n *NodeClient) NetworkListPrivateIPs(ctx context.Context, networkName string) ([]string, error)

NetworkListPrivateIPs list private ips reserved for a network

func (*NodeClient) NetworkListPublicIPs

func (n *NodeClient) NetworkListPublicIPs(ctx context.Context) ([]string, error)

NetworkListPublicIPs list taken public IPs on the node

func (*NodeClient) NetworkListWGPorts

func (n *NodeClient) NetworkListWGPorts(ctx context.Context) ([]uint16, error)

NetworkListWGPorts return a list of all "taken" ports on the node. A new deployment should be careful to use a free port for its network setup.

func (*NodeClient) NetworkSetPublicExitDevice

func (n *NodeClient) NetworkSetPublicExitDevice(ctx context.Context, iface string) error

NetworkSetPublicExitDevice select which physical interface to use as an exit device setting `iface` to `zos` will then make node run in a single nic setup.

func (*NodeClient) Pools

func (n *NodeClient) Pools(ctx context.Context) (pools []pkg.PoolMetrics, err error)

Pools returns statistics of separate pools

func (*NodeClient) SystemDMI

func (n *NodeClient) SystemDMI(ctx context.Context) (result dmi.DMI, err error)

func (*NodeClient) SystemDiagnostics

func (n *NodeClient) SystemDiagnostics(ctx context.Context) (result diagnostics.Diagnostics, err error)

func (*NodeClient) SystemGetNodeFeatures

func (n *NodeClient) SystemGetNodeFeatures(ctx context.Context) (feat []pkg.NodeFeature, err error)

func (*NodeClient) SystemHypervisor

func (n *NodeClient) SystemHypervisor(ctx context.Context) (result string, err error)

func (*NodeClient) SystemVersion

func (n *NodeClient) SystemVersion(ctx context.Context) (ver Version, err error)

type UsersCounters

type UsersCounters struct {
	// Total deployments count
	Deployments int `json:"deployments"`
	// Total workloads count
	Workloads int `json:"workloads"`
}

UsersCounters the expected counters for deployments and workloads

type Version

type Version struct {
	ZOS   string `json:"zos"`
	ZInit string `json:"zinit"`
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL