Ir para o conteúdo
NimbusNexus

Máquinas virtuais

Uma máquina virtual da NimbusNexus é uma instância de computação com um disco de boot e uma interface de rede para cada rede de que ela participa. Você cria uma com POST /api/v1/instance/ na região da sua sessão; todo o resto (volumes de blocos, IPs públicos) é anexado a ela como recursos separados.

Quando usar uma VM

As VMs são a primitiva certa quando você precisa de:

  • Estado persistente em disco entre requisições (um banco de dados, um cache de build, um worker de fila de longa duração).
  • Controle total do SO — instalar pacotes, ajustar parâmetros do kernel, rodar qualquer coisa que precise de acesso ao sistema.
  • Uma configuração de instância específica — a quantidade de vCPUs e de RAM de que a sua carga de trabalho precisa.

Se a sua carga de trabalho é sem estado e orientada a requisições, plataformas de contêineres (serviços gerenciados de Kubernetes, runtimes serverless) costumam ser uma opção melhor. A linha divisória é mais ou menos esta: se você ficaria triste caso um reinício de processo apagasse os arquivos locais, você quer uma VM.

Configuração e criação

POST /api/v1/instance/ recebe um name e um spec que define a configuração da VM: architecture e vm_class, cpu (vCPUs) e ram (MB), e o volume_type do disco de boot dela (veja Armazenamento em blocos). Ele também precisa de uma image (ou de volumes bootáveis), de pelo menos uma network e de pelo menos um security_group. Entre os campos opcionais estão sshs (a chave SSH a instalar), volume_size (o tamanho do disco de boot em GB quando você faz o boot a partir de image; padrão 5), user_data, metadata e subscription. Entrar em uma rede de provedor também exige bandwidth_mbps e subscription.bandwidth; sem eles, a chamada recebe 400.

Não existem códigos de tamanho. GET /api/v1/instance/artifacts lista em vm_options as opções de architecture e vm_class da região da sua sessão, junto com as imagens, redes, grupos de segurança, chaves SSH, grupos de servidores e volumes que você pode usar. A VM roda em um flavor com exatamente o seu cpu e a sua ram; a API cria um se não houver nenhum. Os preços estão em Dados de preços.

Ciclo de vida

Criar uma VM é assíncrono: POST /api/v1/instance/ coloca o trabalho na fila e responde {"success": true}, sem id. Encontre a nova VM em GET /api/v1/instance/ e acompanhe o status dela, o valor do próprio serviço de computação. Os que você vai encontrar com mais frequência:

  • BUILD — a VM está sendo criada.
  • ACTIVE — em execução.
  • SHUTOFF — parada.
  • VERIFY_RESIZE — redimensionada, esperando que você confirme ou reverta (veja Tamanhos de VM).
  • ERROR — algo falhou; fault diz o quê.

POST /api/v1/instance/action inicia, para ou exclui VMs: liste os ids delas em servers e defina cmd como start, stop ou delete. Uma VM parada continua sendo cobrada: a cobrança vai da criação até a exclusão, no plano definido em subscription.vm (padrão Monthly). Excluir uma VM exclui o volume de boot criado a partir da imagem dela; os volumes passados em volumes, ou anexados depois, ficam available.

Nomes e ids estáveis

Toda VM tem dois identificadores:

  • id — o UUID da VM. Estável durante toda a vida da VM. Use-o em URLs, chaves estrangeiras, logs de auditoria.
  • name — legível por humanos, qualquer string não vazia. Altere-o, ou a description, com PATCH /api/v1/instance/{instance_id}. Não o coloque em nenhum caminho de código que você não queira reescrever no dia em que alguém renomear a VM.

A referência de endpoints abaixo usa {instance_id} nos templates de caminho ({server_id} nos endpoints de Interfaces de VM); o valor que você passa é o id da 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 →