CoreCluster API reference

 

This document describes the CoreCluster API. The only packages, which you need to go over this part of documentation CoreCluster and curl program.

CoreCluster should be configured according to installation and configuration guides and available from machine, where you will execute curl commands. If you are going to manage virtual machines, images and networks, remember to add at least one storage, hardware template and node.

Other ways to manage CoreCluster API

Described below API is available for all users, directly by HTTP requests. However this could be a bit nasty. Better way to use CoreCluster API is to use Python’s library - pyCore.

Api structure

Whole CoreCluster’s API is available through http POST requests. All functions exposed by this API are organised in sections (for CoreCluster without any extensions). This sections are organized into directory-like structure with following prefixes:

All parameters are passed in POST data. Parameters should be serialized to JSON dictionary. Important thing is to use double quotation marks. Python json library does not accept single ‘. Sample post data should look like this:


{
    "login": "testUser",
    "pw_hash": "03cfd743661f07975fa2f1220c5194cbaff48451"
}

As response, CoreCluster sends json’ed dictionary too. First element is called status and handles server response code. If everything has gone fine, the status code should be ok. In any other cases, status code should describe what has home wrong. In fatal cases it also could be django error page (e.g. in case when PYTHONPATH is not configured). The second response field is data. It contains all data, which called function returns. To access server response as normal dictionary you should json-decode it.

For future examples, let’s assume, that our CoreCluster is running at host named corecluster_api at port 8000 and the SSL support is enabled. Therefore, simplest request for api, which returns user’s password seed should be:


curl --data '{"login": "testUser"}' https://corecluster_api:8000/user/user/get_seed/

User account

Functions responsible for user account (/user/ prefix) require login and password hash in paameters (the only exception are get_seed and register, which gets no credentials). To generate password hash for given user login, first you should ask core about the seed for it’s login:


curl --data '{"login": "testUser"}' https://corecluster_api:8000/user/user/get_seed/

As a response you will get string associated with given login. To generate password hash use following algorithm:

  1. Concatenate password string and password seed
  2. Calculate sha1 sum from above string

In python, you can do this simply, with hashlib module:


import hashlib
pw_hash = hashlib.sha1(password+seed).hexdigest()

Cloud api

Te easiest way to see whole api is to use CoreUI web interface. Log in and select API in your account details in side menu. On the list you can find all available functions for your account. You can limit those functions for particular roles in cloud (described in Admin guide). Below you can find some examples, which shows how to perform basic operations, directly on OverCluster. Another way to interact with CoreCluster is to use PyCore library delivered by CloudOver.

Create virtual machine

This example shows how to get basic informations required to call vm create action. In first step we need to get API token from core. To do this, let’s check our password seed and get list of tokens:


curl --data '{"login": "testUser"}' https://corecluster_api:8000/user/user/get_seed/
curl --data '{"login": "testUser", "pw_hash": "PASSWORD_AND_SEED_SHA1"}' https://corecluster_api:8000/user/token/get_list/

With the second call we get token list. If none is available we need to create one:


curl --data '{
    "login": "testUser",
    "pw_hash": "HASHED_PASSWORD_AND_SEED",
    "name": "testToken"
}' https://corecluster_api:8000/user/token/create/

As additional data we can pass token name and function_filter to limit access to api.

Now, with our token we could get informations about disk images, hardware templates and ip addresses:


curl --data '{
    "token": TOKEN
}' https://corecluster_api:8000/api/template/get_list/
curl --data '{
    "token": TOKEN
}' https://corecluster_api:8000/api/image/get_list/
curl --data '{
    "token": TOKEN
}' https://corecluster_api:8000/api/network/get_list/

With this informations we can create virtual machine:


curl --data '{
    "token": TOKEN,
    "base_image_id": IMAGE_ID,
    "template_id": TEMPLATE_ID,
    "name": "New virtual machine,
    "description": "Virtual machine description"
}' https://corecluster_api:8000/api/vm/create/

With this call CoreCluster will prepare tasks to deploy your virtual machine on cluster’s node.

Operations on virtual machines and images

All operations are done asynchronous. This means, that i.e. calling function /api/vm/poweroff/ on virtual machine it is added into task queue. Such action will be done after all other actions are done on this VM. For this request you will get immediate response. This causes, that some functions may fail some time after calling them. Let’s see example:


curl --data '{
    "token": TOKEN,
    "base_image_id": IMAGE_ID,
    "template_id": TEMPLATE_ID,
    "name": "New virtual machine,
    "description": "Virtual machine description",
    "lease_id_list": [LEASE_ID_1, LEASE_ID_2]
}' https://corecluster_api:8000/api/vm/create/

Above task manages Core to create new virtual machine. This function is splitted into some tasks:

  1. Copy base image to selected node
  2. Define new libvirt firewall (if network is isolated)
  3. Define new libvirt network (one for each lease)
  4. Define new libvirt domain on node

In versions before 16.06 if any of above tasks fails, this blocks next tasks associated with this VM and node (in case of storage problems). Since 16.06 this behavior is changed and all failed tasks are skipped in queues. Also above chain of tasks takes some time to finish, depending on image copy time (task node:load_image). Usually, if you are creating new virtual machine, you probably want to start it immediately after creating. So in this case, you should call the /api/vm/start_vm/ function with VM's id (which you should get from /api/vm/create):


curl --data '{
    "token": TOKEN,
    "vm_id": VM_ID
}' https://corecluster_api:8000/api/vm/start/

This call creates new task at the end of queue associated with this VM. To obtain status of your virtual machine and get task list, you should call /api/vm/get_by_id/ with vm_id in parameter:


curl --data '{
    "token": TOKEN,
    "vm_id": VM_ID
}' https://corecluster_api:8000/api/vm/get_by_id/

This should return dictionary with many fields. Now, most important fields could be:

If you want to cancel all pending tasks in state Not assigned, call /api/vm/cancel_tasks with vm_id in parameter.

Managing images and other resources

Whole structure of CoreCluster is designed to work asynchronously. Images, networks and other additional resources (also those developed as external plugins) should be handled in similar way.

< Go back     Author: Maciej Nabozny Published: Jan. 13, 2017, 9:56 a.m.