-
Notifications
You must be signed in to change notification settings - Fork 49
FAQ D
DQ1: I want to add a new Cloud Adapter for CBTOOL, and I verified that this new Cloud Model is fully supported by LibCloud (https://libcloud.apache.org/). How should I proceed?
DA1: CBTOOL’s layered architecture was intended to allow the framework to be incrementally expanded in a non-intrusive (i.e., minimal to no changes to the existing “core” code) and incremental manner. ** As of now (early 2017), it is highly recommended that any new Cloud Adapter developed for CBTOOL should follow the guidelines laid out here. **
While multiple Cloud Adapters are already available, new adapters are constantly added. In order to facilitate this work, a new generic "LibCloud" meta-adapter (~/cbtool/lib/clouds/libcloud_common.py
) was made available, which allows a new Cloud-specific adapter to be developed by writing as little as 50 lines of code. This new meta-adapter using the libcloud-based method includes support for the following CBTOOL operations/features:
a. create/destroy instances
b. image capture (from a running instance) and deletion.
c. multi-tenancy (using multiple accounts at the same time)
d. create (and attach)/destroy block storage volumes
e. multi-region support
f. cloud-init support for both SSH-keys and OpenVPN.
The things that our simplified libcloud-support does NOT include:
I. floating IP addresses
II. block storage snapshot management
III. other esoteric functions provided by individual libcloud-based cloud providers.
For example, if you have some “special” feature supported by your cloud which is not standard, such as, docker-specific commands, or auto-configuration of a secret feature that only your cloud knows about, then the simplified libcloud-approach is not for you. You will want to go with the native approach. Assuming that an adapter for a “New Awesome Cloud” (nac) will be written, here we have the required steps summarized:
-
Using
~/cbtool/configs/templates/_digitalocean.txt
as an example, create~/cbtool/configs/templates/_nac.txt
: A simplecp ~/cbtool/configs/templates/_digitalocean.txt ~/cbtool/configs/templates/_nac.txt
should be enough. -
Using
~/cbtool/lib/clouds/do_cloud_ops.py
as an example, create~/cbtool/lib/clouds/nac_cloud_ops.py
. Again, a simplecp ~/cbtool/lib/clouds/do_cloud_ops.py ~/osgcloud/cbtool/lib/clouds/nac_cloud_ops.py
should be sufficient. -
Read the documentation in the
__init__
function at the beginning of the file~/cbtool/lib/clouds/libcloud_common.py
. Edit your own file~/cbtool/lib/clouds/nac_cloud_ops.py
and adapt the options to the__init__
function to match the features supported by your libcloud-based cloud. For example, if you don’t need SSH keys via cloud-init, or you don’t support cloud-init at all, then set those respective options to False. Most options are optional. While the DigitalOcean adapter makes more complete use of all the libcloud features, your cloud may not need them all. -
In the pre_create_vm function, this is where you would add any additional overrides to the function which actually launches VMs to your cloud. Many clouds provide special python keyword arguments to the libcloud create_node() function which are special to your individual cloud. If this is true, then add the respective keyword arguments to the pre_create_vm function. See the example used in the DigitalOcean adapter for such an override:
~/cbtool/lib/clouds/do_cloud_ops.py
. -
Once you are done, you should have a very short cloud adapter. The recommended way to test the new adapter is to start with a simple “cldattach npc TESTNPCCLOUD”, followed by “vmcattach all”, directly on CBTOOL’s CLI.
This operation will ensure that vmccleanup and vmcregister methods are properly implemented.
-
At this point, select an image that contains a "vanilla" Ubuntu/Centos/RHEL/Fedora image. You can test the instance creation with
vmattach check:<SELECTED IMAGEID>
, and instance destruction withvmdetach youngest
.
If you are running into trouble adding the new adapter, we will be more than happy to help you on the mailing lists. Join the lists and let us know how it goes.
DQ2: I want to add a new Cloud Adapter for CBTOOL, and I cannot use LibCloud (https://libcloud.apache.org/). How should I proceed?]
DA2: CBTOOL’s layered architecture was intended to allow the framework to be incrementally expanded in a non-intrusive (i.e., minimal to no changes to the existing “core” code) and incremental manner. First of all, make sure that you cloud is indeed not covered on the extensive list provided by LibCloud.
While multiple Cloud Adapters are already available, new adapters are constantly added. These adapters can be divided in two broad classes, following the Cloud’s classification, white-box and black-box (i.e., public). It is recommended that, for the addition of a new cloud adapter, one uses either OpenStack (in case of white box) or EC2 (in case of black-box) as examples.
Assuming that an adapter for a “New Public Cloud” (npc) will be written, here is the summarization of the required steps.
-
Using
~/cbtool/configs/templates/_ec2.txt
as an example, create~/cbtool/configs/templates/_npc.txt
: -
A simple
cp ~/cbtool/configs/templates/_ec2.txt ~/cbtool/configs/templates/_npc.txt
should be enough Using~/cbtool/lib/clouds/ec2_cloud_ops.py
as an example, create~/cbtool/lib/clouds/npc_cloud_ops.py
. Again, a simplecp ~/cbtool/lib/clouds/ec2_cloud_ops.py ~/cbtool/lib/clouds/npc_cloud_ops.py
should be enough. Open the file~/cbtool/lib/clouds/npc_cloud_ops.py
and start by changing lines 37-38 (import New Public Cloud’s native python client) and line 40 (rename Ec2Cmds into NpcCmds) -
CBTOOL’s abstract operations are mapped to five mandatory methods in the (newly created by the implementer) class NpcCmds:
- vmccleanup
- vmcregister
- vmcunregister
- vmcreate
- vmdestory
- vmcapture
-
In addition to the mandatory mapping methods, the following methods are also part of each Cloud adapter:
- get_description
- connect
- check_networks
- check_images
- check_ssh
- check_security_group
- discover_hosts
- test_vmc_connection
- is_vm_running
- is_vm_ready
- get_ip_address
- get_instances
- get_images
- get_networks
- vm_placement
-
In addition to the “mandatory” methods one might opt for (as shown in the aforementioned table of already existing Cloud Adapters) to implement “optional” operations, such as “vmcapture” and “vmrunstate” (both additional methods in the same class).
- vmcapture
- vmrunstate
- vmmigrate
- vmresize
- imgdelete
It is also possible to add the ability for persistent storage attachment and detachment (i.e., “virtual volumes”) through the methods “vvcreate” and “vvdestroy”.
- vvcreate
- vvdestroy
-
Finally, it is important to remember that the parameters in _npc.txt will have to be changed taking into account specific features on this cloud.
-
The recommended way to test the new adapter is to start with a simple “cldattach npc TESTNPCCLOUD”, followed by “vmcattach all”, directly on CBTOOL’s CLI.
This operation will ensure that vmccleanup and vmcregister methods are properly implemented.
- At this point, select an image that contains a "vanilla" Ubuntu/Centos/RHEL/Fedora image. You can test the instance creation with
vmattach check:<SELECTED IMAGEID>
, and instance destruction withvmdetach youngest
.
DQ3: I am creating a new Virtual Application (VApp) type for CBTOOL. How can I debug my application-specific "setup" configuration scripts?
DA3: Debug instructions
DQ4: I have implemented a new core feature, Cloud Adapter or Virtual Application (VApp) for CBTOOL. How can I run a regression test?