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

manual added whole devs

Browse Source
This commit is contained in:
mik-tf
2024-04-15 18:35:56 +00:00
parent 3cd741971c
commit 2c0f849383
175 changed files with 12747 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
collections/manual/documentation/developers/tfrobot/tfrobot.md Normal file
View File

@@ -0,0 +1,13 @@
<h1>TFROBOT</h1>
TFROBOT (`tfrobot`) is a command line interface tool that offers simultaneous mass deployment of groups of VMs on the ThreeFold Grid, with support of multiple retries for failed deployments, and customizable configurations, where you can define node groups, VMs groups and other configurations through a YAML or a JSON file.
Consult the [ThreeFoldTech TFROBOT repository](https://github.com/threefoldtech/tfgrid-sdk-go/tree/development/tfrobot) for the latest updates and read the [basics](../../system_administrators/getstarted/tfgrid3_getstarted.md) to get up to speed if needed.
<h2>Table of Contents</h2>
- [Installation](./tfrobot_installation.md)
- [Configuration File](./tfrobot_config.md)
- [Deployment](./tfrobot_deploy.md)
- [Commands and Flags](./tfrobot_commands_flags.md)
- [Supported Configurations](./tfrobot_configurations.md)

57
collections/manual/documentation/developers/tfrobot/tfrobot_commands_flags.md Normal file
View File

@@ -0,0 +1,57 @@
<h1> Commands and Flags </h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Commands](#commands)
- [Subcommands](#subcommands)
- [Flags](#flags)
***
## Introduction
We present the various commands, subcommands and flags available with TFROBOT.
## Commands
You can run the command `tfrobot help` at any time to access the help section. This will also display the available commands.
| Command | Description |
| ---------- | ---------------------------------------------------------- |
| completion | Generate the autocompletion script for the specified shell |
| help | Help about any command |
| version | Get latest build tag |
Use `tfrobot [command] --help` for more information about a command.
## Subcommands
You can use subcommands to deploy and cancel workloads on the TFGrid.
- **deploy:** used to mass deploy groups of vms with specific configurations
```bash
tfrobot deploy -c path/to/your/config.yaml
```
- **cancel:** used to cancel all vms deployed using specific configurations
```bash
tfrobot cancel -c path/to/your/config.yaml
```
- **load:** used to load all vms deployed using specific configurations
```bash
tfrobot load -c path/to/your/config.yaml
```
## Flags
You can use different flags to configure your deployment.
| Flag | Usage |
| :---: | :---: |
| -c | used to specify path to configuration file |
| -o | used to specify path to output file to store the output info in |
| -d | allow debug logs to appear in the output logs |
| -h | help |
> **Note:** Make sure to use every flag once. If the flag is repeated, it will ignore all values and take the last value of the flag.`

131
collections/manual/documentation/developers/tfrobot/tfrobot_config.md Normal file
View File

@@ -0,0 +1,131 @@
<h1> Configuration File</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Examples](#examples)
- [YAML Example](#yaml-example)
- [JSON Example](#json-example)
- [Create a Configuration File](#create-a-configuration-file)
***
## Introduction
To use TFROBOT, the user needs to create a YAML or a JSON configuration file that will contain the mass deployment information, such as the groups information, number of VMs to deploy how, the compute, storage and network resources needed, as well as the user's credentials, such as the SSH public key, the network (main, test, dev, qa) and the TFChain mnemonics.
## Examples
We present here a configuration file example that deploys 3 nodes with 2 vcores, 16GB of RAM, 100GB of SSD, 50GB of HDD and an IPv4 address. The same deployment is shown with a YAML file and with a JSON file. Parsing is based on file extension, TFROBOT will use JSON format if the file has a JSON extension and YAML format otherwise.
You can use this example for guidance, and make sure to replace placeholders and adapt the groups based on your actual project details. To the minimum, `ssh_key1` should be replaced by the user SSH public key and `example-mnemonic` should be replaced by the user mnemonics.
Note that if no IPs are specified as true (IPv4 or IPv6), an Yggdrasil IP address will automatically be assigned to the VM, as at least one IP should be set to allow an SSH connection to the VM.
### YAML Example
```
node_groups:
- name: group_a
nodes_count: 3
free_cpu: 2
free_mru: 16
free_ssd: 100
free_hdd: 50
dedicated: false
public_ip4: true
public_ip6: false
certified: false
region: europe
vms:
- name: examplevm123
vms_count: 5
node_group: group_a
cpu: 1
mem: 0.25
public_ip4: true
public_ip6: false
ssd:
- size: 15
mount_point: /mnt/ssd
flist: https://hub.grid.tf/tf-official-apps/base:latest.flist
entry_point: /sbin/zinit init
root_size: 0
ssh_key: example1
env_vars:
user: user1
pwd: 1234
ssh_keys:
example1: ssh_key1
mnemonic: example-mnemonic
network: dev
max_retries: 5
```
### JSON Example
```
{
"node_groups": [
{
"name": "group_a",
"nodes_count": 3,
"free_cpu": 2,
"free_mru": 16,
"free_ssd": 100,
"free_hdd": 50,
"dedicated": false,
"public_ip4": true,
"public_ip6": false,
"certified": false,
"region": europe,
}
],
"vms": [
{
"name": "examplevm123",
"vms_count": 5,
"node_group": "group_a",
"cpu": 1,
"mem": 0.25,
"public_ip4": true,
"public_ip6": false,
"ssd": [
{
"size": 15,
"mount_point": "/mnt/ssd"
}
],
"flist": "https://hub.grid.tf/tf-official-apps/base:latest.flist",
"entry_point": "/sbin/zinit init",
"root_size": 0,
"ssh_key": "example1",
"env_vars": {
"user": "user1",
"pwd": "1234"
}
}
],
"ssh_keys": {
"example1": "ssh_key1"
},
"mnemonic": "example-mnemonic",
"network": "dev",
"max_retries": 5
}
```
## Create a Configuration File
You can start with the example above and adjust for your specific deployment needs.
- Create directory
```
mkdir tfrobot_deployments && cd $_
```
- Create configuration file and adjust with the provided example above
```
nano config.yaml
```
Once you've set your configuration file, all that's left is to deploy on the TFGrid. Read the next section for more information on how to deploy with TFROBOT.

68
collections/manual/documentation/developers/tfrobot/tfrobot_configurations.md Normal file
View File

@@ -0,0 +1,68 @@
<h1> Supported Configurations </h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Config File](#config-file)
- [Node Group](#node-group)
- [Vms Groups](#vms-groups)
- [Disk](#disk)
***
## Introduction
When deploying with TFROBOT, you can set different configurations allowing for personalized deployments.
## Config File
| Field | Description| Supported Values|
| :---: | :---: | :---: |
| [node_group](#node-group) | description of all resources needed for each node_group | list of structs of type node_group |
| [vms](#vms-groups) | description of resources needed for deploying groups of vms belong to node_group | list of structs of type vms |
| ssh_keys | map of ssh keys with key=name and value=the actual ssh key | map of string to string |
| mnemonic | mnemonic of the user | should be valid mnemonic |
| network | valid network of ThreeFold Grid networks | main, test, qa, dev |
| max_retries | times of retries of failed node groups | positive integer |
## Node Group
| Field | Description| Supported Values|
| :---: | :---: | :---: |
| name | name of node_group | node group name should be unique |
| nodes_count | number of nodes in node group| nonzero positive integer |
| free_cpu | number of cpu of node | nonzero positive integer max = 32 |
| free_mru | free memory in the node in GB | min = 0.25, max = 256 |
| free_ssd | free ssd storage in the node in GB | positive integer value |
| free_hdd | free hdd storage in the node in GB | positive integer value |
| dedicated | are nodes dedicated | `true` or `false` |
| public_ip4 | should the nodes have free ip v4 | `true` or `false` |
| public_ip6 | should the nodes have free ip v6 | `true` or `false` |
| certified | should the nodes be certified(if false the nodes could be certified or DIY) | `true` or `false` |
| region | region could be the name of the continents the nodes are located in | africa, americas, antarctic, antarctic ocean, asia, europe, oceania, polar |
## Vms Groups
| Field | Description| Supported Values|
| :---: | :---: | :---: |
| name | name of vm group | string value with no special characters |
| vms_count | number of vms in vm group| nonzero positive integer |
| node_group | name of node_group the vm belongs to | should be defined in node_groups |
| cpu | number of cpu for vm | nonzero positive integer max = 32 |
| mem | free memory in the vm in GB | min = 0.25, max 256 |
| planetary | should the vm have yggdrasil ip | `true` or `false` |
| public_ip4 | should the vm have free ip v4 | `true` or `false` |
| public_ip6 | should the vm have free ip v6 | `true` or `false` |
| flist | should be a link to valid flist | valid flist url with `.flist` or `.fl` extension |
| entry_point | entry point of the flist | path to the entry point in the flist |
| ssh_key | key of ssh key defined in the ssh_keys map | should be valid ssh_key defined in the ssh_keys map |
| env_vars | map of env vars | map of type string to string |
| ssd | list of disks | should be of type disk|
| root_size | root size in GB | 0 for default root size, max 10TB |
## Disk
| Field | Description| Supported Values|
| :---: | :---: | :---: |
| size | disk size in GB| positive integer min = 15 |
| mount_point | disk mount point | path to mountpoint |

59
collections/manual/documentation/developers/tfrobot/tfrobot_deploy.md Normal file
View File

@@ -0,0 +1,59 @@
<h1> Deployment </h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Deploy Workloads](#deploy-workloads)
- [Delete Workloads](#delete-workloads)
- [Logs](#logs)
- [Using TFCMD with TFROBOT](#using-tfcmd-with-tfrobot)
- [Get Contracts](#get-contracts)
***
## Introduction
We present how to deploy workloads on the ThreeFold Grid using TFROBOT.
## Prerequisites
To deploy workloads on the TFGrid with TFROBOT, you first need to [install TFROBOT](./tfrobot_installation.md) on your machine and create a [configuration file](./tfrobot_config.md).
## Deploy Workloads
Once you've installed TFROBOT and created a configuration file, you can deploy on the TFGrid with the following command. Make sure to indicate the path to your configuration file.
```bash
tfrobot deploy -c ./config.yaml
```
## Delete Workloads
To delete the contracts, you can use the following line. Make sure to indicate the path to your configuration file.
```bash
tfrobot cancel -c ./config.yaml
```
## Logs
To ensure a complete log history, append `2>&1 | tee path/to/log/file` to the command being executed.
```bash
tfrobot deploy -c ./config.yaml 2>&1 | tee path/to/log/file
```
## Using TFCMD with TFROBOT
### Get Contracts
The TFCMD tool works well with TFROBOT, as it can be used to query the TFGrid, for example you can see the contracts created by TFROBOT by running the TFCMD command, taking into consideration that you are using the same mnemonics and are on the same network:
```bash
tfcmd get contracts
```
For more information on TFCMD, [read the documentation](../tfcmd/tfcmd.md).

36
collections/manual/documentation/developers/tfrobot/tfrobot_installation.md Normal file
View File

@@ -0,0 +1,36 @@
<h1>Installation</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Installation](#installation)
***
## Introduction
This section covers the basics on how to install TFROBOT (`tfrobot`).
TFROBOT is available as binaries. Make sure to download the latest release and to stay up to date with new releases.
## Installation
To install TFROBOT, simply download and extract the TFROBOT binaries to your path.
- Create a new directory for `tfgrid-sdk-go`
```
mkdir tfgrid-sdk-go
cd tfgrid-sdk-go
```
- Download latest release from [releases](https://github.com/threefoldtech/tfgrid-sdk-go/releases)
- ```
wget https://github.com/threefoldtech/tfgrid-sdk-go/releases/download/v0.14.4/tfgrid-sdk-go_Linux_x86_64.tar.gz
```
- Extract the binaries
- ```
tar -xvf tfgrid-sdk-go_Linux_x86_64.tar.gz
```
- Move `tfrobot` to any `$PATH` directory:
```bash
mv tfrobot /usr/local/bin
```