Как управлять парком серверов с помощью API: примеры

Бесплатный перенос IT-инфраструктуры в облако

22 ноября 2024 г.

14 минут чтения

Планомерное развитие серверной инфраструктуры закономерно приводит к ее усложнению — поддерживаемых сервисов становится все больше, а их взаимодействие между собой становится все запутаннее.

Чем масштабнее инфраструктура, тем сложнее ей управлять. На помощь приходит автоматизация, когда рутинные действия и анализ данных выполняются без прямого участия человека.

Автоматизация серверной инфраструктуры возможна благодаря API — «application programming interface» или «интерфейс прикладного программирования».

По сути, это набор методов для взаимодействия кода одного программного продукта с кодом другого программного продукта.

Таким образом, можно написать программу, которая сможет, будучи полностью самостоятельной и изолированной, взаимодействовать с другой программой (такой же самостоятельной и изолированной).

В абстрактном примере мы могли бы из кода программы на Go или Python отправить запрос на перезапуск сервера (на котором, в свою очередь, запущена другая программа, прослушивающая порты) в формате JSON-файла:

{ 'login': 'goodGuy', 'password': 'mQGtAK9e', 'action': 'reload' }

В этом случае переменные login и password авторизуют пользователя, а action указывает на конкретное действие, которое необходимо выполнить на удаленном сервере.

Ответом на такой абстрактный запрос может быть сообщение об исполнении запрошенного действия:

{ 'action': 'reload', 'result': 'OK' }

В этом случае action указывает на выполненное действие, а result — на статус его выполнения.

Разумеется, API современных программных продуктов устроен несколько сложнее и по этой причине он намного безопаснее показанного выше примера (например, вместо логина и пароля используется токен).

В этой статье мы рассмотрим, как автоматически управлять удаленными серверами Timeweb Cloud с помощью соответствующего API, тем самым упрощая выполнение массовых рутинных действий и сбор аналитических данных.

Когда нужен API?

Использование API актуально в двух основных случаях:

Отправка данных (POST, PUT, PATCH, DELETE). Информация отправляется в инфраструктуру для совершения каких-либо действий. Например, серверу или группе серверов отправляется команда на перезагрузку или обновление конфигурации. В первом случае отправляется просто команда, во втором случае команда дополняется обновленным конфигурационным файлом.

Получение данных (GET). Информация получается из инфраструктуры для формирования каких-либо сведений. Например, на сервер отправляется запрос для получения актуальных данных о его работе, на основе которых формируется статистика в виде специальных метрик для системы мониторинга и аналитики. Это могут быть платежные транзакции, местонахождение серверов, потребление трафика или электроэнергии.

Можно сказать, что API существует в рамках этих двух базовых понятий — отправка и получение данных, которые приводят к определенным результатам.

Таким образом, когда серверная инфраструктура масштабируется, становясь сложнее, ручное управление и сбор данных становятся трудоемкой или невозможной задачей.

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

Поэтому, если издержки на выполнение операций начинают перевешивать их результативность, то пора задуматься об использовании API.

cloud

Управление серверами Timeweb Cloud в curl

Публичный API, который предоставляет Timeweb Cloud, позволяет управлять облачными ресурсами с помощью обыкновенных HTTP-запросов через методы GET, POST, PUT, PATCH, DELETE.

Большинство функций облака, доступных в панели управления Timeweb Cloud, также доступны и в API. Таким образом можно автоматизировать уже привычные ручные сценарии управления облачной инфраструктурой Timeweb Cloud.

Создание токена авторизации

В любом запросе к API Timeweb Cloud должен указываться специальный токен авторизации. Создать этот токен можно в панели управления в разделе API и Terraform.

Страница со списком существующих (если есть) токенов авторизации

Перейдя на страницу с токенами API, нужно нажать на кнопку Создать, после чего откроется страница конфигурации нового токена с рядом параметров:

Имя токена. Произвольное имя исключительно для того, чтобы различать множество разных токенов внутри панели управления.

Срок действия. Промежуток времени, в течении которого можно будет использовать токен. По истечении указанного срока токен удалится и доступ по нему прекратится.

Настройки токена. Список разрешенных действий (права доступа), которые можно совершать через API с использованием этого токена.

После указания всех параметров нужно нажать на кнопку Выпустить.

Страница настройки параметров будущего токена авторизации

После этого появится окно со сгенерированным токеном. Его нужно скопировать и сохранить в защищенный текстовый файл.

Под каждую программу, использующую API, можно выделить отдельный токен только с тем набором прав, который необходим для корректной работы конкретно этой программы.

Таким образом, токен снимает необходимость в явной передаче логина и пароля при совершении запросов, а также позволяет устанавливать ограничения на доступ к определенным функциям в целях безопасности.

Окно, предлагающее вручную скопировать и сохранить токен

Чтобы быстро и легко использовать полученный токен во время выполнения запросов, его необходимо сохранить в виде переменной в терминале консоли:

TIMEWEB_CLOUD_TOKEN=eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IjFrYnhacFJNQGJSI0tSbE1xS1lqIn0.eyJ1c2VyIjoieW41NTY2NSIsInR5cGUiOiJhcGlfa2V5IiwicG9ydGFsX3Rva2VuIjoiR1Z4Y0JBaGdnYXFXU1VZSEpDRnZneHQrZkFkSTdkN2ZOMXlhbnhVNzdneGNCOUQ3cGRjZ29vTC9FRzJRNnBEY0lMOXJJZms2K1ZiVjdvUDZSTHIxSENDa2pQZmIxTG5DRGwxSXQ5dGc2N2MvYlhQcUtHbVNnSSs4N1R5djBwRFNWZlBpWm13Q2U0b3dlT1Q5em9uZ1E0MkhTT2I2RDdBeWhUbktaU0JaRkd3PSIsImFwaV9rZXlfaWQiOiJmMjFjYzQ1NS0xZTUwLTRiNjAtYjVmMC05ZmExYzg3ZjM0MzYiLCJpYXQiOjE3MzEyNzkyMDF9.S5p_hmqgukvvPAfity7GPDEMmspV4KKZXT61XanduyD_SFx1iMsThgyY3kLCn4sSHQLh8VqBPu4rTUC5BsaIyaxR-4vFynWebqvEbirKttHtqH1IESysoNdPZfV2HY4906uefsqyOVChoQl8bCMiQ9HqFrYgPG-NnTzKBF0VemBAGZ8_np93frxiLwLaI7QwBrN9w5RMkcCWYDiPi3UEMrEhq10AaHfAWdMLdQzZ3UHn1yoSYxFlZ5_KMRsn7h5hC2DXzNNJ-EWGN943M4vGBKhBDRK2yBFXKVx3uA57P_hwmzjexxwcx0SrOz__wFKUHxc8WcGrjAATAQ5metYAv8ZcpRTAvGjrcIhDptuKlG4Pw_R_I3ZOF23j7B4ynfx36_RIC00fFMcXH4t6mZ0xF0Dndhbd77Vd701Mv4JRrCAb10WMAYh6T8O0_muvdcXKhXefbDHXeKu0wR4mq1FxJ8w2_-WFl47MNOxuew3tQLStWQwxSopbM9m5eJWwr5V2

Информация о балансе

Для проверки работы токена можно запросить состояние баланса в аккаунте Timeweb Cloud:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" \
  "https://api.timeweb.cloud/api/v1/account/finances"

Обратите внимание, что в команду запроса вставляется ранее созданная переменная TIMEWEB_CLOUD_TOKEN.

При этом:

Символ \ необходим, чтобы ввести команду в терминал консоли построчно.
Флаг -X указывает метод запроса.
Флаг -H указывает необходимый HTTP-заголовок.

Если запрос был отправлен корректно, в консольном терминале появится вывод с ответом сервера в формате JSON:

{"finances":{"balance":8.24,"currency":"RUB","discount_end_date_at":null,"discount_percent":0,"hourly_cost":0.41,"hourly_fee":0.41,"monthly_cost":300,"monthly_fee":300,"total_paid":930,"hours_left":20,"autopay_card_info":null,"total_balance":8.24454143},"response_id":"209c3c7a-c2da-45f1-9399-ad1874cfe1d6"}

В более читабельном виде ответ сервера выглядит так:

{
	"finances":
	{
		"balance":8.24,
		"currency":"RUB",
		"discount_end_date_at":null,
		"discount_percent":0,
		"hourly_cost":0.41,
		"hourly_fee":0.41,
		"monthly_cost":300,
		"monthly_fee":300,
		"total_paid":930,
		"hours_left":20,
		"autopay_card_info":null,
		"total_balance":8.24454143
	},
	"response_id":"209c3c7a-c2da-45f1-9399-ad1874cfe1d6"
}

Перезагрузка сервера

Еще одна простая команда — перезагрузка удаленного сервера.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" \
 "https://api.timeweb.cloud/api/v1/servers/{server_id}/reboot"

В этой команде {server_id} нужно заменить на уникальный идентификатор облачного сервера. Взять этот идентификатор можно из адресной строки браузера.

Слева вверху в конце адресной строки браузера можно найти идентификатор облачного сервера

Таким образом, команда перезагрузки облачного сервера будет выглядеть примерно так:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TIMEWEB_CLOUD_TOKEN" \
 "https://api.timeweb.cloud/api/v1/servers/3738417/reboot"

Обратите внимание, что в этом случае используется метод POST, а не GET. Таким образом, этот запрос изменяет состояние сервера, а не просто получает данные.

Управление серверами Timeweb Cloud в Golang

Разумеется, API необходим не для выполнения запросов через терминал консоли, а для управления облачными серверами из кода программ.

Поэтому мы рассмотрим несколько простых примеров работы с API в языке программирования Golang.

В этом руководстве используется интерпретатор Go версии 1.23.3, запущенный в операционной системе Ubuntu 22.04 на облачном сервере Timeweb Cloud.

Установка Go

Если в вашей системе еще не установлен Golang, то его необходимо загрузить с официального сайта в формате архива:

wget https://go.dev/dl/go1.23.3.linux-amd64.tar.gz -O go.tar.gz

А потом извлечь:

sudo tar -xzvf go.tar.gz -C /usr/local

Далее нужно указать бинарный файл в переменной PATH:

echo export PATH=$HOME/go/bin:/usr/local/go/bin:$PATH >> ~/.profile

И сохранить изменения:

source ~/.profile

Создание проекта

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

mkdir api

А потом перейдем в нее:

cd api

Теперь можно инициализировать проект Go:

go mod init api

Получение информации о балансе

Как и в случае с curl, наиболее простая вещь, которую можно сделать. — проверить состояние баланса на аккаунте.

Создадим отдельный скрипт для этого:

sudo nano balance.go

Скрипт будет представлять собой вот такой код:

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	client := &http.Client{} // создаем HTTP-клиент

	req, err := http.NewRequest("GET", "https://api.timeweb.cloud/api/v1/account/finances", nil) // создаем GET-запрос по API Timeweb Cloud
	if err != nil { log.Fatal(err) } // обрабатываем возможные ошибки

	// устанавливаем необходимые HTTP-заголовки
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer " + os.Getenv("TIMEWEB_CLOUD_TOKEN"))

	resp, err := client.Do(req) // выполняем запрос
	if err != nil { log.Fatal(err) } // обрабатываем возможные ошибки

	defer resp.Body.Close() // закрываем ответ сервера

	bodyText, err := io.ReadAll(resp.Body) // извлекаем тело ответа сервера
	if err != nil { log.Fatal(err) } // обрабатываем возможные ошибки

	fmt.Printf("%s\n", bodyText) // выводим в консоль ответ сервера
}

Однако, чтобы скрипт работал корректно, нужно перед его запуском в терминале консоли определить экспортируемую переменную с токеном авторизации:

export TIMEWEB_CLOUD_TOKEN="тут_токен"

И только после этого можно запустить скрипт:

go run balance.go

Результатом работы этого скрипта станет следующий консольный вывод:

{"finances":{"balance":48.82,"currency":"RUB","discount_end_date_at":null,"discount_percent":0,"hourly_cost":0.41,"hourly_fee":0.41,"monthly_cost":300,"monthly_fee":300,"total_paid":980,"hours_left":119,"autopay_card_info":null,"total_balance":48.81831205},"response_id":"7f849b90-5d42-44c7-a90a-a12875878bb3"}

Как видно, ответ сервера такой же, как и в случае с cURL.

Перезагрузка сервера в Go

Точно также можно перезагрузить сервер из кода программы на Go.

Создадим еще один скрипт:

sudo nano restart.go

Содержимым которого выступит код, практически аналогичный предыдущему примеру:

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	client := &http.Client{}

	req, err := http.NewRequest("POST", "https://api.timeweb.cloud/api/v1/servers/3738417/reboot", nil) // здесь нужно указать уникальный идентификатор сервера
	if err != nil { log.Fatal(err) }

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer " + os.Getenv("TIMEWEB_CLOUD_TOKEN"))

	resp, err := client.Do(req)
	if err != nil { log.Fatal(err) }

	defer resp.Body.Close()

	bodyText, err := io.ReadAll(resp.Body)
	if err != nil { log.Fatal(err) }

	fmt.Printf("%s\n", bodyText)
}

Аналогично перед запуском скрипта нужно убедиться в существовании экспортируемой переменной TIMEWEB_CLOUD_TOKEN, содержащей токен авторизации.

Либо можно использовать токен приложения внутри кода вашей программы в виде строковой переменной.

Управление серверами Timeweb Cloud в Python

Функционал, аналогичный терминалу curl и скриптам Go, можно реализовать на языке программирования Python.

Для простоты файлы с кодом на Python будем размещать в том же каталоге с проектом Go.

Получение данных о балансе

Создадим файл со скриптом, который будет запрашивать платежную информацию аккаунта Timeweb Cloud:

sudo nano balance.py

Код внутри будет таким:

import os
import requests

# объявляем список заголовков
headers = {
	'Content-Type': 'application/json',
	'Authorization': 'Bearer ' + os.getenv('TIMEWEB_CLOUD_TOKEN', ''),
}

# выполняем запрос к серверу
response = requests.get('https://api.timeweb.cloud/api/v1/account/finances', headers=headers)

print(response.content) # выводим ответ сервера в консоль

Далее запускаем скрипт:

python balance.py

После чего в консольном терминале должен появиться ответ удаленного сервера:

b'{"finances":{"balance":49.64,"currency":"RUB","discount_end_date_at":null,"discount_percent":0,"hourly_cost":0.41,"hourly_fee":0.41,"monthly_cost":300,"monthly_fee":300,"total_paid":980,"hours_left":121,"autopay_card_info":null,"total_balance":49.63798417},"response_id":"e5c379ad-d7e6-4963-9774-b457e52b9148"}'

Перезагрузка сервера в Python

Теперь создадим отдельный скрипт, выполняющий перезагрузку сервера:

sudo nano restart.py

Его код будет таким:

import os
import requests

# объявляем список заголовков
headers = {
	'Content-Type': 'application/json',
	'Authorization': 'Bearer ' + os.getenv('TIMEWEB_CLOUD_TOKEN', ''),
}

response = requests.post('https://api.timeweb.cloud/api/v1/servers/3738417/reboot', headers=headers) # в адресе запроса на месте цифр указываем уникальный идентификатор облачного сервера

print(response) # выводим СТАТУС ответ сервера в консоль

Теперь запускаем выполнение скрипта:

python restart.py

В консольном терминале появится вывод, содержащий статус выполненного действия:

<Response [204]>

После этого облачный сервер начнет перезагружаться.

Перезагрузка всех существующих серверов

Как правило с помощью API управляют не одним сервером, а несколькими. Поэтому рассмотрим наипростейший пример одновременной перезагрузки всех имеющихся облачных серверов.

Для этого создадим новый файл:

sudo nano restart_all.py

И поместим в него следующий код:

import os
import requests
import json # модуль понадобится для работы с JSON-данными

headers = {
	'Content-Type': 'application/json',
	'Authorization': 'Bearer ' + os.getenv('TIMEWEB_CLOUD_TOKEN', ''),
}

# запрос на получение списка серверов
response = requests.get('https://api.timeweb.cloud/api/v1/servers', headers=headers)

# возвращенный словарь со списком сервером нужно сперва декодировать в строку, а потом преобразовать в JSON
servers = json.loads(response.content.decode('utf-8'))['servers']

# итерация по списку всех полученных серверов
for server in servers:
	requests.post('https://api.timeweb.cloud/api/v1/servers/' + str(server['id']) + '/reboot', headers=headers) # отправка запроса на перезагрузку каждого сервера с указанием его уникального идентификатора

Соответственно, запустить скрипт можно следующим образом:

python restart_all.py

В этом примере сначала запрашивается список всех существующих серверов, после чего по нему выполняется итерация, внутри которой отправляются запросы на перезагрузку каждого сервера через уникальный идентификатор.

Более подробно о структуре ответа на запрос списка серверов можно узнать в документации API Timeweb Cloud.

Заключение

С помощью API можно создавать автоматизированные сценарии управления облачными серверами. Как правило эти сценарии повторяют ручные способы управления, доступные через панель управления.

При этом выполнять API-запросы можно как в консольном терминале через утилиту curl, так и в коде любого популярного языка программирования, вроде Golang или Python.

Подробную информацию о структуре запросов и их ответов можно найти в официальной документации публичного API Timeweb Cloud.

Эта документация содержит обширное описание возможностей API Timeweb Cloud, а также интерактивные инструменты тестирования запросов с примерами кода на популярных языках программирования.

Документация API Timeweb Cloud с интерактивными примерами кода

Важно понимать, что показанные в нашем руководстве примеры — лишь малая часть от всех возможностей API Timeweb Cloud. Тем не менее, общий принцип формирования запросов и ответов одинаков.

Хотите внести свой вклад?

Участвуйте в нашей контент-программе за
вознаграждение или запросите нужную вам инструкцию

22 ноября 2024 г.

14 минут чтения

API Автоматизация Go Python

Пока нет комментариев

Как управлять парком серверов с помощью API