AT&T Interactive R&D

 
 

Basic plugin tutorial

A plugin is a container for resources. Resources are described here. Plugins are very similar to chef recipies. In fact, you can get the same functionality by writing a chef recipie and including it in your clouds.rb file, has_chef_recipie 'path/to/recipie'

The structure of a PoolParty plugin looks like 

   1    plugin_name/
   2      plugin_name.rb
   3      spec/
   4          spec_helper.rb
   5          plugin_name_spec.rb
The spec_helper will be generated for you or looks something like: 
   1  [File.dirname(__FILE__), "#{File.dirname(__FILE__)}/.."].each {|dir| $:.unshift(dir) }
   2  require "poolparty"
   3  
   4  include PoolParty::Resources
Of course, you can write your own helpers in here to help out with your specs as well.

Now it's time to start writing some plugin functionality, of course after you have spec'd the functionality you want in your spec file.

We'll write a basic plugin to setup mysql on your servers. This is what our directory will look like: 

   1    mysql_plugin/
   2      mysql.rb
   3      spec/
   4          spec_helper.rb
   5          mysql_spec.rb

First, let's look at the finished basic plugin, then we'll disect it 

   1  module PoolParty
   2    class Database
   3      
   4      plugin :mysql do
   5        
   6        # Enable is called if there is no block given when the 
   7        # mysql plugin is called in the cloud
   8        def enable
   9          base_install
  10        end
  11              
  12        def base_install
  13          # Required packages
  14          has_package(:name => "MySQL-server")
  15          has_package(:name => "MySQL-shared")
  16          has_package(:name => "MySQL-client")
  17          
  18          # Setting the Mysql password
  19          has_exec(:name => "Set the Mysql Password") do
  20            subscribe [package(:name => "MySQL-server"), package(:name => "MySQL-client"), package(:name => "MySQL-shared")]
  21            refreshonly true
  22            ifnot "mysqladmin -uroot -p$password status"
  23            command "mysqladmin -uroot password $password"
  24          end
  25        end
  26        
  27        # Allow us to set a password
  28        def password(pass="default_poolparty_password")
  29          has_variable(:name => "password", :value => pass)
  30        end
  31        
  32      end
  33      
  34    end
  35  end

Packages

First, you'll notice that there are some lines with has_package This tells your nodes and instances that they make sure they have these packages and if not, that they should be installed (installed with the preferred package manager). These are called "Resources." There is a list of the available docs/Resources here. Note that they can be preceeded by either has_ or does_not_have_, which does exactly what it sounds like. has_ sends a present notice to the resource and does_not_have_ sends an absent notice to the resource.

Setup

The has_exec function from within the base_install method is relatively obvious, however let's run through it, just in case. The function is used to set the mysqladmin password, as noted by the description.

Subscribe Anytime that the packages Mysql-server, Mysql-shared and/or Mysql-client are changed, the exec will run.
Refreshonly It will only run if there is a change to these packages.
ifnot First and foremost, it will run the ifnot command before running the exec. If the ifnot command returns anything other than an empty string or false, then the exec will be run.
command This defines the command that we are going to run.

Functions

Notice there is a password function defined on the plugin. This way, from within the plugin call, we can say password("mypassword"). This will set the variable: $password so we can use it from within the plugin.

Usage

   1  pool :app do
   2    
   3    # this will load all the plugins in the directory
   4    # It deep includes every .rb file in the directory
   5    # 
   6    # Example will require mysql.rb and apache.rb
   7    # plugins/
   8    #   mysql/
   9    #     mysql.rb
  10    #   apache/
  11    #     apache.rb
  12    #     spec/
  13    #       apache_spec.rb
  14    plugin_directory File.dirname(__FILE__) + "/plugins"
  15    
  16    cloud :app do
  17      
  18      # Call the mysql plugin
  19      mysql do
  20        # It's important to set the password before installing to set the password
  21        # on the server
  22        password("frankspassword")
  23        base_install
  24      end
  25      
  26    end
  27  end

Stay tuned for more updates to this tutorial as we continue to advance the plugin and give it some virtual resources where we can ensure that there are specific databases setup and other setups for mysql.