dynamix-standard-go-sdk/README.md

# Dynamix standart SDK

Dynamix standart SDK - это библиотека, написанная на языке GO, позволяющая взаимодействовать с API облачной платформы **Vcontrol**. Библиотека содержит в себе структуры и методы, необходимые для отправки запросов. Dynamix standart SDK имеет встроенный http-клиент и поддерживает разные способы авторизации на платформе. Библиотека так же содержит в себе модели ответов от платформы.

## Оглавление

- [Dynamix standart SDK](#dynamix-standart-sdk)
  - [Оглавление](#оглавление)
  - [Установка](#установка)
  - [Список API](#список-api)
    - [API](#api)
  - [Работа с библиотекой](#работа-с-библиотекой)
    - [Настройка конфигурации клиента](#настройка-конфигурации-клиента)
      - [Пример конфигурации клиента](#пример-конфигурации-клиента)
      - [Парсинг конфигурации из файла](#парсинг-конфигурации-из-файла)
      - [Пример JSON конфигурации](#пример-json-конфигурации)
      - [Пример YAML конфигурации](#пример-yaml-конфигурации)
    - [Создание клиента](#создание-клиента)
    - [Пример](#пример)
    - [Создание структуры запроса](#создание-структуры-запроса)
      - [Пример комментариев структуры](#пример-комментариев-структуры)
      - [Пример создания запроса для развертывания виртуальной машины:](#пример-создания-запроса-для-развертывания-виртуальной-машины)
    - [Выполнение запроса](#выполнение-запроса)
      - [Пример выполнения запроса](#пример-выполнения-запроса)
      - [Пример выполнения GetRaw и ListRaw запросов](#пример-выполнения-getraw-и-listraw-запросов)


## Установка

Выполните команду в терминале:

```bash
go get -u repository.basistech.ru/BASIS/dynamix-standart-go-sdk
```

## Список API

Библиотека поддерживает одну группу API платформы:

- `api` - группа, которая позволяет воспользоваться всем стандартным функционалом платформы;

### API

Данная группа ручек позволяет выполнять следующие операции в платформе:

- `Cluster` - управление списками кластеров
- `Extstorage` - управление хранилищами для дисков ВМ;
- `Folder` - управление списками логических папок;
- `Image` - управление списками образов ВМ;
- `Node` - управление списками хостов;
- `Respool` - управление списками пулов ресурcов;
- `Tempate` - управление шаблонами виртуальных машин;
- `VM` - управление виртуальными машинами;

## Работа с библиотекой

Алгоритм работы с библиотекой выглядит следующим образом:

1. Выполнение одного из действий:
- настройка конфигурации клиента;
- парсинг конфигурации из файла.
2. Создание клиента.
3. Создание структуры запроса.
4. Выполнение запроса.

### Настройка конфигурации клиента

Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.
| Поле | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| Username | string | Да | username пользователя для выполнения запроса |
| Password | string | Да | password пользователя для выполнения запроса |
| VControlURL | string | Да | URL адрес платформы, с которой будет осуществляться взаимодействие |
| Retries | uint | Нет | Кол-во неудачных попыток выполнения запроса, по умолчанию - 5 |
| Timeout | config.Duration | Нет | Таймаут HTTP клиента, по умолчанию - без ограничений |
| SSLSkipVerify | bool | Нет | Пропуск проверки подлинности сертификата |
| Token | string | Нет | JWT токен |

##### Пример конфигурации клиента

```go
import (
"repository.basistech.ru/BASIS/dynamix-standart-go-sdk/config"
)

func main(){
// Настройка конфигурации
cfg := config.Config{
    Username:      "<USERNAME>",
    Password:      "<PASSWORD>",
    VControlURL:   "<VCONTROL_URL>",
    Retries:       5,
    SSLSkipVerify: true,
}

cfg.SetTimeout(5 * time.Minute)
}
```

#### Парсинг конфигурации из файла

Также возможно создать переменную конфигурации из JSON или YAML файла, используя функцию `ParseConfigJSON` (или `ParseConfigYAML`) из пакета config.
<br>
*См. пример файлов конфигурации ниже и в директории `samples/`.*

```go
import (
"repository.basistech.ru/BASIS/dynamix-standart-go-sdk/config"
)

func main() {
// Парсинг конфигурации из JSON-файла
cfg, _ := config.ParseConfigJSON("<PATH>")
}
```

#### Пример JSON конфигурации

```json
{
	"username": "<USERNAME>",
	"password": "<PASSWORD>",
	"vControlURL": "<VCONTROL_URL>",
	"retries": 5,
	"timeout": "5m",
	"sslSkipVerify": false
}
```

#### Пример YAML конфигурации

```yaml
username: <USERNAME>
password: <PASSWORD>
vControlURL: <VCONTROL_URL>
retries: 5
timeout: 5m
sslSkipVerify: false
```

### Создание клиента

Создание клиента происходит с помощью функции-строителя `New` из основного пакета `dynamix-standart-go-sdk`, для избежания проблем с именами, пакету можно присвоить алиас `vcontrol`. Функция принимает конфигурацию, возвращает структуру `VControlClient`, с помощью которой можно взаимодействовать с платформой.

### Пример

```go
package main

import (
    vcontrol "repository.basistech.ru/BASIS/dynamix-standart-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/config"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    cfg.SetTimeout(5*time.Minute)

    // Создание клиента
    client := vcontrol.New(cfg)
}
```

### Создание структуры запроса

Структуры запросов определены в пакете `pkg/`:

В пакете находятся пакеты групп API:

- **api**:
  - `pkg/cluster` - для `Cluster`
  - `pkg/extstorage` - для `External storage`
  - `pkg/folder` - для `Folrer`
  - `pkg/image` - для `Image`
  - `pkg/node` - для `Node`
  - `pkg/respool` - для `Resourse pool`
  - `pkg/tempalte` - для `Template`
  - `pkg/vm` - для `VM`

В каждом пакете находится пакет `requests` с структурами запросов

Все поля структуры имеют описание, в которых содержится:

- Их назначение;
- Обязательный или нет - поле required в комментариях;
- Доп. информация (допустимые значения, значения по умолчанию).

#### Пример комментариев структуры
```go
// ListImageRequest struct to get list of images
type ListImageRequest struct {
    // Name of image
    // Required: false
    Name string `url:"name,omitempty" json:"name,omitempty"`

    // Size of image
    // Required: false
    Size string `url:"size,omitempty" json:"size,omitempty"`

    // Type of image
    // Required: false
    ImageType string `url:"image_type,omitempty" json:"image_type,omitempty" validate:"omitempty,image_type"`

    // Status of image
    // Required: false
    Status string `url:"status,omitempty" json:"status,omitempty" validate:"omitempty,image_status"`

    // ShareID of image
    // Required: false
    ShareID string `url:"share_id,omitempty" json:"share_id,omitempty"`

    // Active if True Image is active
    // Required: false
    Active interface{} `url:"active,omitempty" json:"active,omitempty" validate:"omitempty,is_bool"`

    // IsTemplateImage If True Image is template
    // Required: false
    // Default: False
    IsTemplateImage bool `url:"is_template_image,omitempty" json:"is_template_image,omitempty"`

    // Mark of image
    // Required: false
    Mark string `url:"mark,omitempty" json:"mark,omitempty"`

    // image for filtering by text field
    // Required: false
    FilterText string `url:"filter_text,omitempty" json:"filter_text,omitempty"`

    // List columns which will be used by filter_text
    // Required: false
    FilterColumns string `url:"filter_columns,omitempty" json:"filter_columns,omitempty"`

    // List of columns for sorting.
    // Required: false
    Sort []string `url:"sort,omitempty" json:"sort,omitempty"`

    // Visibility status of the interface (visible, all, deleted).
    // Required: false
    Visibility string `url:"visibility,omitempty" json:"visibility,omitempty" validate:"omitempty,visibility"`

    // Filter VM Images that are unavailable now, because share is unavailable
    // Required: false
    HideUnavailable interface{} `url:"hide_unavailable,omitempty" json:"hide_unavailable,omitempty" validate:"omitempty,is_bool"`

    // Number of the page to return.
    // Required: false
    Page int `url:"page,omitempty" json:"page,omitempty"`

    // Number of items to return per page.
    // Required: false
    Limit int `url:"limit,omitempty" json:"limit,omitempty"`
}
```

#### Пример создания запроса для развертывания виртуальной машины:

```go
package main

import (
    vcontrol "repository.basistech.ru/BASIS/dynamix-standart-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/config"
    vm "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/pkg/vm/requests"
)

func main() {
    // Настройка конфигурации
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    // Создание клиента
    client := vcontrol.New(cfg)

    // Создание структуры запроса
    // CreateRequest - реквест на создание виртуальной машины
    req := vm.CreateVMRequest{
        Name: "VMname",
        RAMSize: 1024,
        VideoRAMSize: 64
        CPUCount:     1,
        CPUSockets:   1,
    }
}
```

### Выполнение запроса

Чтобы выполнить запрос, необходимо:

1. Вызвать у клиента метод, отвечающий за определение группы API для взаимодействия, на данный момент это `.API()`. Данный метод возвращает соответствующие структуры, с помощью которых можно совершать запросы.
2. Вызвать у возвращенной структуры метод, определяющий группу ручек для взаимодействия.

   Доступные методы для `.API()`:

- `.Cluster()` - для работы с `Cluster`
- `.Extstorage()` - для работы с `External storage`
- `.Folder()` - для работы с `Folder`
- `.Image()` - для работы с `Image`
- `.Node()` - для работы с `Node`
- `.Respool()` - для работы с `Resource pool`
- `.Template()` - для работы с `Template`
- `.VM()` - для работы с `VM`

3. Вызвать метод, отвечающий за выполнение запроса и передать в него:

- контекст;
- структуру запроса.

4. Обработать результат и ошибки.

Т.к. все вызовы методов идут последовательно, можно их объединить в конвейер:
Общий вид конвейера будет выглядеть так:

```go
    client.<API>.<группа>.<метод>
```

#### Пример выполнения запроса

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    vcontrol "repository.basistech.ru/BASIS/dynamix-standart-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/config"
    vm "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/pkg/vm/requests"
    )

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    cfg.SetTimeout(5 * time.Minute)

    // Создание клиента
    client := vcontrol.New(cfg)

    // Создание структуры запроса
    req := vm.CreateVMRequest{
        Name:         "VMname",
        RAMSize:      1024,
        VideoRAMSize: 64,
        CPUCount:     1,
        CPUSockets:   1,
    }

    // Выполнение запроса с помощью конвейера
    res, err := client.API().VM().Create(context.Background(), req)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("%+v", res)
}
```

Для запросов Get и List реализованы запросы GetRaw и ListRaw, которые возвращают ответ не в виде соответствующей структуры, а в виде массива байт (JSON).
Выполнение таких запросов происходит аналогично.

#### Пример выполнения GetRaw и ListRaw запросов

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    vcontrol "repository.basistech.ru/BASIS/dynamix-standart-go-sdk"
    "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/config"
    vm "repository.basistech.ru/BASIS/dynamix-standart-go-sdk/pkg/vm/requests"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        Username:      "<USERNAME>",
        Password:      "<PASSWORD>",
        VControlURL:   "<VCONTROL_URL>",
        Retries:       5,
    }

    cfg.SetTimeout(5 * time.Minute)

    // Создание клиента
    client := vcontrol.New(cfg)

    // Создание структуры запроса
    // 1. Создание структуры запроса GetVMRequest на получение информации об виртуальной машине и выполнение GetRaw запроса с помощью конвейера
    req1 := vm.GetVMRequest{
        VmID:    360,
    }
    res1, err := client.API().VM().GetRaw(context.Background(), req1)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(res1))

    // 2. Создание структуры запроса ListVMRequest на получение информации об виртуальных машинах и выполнение ListRaw запроса с помощью конвейера
    req2 := vm.ListVMRequest{}
    res2, err := client.API().VM().ListRaw(context.Background(), req2)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(res2))
}
```