Yandex Cloud API (IAM, Resource Manager, Compute Cloud): Создать виртуальную машину и дождаться готовности

Сценарий из mcp-everything. Актуально на 2026-10-24.

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

1. Отправь запрос: POST /compute/v1/instances с folderId, zoneId (например, ru-central1-a), platformId, resourcesSpec (memory в байтах, cores, coreFraction), bootDiskSpec с образом и networkInterfaceSpecs с подсетью. Числа int64 передаются строками.
2. Ответ — объект Operation: создание идёт асинхронно. Сохрани его id.
3. Проверяй статус: GET /operations/{operationId} на operation.api.cloud.yandex.net. done = true — операция завершилась; если есть error — с ошибкой, иначе в response будет созданная ВМ.
4. Удалить машину — DELETE /compute/v1/instances/{instanceId}, тоже через операцию.

OP=$(curl -s -X POST https://compute.api.cloud.yandex.net/compute/v1/instances \
  -H "Authorization: Bearer $IAM_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "folderId": "<id каталога>",
        "name": "test-vm",
        "zoneId": "ru-central1-a",
        "platformId": "standard-v3",
        "resourcesSpec": {"memory": "2147483648", "cores": "2", "coreFraction": "20"},
        "bootDiskSpec": {"diskSpec": {"size": "21474836480", "imageId": "<id образа>"}},
        "networkInterfaceSpecs": [{"subnetId": "<id подсети>", "primaryV4AddressSpec": {"oneToOneNatSpec": {"ipVersion": "IPV4"}}}],
        "metadata": {"user-data": "#cloud-config\nusers:\n  - name: admin\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-ed25519 AAAA..."}
      }' | jq -r .id)

curl https://operation.api.cloud.yandex.net/operations/$OP -H "Authorization: Bearer $IAM_TOKEN"

Базовые URL

• IAM: https://iam.api.cloud.yandex.net
• Resource Manager: https://resource-manager.api.cloud.yandex.net
• Compute Cloud: https://compute.api.cloud.yandex.net
• Операции: https://operation.api.cloud.yandex.net

Авторизация

Тип: Bearer-токен

Все запросы, кроме получения токена, передают IAM-токен в заголовке:

IAM-токен получают методом POST /iam/v1/tokens в обмен на OAuth-токен аккаунта на Яндексе или JWT сервисного аккаунта.

Authorization: Bearer <IAM-токен>

Методы сценария

POST /compute/v1/instances — Создание виртуальной машины

Асинхронная операция; её можно отменить, пока она выполняется.

Параметр	Где	Тип	Обяз.	Описание
folderId	body	string	да	ID каталога
zoneId	body	string	да	Зона доступности
platformId	body	string	да	Аппаратная платформа
resourcesSpec.memory	body	string	да	Объём памяти в байтах
resourcesSpec.cores	body	string	да	Число ядер
resourcesSpec.coreFraction	body	string	нет	Гарантированная доля vCPU: 0, 5, 20, 50, 100
resourcesSpec.gpus	body	string	нет	Число GPU: 0, 1, 2, 4
bootDiskSpec	body	object	да	Загрузочный диск: diskSpec (size, imageId, typeId) или diskId
networkInterfaceSpecs	body	array	да	Сетевые интерфейсы
name	body	string	нет	Имя ВМ
description	body	string	нет	Описание, до 256 символов
labels	body	object	нет	Метки ключ:значение
metadata	body	object	нет	Метаданные (в том числе пользовательские ключи)
secondaryDiskSpecs	body	array	нет	Дополнительные диски, до 3
hostname	body	string	нет	Имя хоста
schedulingPolicy	body	object	нет	Политика планирования
serviceAccountId	body	string	нет	Сервисный аккаунт для аутентификации изнутри ВМ

DELETE /compute/v1/instances/{instanceId} — Удаление виртуальной машины

Параметр	Где	Тип	Обяз.	Описание
instanceId	path	string	да	ID виртуальной машины

GET /operations/{operationId} — Статус операции

Хост operation.api.cloud.yandex.net.

Параметр	Где	Тип	Обяз.	Описание
operationId	path	string	да	ID операции

Пример запроса:

GET https://operation.api.cloud.yandex.net/operations/fcmq0j5033e516c56ctq

Нюансы

• Каждая операция, изменяющая ресурс, возвращает объект Operation: id, created_at, created_by, modified_at, done, metadata и одно из полей response/error. Отслеживайте статус по id.
• done: true означает завершение операции, в том числе с ошибкой. Поле error может появиться раньше — пока сервис откатывает изменения.
• Для Create/Update поле response содержит созданный или изменённый ресурс.
• Числа int64 (pageSize, memory, cores) передаются строками.
• Пагинация: pageSize и pageToken, следующая страница — по nextPageToken из ответа.

Другие сценарии

• Получить IAM-токен для запросов к API
• Найти каталог и посмотреть виртуальные машины
• Выключать машины на ночь и включать утром

---

Если этого недостаточно — официальная документация: https://yandex.cloud/ru/docs/api-design-guide/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandex-cloud.md