# Decort SDK

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

## Версии
	- Версия 1.0.0 Decort-SDK соответствует 3.8.4 версии платформы 
	- Версия 1.1.0 Decort-SDK соответствует 3.8.5 версии платформы 

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

- [Установка](#установка)
- [Список API](#список-api)
  - [Cloudapi](#cloudapi)
  - [Cloudbroker](#cloudbroker)
- [Работа с библиотекой](#работа-с-библиотекой)
  - [Настройка конфигурации клиента](#настройка-конфигурации-клиента)
  - [Создание клиента](#создание-клиента)
  - [Создание структуры запроса](#cоздание-структуры-запроса)
  - [Выполнение запроса](#выполнение-запроса)

## Установка

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

```bash
go get -u github.com/rudecs/decort-sdk
```

## Список API

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

- `cloudapi` - пользовательская группа, которая позволяет воспользоваться всем стардартным функционалом платформы;
- `cloudbroker` - административная группа, которая позволяет воспользоваться всем стандартным функционалом платформы и расширенными возможностями, включающими в себя управление пользователями, ресурсами, платформами размещения ресурсов и т.д.

### Cloudapi

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

- `Account` - управление аккаунтами - внутренними учетными записями платформы, которые являются владельцами вычислительных ресурсов;
- `BService` - управление группами виртуальных машин (computes);
- `Compute` - управление виртуальными машинами (индивидуально);
- `ComputeCI` - управление конвейром для создания виртуальных машин;
- `Disks` - управление виртуальными дисками;
- `ExtNet` - управление виртуальными сетями, отвечающими за внешний доступ;
- `FLIPgroup` - управление группами "плавающими" ip - адресами;
- `Image` - управление образами операционных систем;
- `K8CI` - управление конвейром для создания кластера;
- `K8S` - управление кластерами kubernetes;
- `KVMPPC` - создание виртуальной машины Power PC (IBM);
- `KVMx86` - создание виртуальной машины x86;
- `LB` - управление балансировщиками нагрузки;
- `Locations` - получение информации о grid площадки;
- `RG` - управление ресурсными группами аккаунта;
- `Sizes` - получение информации о потребляемых ресурсах виртуальными машинами и дисками;
- `Tasks` - получение информации о ходе выполнения асинхронных задач (например, создание кластера);
- `VINS` - управление виртуальными изолированными сетями.

### Cloudbroker

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

- `Account` - управление аккаунтами - внутренними учетными записями платформы, которые являются владельцами вычислительных ресурсов;
- `Compute` - управление виртуальными машинами (индивидуально);
- `Disks` - управление виртуальными дисками;
- `ExtNet` - управление виртуальными сетями, отвечающими за внешний доступ;
- `Grid` - управление площадками;
- `Image` - управление образами операционных систем;
- `K8CI` - управление конвейром для создания кластера;
- `K8S` - управление кластерами kubernetes;
- `KVMPPC` - создание виртуальной машины Power PC (IBM);
- `KVMx86` - создание виртуальной машины x86;
- `LB` - управление балансировщиками нагрузки;
- `RG` - управление ресурсными группами аккаунта;
- `SEP` - управление storage endpoint (sep);
- `Tasks` - получение информации о ходе выполнения асинхронных задач (например, создание кластера);
- `VINS` - управление виртуальными изолированными сетями.

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

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

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

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

Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.
| Поле | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| AppID | string | Да | app_id ключа для выполнения запросов |
| AppSecret | string | Да | app_secret ключ для выполнения запроса |
| SSOURL | string | Да | URL адрес сервиса аутентификации и авторизации |
| DecortURL | string | Да | URL адрес платформы, с которой будет осуществляться взаимодействие |
| Retries | uint | Нет | Кол-во неудачных попыток выполнения запроса, по умолчанию - 5 |
| SSLSkipVerify | bool | Нет | Пропуск проверки подлинности сертификата, по умолчанию - true |
| Token | string | Нет | JWT токен |

Пример кода:

```go
import (
    "github.com/rudecs/decort-sdk/config"
)
func main(){
    // Настройка конфигурации
    cfg := config.Config{
        AppID:     "<APP_ID>",
        AppSecret: "<APP_SECRET>",
        SSOURL:    "https://sso.digitalenergy.online",
        DecortURL: "https://mr4.digitalenergy.online",
        Retries:   5,
    }
}
```

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

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

### Пример

```go
package main

import (
    "github.com/rudecs/decort-sdk/config"
    decort "github.com/rudecs/decort-sdk"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        AppID:     "<APPID>",
        AppSecret: "<APPSECRET>",
        SSOURL:    "https://sso.digitalenergy.online",
        DecortURL: "https://mr4.digitalenergy.online",
        Retries:   5,
    }

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

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

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

- `pkg/cloudapi` - для `cloudapi`
- `pkg/cloudbroker` - для `cloudbroker`

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

- **cloudapi**:
  - `pkg/cloudapi/account` - для `Account`
  - `pkg/cloudapi/bservice` - для `Basic Service`
  - `pkg/cloudapi/compute` - для `Compute`
  - `pkg/cloudapi/computeci` - для `ComputeCI`
  - `pkg/cloudapi/disks` - для `Disks`
  - `pkg/cloudapi/extnet` - для `ExtNet`
  - `pkg/cloudapi/flipgroup` - для `FLIPGroup`
  - `pkg/cloudapi/image` - для `Image`
  - `pkg/cloudapi/k8ci` - для `K8CI`
  - `pkg/cloudapi/k8s` - для `K8S`
  - `pkg/cloudapi/kvmppc` - для `KVMPPC`
  - `pkg/cloudapi/kvmx86` - для `KVMX86`
  - `pkg/cloudapi/lb` - для `LB`
  - `pkg/cloudapi/locations` - для `Locations`
  - `pkg/cloudapi/rg` - для `RG`
  - `pkg/cloudapi/sizes` - для `RG`
  - `pkg/cloudapi/tasks` - для `Tasks`
  - `pkg/cloudapi/vins` - для `VINS`
- **cloudbroker**:
  - `pkg/cloudbroker/account` - для `Account`
  - `pkg/cloudbroker/compute` - для `Compute`
  - `pkg/cloudbroker/disks` - для `Disks`
  - `pkg/cloudbroker/extnet` - для `ExtNet`
  - `pkg/cloudbroker/grid` - для `Grid`
  - `pkg/cloudbroker/image` - для `Image`
  - `pkg/cloudbroker/k8ci` - для `K8CI`
  - `pkg/cloudbroker/k8s` - для `K8S`
  - `pkg/cloudbroker/kvmppc` - для `KVMPPC`
  - `pkg/cloudbroker/kvmx86` - для `KVMX86`
  - `pkg/cloudbroker/lb` - для `LB`
  - `pkg/cloudbroker/rg` - для `RG`
  - `pkg/cloudbroker/sep` - для `SEP`
  - `pkg/cloudbroker/tasks` - для `Tasks`
  - `pkg/cloudbroker/vins` - для `VINS`

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

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

#### Пример комментарие структуры

```go
type CreateRequest struct {
	// ID of the resource group, which will own this VM
	// Required: true
	RGID uint64 `url:"rgId"`

	// Name of this VM.
	// Must be unique among all VMs (including those in DELETED state) in target resource group
	// Required: true
	Name string `url:"name"`

	// Number CPUs to allocate to this VM
	// Required: true
	CPU uint64 `url:"cpu"`

	// Volume of RAM in MB to allocate to this VM
	// Required: true
	RAM uint64 `url:"ram"`

	// ID of the OS image to base this VM on;
	// Could be boot disk image or CD-ROM image
	// Required: true
	ImageID uint64 `url:"imageId"`

	// Size of the boot disk in GB
	// Required: false
	BootDisk uint64 `url:"bootDisk,omitempty"`

	// ID of SEP to create boot disk on.
	// Uses images SEP ID if not set
	// Required: false
	SEPID uint64 `url:"sepId,omitempty"`

	// Pool to use if SEP ID is set, can be also empty if needed to be chosen by system
	// Required: false
	Pool string `url:"pool,omitempty"`

	// Network type
	// Should be one of:
	//	- VINS
	//	- EXTNET
	//	- NONE
	// Required: false
	NetType string `url:"netType,omitempty"`

	// Network ID for connect to,
	// for EXTNET - external network ID,
	// for VINS - VINS ID,
	// when network type is not "NONE"
	// Required: false
	NetID uint64 `url:"netId,omitempty"`

	// IP address to assign to this VM when connecting to the specified network
	// Required: false
	IPAddr string `url:"ipAddr,omitempty"`

	// Input data for cloud-init facility
	// Required: false
	Userdata string `url:"userdata,omitempty"`

	// Text description of this VM
	// Required: false
	Description string `url:"desc,omitempty"`

	// Start VM upon success
	// Required: false
	Start bool `url:"start,omitempty"`

	// Stack ID
	// Required: false
	StackID uint64 `url:"stackId,omitempty"`

	// System name
	// Required: false
	IS string `url:"IS,omitempty"`

	// Compute purpose
	// Required: false
	IPAType string `url:"ipaType,omitempty"`

	// Reason for action
	// Required: false
	Reason string `url:"reason,omitempty"`
}
```

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

```go
package main

import (
    "github.com/rudecs/decort-sdk/config"
    decort "github.com/rudecs/decort-sdk"
    "github.com/rudecs/decort-sdk/pkg/cloudapi/kvmx86"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        AppID:     "<APPID>",
        AppSecret: "<APPSECRET>",
        SSOURL:    "https://sso.digitalenergy.online",
        DecortURL: "https://mr4.digitalenergy.online",
        Retries:   5,
    }

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

    // Создание структуры запроса
    // CreateRequest - реквест на создание виртуальной машины
    req := kvmx86.CreateRequest{
        RGID:    123,
        Name:    "compute",
        CPU:     4,
        RAM:     4096,
        ImageID: 321,
    }
}
```

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

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

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

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

   - `.Account()` - для работы с `Account`
   - `.BService()` - для работы с `BService`
   - `.Compute()` - для работы с `Compute`
   - `.ComputeCI()` - для работы с `ComputeCI`
   - `.Disks()` - для работы с `Disks`
   - `.ExtNet()` - для работы с `ExtNet`
   - `.FLIPgroup()` - для работы с `FLIPGroup`
   - `.Image()` - для работы с `Image`
   - `.K8CI()` - для работы с `K8CI`
   - `.K8S()` - для работы с `K8S`
   - `.KVMPPC()` - для работы с `KVMPPC`
   - `.KVMx86()` - для работы с `KVMX86`
   - `.LB()` - для работы с `LB`
   - `.Locations()` - для работы с `Locations`
   - `.RG()` - для работы с `RG`
   - `.Sizes()` - для работы с `Sizes`
   - `.Tasks()` - для работы с `Tasks`
   - `.VINS()` - для работы с `VINS`

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

   - `.Account()` - для работы с `Account`
   - `.Compute()` - для работы с `Compute`
   - `.Disks()` - для работы с `Disks`
   - `.ExtNet()` - для работы с `ExtNet`
   - `.Grid()` - для работы с `Grid`
   - `.Image()` - для работы с `Image`
   - `.K8CI()` - для работы с `K8CI`
   - `.K8S()` - для работы с `K8S`
   - `.KVMPPC()` - для работы с `KVMPPC`
   - `.KVMx86()` - для работы с `KVMX86`
   - `.LB()` - для работы с `LB`
   - `.RG()` - для работы с `RG`
   - `.SEP()` - для работы с `SEP`
   - `.Tasks()` - для работы с `Tasks`
   - `.VINS()` - для работы с `VINS`

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

- контекст;
- структуру запроса.
  У кождой группы ручек API имеются свои доступные методы, которые определяются платформой.

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

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

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

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

```go
package main

import (
    "log"
    "fmt"

    "github.com/rudecs/decort-sdk/config"
    decort "github.com/rudecs/decort-sdk"
    "github.com/rudecs/decort-sdk/pkg/cloudapi/kvmx86"
)

func main() {
    // Настройка конфигурации
    cfg := config.Config{
        AppID:     "<APPID>",
        AppSecret: "<APPSECRET>",
        SSOURL:    "https://sso.digitalenergy.online",
        DecortURL: "https://mr4.digitalenergy.online",
        Retries:   5,
    }

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

    // Создание структуры запроса
    // CreateRequest - реквест на создание виртуальной машины
    req := kvmx86.CreateRequest{
        RGID:    123,
        Name:    "compute",
        CPU:     4,
        RAM:     4096,
        ImageID: 321,
    }

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

    fmt.Println(res)
}
```