foreman_reserve 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b47f26dc034d5b901b2661b71bb038d7555b864f
-  data.tar.gz: 312437ec807d584309fb1cc3eef4e050a7eacc20
+  metadata.gz: edaeb4e6dd24d5ca57297860ae94f8e49f47ac39
+  data.tar.gz: 79c1507a10634769373a92ba9f9d256d862ae155
 SHA512:
-  metadata.gz: 967b9021d5c71dabd6eddf4c8c7ec0d213ee356b63fab9aaadb2d0836a533b19c982babcef6bc45e37359b7603f7a4975c32af3c2c42543ab3cf22584bf796ce
-  data.tar.gz: 84457171d2912961de32a5b7802643d7297a29ed84ad35735f115d8c906da740cccba40fba6bf9d65ace5e3f891f1ac91f2b34fe2533206eb1edabdefa19205d
+  metadata.gz: 1c929a0f33b04449f517359cd7cb292cf1abb9e41fb1968e114e6fd6b1ed3d814c653da9be2715a26fe0510c4691eee39c47b77209627ffcddf03aa5a6c1da55
+  data.tar.gz: 63c57ee74c1a651740656ed52defbc1ee28de60e869e04e1b755424693ceecd7153c42f97ac52c38b8fc26aea2c37e41ad18145f02acb2a187822e258bbe5b9d

data/README.rdoc

@@ -1,39 +1,73 @@
 = foreman_reserve
 
+{<img src="https://badge.fury.io/rb/foreman_reserve.png" alt="Gem Version" />}[http://badge.fury.io/rb/foreman_reserve]
+
 This gem will added a route to the API to return the name of available host(s)
 
 = Installation:
 
-gem 'foreman_reserve', :git => "https://github.com/isratrade/foreman_reserve.git"
+You have to make sure that the gem is available to foreman, to do that the
+recommended way is to add a new file to <i>$FOREMAN_DIR/bundler.d</i> named
+<i>foreman_reserve.rb</i> with the next content:
+
+* You can use the git code to get the latest:
+
+ gem 'foreman_reserve', :git => "https://github.com/david-caro/foreman_reserve.git"
+
+* Or the gem from rubygems:
+
+ gem 'foreman_reserve'
+
+After that you'll need to create the bundle for foreman, as foreman user run
+from the <i>$FOREMAN_DIR</i>:
+
+<tt>>$ bunde --deploy</tt>
+
+
+== Foreman 1.1
 
 In order to work, the foreman application must be the following two lines commented out.
 
 config/routes.rb 
-	# match '*a', :to => 'errors#routing'
+ # match '*a', :to => 'errors#routing'
 
 config/routes/v1.rb
-	# match '*other', :to => 'home#route_error'
+ # match '*other', :to => 'home#route_error'
 
 = Usage
 
+To make a host 'reservable', you need to make sure it has a parameter named
+<b>RESERVED</b>, that parameter will be used to store the current reservation
+status, you can safely add the parameter to a hostgroup for the hsot to inherit
+from.
+
 To return 1 host:
-curl -u admin:secret -H 'accept:application/json' http://0.0.0.0:3000/api/hosts_reserve
+
+<tt>>$ curl -u admin:secret -H 'accept:application/json' http://0.0.0.0:3000/api/hosts_reserve</tt>
 
 To return multiple hosts, pass a parameter called 'amount'
 
-curl -u admin:secret -H 'accept:application/json' http://0.0.0.0:3000/api/hosts_reserve?amount=3
+<tt>>$ curl -u admin:secret -H 'accept:application/json' http://0.0.0.0:3000/api/hosts_reserve?amount=3</tt>
 
 Filter using a specific query: (name ~ virt%)
 
-curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts_reserve?query=name%20~%20virt%25'
+<tt>>$ curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts_reserve?query=name%20~%20virt%25'</tt>
 
 Release a specific host:
 
-curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts_release?host_name=myreservedhost'
+<tt>>$ curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts_release?host_name=myreservedhost'</tt>
 
 Release a group of hosts using a query: (name ~ virt%)
 
-curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts_reserve?query=name%20~%20virt%25'
+<tt>>$ curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts_reserve?query=name%20~%20virt%25'</tt>
+
+== foreman-python
+
+In order to use from python, there's a python module that already includes
+this plugin calls, you can find it on pypi or on github:
+
+* https://github.com/david-caro/python-foreman
+* https://pypi.python.org/pypi/python-foreman
 
 == Contributing to foreman_reserve
  
@@ -47,6 +81,6 @@ curl -u admin:secret -H 'accept:application/json' 'http://0.0.0.0:3000/api/hosts
 
 == Copyright
 
-Copyright (c) 2012 Joseph Mitchell Magen. See LICENSE.txt for
+Copyright (c) 2013 Joseph Mitchell Magen and David Caro. See LICENSE.txt for
 further details.
 

data/VERSION

@@ -1 +1 @@
-0.1.6
+0.1.7

data/app/controllers/foreman_reserve/api/hosts_controller.rb

@@ -3,103 +3,149 @@ module Api
     class ForemanReserveController < Api::V1::BaseController
       unloadable
 
-    def get_reserved(query='')
-      hosts = User.current.admin? ? Host::Managed : Host::Managed.my_hosts
-      hosts.search_for(query)
-      hosts.each do |host|
-        params = host.info()['parameters']
-        if params and
-            params.key?('RESERVED') and 
-            params['RESERVED'] != 'false'
-          host
+      # Get the list of reserved hosts
+      # @param query [String] Query to filter the hosts with
+      def get_reserved(query='')
+        hosts = User.current.admin? ? Host::Managed : Host::Managed.my_hosts
+        hosts.search_for(query)
+        hosts.each do |host|
+          params = host.info()['parameters']
+          if params and
+              params.key?('RESERVED') and
+              params['RESERVED'] != 'false'
+            host
+          end
         end
       end
-    end
 
-    def get_free(query='')
-      hosts = User.current.admin? ? Host::Managed : Host::Managed.my_hosts
-      hosts.search_for(query)
-      hosts.each do |host|
-        params = host.info()['parameters']
-        if params
-            and params.has_key('RESERVED')
-            and params['RESERVED'] == 'false'
-          host
+      # Get the list of available hosts
+      # @param query [String] Query to filter the hosts with
+      def get_free(query='')
+        hosts = User.current.admin? ? Host::Managed : Host::Managed.my_hosts
+        hosts.search_for(query)
+        hosts.each do |host|
+          params = host.info()['parameters']
+          if params and
+              params.has_key('RESERVED') and
+              params['RESERVED'] == 'false'
+            host
+          end
         end
       end
-    end
 
-    def not_found(exception = nil)
-        logger.debug "not found: #{exception}" if exception
-        respond_to do |format|
-            format.html { render "common/404", :status => 404 }
-            format.json { head :status => 404}
-            format.yaml { head :status => 404}
-        end 
-        true
-    end 
+      # Return not found
+      # @param exception [String] Message to show
+      def not_found(exception = nil)
+          logger.debug "not found: #{exception}" if exception
+          respond_to do |format|
+              format.html { render "common/404", :status => 404 }
+              format.json { head :status => 404}
+              format.yaml { head :status => 404}
+          end
+          true
+      end
 
-    def reserve
-      amount          = (params[:amount] || 1).to_i
-      reason          = params[:reason] || 'true'
-      ## Lock to avoid reserving the same host twice
-      unless File.exists? "/tmp/foreman_reserve.lock"
-        File.open("/tmp/foreman_reserve.lock", 'w') {}
-      end 
-      lock = File.new("/tmp/foreman_reserve.lock")
-      begin
-        lock.flock(File::LOCK_EX)
-        potential_hosts = get_free(params[:query])
-        return not_found if potential_hosts.empty?
-        return not_acceptable if potential_hosts.count < amount
-        @hosts = potential_hosts[0..(amount-1)].each do |host|
-          logger.error host.class.name
-          logger.error host.class.instance_methods(false)
-          logger.error Host.class.instance_methods(false)
-          host.reserve!(reason)
+      # <b>API METHOD</b>: Reserve one or more hosts, will return 404 if the
+      # given query gives no results and 406 (Not acceptable) if not enough free
+      # hosts
+      #
+      # <b>Query parameters:</b>
+      #
+      # * <tt><b>amount</b> (Int)</tt> <i>(defaults to: <tt>1</tt>)</i> ---
+      #   Amount of hosts to reserve
+      # * <tt><b>reason</b> (String)</tt> <i>(defaults to: <tt>true</tt>)</i> ---
+      #   Reason to reserve the hosts under, this is the string that will be
+      #   put in the <i>RESERVED</i> host parameter
+      # * <tt><b>query</b> (String)</tt> <i>(defaults to: <tt>''</tt>)</i> ---
+      #   Query to filter the list of hosts with
+      def reserve
+        amount          = (params[:amount] || 1).to_i
+        reason          = params[:reason] || 'true'
+        ## Lock to avoid reserving the same host twice
+        unless File.exists? "/tmp/foreman_reserve.lock"
+          File.open("/tmp/foreman_reserve.lock", 'w') {}
+        end
+        lock = File.new("/tmp/foreman_reserve.lock")
+        begin
+          lock.flock(File::LOCK_EX)
+          potential_hosts = get_free(params[:query])
+          return not_found if potential_hosts.empty?
+          return not_acceptable if potential_hosts.count < amount
+          @hosts = potential_hosts[0..(amount-1)].each do |host|
+            logger.error host.class.name
+            logger.error host.class.instance_methods(false)
+            logger.error Host.class.instance_methods(false)
+            host.reserve!(reason)
+          end
+        ensure
+          lock.flock(File::LOCK_UN)
+        end
+        respond_to do |format|
+          format.json {render :json => @hosts }
+          format.yaml {render :text => @hosts.to_yaml}
+          format.html {not_found }
         end
-      ensure
-        lock.flock(File::LOCK_UN)
-      end
-      respond_to do |format|
-        format.json {render :json => @hosts }
-        format.yaml {render :text => @hosts.to_yaml}
-        format.html {not_found }
       end
-    end
 
-    def release
-      host_name     = (params[:host_name] || '')
-      query         = params[:query]
-      amount        = (params[:amount] || 0 ).to_i
-      if host_name != ''
-        query = "#{query} AND name = #{host_name}"
-      end
-      reserved_hosts = get_reserved(query)
-      return not_found if reserved_hosts.empty?
-      if amount != 0
-        return not_acceptable if reserved_hosts.count < amount
-        @hosts = reserved_hosts[0..(amount-1)].each { |host| host.release! }
-      else
-        @hosts = reserved_hosts.each { |host| host.release! }
-      end
-      respond_to do |format|
-        format.json {render :json => @hosts.map(&:name) }
-        format.yaml {render :text => @hosts.to_yaml}
-        format.html {not_found }
+      # <b>API METHOD</b>: Release one or more hosts, will return 406 if there
+      # are less than <tt>amount</tt> reserved hosts
+      #
+      # <b>Query parameters:</b>
+      #
+      # * <tt><b>amount</b> (Int)</tt> <i>(defaults to: <tt>1</tt>)</i> ---
+      #   Amount of hosts to release
+      # * <tt><b>host_name</b> (String)</tt> 
+      #   <i>(defaults to: <tt>''</tt>)</i> ---
+      #   If given, will also filter by that host name
+      # * <tt><b>query</b> (String)</tt> <i>(defaults to: <tt>''</tt>)</i> ---
+      #   Query to filter the list of hosts with
+      def release
+        host_name     = (params[:host_name] || '')
+        query         = params[:query]
+        amount        = (params[:amount] || 0 ).to_i
+        if host_name != ''
+          query = "#{query} AND name = #{host_name}"
+        end
+        reserved_hosts = get_reserved(query)
+        return not_found if reserved_hosts.empty?
+        if amount != 0
+          return not_acceptable if reserved_hosts.count < amount
+          @hosts = reserved_hosts[0..(amount-1)].each { |host| host.release! }
+        else
+          @hosts = reserved_hosts.each { |host| host.release! }
+        end
+        respond_to do |format|
+          format.json {render :json => @hosts.map(&:name) }
+          format.yaml {render :text => @hosts.to_yaml}
+          format.html {not_found }
+        end
       end
-    end
 
-    def show_reserved
-      hosts = get_reserved(params[:query])
-      return not_found if hosts.empty?
-      respond_to do |format|
-        format.json {render :json => hosts }
-        format.yaml {render :text => hosts.to_yaml}
-        format.html {not_found }
+      # <b>API METHOD</b>: Show the list of resrved hosts
+      #
+      # <b>Query parameters:</b>
+      #
+      # * <tt><b>query</b> (String)</tt> <i>(defaults to: <tt>''</tt>)</i> ---
+      #   Query to filter the list of hosts with
+      def show_reserved
+        hosts = get_reserved(params[:query])
+        return not_found if hosts.empty?
+        respond_to do |format|
+          format.json {render :json => hosts }
+          format.yaml {render :text => hosts.to_yaml}
+          format.html {not_found }
+        end
       end
-    end
 
+      # <b>API METHOD</b>: Show the list of available hosts, will return 406
+      # (Not acceptable) if <tt>amount</tt> given and not enough free hosts found
+      #
+      # <b>Query parameters:</b>
+      #
+      # * <tt><b>amount</b> (Int)</tt> <i>(defaults to: <tt>0</tt>)</i> ---
+      #   Amount of hosts to show, 0 for all
+      # * <tt><b>query</b> (String)</tt> <i>(defaults to: <tt>''</tt>)</i> ---
+      #   Query to filter the list of hosts with
       def show_available
         amount = (params[:amount] || 0).to_i
         hosts  = get_free(params[:query])
@@ -115,6 +161,18 @@ module Api
         end
       end
 
+      # <b>API METHOD</b>: Update the reserved reason
+      #
+      # <b>Query parameters:</b>
+      #
+      # * <tt><b>amount</b> (Int)</tt> <i>(defaults to: <tt>0</tt>)</i> ---
+      #   Amount of hosts to show, 0 for all
+      # * <tt><b>reason</b> (String)</tt>
+      #   <i>(defaults to: <tt>true</tt>)</i> ---
+      #   New reason to reserve the hosts under, this is the string that will
+      #   be put in the <i>RESERVED</i> host parameter
+      # * <tt><b>query</b> (String)</tt> <i>(defaults to: <tt>''</tt>)</i> ---
+      #   Query to filter the list of hosts with
       def update_reason
         amount          = (params[:amount] || 0).to_i
         reason          = params[:reason] || 'true'
@@ -134,6 +192,7 @@ module Api
         end
       end
 
+      # Return HTTP 406 (Not acceptable)
       def not_acceptable
         head :status => 406
       end

data/app/models/foreman_reserve/host_extensions.rb

@@ -1,24 +1,33 @@
 module ForemanReserve
   module HostExtensions
     extend ActiveSupport::Concern
-      module InstanceMethods
-        def reserve!(reason = 'true')
-          param = "RESERVED"
-            if p=host_parameters.find_by_name(param)
-            p.update_attribute(:value, reason)
-          else
-            host_parameters.create!(:name => param, :value => reason)
-          end
+    module InstanceMethods
+
+      # Reserve the host
+      #
+      # @param reason [String] Reason to reserve the host under
+      def reserve!(reason = 'true')
+        param = "RESERVED"
+        if p=host_parameters.find_by_name(param)
+          p.update_attribute(:value, reason)
+        else
+          host_parameters.create!(:name => param, :value => reason)
         end
-        def release!
-          param = "RESERVED"
-          if p=host_parameters.find_by_name(param)
-            p.update_attribute(:value, "false")
-          end
+      end
+
+      # Release the host
+      def release!
+        param = "RESERVED"
+        if p=host_parameters.find_by_name(param)
+          p.update_attribute(:value, "false")
         end
-        def as_json(options={})
-          super(:methods => [:host_parameters])
       end
+
+      # Return a json represenatation of the host
+      def as_json(options={})
+        super(:methods => [:host_parameters])
+      end
+
     end
   end
 end

data/foreman_reserve.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = "foreman_reserve"
-  s.version = "0.1.6"
+  s.version = "0.1.7"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joseph Mitchell Magen", "David Caro"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foreman_reserve
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Joseph Mitchell Magen
@@ -116,3 +116,4 @@ signing_key:
 specification_version: 3
 summary: Plugin engine for Foreman to allocate hosts
 test_files: []
+has_rdoc: