openstack_activeresource 0.2.1 → 0.3.0

data/lib/open_stack/nova/compute/base.rb

@@ -21,6 +21,7 @@ module OpenStack
 
       class Base < OpenStack::Common
 
+        # Get the Nova Compute endpoint assigned to OpenStack::Nova::Compute classes
         def self.site
           if self == OpenStack::Nova::Compute::Base
             Thread.current[:open_stack_nova_compute_site]
@@ -29,6 +30,7 @@ module OpenStack
           end
         end
 
+        # Set the Nova Compute endpoint for OpenStack::Nova::Compute classes
         def self.site=(site)
           super(site)
           Thread.current[:open_stack_nova_compute_site] = @site

data/lib/open_stack/nova/compute/base_detail.rb

@@ -19,7 +19,7 @@ module OpenStack
   module Nova
     module Compute
 
-      class BaseDetail < Base
+      class BaseDetail < Base #:nodoc:
 
         # Overrides ActiveResource::Base::collection_path to add /details to resource path for servers and
         # to remove .<extension>

data/lib/open_stack/nova/compute/flavor.rb

@@ -19,7 +19,17 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Floating Ip
+      #
+      # ==== Attributes
+      # * +name+ - The name of the flavor
+      # * +ram+ - Amount of RAM (MBytes)
+      # * +disk+ - Amount of storage (GBytes)
+      # * +vcpus+ - Virtual CPUs
+      # * +rxtx_factor+ - Traffic shaping (?)
+      # * +ephemeral_disk+ - Ephemeral storage amount (GByte)
       class Flavor < BaseDetail
+
         schema do
           attribute :name, :string
           attribute :ram, :integer
@@ -35,37 +45,55 @@ module OpenStack
         validates :disk, :presence => true, :numericality => {:greater_than_or_equal_to => 10, :only_integer => true}
         validates :ephemeral_disk, :presence => false, :numericality => {:greater_than_or_equal_to => 10, :only_integer => true}
 
+        # Returns a list of Flavor for a given name
+        #
+        # ==== Attributes
+        # * +name+ - A string
         def self.find_all_by_name(name)
           all.reject { |flavor| flavor.name != name }
         end
 
+        # Returns the first Flavor for a given name
+        #
+        # ==== Attributes
+        # * +name+ - A string
         def self.find_by_name(name)
-          all.each { |flavor| return flavor if flavor.name == name }
-
-          nil
+          all.detect { |flavor| flavor.name == name }
         end
 
+        # Returns a list of Flavor that can be used with the given constraints
+        #
+        # ==== Attributes
+        # * +constraints+ - Hash of constraints. Valid keys are: :ram, :vcpus, :disk
         def self.find_by_constraints(constraints = {})
           constraints = constraints.with_indifferent_access
-          constraints[:ram]   ||= -1.0/0.0
+          constraints[:ram] ||= -1.0/0.0
           constraints[:vcpus] ||= -1.0/0.0
-          constraints[:disk]  ||= -1.0/0.0
+          constraints[:disk] ||= -1.0/0.0
 
           all.select { |flavor| flavor.ram >= constraints[:ram] and flavor.vcpus >= constraints[:vcpus] and flavor.disk >= constraints[:disk] }
         end
 
+        # Returns a list of Flavor that can be used with the given Image
+        #
+        # ==== Attributes
+        # * +image+ - An OpenStack::Nova::Compute::Image instance or an Image id
         def self.applicable_for_image(image)
+          image_instance = image.is_a?(OpenStack::Nova::Compute::Image) ? image : Image.find(image)
+
           constraints = {}
-          constraints[:ram]   = image.min_ram if image.min_ram > 0
-          constraints[:disk]  = image.min_disk if image.min_disk > 0
+          constraints[:ram] = image.min_ram if image_instance.min_ram > 0
+          constraints[:disk] = image.min_disk if image_instance.min_disk > 0
 
           find_by_constraints constraints
         end
 
+        # Returns the amount of ephemeral disk
         def ephemeral_disk
           @attributes[:'OS-FLV-EXT-DATA:ephemeral'] || nil
         end
 
+        # Returns a human-friendly description for this Flavor
         def description
           "#{vcpus} vCPU - #{ram} MB RAM - #{disk} GB Disk"
         end

data/lib/open_stack/nova/compute/floating_ip.rb

@@ -19,6 +19,13 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Floating Ip
+      #
+      # ==== Attributes
+      # * +ip+ - Floating IP(v4/v6) address
+      # * +fixed_ip+ - Fixed IP(v4/V6) address
+      # * +pool+ - The id of the pool this IP belongs to
+      # * +instance_id+ - Identifier of server this IPis assigned to (if any)
       class FloatingIp < Base
         self.collection_name = "os-floating-ips"
         self.element_name = "floating_ip"
@@ -30,9 +37,8 @@ module OpenStack
           attribute :instance_id, :string
         end
 
-        # Overload ActiveRecord::encode method
-        # Custom encoding to deal with openstack API
-        def encode(options={})
+        # Overloads ActiveRecord::encode method
+        def encode(options={}) #:nodoc: Custom encoding to deal with openstack API
           to_encode = {}
           # Optional attributes (openstack will not accept empty attribute for update/create)
           to_encode[:pool] = pool if pool.present?
@@ -40,19 +46,32 @@ module OpenStack
           to_encode.send("to_#{self.class.format.extension}", options)
         end
 
+        # List of addresses for a given pool
+        #
+        # ==== Attributes
+        # * +pool+ - an instance of OpenStack::Nova::Compute::FloatingIpPool or a pool id
         def self.find_all_by_pool(pool)
-          all.reject! { |floating_ip| floating_ip.pool != pool }
+          pool_id = pool.is_a?(OpenStack::Nova::Compute::FloatingIpPool) ? pool.id : pool
+          all.reject! { |floating_ip| floating_ip.pool != pool_id }
         end
 
+        # The OpenStack::Nova::Compute::Server instance this address belongs to (if any)
         def instance
-          Server.find(instance_id) if instance_id
+          if instance_id
+            @instance ||= Server.find(instance_id)
+          end
         end
 
-        # Assign the IP to a given server
-        # Params:
-        # ::server:: the server to assign the floating ip to
+        # Assign the IP to a server
+        #
+        # ==== Attributes:
+        # * +server+ - An instance of OpenStack::Nova::Compute::Server (or a server id) to assign the floating IP to
         def assign!(server)
-          server.add_floating_ip(self)
+          server_instance = server.is_a?(OpenStack::Nova::Compute::Server) ? server : Server.find(server)
+          @instance = server_instance
+          self.instance_id = server_instance.id
+
+          server_instance.add_floating_ip(self)
         end
       end
 

data/lib/open_stack/nova/compute/floating_ip_pool.rb

@@ -19,6 +19,11 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Floating Ip Pool
+      #
+      # ==== Attributes
+      # * +id+ - Id of the pool
+      # * +name+ - Name of the pool
       class FloatingIpPool < Base
         self.collection_name = "os-floating-ip-pools"
         self.element_name = "floating_ip_pool"

data/lib/open_stack/nova/compute/image.rb

@@ -19,10 +19,24 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Image
+      #
+      # ==== Attributes
+      # * +name+ - Name of this image
+      # * +tenant_id+ - Tenant id to which this image belongs to (if applicable)
+      # * +server_id+ - Server id to which this image belongs to (if applicable)
+      # * +user_id+ - User id to which this image belongs to (if applicable)
+      # * +status+ - Status of image (e.g. ACTIVE)
+      # * +progress+ - Progress of image
+      # * +min_disk+ - Minimal amount of storage needed by this image (GBytes)
+      # * +min_ram+ - Minimal amount of RAM needed by this image (MBytes)
+      # * +updated_at+ - Modification date
+      # * +created_at+ - Creation date
       class Image < BaseDetail
         schema do
           attribute :name, :string
           attribute :tenant_id, :string
+          attribute :server_id, :string
           attribute :user_id, :string
           attribute :status, :string
           attribute :progress, :string
@@ -32,7 +46,7 @@ module OpenStack
           attribute :created_at, :datetime
         end
 
-        def initialize(attributes = {}, persisted = false)
+        def initialize(attributes = {}, persisted = false) # :notnew:
           attributes = attributes.with_indifferent_access
           new_attributes = {
               :id => attributes[:id],
@@ -42,6 +56,8 @@ module OpenStack
               :progress => attributes[:progress],
               :status => attributes[:status],
               :metadata => attributes[:metadata],
+              :user_id => attributes[:user_id],
+              :tenant_id => attributes[:tenant_id],
               :server_id => attributes[:server].present? ? attributes[:server][:id] : nil,
               :updated_at => attributes[:updated].present? ? DateTime.strptime(attributes[:updated], OpenStack::DATETIME_FORMAT) : nil,
               :created_at => attributes[:created].present? ? DateTime.strptime(attributes[:created], OpenStack::DATETIME_FORMAT) : nil
@@ -50,25 +66,39 @@ module OpenStack
           super(new_attributes, persisted)
         end
 
+        # Returns the list of Image instances with the specified name
+        #
+        # ==== Attributes
+        # * +name+ : A string
         def self.find_all_by_name(name)
           all.reject! { |image| image.name != name }
         end
 
+        # Returns the first Image instance with the specified name
+        #
+        # ==== Attributes
+        # * +name+ : A string
         def self.find_by_name(name)
-          all.each { |image| return image if image.name == name }
-
-          nil
+          all.detect { |image| image.name == name }
         end
 
+        # Returns the Server instance to which this image belongs to (if applicable)
         def server
           Server.find(server_id) if server_id.present?
         end
 
+        # Returns the type of image: image or snapshot
         def image_type
           metadata.image_type
         rescue NoMethodError
           'image'
         end
+
+        # True if this image is a snapshot
+        def snapshot?
+          image_type != 'image'
+        end
+
       end
 
     end

data/lib/open_stack/nova/compute/key_pair.rb

@@ -19,6 +19,13 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack KeyPair
+      #
+      # ==== Attributes
+      # * +name+ - Bridge name for this network
+      # * +public_key+ - Public key
+      # * +private_key+ - Private key (write only)
+      # * +fingerprint+ - The fingerprint for this keypair
       class KeyPair < Base
         self.collection_name = "os-keypairs"
         self.element_name = "keypair"
@@ -30,18 +37,24 @@ module OpenStack
           attribute :fingerprint, :string
         end
 
-        def id
+        def id #:nodoc:
           name
         end
 
+        # The list of keypair with a given name
+        #
+        # ==== Attributes
+        # * +name+ - A keypairs name
         def self.find_all_by_name(name)
           all.reject! { |key_pair| key_pair.name != name }
         end
 
+        # The first keypair with a given name
+        #
+        # ==== Attributes
+        # * +name+ - A keypair name
         def self.find_by_name(name)
-          all.each { |key_pair| return key_pair if key_pair.name == name }
-
-          nil
+          all.detect { |key_pair| key_pair.name == name }
         end
 
       end

data/lib/open_stack/nova/compute/network.rb

@@ -19,6 +19,16 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Network (\*WARNING:* incomplete)
+      #
+      # ==== Attributes
+      # * +bridge+ - Bridge name for this network
+      # * +bridge_interface+ - Interface for this network
+      # * +cidr+ - CIDR used by this network
+      # * +label+ - Label for this network
+      # * +multi_host+ - True if this network is managed by more than one controller (false otherwise)
+      # * +vlan+ - Vlan ID (802.1q) used by this network
+      # * +project_id+ - Tenant id associated with this network (if any)
       class Network < Base
         self.collection_name = "os-networks"
 

data/lib/open_stack/nova/compute/security_group.rb

@@ -19,6 +19,12 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Security Group
+      #
+      # ==== Attributes
+      # * +tenant_id+ - Tenant id for this security group
+      # * +name+ - Name of this security group
+      # * +description+ - Description of this security group
       class SecurityGroup < Base
         self.element_name = "security_group"
         self.collection_name = "os-security-groups"
@@ -34,6 +40,14 @@ module OpenStack
 
       end
 
+      # An OpenStack Security Group Rule
+      #
+      # ==== Attributes
+      # * +ip_protocol+ - Protocol: tcp, udp or icmp
+      # * +from_port+ - Initial port
+      # * +to_port+ - Final port
+      # * +parent_group_id+ - The security group this rule belongs to
+      # * +cidr+ - A cidr
       class SecurityGroup::Rule < Base
         self.element_name = "security_group_rule"
         self.collection_name = "os-security-group-rules"
@@ -60,7 +74,7 @@ module OpenStack
         validates_numericality_of :to_port, :greater_than_or_equal_to => :from_port, :if => Proc.new { |rule| rule.udp? or rule.tcp? }
 
 
-        def initialize(attributes = {}, persisted = false)
+        def initialize(attributes = {}, persisted = false) #:notnew:
           attributes = attributes.with_indifferent_access
           new_attributes = {
               :id => attributes[:id],
@@ -74,8 +88,7 @@ module OpenStack
         end
 
         # Override ActiveRecord::encode method
-        # Custom encoding to deal with openstack API
-        def encode(options={})
+        def encode(options={}) #:nodoc: Custom encoding to deal with openstack API
           to_encode = {
               :security_group_rule => {
                   :ip_protocol => ip_protocol,
@@ -88,23 +101,35 @@ module OpenStack
           to_encode.send("to_#{self.class.format.extension}", options)
         end
 
+        # Set the parent security group (if the rule is not persisted)
+        #
+        # ==== Attributes
+        # * +group+: An instance of OpenStack::Nova::Compute::SecurityGroup or a security group id
         def parent_group=(group)
-          parent_group_id = group.id
+          unless persisted?
+            @parent_group = nil
+            self.parent_group_id = group.is_a?(OpenStack::Nova::Compute::SecurityGroup) ? group.id : group
+          end
         end
 
+        # Parent group for this rule
         def parent_group
-          return nil if parent_group_id.nil?
-          SecurityGroup.find(parent_group_id)
+          unless parent_group_id.nil?
+            @parent_group ||= SecurityGroup.find(parent_group_id)
+          end
         end
 
+        # True if this rule refers to ICMP
         def icmp?
           ip_protocol == 'icmp'
         end
 
+        # True if this rule refers to UDP
         def udp?
           ip_protocol == 'udp'
         end
 
+        # True if this rule refers to TCP
         def tcp?
           ip_protocol == 'tcp'
         end

data/lib/open_stack/nova/compute/server.rb

@@ -19,6 +19,21 @@ module OpenStack
   module Nova
     module Compute
 
+      # An OpenStack Server
+      #
+      # ==== Attributes
+      # * +name+ - The name of the server
+      # * +status+ - Status of the server (see http://docs.openstack.org/api/openstack-compute/2/content/List_Servers-d1e2078.html)
+      # * +vm_state+ - Extended Instance Status
+      # * +task+ - If not +nil+, contains the task OpenStack is preforming on this server
+      # * +power_state+ - Server power state (0|1)
+      # * +tenant_id+ - Identifier of the tenant this server belongs to
+      # * +user_id+ - Identifier of the user that created this server
+      # * +image_id+ - Identifier of the image used to create this server
+      # * +flavor_id+ - Identifier of the flavor used to create this server
+      # * +key_pair_id+ - Identifier of the keypair used by this server
+      # * +updated_at+ - Last modification timestamp
+      # * +created_at+ - Creation timestamp
       class Server < BaseDetail
 
         schema do
@@ -41,13 +56,20 @@ module OpenStack
         validates :image, :presence => true
         validates :flavor, :presence => true
 
+        # Return the list of server for a given tenant
+        #
+        # ==== Attributes
+        # * +tenant+ - an OpenStack::Keystone::Admin::Tenant instance (or a tenant id)
+        #
+        # ==== Notes
+        # This method require an admin access
         def self.all_by_tenant(tenant)
           tenant_id = tenant.is_a?(OpenStack::Keystone::Admin::Tenant) ? tenant.id : tenant
 
           find(:all, :params => {:tenant_id => tenant_id})
         end
 
-        def initialize(attributes = {}, persisted = false)
+        def initialize(attributes = {}, persisted = false) # :notnew:
           attributes = attributes.with_indifferent_access
           new_attributes = {
               :id => attributes[:id],
@@ -99,9 +121,9 @@ module OpenStack
           self
         end
 
-        # Overload ActiveRecord::encode method
-        # Custom encoding to deal with openstack API
-        def encode(options={})
+        # Overloads ActiveRecord::encode method
+        def encode(options={}) #:nodoc:
+                               # Custom encoding to deal with openstack API
           to_encode = {
               :server => {
                   :name => name,
@@ -118,32 +140,61 @@ module OpenStack
           to_encode.send("to_#{self.class.format.extension}", options)
         end
 
-        # Accessors
-
+        # The instance of OpenStack::Nova::Compute::Image used for this server
         def image
-          Image.find(image_id) if image_id.present?
+          if image_id.present?
+            @image ||= Image.find(image_id)
+          end
         end
 
+        # Set the image for this server (if the server is not persisted)
+        #
+        # ==== Attributes
+        # * +image+ - An instance of OpenStack::Nova::Compute::Image or an image id
         def image=(image)
-          self.image_id = image.id
+          unless persisted?
+            @image = nil # nullify @@image because the image id is changed
+            self.image_id = image.is_a?(OpenStack::Nova::Compute::Image) ? image.id : image
+          end
         end
 
+        # The instance of OpenStack::Nova::Compute::Flavor used for this server
         def flavor
-          Flavor.find(flavor_id) if flavor_id.present?
+          if flavor_id.present?
+            @flavor ||= Flavor.find(flavor_id)
+          end
         end
 
+        # Set the flavor for this server (if the server is not persisted)
+        #
+        # ==== Attributes
+        # * +flavor+ - An instance of OpenStack::Nova::Compute::Flavor or a flavor id
         def flavor=(flavor)
-          self.flavor_id = flavor.id
+          unless persisted?
+            @flavor = nil # nullify @flavor because the flavor id is changed
+            self.flavor_id = flavor.is_a?(OpenStack::Nova::Compute::Flavor) ? flavor.id : flavor
+          end
         end
 
+        # The instance of OpenStack::Nova::Compute::KeyPair used for this server (if any)
         def key_pair
-          KeyPair.find(key_pair_id) if key_pair_id.present?
+          if key_pair_id.present?
+            @keypair ||= KeyPair.find(key_pair_id)
+          end
         end
 
+        # Set the keypair for this server (if the server is not persisted)
+        #
+        # ==== Attributes
+        # * +key_pair+ - An instance of OpenStack::Nova::Compute::KeyPair or a key-pair id
         def key_pair=(key_pair)
-          self.key_pair_id = key_pair.name
+          unless persisted?
+            @keypair = nil # nullify @@keypair because the keypair id is changed
+            self.key_pair_id = key_pair.id
+          end
         end
 
+        # The array of OpenStack::Nova::Compute::SecurityGroup instances associated with this server
         def security_groups
           if persisted?
             get('os-security-groups').map { |sg| OpenStack::Nova::Compute::SecurityGroup.new(sg, true) }
@@ -152,14 +203,19 @@ module OpenStack
           end
         end
 
+        # Set security groups for this server
+        #
+        # ==== Attributes
+        # * +security_groups+ - Array of OpenStack::Nova::Compute::SecurityGroup instances
         def security_groups=(security_groups)
           return if persisted? # Do Nothing (it's a read-only attribute for OpenStack)
 
-          security_group_ids = security_groups.map { |sg| sg.id }
+          self.security_group_ids = security_groups.map { |sg| sg.id }
 
           security_groups
         end
 
+        # Addresses hash associated to this server
         def addresses
           addresses = {}
           if persisted?
@@ -171,34 +227,50 @@ module OpenStack
           addresses
         end
 
-        def addresses=(something)
-          # Do Nothing (it's a read-only attribute for OpenStack)
+        def addresses=(something) # :nodoc: do Nothing (it's a read-only attribute for OpenStack)
+
         end
 
+        # The OpenStack::Nova::Compute::VolumeAttachment(s) for this server
+        #
+        # ==== Attributes
+        # * +scope+ - An ActiveResource find scope (default: :all)
         def volume_attachments(scope = :all)
           VolumeAttachment.find(scope, :params => {:server_id => self.id})
         end
 
-        # Misc...
-
-        # Return the list of attached volumes
+        # Array of OpenStack::Nova::Compute::Volume attached to this server
         def attached_volumes
           volume_attachments.present? ? volume_attachments.map { |va| va.volume } : []
         end
 
         # Attach a volume
+        #
+        # ==== Attributes
+        # * +volume+ - An OpenStack::Nova::Compute::Volume instance
+        # * +device_name+ - Name the device (from server perspective) (e.g. "/dev/vdc")
         def attach_volume!(volume, device_name)
           VolumeAttachment.create(:volume => volume, :device => device_name, :server => self)
         end
 
         # Refresh server status
+        # This method updates the following attributes:
+        #  * progress
+        #  * status
+        #  * task
+        #  * power_state
+        #  * vm_state
         def refresh_status!
-          updated = Server.find(self.id)
-          self.progress = updated.progress
-          self.status = updated.status
-          self.task = updated.task
-
-          self
+          if persisted?
+            updated = Server.find(self.id)
+            self.progress = updated.progress
+            self.status = updated.status
+            self.task = updated.task
+            self.power_state = updated.power_state
+            self.vm_state = updated.vm_state
+
+            self
+          end
         end
 
         SERVER_STATUSES = {
@@ -220,7 +292,7 @@ module OpenStack
             :VERIFY_RESIZE => I18n.t(:awaiting_verification, :scope => [:openstack, :status])
         }.with_indifferent_access
 
-        # Returns an extended description for the server status
+        # Returns an extended (and localized) description for the server status
         def status_description
           SERVER_STATUSES[status]
         end
@@ -230,42 +302,45 @@ module OpenStack
           I18n.t(task, :scope => [:openstack, :tasks]) if task.present?
         end
 
-        ## Actions
-
-        # Assign a floating IP to the server.
-        # Params:
-        # +floating_ip+:: a FloatingIP to be attached to the server.
+        # Assign a floating IP to the server
+        #
+        # ==== Attributes
+        # * +floating_ip+ - a FloatingIP to be attached to the server.
         def add_floating_ip(floating_ip)
           post(:action, {}, {:addFloatingIp => {:address => floating_ip.ip}}.to_json)
         end
 
-        # Reboot the server.
-        # Params:
-        # +type+:: type of reboot. Should be 'hard' or 'soft' (defaults to 'hard', may be nil)
+        # Reboot the server
+        #
+        # ==== Attributes
+        # * +type+ - type of reboot. Should be 'hard' or 'soft' (defaults to 'hard', may be nil)
         def reboot(type=:hard)
           post(:action, {}, {:reboot => {:type => type}}.to_json)
         end
 
-        # Creates a new snapshot of server.
-        # Params:
-        # +name+:: name of the new snapshot image
-        # +metadata+::  hash of metadata (may be nil)
+        # Creates a new snapshot of server
+        #
+        # ==== Attributes
+        # * +name+ - name of the new snapshot image
+        # * +metadata+ -  hash of metadata (may be nil)
         def create_new_image(name, metadata={})
           post(:action, {}, {:createImage => {:name => name, :metadata => metadata}}.to_json)
         end
 
-        # Gets the output from the console log for a server.
-        # Params:
-        # +length+:: numbers of lines to get (defaults to 50, may be nil)
+        # Gets the output from the console log for a server
+        #
+        # ==== Attributes
+        # * +length+ - numbers of lines to get (defaults to 50, may be nil)
         def console_output(length=50)
           response = post(:action, {}, {:'os-getConsoleOutput' => {:length => length}}.to_json)
 
           ActiveSupport::JSON.decode(response.body)['output']
         end
 
-        # Accesses a VNC console for a specific server.
-        # Params:
-        # +length+:: numbers of lines to get (defaults to 50, may be nil)
+        # Accesses a VNC console for a specific server
+        #
+        # ==== Attributes
+        # * +length+ - numbers of lines to get (defaults to 50, may be nil)
         def vnc_console(type='novnc')
           response = post(:action, {}, {:'os-getVNCConsole' => {:type => type}}.to_json)