Claudius

Claudius is an easy-to-use domain specific language for cloud experiments. It has been designed to speed up process of building distributed experiments and highly reduce time of remote machines configuration. To avoid vendor lock-in, Claudius was build on top of fog.io library, which enables flexible and powerful way to manage machine instances at various cloud providers. Remote commands execution is based on SSH protocol (SSH-2). DLS allow users to generate readable execution graph, which is extremely useful for experiment flow verification and help avoid wasting money.

Installation

Install it as:

$ sudo gem install claudius

If you want export execution tree to image you need Graphivz.

Keywords

  • experiment -- main part of Claudius DLS, which defines a new experiment. After command, you are obligated to provide 2 parameters:

    • experiment_name - string, which is the name of the experiment
    • body - block of code describing designed experiment

    You are allowed to call following methods on returned experiment object:

    • run - method starts previously designed experiment.
    • export_tree(path = 'execution_tree_path') - method generates readable execution graph. Graph is saved as an image and in .dot file format (graph description language) - for further user processing.

  • define_providers - method takes as a parameter description of machines used in experiment. In experiments You are allowed to use 2 different types of machines

    • manual - those machines have been created before experiment start, You should possess appropriate credentials such as: ip address, login, password etc.
    • cloud - if You like to perform your experiment in cloud, You should firstly provide necessary information to authenticate to Your cloud provider ( e.g. AWS). After successfully authentication, please define instances which You are going to use in your experiment by create_instances method.

  • foreach - keyword is similar to ruby ‘each’ method, but in contrast to ordinary ‘each’, you may provide adjectives describing how parameters should be process Currently supported adjectives are.

    • asynchronously - each parameter is processed in separate thread. Execution of instructions after foreach block is pursued when each loop is finished.
    • safely - experiment is continued even if some exception occurs during loop execution,

  • on - specify on which machine instructions should be executed, by default it is localhost. It takes instance name as a parameter.

  • before, after - keywords are used to construct metrics

  • concurrent - if elements (such as execute or foreach) are in common concurrent block, they are executed each in separate thread.

  • execute - method takes as a parameter block of code (which contain ssh methods calls), end perform instructions sequentially

  • ssh - specify instruction(s) which are going to be invoked on machine. As a parameter takes a string representing shell command.

Credentials

In order to authenticate in AWS services (at other cloud providers also) you are obligated to provide some credentials data, which are: aws_access_key_id, aws_secret_access_key, and so on. It is recomended to store configuration in json file and refer to them, when they are require. Sample config file looks like one below:

{
   "provider" : "AWS",
   "region" : "eu-west-1",
   "aws_access_key_id" : "XXXXXXXXXXXXXXXXXXXX",
   "aws_secret_access_key" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   "key_name" : "My-irleand-key",
   "groups" : ["My-irleand-group"]
   "private_key_path" : "./pems/my-irleand-key.pem"
}

After creation, You could load your file, assign it to variable and use freely as dictionary.

config = load_config('./user_config.json')
aws_key = config['aws_access_key_id']

Usage

Check doc here.

Documentation

Documemtation is autogenerated from examples by Groc. To build doc you need Node.js and Pygments.

npm install -g groc

Generate to doc folder:

groc examples/* README.md

Generate to GitHub page:

groc --gh examples/* README.md

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request