Dynamix SDK - это библиотека, написанная на языке GO, позволяющая взаимодействовать с API облачной платформы **Dynamix**. Библиотека содержит в себе структуры и методы, необходимые для отправки запросов. Dynamix SDK имеет встроенный http-клиент и поддерживает разные способы авторизации на платформе. Библиотека так же содержит в себе модели ответов от платформы.
- [Пример выполнения запроса](#пример-выполнения-запроса-2)
- [Пример валидации запросов, имеющих в своей структуре поле RAM (или MasterRam/WorkerRAM)](#пример-валидации-запросов-имеющих-в-своей-структуре-поле-ram-или-masterramworkerram)
- [Пример выполнения запроса](#пример-выполнения-запроса-3)
- [Работа с универсальным клиентом](#работа-с-универсальным-клиентом)
-`cloudapi` - пользовательская группа, которая позволяет воспользоваться всем стардартным функционалом платформы;
-`cloudbroker` - административная группа, которая позволяет воспользоваться всем стандартным функционалом платформы и расширенными возможностями, включающими в себя управление пользователями, ресурсами, платформами размещения ресурсов и т.д.
### Cloudapi
`Cloudapi` позволяет выполнять запросы к группе пользовательских конечных точек
Данная группа ручек позволяет выполнять следующие операции в платформе:
-`Account` - управление аккаунтами - внутренними учетными записями платформы, которые являются владельцами вычислительных ресурсов;
-`Audit` - получение информации о событиях системы;
-`BService` - управление группами виртуальных машин (computes);
-`Compute` - управление виртуальными машинами (индивидуально);
-`Disks` - управление виртуальными дисками;
-`DPDK` - управление виртуальными сетями DPDK;
-`ExtNet` - управление виртуальными сетями, отвечающими за внешний доступ;
-`FLIPgroup` - управление группами "плавающими" ip - адресами;
-`Image` - управление образами операционных систем;
-`K8CI` - получение информации о конвейере для создания кластера;
-`K8S` - управление кластерами kubernetes;
-`KVMx86` - создание виртуальной машины x86;
-`LB` - управление балансировщиками нагрузки;
-`Locations` - получение информации о grid площадки;
-`RG` - управление ресурсными группами аккаунта;
-`Stack` - получение информации о вычислительных узлах;
-`Tasks` - получение информации о ходе выполнения асинхронных задач (например, создание кластера);
-`VFPool` - управление пулом виртуальных сетевых функций;
-`VINS` - управление виртуальными изолированными сетями.
### Cloudbroker
`Cloudbroker` позволяет выполнять запросы к группе пользовательских конечных точек
Данная группа ручек позволяет выполнять следующие операции в платформе:
-`Account` - управление аккаунтами - внутренними учетными записями платформы, которые являются владельцами вычислительных ресурсов;
-`Audit` - получение информации о событиях системы;
-`APIAccess` - управление доступом к API и его объектам;
-`Backup` - управление резервным копированием;
-`Compute` - управление виртуальными машинами (индивидуально);
-`Disks` - управление виртуальными дисками;
-`DPDK` - управление виртуальными сетями DPDK;
-`ExtNet` - управление виртуальными сетями, отвечающими за внешний доступ;
-`FLIPGroup` - управление группами с «плавающими» ip адресами;
-`Grid` - управление площадками;
-`Group` - управление группами пользователей;
-`Image` - управление образами операционных систем;
-`K8CI` - управление конвейром для создания кластера;
-`K8S` - управление кластерами kubernetes;
-`KVMx86` - создание виртуальной машины x86;
-`LB` - управление балансировщиками нагрузки;
-`Node` - управление нодами платформы;
-`PCIDevice` - управление устройствами;
-`Prometheus` - получение статистики prometheus;
-`Resmon` - получение статистики resource monitoring;
-`RG` - управление ресурсными группами аккаунта;
-`SEP` - управление storage endpoint (sep);
-`Stack` - получение информации о вычислительных узлах;
-`Tasks` - получение информации о ходе выполнения асинхронных задач (например, создание кластера);
-`User` - управление пользователями (индивидуально);
-`VGPU` - управление виртуальными графическими процессорами;
-`VFPool` - управление пулом виртуальных сетевых функций;
-`VINS` - управление виртуальными изолированными сетями.
## Работа с библиотекой
Алгоритм работы с библиотекой выглядит следующим образом:
1. Выполнение одного из действий:
- настройка конфигурации клиента;
- парсинг конфигурации из файла.
2. Создание клиента.
3. Создание структуры запроса.
4. Выполнение запроса.
### Настройка конфигурации клиента
Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.
| Поле | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| AppID | string | Да | app_id ключа для выполнения запросов |
| AppSecret | string | Да | app_secret ключ для выполнения запроса |
| SSOURL | string | Да | URL адрес сервиса аутентификации и авторизации |
| DecortURL | string | Да | URL адрес платформы, с которой будет осуществляться взаимодействие |
| Retries | uint | Нет | Кол-во неудачных попыток выполнения запроса, по умолчанию - 5 |
| Timeout | config.Duration | Нет | Таймаут HTTP клиента, по умолчанию - без ограничений |
Создание клиента происходит с помощью функции-строителя `New` из основного пакета `dynamix-sdk`, для избежания проблем с именами, пакету можно присвоить алиас ``. Функция принимает конфигурацию, возвращает структуру `Client`, с помощью которой можно взаимодействовать с платформой.
// CreateRequest - реквест на создание виртуальной машины
req := kvmx86.CreateRequest{
RGID: 123,
Name: "compute",
CPU: 4,
RAM: 4096,
ImageID: 321,
}
}
```
### Выполнение запроса
Чтобы выполнить запрос, необходимо:
1. Вызвать у клиента метод, отвечаеющий за определение группы API для взаимодействия, это может быть `.CloudAPI()`, либо `.CloudBroker()`. Данные методы возвращаеют соответствующие структуры, с помощью которых можно совершать запросы.
2. Вызвать у возвращенной структуры метод, определяющий группу ручек для взаимодействия.
Доступные методы для `.CloudAPI()`:
-`.Account()` - для работы с`Account`
-`.Audit()` - для работы с`Audit`
-`.BService()` - для работы с`BService`
-`.Compute()` - для работы с`Compute`
-`.Disks()` - для работы с`Disks`
-`.DPDKNet()` - для работы с`DPDK`
-`.ExtNet()` - для работы с`ExtNet`
-`.FLIPgroup()` - для работы с`FLIPGroup`
-`.Image()` - для работы с`Image`
-`.K8CI()` - для работы с`K8CI`
-`.K8S()` - для работы с`K8S`
-`.KVMx86()` - для работы с`KVMX86`
-`.LB()` - для работы с`LB`
-`.Locations()` - для работы с`Locations`
-`.RG()` - для работы с`RG`
-`.Resmon()` - для работы с`Resmon`
-`.Stack()` - для работы с`Stack`
-`.Tasks()` - для работы с`Tasks`
-`.VFPool()` - для работы с`VFPool`
-`.VINS()` - для работы с`VINS`
Доступные методы для `.CloudBroker()`:
-`.Account()` - для работы с`Account`
-`.Audit()` - для работы с`Audit`
-`.APIAccess()` - для работы с`APIAccess`
-`.Backup()` - для работы с`Backup`
-`.Compute()` - для работы с`Compute`
-`.Disks()` - для работы с`Disks`
-`.DPDKNet()` - для работы с`DPDK`
-`.ExtNet()` - для работы с`ExtNet`
-`.FLIPGroup()` - для работы с`FLIPGroup`
-`.Grid()` - для работы с`Grid`
-`.Group()` - для работы с`Group`
-`.Image()` - для работы с`Image`
-`.K8CI()` - для работы с`K8CI`
-`.K8S()` - для работы с`K8S`
-`.KVMx86()` - для работы с`KVMX86`
-`.LB()` - для работы с`LB`
-`.Node()` - для работы с`Node`
-`.PCIDevice()` - для работы с`PCIDevice`
-`.Prometheus()` - для работы с`Prometheus`
-`.Resmon()` - для работы с`Resmon`
-`.RG()` - для работы с`RG`
-`.SEP()` - для работы с`SEP`
-`.Stack()` - для работы с`Stack`
-`.Tasks()` - для работы с`Tasks`
-`.User()` - для работы с`User`
-`.VGPU()` - для работы с`VGPU`
-`.VFPool()` - для работы с`VFPool`
-`.VINS()` - для работы с`VINS`
3. Вызвать метод, отвечающий за выполнение запроса и передать в него:
- контекст;
- структуру запроса.
У каждой группы ручек API имеются свои доступные методы, которые определяются платформой.
4. Обработать результат и ошибки.
Т.к. все вызовы методов идут последовательно, можно их объеденить в конвейер:
Для запросов Get и List реализованы запросы GetRaw и ListRaw, которые возвращают ответ не в виде соответствующей структуры, а в виде массива байт (JSON).
Для каждого `ListRequest` в SDK есть группа функций для фильтрации ответа платформы. Для того чтобы произвести фильтрацию по заданным полям, достаточно описать анонимную функцию (предикат) в `.FilterFunc()`, например:
// Функции сортировки имеют параметр inverse (bool):
// При значении false -> сортировка по возрастанию
// При true -> сортировка по убыванию
sorted := resp.
SortByCPU(false).
SortByRAM(false).
SortByCreatedTime(true)
// ....
```
### Сериализация
Результат преобразований легко сериализовать в JSON при помощи функции `.Serialize()`. Она принимает в себя 2 необязательных аргумента: префикс (prefix) и отступ (Indent).
В случае если функция вызывается без аргументов, то маршализация пройдет успешно, но без отступов и префиксов.
```go
// Сериализация данных с префиксом "" и отступом "\t"
SortByCPU(false). // Сортировка по кол-ву ядер CPU по возрастанию
SortByCreatedTime(true). // Сортировка по времени создания по убыванию
Serialize("", "\t") // Сериализация с префиксом "" и отступом "\t"
// Serialize - терминальная функция, возвращает Serialized (обертку над []byte)
// Запись данных в файл
err = filtered.WriteToFile("<PATH>")
if err != nil {
log.Fatal(err)
}
}
```
### Получение списка уникальных идентификаторов ID объекта
Для всех структур, имеющих поля со списками объектов с уникальными числовыми идентификаторами (ID), добавлены методы IDs(), возвращающие массивы уникальных идентификаторов объектов в этих списках.
Также возможно создать переменную конфигурации из JSON или YAML файла, используя функцию `ParseLegacyConfigJSON` (или `ParseLegacyConfigYAML`) из пакета config.
<br>
*См. пример файлов конфигурации ниже и в директории `samples/`.*
Создание клиента происходит с помощью функции-строителя `NewLegacy` из основного пакета `decort-sdk`, для избежания проблем с именами, пакету можно присвоить алиас `decort`. Функция принимает конфигурацию, возвращает структуру `DecortClient`, с помощью которой можно взаимодействовать с платформой.
Работа с BVS клиентом применяется для пользователей, которые используют для авторизации BVS.
### Настройка параметров BVS в кабинете администратора
Для корректной работы функции обновления токена необходимо соблюдать следующие условия:
на странице администратора по следующему пути: домены-<имя вашего домена>-(символ i)-токены
- параметр "Время жизни токена доступа" - устанавливается для всего домена. Не применяется есть по следующему пути: безопасность-клиентские_системы-(символ i)-токены-"Время жизни токена доступа" не выставлено иное время, которое имеет больший приоритет для конкретной клиентской системы
- параметр "Время простоя сессии" - время жизни токена обновления. В случае указания количества минут меньше, чем время жизни токена, то обновление токена будет работать некорректно. Редомендуется указывать время или равное или больше времени жизни токена
- параметр "Максимальное время жизни сессии" - время в течение которого возможно производить обновление токена. Если данный параметр будет равен времени жизни токена, то обновление токена будет работать некорректно. Редомендуется указывать время больше времени жизни токена
### Настройка конфигурации BVS клиента
Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.
Также возможно создать переменную конфигурации из JSON или YAML файла, используя функцию `ParseConfigBVSJSON` (или `ParseConfigBVSYAML`) из пакета config.
<br>
*См. пример файлов конфигурации ниже и в директории `samples/`.*
Создание клиента происходит с помощью функции-строителя `NewBVS` из основного пакета `decort-sdk`, для избежания проблем с именами, пакету можно присвоить алиас `decort`. Функция принимает конфигурацию, возвращает структуру `DecortClient`, с помощью которой можно взаимодействовать с платформой.
В случае указания значения в переменной конфигурации `PathCfg` токен и конфигурация будут записаны в файл в формате `json`, переменная `PathToken` служит для записи токена в файл в формате `json`
В случае указания значения в переменной конфигурации `PathCfg` обновленный токен и конфигурация будут записаны в файл в формате `json`, переменная `PathToken` служит для записи токена в файл в формате `json`
#### Пример валидации запросов, имеющих в своей структуре поле RAM (или MasterRam/WorkerRAM)
Если структура запроса содержит поле RAM (или MasterRam/WorkerRAM), то он может быть проверен на валидность. Для этого запрос должен быть передан в функцию ValidateRAM. Вторым аргументом ValidateRAM ожидает число uint64. Рекомендуется использовать константу constants.RAM_DIVISIBILITY. Функция проверит кратно ли значение поля RAM (или MasterRam/WorkerRAM) этому числу.
Создание клиента происходит с помощью функции-строителя `NewUniversal` из основного пакета `decort-sdk`, для избежания проблем с именами, пакету можно присвоить алиас `decort`. Функция принимает конфигурацию, возвращает структуру `ClientInterface`, с помощью которой можно взаимодействовать с платформой.
