Перейти до вмісту
NimbusNexus

Віртуальні машини

Віртуальна машина NimbusNexus — це обчислювальний інстанс з одним завантажувальним диском і одним мережевим інтерфейсом на кожну мережу, до якої вона приєднується. VM створюють через POST /api/v1/instance/ у регіоні вашої сесії; усе інше (блокові томи, публічні IP) підʼєднується до неї як окремі ресурси.

Коли використовувати VM

VM — правильний примітив, коли вам потрібні:

  • Постійний стан на диску між запитами (база даних, кеш збірок, тривалий воркер черги).
  • Повний контроль над ОС — встановлення пакетів, налаштування параметрів ядра, запуск будь-чого, що потребує системного доступу.
  • Конкретна конфігурація інстансу — кількість vCPU і обсяг RAM, потрібні вашому навантаженню.

Якщо ваше навантаження не має стану й складається із запитів, зазвичай краще підходять контейнерні платформи (керовані сервіси Kubernetes, serverless-середовища виконання). Межа приблизно така: якщо вас засмутить, що перезапуск процесу стер локальні файли, вам потрібна VM.

Конфігурація та створення

POST /api/v1/instance/ приймає name і spec, який задає конфігурацію VM: architecture і vm_class, cpu (vCPU) і ram (MB), а також volume_type її завантажувального диска (див. Блокове сховище). Також потрібні image (або завантажувальні volumes), щонайменше одна network і щонайменше одна security_group. Серед необовʼязкових полів — sshs (SSH-ключ, який треба встановити), volume_size (розмір завантажувального диска в GB, коли VM завантажується з image; за замовчуванням 5), user_data, metadata і subscription. Для приєднання до мережі провайдера потрібні також bandwidth_mbps і subscription.bandwidth; без них виклик відповідає 400.

Кодів розмірів немає. GET /api/v1/instance/artifacts перелічує в vm_options доступні значення architecture і vm_class для регіону вашої сесії, а також образи, мережі, групи безпеки, SSH-ключі, групи серверів і томи, які ви можете використати. VM працює на flavor-і саме з вашими cpu і ram; якщо такого немає, API його створює. Ціни наведено на сторінці Дані про ціни.

Життєвий цикл

Створення VM асинхронне: POST /api/v1/instance/ ставить роботу в чергу й відповідає {"success": true}, без ідентифікатора. Знайдіть нову VM у GET /api/v1/instance/ і стежте за її status — власним значенням обчислювального сервісу. Найчастіше трапляються такі:

  • BUILD — VM створюється.
  • ACTIVE — працює.
  • SHUTOFF — зупинена.
  • VERIFY_RESIZE — розмір змінено, VM чекає, поки ви підтвердите зміну або скасуєте її (див. Розміри VM).
  • ERROR — щось пішло не так; fault пояснює, що саме.

POST /api/v1/instance/action запускає, зупиняє або видаляє VM: перелічіть їхні ідентифікатори в servers і встановіть cmd у start, stop або delete. За зупинену VM плата все одно нараховується: тарифікація триває від створення до видалення за планом у subscription.vm (за замовчуванням Monthly). Видалення VM видаляє завантажувальний том, створений з її образу; томи, передані в volumes або підʼєднані пізніше, залишаються в стані available.

Імена й стабільні ідентифікатори

Кожна VM має два ідентифікатори:

  • id — UUID VM. Стабільний протягом усього життя VM. Використовуйте його в URL, зовнішніх ключах, журналах аудиту.
  • name — зрозуміле людині, будь-який непорожній рядок. Змініть його або description через PATCH /api/v1/instance/{instance_id}. Не використовуйте його в коді, який не хочете переписувати того дня, коли хтось перейменує VM.

Довідник ендпоінтів нижче використовує {instance_id} у шаблонах шляхів ({server_id} в ендпоінтах інтерфейсів VM); ви передаєте id VM.

Reference

GET/api/v1/instance/

List Instances

List virtual machine instances visible to the caller (own project, or all projects when called as admin).

Parameters

NameInTypeDescription
admin_domainquerystring | null—
admin_projectquerystring | null—
projectquerystring | null—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/instance/" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/instance/

Create Instance

Provision a new virtual machine instance with the requested flavor, image, networks and security groups.

Request body

FieldTypeDescription
admin_domainstring | null—
admin_projectstring | null—
projectstring | null—
name*string—
descriptionstring | null—
imagestring | null—
spec*ServerSpecParams—
subscriptionSubscriptionSpec—
bandwidth_mbpsinteger | null—
network*array of string—
security_group*array of string—
root_passwordstring | null—
sshsstring | null—
volume_sizeinteger | null—
volumesarray of string | null—
server_groupsarray of string | null—
user_datastring | null—
metadataobject | null—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/instance/" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "spec": {
      "architecture": "example",
      "vm_class": "example",
      "cpu": 1,
      "ram": 1,
      "volume_type": "example"
    },
    "network": [
      "example"
    ],
    "security_group": [
      "example"
    ]
  }'
POST/api/v1/instance/action

Instances Action

Execute a power-state or lifecycle action on one or more instances (start, stop, reboot, pause, suspend, etc.).

Request body

FieldTypeDescription
servers*array of string—
cmd*"start" | "stop" | "delete"—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/instance/action" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "servers": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "cmd": "start"
  }'
GET/api/v1/instance/artifacts

Instance Create Artifacts

Return reference data needed to provision a new instance (available images, networks, security groups, key pairs).

Parameters

NameInTypeDescription
admin_domainquerystring | null—
admin_projectquerystring | null—
projectquerystring | null—
product_type_namequerystring—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/instance/artifacts" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/instance/server-groups

List Instance Groups

List server groups (affinity / anti-affinity policies) for VM placement.

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/instance/server-groups" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/instance/server-groups

Create Instance Group

Create a new server group with the chosen affinity / anti-affinity policy.

Request body

FieldTypeDescription
name*string—
policy*string—

Responses

  • 201Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/instance/server-groups" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "policy": "example"
  }'
DELETE/api/v1/instance/server-groups

Delete Instance Groups

Delete one or more server groups by id.

Request body

FieldTypeDescription
ids*array of string—

Responses

  • 204Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X DELETE "https://api.nimbusnexus.net/api/v1/instance/server-groups" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "example"
    ]
  }'
GET/api/v1/instance/{instance_id}

Instance Get

Get the full details of a single virtual machine instance.

Parameters

NameInTypeDescription
instance_id*pathstring—
admin_domainquerystring | null—
admin_projectquerystring | null—
projectquerystring | null—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/instance/<instance_id>" \
  -H "Authorization: Bearer $NIMBUS_KEY"
PATCH/api/v1/instance/{instance_id}

Instance Update

Update mutable properties of an existing instance (e.g. name, metadata).

Parameters

NameInTypeDescription
instance_id*pathstring—

Request body

FieldTypeDescription
namestring | null—
descriptionstring | null—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X PATCH "https://api.nimbusnexus.net/api/v1/instance/<instance_id>" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
POST/api/v1/instance/{instance_id}/confirm_resize

Confirm Instance Resize

Confirm a pending resize, finalising the move to the new flavor and releasing the old one.

Parameters

NameInTypeDescription
instance_id*pathstring—
admin_domainquerystring | null—
admin_projectquerystring | null—
projectquerystring | null—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/instance/<instance_id>/confirm_resize" \
  -H "Authorization: Bearer $NIMBUS_KEY"
GET/api/v1/instance/{instance_id}/console

Console

Open an interactive console session (VNC/serial) for the given instance.

Parameters

NameInTypeDescription
instance_id*pathstring—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X GET "https://api.nimbusnexus.net/api/v1/instance/<instance_id>/console" \
  -H "Authorization: Bearer $NIMBUS_KEY"
POST/api/v1/instance/{instance_id}/resize

Resize Instance

Begin resizing an instance to a different flavor; must be confirmed or reverted before the resize is finalized.

Parameters

NameInTypeDescription
instance_id*pathstring—

Request body

FieldTypeDescription
admin_domainstring | null—
admin_projectstring | null—
projectstring | null—
spec*productVirtualMachineCreateSpec—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/instance/<instance_id>/resize" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "architecture": "example",
      "vm_class": "example",
      "cpu": 1,
      "ram": 1
    }
  }'
POST/api/v1/instance/{instance_id}/revert_resize

Revert Instance Resize

Revert a pending resize, returning the instance to its previous flavor.

Parameters

NameInTypeDescription
instance_id*pathstring—
admin_domainquerystring | null—
admin_projectquerystring | null—
projectquerystring | null—

Responses

  • 200Successful Response
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Validation error
  • 429Too Many Requests
  • 500Internal Server Error

Example

curl -X POST "https://api.nimbusnexus.net/api/v1/instance/<instance_id>/revert_resize" \
  -H "Authorization: Bearer $NIMBUS_KEY"

Need to make a real call? Try these endpoints in the live Swagger UI →