decortsdk

Decort SDK

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

Версии

- Версия 1.0.x Decort-SDK соответствует 3.8.4 версии платформы
- Версия 1.1.x Decort-SDK соответствует 3.8.5 версии платформы
- Версия 1.2.x Decort-SDK соответствует 3.8.5 версии платформы

Оглавление

• Установка
• Список API
  • Cloudapi
  • Cloudbroker
• Работа с библиотекой
  • Настройка конфигурации клиента
  • Создание клиента
  • Создание структуры запроса
  • Выполнение запроса
• Работа с legacy клиентом
  • Настройка конфигурации legacy клиента
  • Создание legacy клиента
  • Создание структуры запроса
  • Выполнение запроса

Установка

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

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. Выполнение запроса.

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

Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.

Пример кода:

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, с помощью которой можно взаимодействовать с платформой.

Пример

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 в комментариях;
• Доп. информация (допустимые значения, значения по умолчанию).

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

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"`
}

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

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 имеются свои доступные методы, которые определяются платформой.

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

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

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

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

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)
}

Работа с legacy клиентом

Работа с legacy клиентом применяется для пользователей, которые не используют для авторизации decs3o.

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

Сначала, необходимо создать переменную конфигурации клиента. Конфигурация состоит как из обязательных, так и необязательных полей.

Пример кода:

import (
    "github.com/rudecs/decort-sdk/config"
)
func main(){
    // Настройка конфигурации
    legacyCfg := config.LegacyConfig{
        Username:     "<USERNAME>",
        Password: "<PASSWORD>",
        DecortURL: "https://mr4.digitalenergy.online",
        Retries:   5,
    }
}

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

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

Пример

package main

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

func main() {
    // Настройка конфигурации
    legacyCfg := config.LegacyConfig{
        Username:  "<USERNAME>",
        Password:  "<PASSWORD>",
        DecortURL: "https://mr4.digitalenergy.online",
        Retries:   5,
    }

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