Skip to content

Commit 7fdf284

Browse files
Eslam-NawaraEslam-Nawara
committed
add registrar client readme file
1 parent cc43f59 commit 7fdf284

File tree

1 file changed

+291
-0
lines changed

1 file changed

+291
-0
lines changed

‎node-registrar/client/README.md

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
# ThreeFold Grid Node Registrar Client
2+
3+
A Go client for interacting with the ThreeFold Grid Node Registrar service. Facilitates node registration and management on the ThreeFold Grid.
4+
5+
## Overview
6+
7+
The Node Registrar Client enables communication with the ThreeFold Grid's node registration service. It provides methods to:
8+
9+
* Register nodes
10+
* Manage node metadata
11+
* Retrieve node information
12+
* Delete node registrations
13+
14+
## Features
15+
16+
### Version
17+
18+
* **Get Zos Version**: Loads zos version for the current network
19+
* **Set Zos Version**: Set zos version to specific version (can only be done by the network admin)
20+
21+
### Accounts
22+
23+
* **Create Account**: Create new account on the registrar with uniqe key.
24+
* **Update Account**: Update the account configuration (relays & rmbEncKey).
25+
* **Ensure Account**: Ensures that an account is created with specific seed.
26+
* **Get Account**: Get an account using either its twin\_id or its public\_key.
27+
28+
### Farms
29+
30+
* **Create Farm**: Create new farm on the registrar with uniqe name.
31+
* **update Farm**: update farm configuration (farm\_id, dedicated).
32+
* **Get Farm**: Get a farm using either its farm\_id.
33+
34+
### Node
35+
36+
* **Register Node**: Register physical/virtual nodes with the TFGrid.
37+
* **Update Node**: Update node configuration (farm\_id, interfaces, resources, location, secure\_boot, virtualized).
38+
* **Get Node**: Fetch registered node details using (node\_id, twin\_id, farm\_id).
39+
* **Update Node Uptime**: Update node Uptime.
40+
41+
### API Methods
42+
43+
#### Version Operations
44+
45+
| Method | Description | Parameters | Returns |
46+
|-----------------|----------------------------------|----------------------------|---------------------|
47+
| GetZosVersion | Get current zos version | None | (ZosVersion, error) |
48+
| SetZosVersion | Update zos version (admin-only) | version string, force bool | error |
49+
50+
#### Account Management
51+
52+
| Method | Description | Parameters | Returns |
53+
|----------------|---------------------------|-----------------------------------|------------------|
54+
| CreateAccount | Create new account | relays []string, rmbEncKey string | (Account, error) |
55+
| EnsureAccount | Create account if missing | relays []string, rmbEncKey string | (Account, error) |
56+
| GetAccount | Get account by twin ID | twinID uint64 | (Account, error) |
57+
| GetAccountByPK | Get account by public key | publicKey string | (Account, error) |
58+
| UpdateAccount | Modify account config | ...UpdateOption | error |
59+
60+
#### Farm Operations
61+
62+
| Method | Description | Parameters | Returns |
63+
|-------------|------------------------|--------------------------------------------|-----------------|
64+
| CreateFarm | Register new farm | name string, twinID uint64, dedicated bool | (uint64, error) |
65+
| UpdateFarm | Modify farm properties | farmID uint64, ...UpdateOption | error |
66+
| GetFarm | Get farm by ID | farmID uint64 | (Farm, error) |
67+
| ListFarms | List farms | ...ListOption | ([]Farm, error) |
68+
69+
#### Node Operations
70+
71+
| Method | Description | Parameters | Returns |
72+
|-----------------|-----------------------|------------------------------------------------|-----------------|
73+
| RegisterNode | Register new node | farmID uint64, twinID uint64, interfaces []Interface, location Location, resources Resources, serial string, secureBoot bool, virtualized bool | (uint64, error) |
74+
| UpdateNode | Modify node config | ...UpdateOption | error |
75+
| GetNode | Get node by node ID | nodeID uint64 | (Node, error) |
76+
| GetNodeByTwinID | Get node by twin ID | twinID uint64 | (Node, error) |
77+
| ListNodes | List nodes | ...ListOption | ([]Node, error) |
78+
| ReportUptime | Submit uptime metrics | report UptimeReport | error |
79+
80+
## Installation
81+
82+
```bash
83+
go get github.com/threefoldtech/tfgrid4-sdk-go/node-registrar/client@f4f5e1fbff97cd685f6f99db265d4b2954e39f90
84+
```
85+
86+
## Usage
87+
88+
### Initialize Client
89+
90+
```go
91+
import (
92+
"github.com/threefoldtech/tfgrid4-sdk-go/node-registrar/client"
93+
)
94+
95+
func main() {
96+
registrarURL := "https://registrar.dev4.grid.tf/v1"
97+
98+
s := make([]byte, 32)
99+
_, err := rand.Read(s)
100+
if err != nil {
101+
log.Fatal().Err(err).Send()
102+
}
103+
seed = hex.EncodeToString(s)
104+
fmt.Println("New Seed (Hex):", seed)
105+
106+
cli, err := client.NewRegistrarClient(registrarURL, s)
107+
if err != nil {
108+
panic(err)
109+
}
110+
}
111+
```
112+
113+
### Get Zos Version
114+
115+
```go
116+
version, err := c.GetZosVersion()
117+
if err != nil {
118+
log.Fatal().Err(err).Msg("failed to set registrar version")
119+
}
120+
121+
log.Info().Msgf("%s version is: %+v", network, version)
122+
```
123+
124+
### Set Zos Version (ONLY for network admin)
125+
126+
```go
127+
err := c.SetZosVersion("v0.1.8", true)
128+
if err != nil {
129+
log.Fatal().Err(err).Msg("failed to set registrar version")
130+
}
131+
132+
log.Info().Msg("version is updated successfully")
133+
```
134+
135+
### Create Account
136+
137+
```go
138+
account, err := c.CreateAccount(relays, rmbEncKey)
139+
if err != nil {
140+
log.Fatal().Err(err).Msg("failed to create new account on registrar")
141+
}
142+
143+
log.Info().Uint64("twinID", account.TwinID).Msg("account created successfully")
144+
145+
```
146+
147+
### Get Account
148+
149+
#### Get Account By Public Key
150+
151+
```go
152+
account, err := c.GetAccountByPK(pk)
153+
if err != nil {
154+
log.Fatal().Err(err).Msg("failed to get account from registrar")
155+
}
156+
log.Info().Any("account", account).Send()
157+
```
158+
159+
#### Get Account By Twin ID
160+
161+
```go
162+
account, err := c.GetAccount(id)
163+
if err != nil {
164+
log.Fatal().Err(err).Msg("failed to get account from registrar")
165+
}
166+
log.Info().Any("account", account).Send()
167+
168+
```
169+
170+
### Update Account
171+
172+
```go
173+
err := c.UpdateAccount(client.UpdateAccountWithRelays(relays), client.UpdateAccountWithRMBEncKey(rmbEncKey))
174+
if err != nil {
175+
log.Fatal().Err(err).Msg("failed to get account from registrar")
176+
}
177+
log.Info().Msg("account updated successfully")
178+
```
179+
180+
### Ensure Account
181+
182+
```go
183+
account, err := c.EnsureAccount(relays, rmbEncKey)
184+
if err != nil {
185+
log.Fatal().Err(err).Msg("failed to ensure account account from registrar")
186+
}
187+
log.Info().Any("account", account).Send()
188+
```
189+
190+
### Create Farm
191+
192+
```go
193+
id, err := c.CreateFarm(farmName, twinID, false)
194+
if err != nil {
195+
log.Fatal().Err(err).Msg("failed to create new farm on registrar")
196+
}
197+
198+
log.Info().Uint64("farmID", id).Msg("farm created successfully")
199+
```
200+
201+
### Get Farm
202+
203+
```go
204+
farm, err := c.GetFarm(id)
205+
if err != nil {
206+
log.Fatal().Err(err).Msg("failed to get farm from registrar")
207+
}
208+
log.Info().Any("farm", farm).Send()
209+
```
210+
211+
### List Farms
212+
213+
```go
214+
farms, err := c.ListFarms(ListFarmWithName(name))
215+
if err != nil {
216+
log.Fatal().Err(err).Msg("failed to list farms from registrar")
217+
}
218+
log.Info().Any("farm", farms[0]).Send()
219+
```
220+
221+
### Update Farm
222+
223+
```go
224+
err := c.UpdateFarm(farmID, client.UpdateFarmWithName(name))
225+
if err != nil {
226+
log.Fatal().Err(err).Msg("failed to get farm from registrar")
227+
}
228+
log.Info().Msg("farm updated successfully")
229+
```
230+
231+
### Register a Node
232+
233+
```go
234+
id, err := c.RegisterNode(farmID, twinID, interfaces, location, resources, serialNumber, secureBoot, virtualized)
235+
if err != nil {
236+
log.Fatal().Err(err).Msg("failed to register a new node on registrar")
237+
}
238+
log.Info().Uint64("nodeID", id).Msg("node registered successfully")
239+
```
240+
241+
### Get Node
242+
243+
#### Get Node With Node ID
244+
245+
```go
246+
node, err := c.GetNode(id)
247+
if err != nil {
248+
log.Fatal().Err(err).Msg("failed to get node from registrar")
249+
}
250+
log.Info().Any("node", node).Send()
251+
```
252+
253+
#### Get Node With Twin ID
254+
255+
```go
256+
node, err := c.GetNodeByTwinID(id)
257+
if err != nil {
258+
log.Fatal().Err(err).Msg("failed to get node from registrar")
259+
}
260+
log.Info().Any("node", node).Send()
261+
```
262+
263+
### List Nodes
264+
265+
```go
266+
nodes, err := c.ListNodes(client.ListNodesWithFarmID(id))
267+
if err != nil {
268+
log.Fatal().Err(err).Msg("failed to list nodes from registrar")
269+
}
270+
log.Info().Any("node", node[0]).Send()
271+
```
272+
273+
### Update Node
274+
275+
```go
276+
err := c.UpdateNode(client.UpdateNodesWithLocation(location))
277+
if err != nil {
278+
log.Fatal().Err(err).Msg("failed to update node location on the registrar")
279+
}
280+
log.Info().Msg("node updated successfully")
281+
```
282+
283+
### Update Node Uptime
284+
285+
```go
286+
err := c.ReportUptime(report)
287+
if err != nil {
288+
log.Fatal().Err(err).Msg("failed to update node uptime in the registrar")
289+
}
290+
log.Info().Msg("node uptime is updated successfully")
291+
```

0 commit comments

Comments
 (0)