tfgrid/info_tfgrid
33
3
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Activity

added developers

Browse Source
This commit is contained in:
mik-tf
2024-04-04 00:47:48 +00:00
parent 848188accb
commit b355e57023
196 changed files with 12932 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
collections/documentation/developers/tfcmd/tfcmd.md Normal file
View File

@@ -0,0 +1,15 @@
<h1>TFCMD</h1>
TFCMD (`tfcmd`) is a command line interface to interact and develop on Threefold Grid using command line.
Consult the [ThreeFoldTech TFCMD repository](https://github.com/threefoldtech/tfgrid-sdk-go/tree/development/grid-cli) for the latest updates. Make sure to read the [basics](../../system_administrators/getstarted/tfgrid3_getstarted.md).
<h2>Table of Contents</h2>
- [Getting Started](./tfcmd_basics.md)
- [Deploy a VM](./tfcmd_vm.md)
- [Deploy Kubernetes](./tfcmd_kubernetes.md)
- [Deploy ZDB](./tfcmd_zdbs.md)
- [Gateway FQDN](./tfcmd_gateway_fqdn.md)
- [Gateway Name](./tfcmd_gateway_name.md)
- [Contracts](./tfcmd_contracts.md)

67
collections/documentation/developers/tfcmd/tfcmd_basics.md Normal file
View File

@@ -0,0 +1,67 @@
<h1>TFCMD Getting Started</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Installation](#installation)
- [Login](#login)
- [Commands](#commands)
- [Using TFCMD](#using-tfcmd)
***
## Introduction
This section covers the basics on how to set up and use TFCMD (`tfcmd`).
TFCMD is available as binaries. Make sure to download the latest release and to stay up to date with new releases.
## Installation
An easy way to use TFCMD is to download and extract the TFCMD binaries to your path.
- Download latest release from [releases](https://github.com/threefoldtech/tfgrid-sdk-go/releases)
- ```
wget <binaries_url>
```
- Extract the binaries
- ```
tar -xvf <binaries_file>
```
- Move `tfcmd` to any `$PATH` directory:
```bash
mv tfcmd /usr/local/bin
```
## Login
Before interacting with Threefold Grid with `tfcmd` you should login with your mnemonics and specify the grid network:
```console
$ tfcmd login
Please enter your mnemonics: <mnemonics>
Please enter grid network (main,test): <grid-network>
```
This validates your mnemonics and store your mnemonics and network to your default configuration dir.
Check [UserConfigDir()](https://pkg.go.dev/os#UserConfigDir) for your default configuration directory.
## Commands
You can run the command `tfcmd help` at any time to access the help section. This will also display the available commands.
| Command | Description |
| ---------- | ---------------------------------------------------------- |
| cancel | Cancel resources on Threefold grid |
| completion | Generate the autocompletion script for the specified shell |
| deploy | Deploy resources to Threefold grid |
| get | Get a deployed resource from Threefold grid |
| help | Help about any command |
| login | Login with mnemonics to a grid network |
| version | Get latest build tag |
## Using TFCMD
Once you've logged in, you can use commands to deploy workloads on the TFGrid. Read the next sections for more information on different types of workloads available with TFCMD.

99
collections/documentation/developers/tfcmd/tfcmd_contracts.md Normal file
View File

@@ -0,0 +1,99 @@
<h1>Contracts</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Get](#get)
- [Get Contracts](#get-contracts)
- [Get Contract](#get-contract)
- [Cancel](#cancel)
- [Optional Flags](#optional-flags)
***
## Introduction
We explain how to handle contracts on the TFGrid with `tfcmd`.
## Get
### Get Contracts
Get all contracts
```bash
tfcmd get contracts
```
Example:
```console
$ tfcmd get contracts
5:13PM INF starting peer session=tf-1184566 twin=81
Node contracts:
ID Node ID Type Name Project Name
50977 21 network vm1network vm1
50978 21 vm vm1 vm1
50980 14 Gateway Name gatewaytest gatewaytest
Name contracts:
ID Name
50979 gatewaytest
```
### Get Contract
Get specific contract
```bash
tfcmd get contract <contract-id>
```
Example:
```console
$ tfcmd get contract 50977
5:14PM INF starting peer session=tf-1185180 twin=81
5:14PM INF contract:
{
"contract_id": 50977,
"twin_id": 81,
"state": "Created",
"created_at": 1702480020,
"type": "node",
"details": {
"nodeId": 21,
"deployment_data": "{\"type\":\"network\",\"name\":\"vm1network\",\"projectName\":\"vm1\"}",
"deployment_hash": "21adc91ef6cdc915d5580b3f12732ac9",
"number_of_public_ips": 0
}
}
```
## Cancel
Cancel specified contracts or all contracts.
```bash
tfcmd cancel contracts <contract-id>... [Flags]
```
Example:
```console
$ tfcmd cancel contracts 50856 50857
5:17PM INF starting peer session=tf-1185964 twin=81
5:17PM INF contracts canceled successfully
```
### Optional Flags
- all: cancel all twin's contracts.
Example:
```console
$ tfcmd cancel contracts --all
5:17PM INF starting peer session=tf-1185964 twin=81
5:17PM INF contracts canceled successfully
```

87
collections/documentation/developers/tfcmd/tfcmd_gateway_fqdn.md Normal file
View File

@@ -0,0 +1,87 @@
<h1>Gateway FQDN</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Deploy](#deploy)
- [Required Flags](#required-flags)
- [Optional Flags](#optional-flags)
- [Get](#get)
- [Cancel](#cancel)
***
## Introduction
We explain how to use gateway fully qualified domain names on the TFGrid using `tfcmd`.
## Deploy
```bash
tfcmd deploy gateway fqdn [flags]
```
### Required Flags
- name: name for the gateway deployment also used for canceling the deployment. must be unique.
- node: node id to deploy gateway on.
- backends: list of backends the gateway will forward requests to.
- fqdn: FQDN pointing to the specified node.
### Optional Flags
-tls: add TLS passthrough option (default false).
Example:
```console
$ tfcmd deploy gateway fqdn -n gatewaytest --node 14 --backends http://93.184.216.34:80 --fqdn example.com
3:34PM INF deploying gateway fqdn
3:34PM INF gateway fqdn deployed
```
## Get
```bash
tfcmd get gateway fqdn <gateway>
```
gateway is the name used when deploying gateway-fqdn using tfcmd.
Example:
```console
$ tfcmd get gateway fqdn gatewaytest
2:05PM INF gateway fqdn:
{
"NodeID": 14,
"Backends": [
"http://93.184.216.34:80"
],
"FQDN": "awady.gridtesting.xyz",
"Name": "gatewaytest",
"TLSPassthrough": false,
"Description": "",
"NodeDeploymentID": {
"14": 19653
},
"SolutionType": "gatewaytest",
"ContractID": 19653
}
```
## Cancel
```bash
tfcmd cancel <deployment-name>
```
deployment-name is the name of the deployment specified in while deploying using tfcmd.
Example:
```console
$ tfcmd cancel gatewaytest
3:37PM INF canceling contracts for project gatewaytest
3:37PM INF gatewaytest canceled
```

88
collections/documentation/developers/tfcmd/tfcmd_gateway_name.md Normal file
View File

@@ -0,0 +1,88 @@
<h1>Gateway Name</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Deploy](#deploy)
- [Required Flags](#required-flags)
- [Optional Flags](#optional-flags)
- [Get](#get)
- [Cancel](#cancel)
***
## Introduction
We explain how to use gateway names on the TFGrid using `tfcmd`.
## Deploy
```bash
tfcmd deploy gateway name [flags]
```
### Required Flags
- name: name for the gateway deployment also used for canceling the deployment. must be unique.
- backends: list of backends the gateway will forward requests to.
### Optional Flags
- node: node id gateway should be deployed on.
- farm: farm id gateway should be deployed on, if set choose available node from farm that fits vm specs (default 1). note: node and farm flags cannot be set both.
-tls: add TLS passthrough option (default false).
Example:
```console
$ tfcmd deploy gateway name -n gatewaytest --node 14 --backends http://93.184.216.34:80
3:34PM INF deploying gateway name
3:34PM INF fqdn: gatewaytest.gent01.dev.grid.tf
```
## Get
```bash
tfcmd get gateway name <gateway>
```
gateway is the name used when deploying gateway-name using tfcmd.
Example:
```console
$ tfcmd get gateway name gatewaytest
1:56PM INF gateway name:
{
"NodeID": 14,
"Name": "gatewaytest",
"Backends": [
"http://93.184.216.34:80"
],
"TLSPassthrough": false,
"Description": "",
"SolutionType": "gatewaytest",
"NodeDeploymentID": {
"14": 19644
},
"FQDN": "gatewaytest.gent01.dev.grid.tf",
"NameContractID": 19643,
"ContractID": 19644
}
```
## Cancel
```bash
tfcmd cancel <deployment-name>
```
deployment-name is the name of the deployment specified in while deploying using tfcmd.
Example:
```console
$ tfcmd cancel gatewaytest
3:37PM INF canceling contracts for project gatewaytest
3:37PM INF gatewaytest canceled
```

147
collections/documentation/developers/tfcmd/tfcmd_kubernetes.md Normal file
View File

@@ -0,0 +1,147 @@
<h1>Kubernetes</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Deploy](#deploy)
- [Required Flags](#required-flags)
- [Optional Flags](#optional-flags)
- [Get](#get)
- [Cancel](#cancel)
***
## Introduction
In this section, we explain how to deploy Kubernetes workloads on the TFGrid using `tfcmd`.
## Deploy
```bash
tfcmd deploy kubernetes [flags]
```
### Required Flags
- name: name for the master node deployment also used for canceling the cluster deployment. must be unique.
- ssh: path to public ssh key to set in the master node.
### Optional Flags
- master-node: node id master should be deployed on.
- master-farm: farm id master should be deployed on, if set choose available node from farm that fits master specs (default 1). note: master-node and master-farm flags cannot be set both.
- workers-node: node id workers should be deployed on.
- workers-farm: farm id workers should be deployed on, if set choose available node from farm that fits master specs (default 1). note: workers-node and workers-farm flags cannot be set both.
- ipv4: assign public ipv4 for master node (default false).
- ipv6: assign public ipv6 for master node (default false).
- ygg: assign yggdrasil ip for master node (default true).
- master-cpu: number of cpu units for master node (default 1).
- master-memory: master node memory size in GB (default 1).
- master-disk: master node disk size in GB (default 2).
- workers-number: number of workers nodes (default 0).
- workers-ipv4: assign public ipv4 for each worker node (default false)
- workers-ipv6: assign public ipv6 for each worker node (default false)
- workers-ygg: assign yggdrasil ip for each worker node (default true)
- workers-cpu: number of cpu units for each worker node (default 1).
- workers-memory: memory size for each worker node in GB (default 1).
- workers-disk: disk size in GB for each worker node (default 2).
Example:
```console
$ tfcmd deploy kubernetes -n kube --ssh ~/.ssh/id_rsa.pub --master-node 14 --workers-number 2 --workers-node 14
4:21PM INF deploying network
4:22PM INF deploying cluster
4:22PM INF master yggdrasil ip: 300:e9c4:9048:57cf:504f:c86c:9014:d02d
```
## Get
```bash
tfcmd get kubernetes <kubernetes>
```
kubernetes is the name used when deploying kubernetes cluster using tfcmd.
Example:
```console
$ tfcmd get kubernetes examplevm
3:14PM INF k8s cluster:
{
"Master": {
"Name": "kube",
"Node": 14,
"DiskSize": 2,
"PublicIP": false,
"PublicIP6": false,
"Planetary": true,
"Flist": "https://hub.grid.tf/tf-official-apps/threefoldtech-k3s-latest.flist",
"FlistChecksum": "c87cf57e1067d21a3e74332a64ef9723",
"ComputedIP": "",
"ComputedIP6": "",
"YggIP": "300:e9c4:9048:57cf:e8a0:662b:4e66:8faa",
"IP": "10.20.2.2",
"CPU": 1,
"Memory": 1024
},
"Workers": [
{
"Name": "worker1",
"Node": 14,
"DiskSize": 2,
"PublicIP": false,
"PublicIP6": false,
"Planetary": true,
"Flist": "https://hub.grid.tf/tf-official-apps/threefoldtech-k3s-latest.flist",
"FlistChecksum": "c87cf57e1067d21a3e74332a64ef9723",
"ComputedIP": "",
"ComputedIP6": "",
"YggIP": "300:e9c4:9048:57cf:66d0:3ee4:294e:d134",
"IP": "10.20.2.2",
"CPU": 1,
"Memory": 1024
},
{
"Name": "worker0",
"Node": 14,
"DiskSize": 2,
"PublicIP": false,
"PublicIP6": false,
"Planetary": true,
"Flist": "https://hub.grid.tf/tf-official-apps/threefoldtech-k3s-latest.flist",
"FlistChecksum": "c87cf57e1067d21a3e74332a64ef9723",
"ComputedIP": "",
"ComputedIP6": "",
"YggIP": "300:e9c4:9048:57cf:1ae5:cc51:3ffc:81e",
"IP": "10.20.2.2",
"CPU": 1,
"Memory": 1024
}
],
"Token": "",
"NetworkName": "",
"SolutionType": "kube",
"SSHKey": "",
"NodesIPRange": null,
"NodeDeploymentID": {
"14": 22743
}
}
```
## Cancel
```bash
tfcmd cancel <deployment-name>
```
deployment-name is the name of the deployment specified in while deploying using tfcmd.
Example:
```console
$ tfcmd cancel kube
3:37PM INF canceling contracts for project kube
3:37PM INF kube canceled
```

171
collections/documentation/developers/tfcmd/tfcmd_vm.md Normal file
View File

@@ -0,0 +1,171 @@
<h1>Deploy a VM</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Deploy](#deploy)
- [Flags](#flags)
- [Required Flags](#required-flags)
- [Optional Flags](#optional-flags)
- [Examples](#examples)
- [Deploy a VM without GPU](#deploy-a-vm-without-gpu)
- [Deploy a VM with GPU](#deploy-a-vm-with-gpu)
- [Get](#get)
- [Get Example](#get-example)
- [Cancel](#cancel)
- [Cancel Example](#cancel-example)
- [Questions and Feedback](#questions-and-feedback)
***
# Introduction
In this section, we explore how to deploy a virtual machine (VM) on the ThreeFold Grid using `tfcmd`.
# Deploy
You can deploy a VM with `tfcmd` using the following template accompanied by required and optional flags:
```bash
tfcmd deploy vm [flags]
```
## Flags
When you use `tfcmd`, there are two required flags (`name` and `ssh`), while the other remaining flags are optional. Using such optional flags can be used to deploy a VM with a GPU for example or to set an IPv6 address and much more.
### Required Flags
- **name**: name for the VM deployment also used for canceling the deployment. The name must be unique.
- **ssh**: path to public ssh key to set in the VM.
### Optional Flags
- **node**: node ID the VM should be deployed on.
- **farm**: farm ID the VM should be deployed on, if set choose available node from farm that fits vm specs (default `1`). Note: node and farm flags cannot both be set.
- **cpu**: number of cpu units (default `1`).
- **disk**: size of disk in GB mounted on `/data`. If not set, no disk workload is made.
- **entrypoint**: entrypoint for the VM FList (default `/sbin/zinit init`). Note: setting this without the flist option will fail.
- **flist**: FList used in the VM (default `https://hub.grid.tf/tf-official-apps/threefoldtech-ubuntu-22.04.flist`). Note: setting this without the entrypoint option will fail.
- **ipv4**: assign public ipv4 for the VM (default `false`).
- **ipv6**: assign public ipv6 for the VM (default `false`).
- **memory**: memory size in GB (default `1`).
- **rootfs**: root filesystem size in GB (default `2`).
- **ygg**: assign yggdrasil ip for the VM (default `true`).
- **gpus**: assign a list of gpus' IDs to the VM. Note: setting this without the node option will fail.
## Examples
We present simple examples on how to deploy a virtual machine with or without a GPU using `tfcmd`.
### Deploy a VM without GPU
```console
$ tfcmd deploy vm --name examplevm --ssh ~/.ssh/id_rsa.pub --cpu 2 --memory 4 --disk 10
12:06PM INF deploying network
12:06PM INF deploying vm
12:07PM INF vm yggdrasil ip: 300:e9c4:9048:57cf:7da2:ac99:99db:8821
```
### Deploy a VM with GPU
```console
$ tfcmd deploy vm --name examplevm --ssh ~/.ssh/id_rsa.pub --cpu 2 --memory 4 --disk 10 --gpus '0000:0e:00.0/1882/543f' --gpus '0000:0e:00.0/1887/593f' --node 12
12:06PM INF deploying network
12:06PM INF deploying vm
12:07PM INF vm yggdrasil ip: 300:e9c4:9048:57cf:7da2:ac99:99db:8821
```
# Get
To get the VM, use the following template:
```bash
tfcmd get vm <vm>
```
Make sure to replace `<vm>` with the name of the VM specified using `tfcmd`.
## Get Example
In the following example, the name of the deployment to get is `examplevm`.
```console
$ tfcmd get vm examplevm
3:20PM INF vm:
{
"Name": "examplevm",
"NodeID": 15,
"SolutionType": "examplevm",
"SolutionProvider": null,
"NetworkName": "examplevmnetwork",
"Disks": [
{
"Name": "examplevmdisk",
"SizeGB": 10,
"Description": ""
}
],
"Zdbs": [],
"Vms": [
{
"Name": "examplevm",
"Flist": "https://hub.grid.tf/tf-official-apps/threefoldtech-ubuntu-22.04.flist",
"FlistChecksum": "",
"PublicIP": false,
"PublicIP6": false,
"Planetary": true,
"Corex": false,
"ComputedIP": "",
"ComputedIP6": "",
"YggIP": "301:ad3a:9c52:98d1:cd05:1595:9abb:e2f1",
"IP": "10.20.2.2",
"Description": "",
"CPU": 2,
"Memory": 4096,
"RootfsSize": 2048,
"Entrypoint": "/sbin/zinit init",
"Mounts": [
{
"DiskName": "examplevmdisk",
"MountPoint": "/data"
}
],
"Zlogs": null,
"EnvVars": {
"SSH_KEY": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDcGrS1RT36rHAGLK3/4FMazGXjIYgWVnZ4bCvxxg8KosEEbs/DeUKT2T2LYV91jUq3yibTWwK0nc6O+K5kdShV4qsQlPmIbdur6x2zWHPeaGXqejbbACEJcQMCj8szSbG8aKwH8Nbi8BNytgzJ20Ysaaj2QpjObCZ4Ncp+89pFahzDEIJx2HjXe6njbp6eCduoA+IE2H9vgwbIDVMQz6y/TzjdQjgbMOJRTlP+CzfbDBb6Ux+ed8F184bMPwkFrpHs9MSfQVbqfIz8wuq/wjewcnb3wK9dmIot6CxV2f2xuOZHgNQmVGratK8TyBnOd5x4oZKLIh3qM9Bi7r81xCkXyxAZbWYu3gGdvo3h85zeCPGK8OEPdYWMmIAIiANE42xPmY9HslPz8PAYq6v0WwdkBlDWrG3DD3GX6qTt9lbSHEgpUP2UOnqGL4O1+g5Rm9x16HWefZWMjJsP6OV70PnMjo9MPnH+yrBkXISw4CGEEXryTvupfaO5sL01mn+UOyE= abdulrahman@AElawady-PC\n"
},
"NetworkName": "examplevmnetwork"
}
],
"QSFS": [],
"NodeDeploymentID": {
"15": 22748
},
"ContractID": 22748
}
```
# Cancel
To cancel your VM deployment, use the following template:
```bash
tfcmd cancel <deployment-name>
```
Make sure to replace `<deployment-name>` with the name of the deployment specified using `tfcmd`.
## Cancel Example
In the following example, the name of the deployment to cancel is `examplevm`.
```console
$ tfcmd cancel examplevm
3:37PM INF canceling contracts for project examplevm
3:37PM INF examplevm canceled
```
# Questions and Feedback
If you have any questions or feedback, you can ask the ThreeFold community for help on the [ThreeFold Forum](http://forum.threefold.io/) or on the [ThreeFold Grid Tester Community](https://t.me/threefoldtesting) on Telegram.

125
collections/documentation/developers/tfcmd/tfcmd_zdbs.md Normal file
View File

@@ -0,0 +1,125 @@
<h1>ZDBs</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Deploy](#deploy)
- [Required Flags](#required-flags)
- [Optional Flags](#optional-flags)
- [Get](#get)
- [Cancel](#cancel)
***
## Introduction
In this section, we explore how to use ZDBs related commands using `tfcmd` to interact with the TFGrid.
## Deploy
```bash
tfcmd deploy zdb [flags]
```
### Required Flags
- project_name: project name for the ZDBs deployment also used for canceling the deployment. must be unique.
- size: HDD of zdb in GB.
### Optional Flags
- node: node id zdbs should be deployed on.
- farm: farm id zdbs should be deployed on, if set choose available node from farm that fits zdbs deployment specs (default 1). note: node and farm flags cannot be set both.
- count: count of zdbs to be deployed (default 1).
- names: a slice of names for the number of ZDBs.
- password: password for ZDBs deployed
- description: description for your ZDBs, it's optional.
- mode: the enumeration of the modes 0-db can operate in (default user).
- public: if zdb gets a public ip6 (default false).
Example:
- Deploying ZDBs
```console
$ tfcmd deploy zdb --project_name examplezdb --size=10 --count=2 --password=password
12:06PM INF deploying zdbs
12:06PM INF zdb 'examplezdb0' is deployed
12:06PM INF zdb 'examplezdb1' is deployed
```
## Get
```bash
tfcmd get zdb <zdb-project-name>
```
`zdb-project-name` is the name of the deployment specified in while deploying using tfcmd.
Example:
```console
$ tfcmd get zdb examplezdb
3:20PM INF zdb:
{
"Name": "examplezdb",
"NodeID": 11,
"SolutionType": "examplezdb",
"SolutionProvider": null,
"NetworkName": "",
"Disks": [],
"Zdbs": [
{
"name": "examplezdb1",
"password": "password",
"public": false,
"size": 10,
"description": "",
"mode": "user",
"ips": [
"2a10:b600:1:0:c4be:94ff:feb1:8b3f",
"302:9e63:7d43:b742:469d:3ec2:ab15:f75e"
],
"port": 9900,
"namespace": "81-36155-examplezdb1"
},
{
"name": "examplezdb0",
"password": "password",
"public": false,
"size": 10,
"description": "",
"mode": "user",
"ips": [
"2a10:b600:1:0:c4be:94ff:feb1:8b3f",
"302:9e63:7d43:b742:469d:3ec2:ab15:f75e"
],
"port": 9900,
"namespace": "81-36155-examplezdb0"
}
],
"Vms": [],
"QSFS": [],
"NodeDeploymentID": {
"11": 36155
},
"ContractID": 36155,
"IPrange": ""
}
```
## Cancel
```bash
tfcmd cancel <zdb-project-name>
```
`zdb-project-name` is the name of the deployment specified in while deploying using tfcmd.
Example:
```console
$ tfcmd cancel examplezdb
3:37PM INF canceling contracts for project examplezdb
3:37PM INF examplezdb canceled
```