Автоматизация

VP
Vasiliy Ponomarenko
4 сентября 2021

Список API ключей

API ключи для доступа к вашему проекту.

API

Serverspace Public API - публичный API для взаимодействия с услугами Serverspace. Действия, выполняемые в панели управления Serverspace, также могут быть выполнены с помощью публичного API.

Авторизация

Для работы с публичным API создайте API-ключ для проекта и передавайте его при каждом запросе в заголовке X-API-KEY. Например, при использовании утилиты cURL, заголовок будет выглядеть следующим образом:

-H "X-API-KEY: lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r"

Все запросы API необходимо выполнять через протокол HTTPS, эндпоинт публичного API находится по следующему URL:

https://api.serverspace.io/

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

Получим информацию о проекте, для этого отправим запрос, воспользовавшись утилитой cURL:

curl -X GET
https://api.serverspace.io/api/v1/project
-H 'content-type: application/json'
-H 'x-api-key: lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r'

В результате будет возвращена информация о проекте:

{
"project": {
"balance": 400.07,
"created": "2019-04-08T10:35:53.7021047Z",
"currency": "EUR",
"id": 1,
"state": "Active"
}
}

Создадим сервер со следующей конфигурацией: Амстердам, название “api-example”, операционная система Debian 10.7, конфигурация сервера 1 ГБ RAM, 1 CPU, загрузочный диск 25 ГБ SSD, 50 Мбит/с:

curl -X POST
https://api.serverspace.io/api/v1/servers
-H 'content-type: application/json'
-H 'x-api-key: lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r'
-d '{
"location_id": "am2",
"image_id": "Debian-10.7-X64",
"cpu": 1,
"ram_mb": 1024,
"volumes": [
{
"name": "boot",
"size_mb": 25600
}
],
"networks": [
{
"bandwidth_mbps": 50
}
],
"name": "api-example"
}'

 В результате возвращается ID задачи, по которой можно отследить процесс создания сервера:

{
"task_id" : "lt1507097"
}

CLI

s2ctl – это Serverspace в командной строке. CLI даёт возможность контролировать вашу инфраструктуру в терминале, так же как через панель управления. Инструмент можно получить на нашем Github.

Установка

s2ctl доступен для Linux и Windows как отдельный бинарный файл. Скачайте архив с Github и распакуйте его.

Установка на Linux

  1. Загрузите архив из репозитория GitHub:
wget https://github.com/itglobalcom/s2ctl/releases/download/vX.X.X/s2ctl-vX.X.X-linux.tar.gz

Здесь X.X.X это номер последней версии утилиты.

  1. Разархивируйте загруженный архив:
tar -xzf s2ctl-vX.X.X-linux.tar.gz
  1. Перейдите в созданную директорию и запустите утилиту s2ctl:
cd s2ctl-vX.X.X-linux
./s2ctl --help
  1. (Опционально) Вы также можете добавить каталог, в который вы поместили исполняемый файл s2ctl, в переменную среды $PATH, чтобы получить доступ к утилите из любой точки операционной системы. Чтобы увидеть, что находится в переменной $PATH прямо сейчас, введите команду:
echo $PATH

Для добавления новой директории в список используйте команду:

export PATH=$PATH:"<download directory>"

Переменная $PATH устанавливается оболочкой при каждом ее запуске, но вы можете сделать, так чтобы она всегда включала путь до утилиты в каждой новой оболочке, которую вы открываете. Точный способ зависит от того, какую оболочку вы используете.
Например, для bash нужно добавить строку о соответствующем файле следующим образом:

echo 'export PATH=$PATH:"<download directory>"' >> .bashrc

Для применения изменений используйте команду:

source ~/.bashrc

Установка на Windows

  1. Загрузите файл s2ctl-vX.X.X-windows.zip с Github и разархивируйте его.
  2. Запустите командную строку:
  • 1. Нажмите Win+R или Start → Поиск → Введите run → OK
  • 2. Введите команду cmd → OK
  1. По умолчанию в командной строке отображается домашняя директория текущего пользователя. Перейдите в директорию с извлечённым файлом:
cd <extracted file directory>
  1. Перейдя в нужную директорию, запустите команду:
s2ctl --help
  1. (Опционально) Вы также можете добавить каталог, в который вы поместили бинарный файл s2ctl, в переменную среды PATH, чтобы получить доступ к утилите из любой точки операционной системы.
  • 1. В поиске откройте и выберите: System (Control Panel).
  • 2. Нажмите ссылку Advanced system settings.
  • 3. Нажмите Environment Variables. В разделе System Variables Найдите переменную PATH и выберите её. Кликните Edit. Если переменная PATH не существует, то нажмите New.
  • 4. В окне Edit System Variable (или New System Variable), укажите значение переменной окружения PATH . Нажмите OK. Закройте все оставшиеся окна, нажав OK.

Авторизация

Для работы с CLI необходимо создать API-ключ для проекта и создать контекст или передавать API-ключ при каждом запросе.

Создание контекста

Использование контекстов упрощает использование утилиты s2ctl, т.к. не приходится для каждой команды в явном виде указывать API-ключ.

Для создания контекста используйте следующую команду:

s2ctl context create -k <api-ключ> -n <имя>

Например:

s2ctl context create -k lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r -n example

Передача ключа

Для передачи API-ключа в явном виде, его необходимо указывать в конце команды с помощью опции --apikey:

s2ctl <команда> --apikey <api-ключ>

Например:

s2ctl images --apikey lmGwbvllpIqIrKROOCLgE5Z941MKP5EYfbkgwtqJZGigfXUTpuYRpNQkCqShmm6r

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

Получим информацию о проекте с помощью следующей команды:

s2ctl project show

 В результате будет возвращена информация о проекте:

id: '1'
balance: '400.24'
currency: EUR
state: Active
created: '2019-04-08T10:35:53.7021047Z'

Создадим сервер:

s2ctl server create --name test-cli --location nj3 --image Ubuntu-20.04-X64 --cpu 2 --ram 2048M --volume boot:30720M --volume volume:10240M --public-network 50 --public-network 60

В результате возвращается ID задачи, по которой можно отследить процесс создания сервера:

task_id: lt1512053

Terraform

 Terraform-провайдер Serverspace позволяет управлять облачными ресурсами используя подход Infrastructure as Code. Управление осуществляется с помощью специальных конфигурационных файлов, в которых вы описываете желаемое состояние вашей инфраструктуры.

Установка Terraform

Для начала установите Terraform на вашу операционную систему. Рекомендуем воспользоваться инструкцией разработчика Terraform.

Конфигурация провайдера

  1. Для работы с Terraform создайте API-ключ для проекта.
  2. Создайте и перейдите в каталог, в котором вы будете работать с Terraform-провайдером.
  3. Создайте и откройте конфигурационный файл provider.tf.
  4. Вставьте в файл информацию о провайдере, где <api-ключ> это ваш API ключ, и сохраните изменения:
terraform {
required_providers {
serverspace = {
source = "itglobalcom/serverspace"
version = "0.2.0"
}
}
}variable "s2_token" {
type = string
default = "<api-ключ>"
}provider "serverspace" {
key = var.s2_token
}
  1. Откройте командную строку и перейдите в каталог, в котором вы создали файл. Выполните инициализацию для проверки корректности:
terraform init

 В случае успеха вы увидите следующее сообщение:

Initializing the backend...

Initializing provider plugins...
- Finding itglobalcom/serverspace versions matching "0.2.0"...
- Installing itglobalcom/serverspace v0.2.0...
- Installed itglobalcom/serverspace v0.2.0 (self-signed, key ID 062XXXXXXXXXXXX)

Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here: https://www.terraform.io/docs/cli/plugins/signing.html

Terraform has created a lock file .terraform.lock.hcl to record the provider selections it made above. Include this file in your version control repository so that Terraform can guarantee to make the same selections by default when you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure. All Terraform commands should now work.

If you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.

Описание вашей инфраструктуры

С помощью Terraform-провайдера Serverspace вы можете создавать инфраструктуру разной конфигурации. Подробную документацию вы можете найти в Terraform Registry.

 Рассмотрим пример создания простой инфраструктуры из двух серверов, объединенных в изолированную сеть:

  • Сервер в Амстердаме под названием “server-1” с операционной системой Ubuntu 20.04, конфигурация сервера 2 ГБ RAM, 2 CPU, загрузочный диск 40 ГБ SSD, дополнительный диск 20 ГБ SSD, 50 Мбит/с. Подключение к серверу будет осуществляться через SSH-ключ. На сервер будет установлено хранилище данных Redis.
  • Сервер в Амстердаме под названием “server-2” с операционной системой Ubuntu 20.04, конфигурация сервера 8 ГБ RAM, 4 CPU, загрузочный диск 40 ГБ SSD, 70 Мбит/с.
  • Изолированная сеть в Амстердаме с адресацией 192.168.0.0/24

 Для создания инфраструктуры выполните следующие шаги. 

  1. Создайте и откройте файл ssh_key.tf, в котором будет находиться публичная часть ssh-ключа для создания сервера.
  2. Вставьте в файл информацию о публичной части ssh-ключа и сохраните изменения, замените содержимое переменной public_key своим значением:
resource "serverspace_ssh" "terraform" {
name = "terraform-key"
public_key = "ssh-rsa AAAAB3Nza...JUDjlM= root@CentOS.local"
} variable "pvt_key" {type = stringdefault = "<путь до приватного ключа>"}
  1. Создайте и откройте файл main.tf, в котором будет находиться описание инфраструктуры.
  2. Вставьте в файл описание вашей инфраструктуры.
resource "serverspace_server" "server1" {
image = "Ubuntu-20.04-X64"
name = "server-1"
location = "am2"
cpu = 2
ram = 2048boot_volume_size = 40*1024volume {
name = "bar"
size = 20*1024
}nic {
network = ""
network_type = "PublicShared"
bandwidth = 50
}
nic {
network = resource.serverspace_isolated_network.my_net.id
network_type = "Isolated"
bandwidth = 0
}ssh_keys = [
resource.serverspace_ssh.terraform.id,
]connection {
host = self.public_ip_addresses[0]
user = "root"
type = "ssh"
private_key = file(var.pvt_key)
timeout = "2m"
}provisioner "remote-exec" {
inline = [
"export PATH=$PATH:/usr/bin",
"sudo apt-get update",
"sudo apt-get install -y redis-server",
"exit 0"
]
}resource "serverspace_server" "server2" {
image = "Ubuntu-20.04-X64"
name = "server-2"
location = "am2"
cpu = 4
ram = 8192

boot_volume_size = 40*1024

nic {
network = ""
network_type = "PublicShared"
bandwidth = 70
}
nic {
network = resource.serverspace_isolated_network.my_net.id
network_type = "Isolated"
bandwidth = 0
}
}

resource "serverspace_isolated_network" "my_net" {
location = "am2"
name = "my_net"
description = "Example for Terraform"
network_prefix = "192.168.0.0"
mask = 24
}
  1. Для создания инфраструктуры описанной выше выполните команду:
terraform apply

В результате появится диалоговое окно:

Terraform used the selected providers to generate the following execution plan.
Resource actions are indicated with the following symbols:
+ createTerraform will perform the following actions:# serverspace_isolated_network.my_net will be created
+ resource "serverspace_isolated_network" "my_net" {
+ description    = "Example for Terraform"
+ id             = (known after apply)
+ location       = "am2"
+ mask           = 24
+ name           = "my_net"
+ network_prefix = "192.168.0.0"
}# serverspace_server.server1 will be created
+ resource "serverspace_server" "server1" {
+ boot_volume_id      = (known after apply)
+ boot_volume_size    = 40960
+ cpu                 = 2
+ id                  = (known after apply)
+ image               = "Ubuntu-20.04-X64"
+ location            = "am2"
+ name                = "server-1"
+ public_ip_addresses = (known after apply)
+ ram                 = 2048
+ ssh_keys            = (known after apply)+ nic {
+ bandwidth    = 0
+ id           = (known after apply)
+ ip_address   = (known after apply)
+ network      = (known after apply)
+ network_type = "Isolated"
}
+ nic {
+ bandwidth    = 50
+ id           = (known after apply)
+ ip_address   = (known after apply)
+ network_type = "PublicShared"
}+ volume {
+ id   = (known after apply)
+ name = "bar"
+ size = 20480
}
}# serverspace_server.server2 will be created
+ resource "serverspace_server" "server2" {
+ boot_volume_id      = (known after apply)
+ boot_volume_size    = 40960
+ cpu                 = 4
+ id                  = (known after apply)
+ image               = "Ubuntu-20.04-X64"
+ location            = "am2"
+ name                = "server-2"
+ public_ip_addresses = (known after apply)
+ ram                 = 8192
+ ssh_keys            = (known after apply)+ nic {
+ bandwidth    = 0
+ id           = (known after apply)
+ ip_address   = (known after apply)
+ network      = (known after apply)
+ network_type = "Isolated"
}
+ nic {
+ bandwidth    = 70
+ id           = (known after apply)
+ ip_address   = (known after apply)
+ network_type = "PublicShared"
}
}# serverspace_ssh.terraform will be created
+ resource "serverspace_ssh" "terraform" {
+ id         = (known after apply)
+ name       = "terraform-key"
+ public_key = "ssh-rsa AAAAB3Nza...JUDjlM= root@CentOS.local"
}

Plan: 4 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.

  1. Для создания инфраструктуры введите yes.
 
Enter a value: yes

serverspace_ssh.terraform: Creating...

serverspace_isolated_network.my_net: Creating...

serverspace_ssh.terraform: Creation complete after 1s [id=3181]

serverspace_isolated_network.my_net: Creation complete after 8s [id=l2n403]

serverspace_server.server2: Creating...

serverspace_server.server1: Creating...

serverspace_server.server1: Still creating... [10s elapsed]

serverspace_server.server2: Still creating... [10s elapsed]

...

serverspace_server.server1 (remote-exec): (Reading database ...

serverspace_server.server1 (remote-exec): (Reading database ... 5%

serverspace_server.server1 (remote-exec): (Reading database ... 10%

...

serverspace_server.server1: Creation complete after 1m3s [id=l2s190038]

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

 

  1. Для просмотра текущей инфраструктуры выполните команду:
terraform show
  1. В результате будет отображена текущая конфигурация инфраструктуры:
# serverspace_isolated_network.my_net:
resource "serverspace_isolated_network" "my_net" {
description    = "Example for Terraform"
id             = "l2n403"
location       = "am2"
mask           = 24
name           = "my_net"
network_prefix = "192.168.0.0"
}# serverspace_server.server1:
resource "serverspace_server" "server1" {
boot_volume_id      = 58909
boot_volume_size    = 40960
cpu                 = 2
id                  = "l2s190038"
image               = "Ubuntu-20.04-X64"
location            = "am2"
name                = "server-1"
public_ip_addresses = [
"45.138.24.19",
]
ram                 = 2048
ssh_keys            = [
3181,
]nic {
bandwidth    = 0
id           = 59576
ip_address   = "192.168.0.1"
network      = "l2n403"
network_type = "Isolated"
}
nic {
bandwidth    = 50
id           = 59575
ip_address   = "45.138.24.19"
network_type = "PublicShared"
}volume {
id   = 58910
name = "bar"
size = 20480
}
}# serverspace_server.server2:
resource "serverspace_server" "server2" {
boot_volume_id      = 58911
boot_volume_size    = 40960
cpu                 = 4
id                  = "l2s190039"
image               = "Ubuntu-20.04-X64"
location            = "am2"
name                = "server-2"
public_ip_addresses = [
"31.44.3.68",
]
ram                 = 8192
ssh_keys            = []nic {
bandwidth    = 0
id           = 59578
ip_address   = "192.168.0.2"
network      = "l2n403"
network_type = "Isolated"
}
nic {
bandwidth    = 70
id           = 59577
ip_address   = "31.44.3.68"
network_type = "PublicShared"
}
}# serverspace_ssh.terraform:
resource "serverspace_ssh" "terraform" {
id         = "3181"
name       = "terraform-key"
public_key = "ssh-rsa AAAAB3Nza...JUDjlM= root@CentOS.local"
}
Остались вопросы? Задайте их нашему эксперту и получите квалифицированную помощь