Decort SDK - это библиотека, написанная на языке GO, позволяющая взаимодействовать с API облачной платформы **DECORT**. Библиотека содеражит в себе структуры и методы, необходимые для отправки запросов. Decort SDK имеет встроенный http-клиент и поддерживает разные способы авторизации на платформе. Библиотека так же содержит в себе модели ответов от платформы.
- [Создание структуры запроса](#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 (
"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"`
}
```
#### Пример создания запроса для развертывания виртуальной машины:
// 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. Обработать результат и ошибки.
Т.к. все вызовы методов идут последовательно, можно их объеденить в конвейер:
stSolo
2 years ago