VMmanager 6: Administrator guide

Examples of how to use API


In this article, you will find simplified examples written on Python 3.6 with the libraries JSON and request. 

Checking access level 

  1. Log in to VMmanager as Admin:

    url = "https://vm-1.vm-demo.com/auth/v3/auth"
    data = json.loads('{"email": "admin@example.com", "password": "123456"}')
    auth = requests.post(url=url, json=data)
  2. Request the information about the user:

    Request information about the user
    session = json.loads(auth.content.decode('utf-8')).get('session')
    url = "https://vm-1.vm-demo.com/auth/v3/whoami"
    cookie = {'Cookie': f'ses6={session}'}
    whoami = requests.get(url=url, headers=cookie)
  3. Check that the user has admin permissions: 

    Check access permissions
    is_admin = '@admin' in json.loads(whoami.content.decode('utf-8')).get('roles')

Receiving task statuses 

  1. When a long task is created in VMmanager the response will contain a JSON-object. Use its field task to filter a list of tasks: 

    Receive information about the task
    url = f"https://vm-1.vm-demo.com/vm/v3/task?where=((consul_id+EQ+'{task_id}')+AND+(name+EQ+'{task_name}'))"
    response = requests.get(url=url, headers=cookie)
    task_info = json.loads(response.content.decode('utf-8')).get('list')[0]
  2. Process the field status in the JSON-object that you have received. Possible values:  
    • created — the task has been created but it has not been started yet;
    • running — the task has been started; 
    • deferred — the start has been delayed; 
    • complete — the task has been completed;
    • fail — the task has failed. 

Creating a VM

  1. Log in to VMmanager as Admin:

    url = "https://vm-1.vm-demo.com/auth/v3/auth"
    data = json.loads('{"email": "admin@example.com", "password": "123456"}')
    auth = requests.post(url=url, json=data)
  2. Make sure that the user is registered in VMmanager: 

    Search for a user by email
    email = "user@example.com"
    url = f"https://vm-1.vm-demo.com/vm/v3/account?where=(email+EQ+'{email}')"
    account_info = requests.get(url=url, headers=cookie)
    user_registered = json.loads(account_info.content.decode('utf-8')).get('size') != 0
  3. Register a user if it is not found: 

    Add a user
    data = json.loads('{"email": "user@example.com", "password": "strong_password", "role": "@user"}')
    url = "https://vm-1.vm-demo.com/vm/v3/account"
    new_user = requests.post(url=url, json=data, headers=cookie)
  4. Save the user ID. It can be retrieved from account_info (step 2) or after registration (step 3). 
  5. Generate VM parameters: 
    • mandatory — name, root password,  cluster ID, account owner ID, list of IP pools;
    • optional — domain name; 
    • resources — amount of CPU, RAM, disk space; 
    • ID of the os image or VM. 
  6. Send the VM creation request: 

    Create a VM
    url = "https://vm-1.vm-demo.com/vm/v3/host"
    new_host = requests.post(url=url, json=vm_params, headers=cookie)
  7. Wait when the operation is completed.

Operations with VM

Delete the VM
url = f"https://vm-1.vm-demo.com/vm/v3/host/{host_id}"
deleted_host = requests.delete(url=url, headers=cookie)
Suspend the VM
url = f"https://vm-1.vm-demo.com/vm/v3/host/{host_id}/stop"
data = json.loads('{}')
host = requests.post(url=url, json=data, headers=cookie)
Start the VM
url = f"https://vm-1.vm-demo.com/vm/v3/host/{host_id}/start"
data = json.loads('{}')
host = requests.post(url=url, json=data, headers=cookie)

Operations with IP addresses

The following examples are for IPv4. 

Adding an IP address

  1. Receive a list of pools available for the cluster: 

    Receive cluster IP pools
    url = f"https://vm-1.vm-demo.com/vm/v3/cluster?where=(id+EQ+'{cluster_id}')"
    cluster_info = requests.get(url=url, headers=cookie)
    cluster_ip_pools = json.loads(cluster_info.content.decode('utf-8')).get('list')[0].get('ippools')
    ip_pools = [pool['id'] for pool in cluster_ip_pools]
  2. Add the IP address to one of the pools:

    Add the IP address
    url = f"https://vm-1.vm-demo.com/vm/v3/host/{host_id}/ip"
    data = json.loads(f'{{"ipv4_number": {ipv4_number}, "ipv4_pool": {ip_pools}}}')
    ip_add = requests.post(url=url, json=data, headers=cookie)

Deleting the IP address 

Delete the IP
url = f"https://vm-1.vm-demo.com/vm/v3/ip/{ip_id}"
ip_delete = requests.delete(url=url, headers=cookie)

Changing VM resources

Reboot the virtual machine to change the amount of its resources. When starting the task to change resources, the VM will be rebooted automatically. If several tasks are created, the machine will be rebooted several times.  To avoid multiple reboots we recommend using delayed tasks: 

  1. Describe JSON for the delayed task to change CPU and RAM: 

    JSON for CPU and RAM
    resource_data = json.loads(f'{{
        "cpu_number": {cpu_number},
        "ram_mib": {ram_mib},
        "defer": {{"action": "host_stop"}}
  2. Describe JSON for the delayed task to change disk space: 

    JSON for disk
    disk_data = json.loads(f'{{
        "size_mib": {hdd_mib},
        "defer": {{"action": "host_stop"}}
  3. Send the resources change request:  

    Change CPU, RAM, and disk
    resource_url = f"https://vm-1.vm-demo.com/v3/host/{host_id}/resource"
    host_change_resource = requests.post(url=resource_url, json=resource_data, headers=cookie)
    disk_url = f"https://vm-1.vm-demo.com/v3/disk/{disk_id}"
    disk_resize = requests.post(url=disk_url, json=disk_data, headers=cookie)
  4. Restart the virtual machine:  

    Restart the VM
    host_restart_url = f"https://vm-1.vm-demo.com/vm/v3/host/{host_id}/restart"
    restart_data = json.loads('{}')
    host_restart = requests.post(url=host_restart_url, json=restart_data, headers=cookie)
  5. The response will contain the ID of the tasks task and start_task. Wait when start_task is completed. 

Related topics

Thank you for your feedback!
Was the article useful?
Tell us why not:

it does not match the title

it was hard to understand

I didn't find the answer

recommendations from the article did not help


Tell us what you didn't like in the article: