MiCADO Project
==============
.. image:: _static/Cola_colored_kl.jpg
   :scale: 50 %
   :alt: alternate text
   :align: right

Here you can find all the useful information on the MiCADO and COLA project:

http://project-cola.eu/

Here you can find the github accounts:
  - for the whole project:
    https://github.com/micado-scale

  - for TOSCA topologies and custom types:
    https://github.com/COLAProject/COLARepo
    (This is the current repository but might change in the future)

  - for the submitter:
    https://github.com/micado-scale/component_submitter

Configuration
==============

The submitter is configurable via the KeyLists class. The KeyLists class will read the key_config.yml file that is located in
the system directory.

The key_config.yml file looks like follow:


.. literalinclude:: ../system/key_config.yml
    :language: yaml



The first key ``config`` defines parameter for the whole infrastructure.
The ``dry_run`` parameter that will tell to the adaptor to mimic the execution of their adaptor without actually executing it
it will only log the action. The KeyLists class will add in each dictionary created for their adaptor this parameter.

The ``path_log`` parameter under the config key will configure where the log should be stored.


The second key ``Adaptor_config`` will configure the adaptor itself. Each adaptor will have its own configuration that is
defined by the devs. The ``types`` will define what the adaptor will expect, the rest of the configure is at the discretion of the devs.






How to create your Adaptor:
===========================

At the moment we have the abstract base Adaptor that is describing these abstract
sub methods:

 - __init__()
 - translate()
 - execute()
 - update()
 - undeploy()
 - cleanup()

__init__()
-----------

This is the constructor. Adaptor devs must allow for 3 parameters. The
``adaptor_id`` (required), which will be generated by the submitter engine, the ``config`` which will store the
configuration of the adaptor that the devs specify in the key_lists.yml and the ``template`` (optional) as a TOSCA Parser object.

The Adaptor is a stateful object which always operates using the ID and, for
launch() or update() operations, requires the template itself.

The config parameter is a dictionary, it as a key which is dry_run which should be implemented by the devs for development purposes.
If dry_run flag is True then the rest of the execution shouldn't actually produce anything but rather a log mimicking the execute.
The rest of the parameter is at the discretion of the devs.


translate([tmp=False])
----------------------

This method should create a configuration file for your external component,
and store it in the ``files/output_configs`` directory located in the package
where all the configuration files produced by the other Adaptors are.
This configuration file should take the name of the ``adaptor_id``.

The parameter ``tmp`` is set to True during update() and this method should
change the default save behaviour when this flag is set.


execute()
---------

This method should execute the desired commands (using system or API calls)
for the desired component. It uses the output file generated by the translate()
method to communicate with its component.


update()
--------

This method should take the new template that contains changed values to update.
It should run translate(True) to save the output as a tmp file, then do a diff
of the new tmp file and the file created during launch() and the original translate().

If there is a difference between the file, then the tmp file replaces the original
file, and calls execute(). If there is no difference, simply delete the tmp file.

undeploy()
----------

This method should bring down the portion of the component relevant to this
application (using system/API calls). It should undo whatever was done in execute()


cleanup()
---------

This method should remove any files produced which were required by this component
for the execution of this application, located under ``files/output_configs``.

=======================
Other helpful things...
=======================

component_submitter.utils
-------------------------

We give access to utils method listed bellow:
  - dump_order_yaml: that dump in order into a yaml file

for more information go to the utils method to see how to use those methods.


TOSCAParser Objects
-------------------

.. toctree::
    :maxdepth: 1

    toscaparser

DockerAdaptor
-------------

Also see the DockerAdaptor for examples. For any help contact: g.gesmier@westminster.ac.uk