v1.0.0

2022-12-22 17:56:47 +03:00
parent 8712561853
commit d4b1ab7133
672 changed files with 28509 additions and 4419 deletions
--- a/README.md
+++ b/README.md
@@ -1,47 +1,427 @@
 # Decort SDK

-## Install
+Decort SDK - это библиотека, написанная на языке GO, позволяющая взаимодействовать с API облачной платформы **DECORT**. Библиотека содеражит в себе структуры и методы, необходимые для отправки запросов. Decort SDK имеет встроенный http-клиент и поддерживает разные способы авторизации на платформе. Библиотека так же содержит в себе модели ответов от платформы.
+
+## Оглавление
+
+- [Установка](#установка)
+- [Список API](#список-api)
+  - [Cloudapi](#cloudapi)
+  - [Cloudbroker](#cloudbroker)
+- [Работа с библиотекой](#работа-с-библиотекой)
+  - [Настройка конфигурации клиента](#настройка-конфигурации-клиента)
+  - [Создание клиента](#создание-клиента)
+  - [Создание структуры запроса](#cоздание-структуры-запроса)
+  - [Выполнение запроса](#выполнение-запроса)
+
+## Установка
+
+Выполните команду в терминале:

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

-## Example
+## Список 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 (
-	"context"
-	"fmt"
-	"log"
-
-	"github.com/rudecs/decort-sdk/config"
-	"github.com/rudecs/decort-sdk/pkg/cloudapi/kvmx86"
+    "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)
-	req := kvmx86.CreateRequest{
-		RGID:    123,
-		Name:    "compute",
-		CPU:     4,
-		RAM:     4096,
-		ImageID: 321,
-	}
+    // Настройка конфигурации
+    cfg := config.Config{
+        AppID:     "<APPID>",
+        AppSecret: "<APPSECRET>",
+        SSOURL:    "https://sso.digitalenergy.online",
+        DecortURL: "https://mr4.digitalenergy.online",
+        Retries:   5,
+    }

-	res, err := client.KVMX86().Create(context.Background(), req)
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	fmt.Println(res)
+    // Создание клиента
+    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.СloudAPI().KVMX86().Create(context.Background(), req)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println(res)
 }
 ```