CoreCluster coding guide

 

This document describes coding conventions used in CoreCluster, PyCore library and all other extensions delivered by CloudOver.

Code separation

In CoreCluster's source code you can find four places where you could insert new code to provide new functionality:

For each of this locations, there are some guidelines to use:

API code

In almost all extensions, there is need to add some new functionality. Usually it is done by new API functions. Every part of code, which is related to database models (e.g. check weather VM instance is running, or list objects) should be placed in API. All functions registered in API should be fast and responsible. To learn more about extending API, go to Extending API guide. There are also some exceptions, what could be put into API (or guidelines):

Above rules are not mandatory, but may make your code consistent with whole project.

Database

Obvious place to keep your extension’s data is database model. Create your own models to keep necessary data. CoreCluster’s (and indirectly Django’s) models allow you to put some code into model class. Yes – each model in CoreCluster and Django is separate python class, which inherits form CoreModel. You could put there your methods, which process model’s data.

Each model inherits CoreModel class. It defines several standard fields and methods for each delivered model, like standard for whole CoreCluster ID, get_prop, set_prop and to_dict methods. See more in Database model reference .

Let’s see Subnet example: Subnet class keeps information about network address, mask and parent entity in NetworkPool table. All other required informations, like gateway, broadcast address or lease count are defined as class methods with decorator @property. This makes possible to use this methods as they are normal model’s fields in rest of code. See more in Database model reference

Agent

Agents are processes created to execute tasks, which are too heavy to do process them directly in API (or internal CI). For example, creating virtual machine takes usually a long time and depends on storage type and hypervisor. API method /api/vm/create/ schedules some tasks in to task queue and fastly returns to user ok code. All actions related to create virtual machine are executed later, by agents. So, if your code does a lot of work, consider creating new agent. What is important - by making a bit more effort, you can make your code scalable horizontally. Due to API service is usually executed at one machine – agents may be spreaded to many machines.

If you are considering if your code should be moved to new agent, check if:

Whatever you chose - remember, that agents give you very easy way to make whole application scalable, failure-proof and safe. Unless API should be exposed for users, all agents may be hidden inside cluster’s infrastructure. Remember, that each agent have access to all nodes! To learn more, check Agent reference

Hooks

If you are considering to override any API or Agent function to change it behavior - first, check the Hooks mechanism. Hooks should give you some tools to insert specific actions on each type of task execution, even at nodes. Hooks are special Python classes with pre- and post-execution of specific classes. You could trigger it on e.g. vm create or on vm destroy tasks executed by agents. To learn more about hooks, go to Hook reference missing article

Code reusage

If you are about to extend any existing class by your code, try to make it with new Mixin. See CoreModel in database model or any Driver missing article from CoreNetwork package. All methods are groupped by funcitonality. For example, CoreModel class defines basic fields and methods:


id field
_data field
to_dict property
get_prop method
set_prop method
...
If your new database model should be related to user’s account, for example this is VM instance - inherit both, CoreModel and UserMixin from corecluster.models package. UserMixin class delivers some additional fields and methods: Using such mixins have one huge adventage. When some part of mixin is about to change - it doesn’t require to change whole code. Once defined mixin may be used in many places. For better understanding go to database model reference and see CoreNetwork drivers.

If your code doesn’t fit to above rules and you feel, that it might be reused in future - create utils directory in your extension (or use existing, if you are extending CoreCluster). This is right place to keep common functions, like decorators, exceptions and small functions-tools.

Code formatting

Following rules are used to make code consistent acroll all project (except CoreUI):

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