Aller au contenu
NimbusNexus

Machines virtuelles

Une machine virtuelle NimbusNexus est une instance de calcul dotée d’un disque de démarrage et d’une interface réseau par réseau qu’elle rejoint. Vous en créez une avec POST /api/v1/instance/ dans la région de votre session ; tout le reste (volumes block, IP publiques) s’y attache sous forme de ressources distinctes.

Quand utiliser une VM

Les VM sont la bonne brique quand il vous faut :

  • Un état persistant sur disque entre les requêtes (une base de données, un cache de build, un worker de file d’attente qui tourne longtemps).
  • Un contrôle total de l’OS — installer des paquets, régler des paramètres du noyau, exécuter tout ce qui demande un accès système.
  • Une forme d’instance précise — le nombre de vCPU et la RAM dont votre charge de travail a besoin.

Si votre charge de travail est sans état et organisée en requêtes, les plateformes de conteneurs (services Kubernetes managés, runtimes serverless) conviennent généralement mieux. La frontière est à peu près la suivante : si un redémarrage de processus qui effacerait les fichiers locaux vous poserait problème, il vous faut une VM.

Forme et création

POST /api/v1/instance/ prend un name et une spec qui définit la forme de la VM : architecture et vm_class, cpu (vCPU) et ram (MB), ainsi que le volume_type de son disque de démarrage (voir Stockage en bloc). Il faut aussi une image (ou des volumes amorçables), au moins un network et au moins un security_group. Les champs facultatifs comprennent sshs (la clé SSH à installer), volume_size (la taille du disque de démarrage en GB quand vous démarrez depuis image ; 5 par défaut), user_data, metadata et subscription. Rejoindre un réseau fournisseur exige aussi bandwidth_mbps et subscription.bandwidth ; sans eux, l’appel répond 400.

Il n’y a pas de codes de taille. GET /api/v1/instance/artifacts liste dans vm_options les choix d’architecture et de vm_class pour la région de votre session, ainsi que les images, réseaux, groupes de sécurité, clés SSH, groupes de serveurs et volumes que vous pouvez utiliser. La VM tourne sur un flavor qui a exactement vos cpu et ram ; l’API en crée un s’il n’en existe aucun. Les prix se trouvent dans Données tarifaires.

Cycle de vie

La création d’une VM est asynchrone : POST /api/v1/instance/ met le travail en file d’attente et répond {"success": true}, sans identifiant. Retrouvez la nouvelle VM dans GET /api/v1/instance/ et suivez son status, la valeur propre au service de calcul. Les valeurs que vous rencontrerez le plus souvent :

  • BUILD — la VM est en cours de création.
  • ACTIVE — en cours d’exécution.
  • SHUTOFF — arrêtée.
  • VERIFY_RESIZE — redimensionnée, en attente de votre confirmation ou de votre retour arrière (voir Tailles de VM).
  • ERROR — quelque chose a échoué ; fault indique quoi.

POST /api/v1/instance/action démarre, arrête ou supprime des VM : listez leurs identifiants dans servers et définissez cmd à start, stop ou delete. Une VM arrêtée reste facturée : la facturation court de la création à la suppression, selon le plan indiqué dans subscription.vm (Monthly par défaut). Supprimer une VM supprime le volume de démarrage créé à partir de son image ; les volumes passés dans volumes, ou attachés plus tard, restent available.

Nommage et identifiants stables

Chaque VM porte deux identifiants :

  • id — l’UUID de la VM. Stable pendant toute la vie de la VM. Utilisez-le dans les URL, les clés étrangères, les journaux d’audit.
  • name — lisible par un humain, n’importe quelle chaîne non vide. Modifiez-le, ou la description, avec PATCH /api/v1/instance/{instance_id}. Ne l’utilisez dans aucun chemin de code que vous ne voulez pas réécrire le jour où quelqu’un renomme la VM.

La référence des endpoints ci-dessous utilise {instance_id} dans les modèles de chemin ({server_id} sur les endpoints des interfaces de VM) ; la valeur à passer est l’id de la 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 →