squall 1.3.0 → 1.3.1

data/lib/squall/virtual_machine.rb

@@ -1,311 +1,287 @@
 module Squall
   # OnApp VirtualMachine
   class VirtualMachine < Base
-    # Return a list of virtual machines
+    # Public: List all virtual machines.
+    #
+    # Returns an Array.
     def list
       response = request(:get, '/virtual_machines.json')
       response.collect { |v| v['virtual_machine'] }
     end
 
-    # Return a Hash for the given virtual machines
+    # Public: Get info for a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def show(id)
       response = request(:get, "/virtual_machines/#{id}.json")
       response.first[1]
     end
 
-    # Create a new virtual machine
-    #
-    # ==== Params
-    #
-    # * +options+ - Params for creating the virtual machine
-    #
-    # ==== Options
-    #
-    # * +label*+ - Label for the virtual machine
-    # * +hostname*+ - Hostname for the virtual machine
-    # * +memory*+ - Amount of RAM assigned to this virtual machine
-    # * +cpus*+ - Number of CPUs assigned to the virtual machine
-    # * +cpu_shares*+ - CPU priority for this virtual machine
-    # * +primary_disk_size*+ - Disk space for this virtual machine
-    # * +template_id*+ - ID for a template from which the virtual machine will be built
-    # * +hypervisor_id+ - ID for a hypervisor where virtual machine will be built.  If not provided the virtual machine will be assigned to the first available hypervisor
-    # * +swap_disk_size+ - Swap space (does not apply to Windows virtual machines)
-    # * +primary_network_id+ - ID of the primary network
-    # * +required_automatic_backup+ - Set to '1' if automatic backups are required
-    # * +rate_limit+ - Max port speed
-    # * +required_ip_address_assignment+ - Set to '1' if you wish to assign an IP address automatically
-    # * +required_virtual_machine_build+ - Set to '1' to build virtual machine automatically
-    # * +admin_note+ - Comment that can only be set by admin of virtual machine
-    # * +note+ - Comment that can be set by the user of the virtual machine
-    # * +allowed_hot_migrate+ - Set to '1'  to allow hot migration
-    # * +initial_root_password+ - Root password for the virtual machine.  6-31 characters consisting of letters, numbers, '-' and '_'
-    # * hypervisor_group_id - the ID of the hypervisor zone in which the VM will be created. Optional: if no hypervisor zone is set, the VM will be built in any available hypervisor zone.
-
-    #
-    # ==== Example
-    #
-    #  params = {
-    #    :label => 'testmachine',
-    #    :hypervisor_id => 5,
-    #    :hostname => 'testmachine',
-    #    :memory => 512,
-    #    :cpus => 1,
-    #    :cpu_shares => 10,
-    #    :primary_disk_size => 10,
-    #    :template_id => 1
-    #  }
-    #
-    #  create params
+    # Public: Create a new virtual machine.
+    #
+    # options - Params for creating the virtual machine:
+    #           admin_note                     - Comment that can only be set by
+    #                                            admin of virtual machine
+    #           allowed_hot_migrate            - Set to '1' to allow hot
+    #                                            migration
+    #           cpu_shares                     - CPU priority for this virtual
+    #                                            machine
+    #           cpus                           - Number of CPUs assigned to the
+    #                                            virtual machine
+    #           hostname                       - Hostname for the virtual machine
+    #           hypervisor_group_id            - the ID of the hypervisor zone in
+    #                                            which the VM will be created.
+    #                                            Optional: if no hypervisor zone
+    #                                            is set, the VM will be built in
+    #                                            any available hypervisor zone.
+    #           hypervisor_id                  - ID for a hypervisor where
+    #                                            virtual machine will be built.
+    #                                            If not provided the virtual
+    #                                            machine will be assigned to the
+    #                                            first available hypervisor
+    #           initial_root_password          - Root password for the virtual
+    #                                            machine. 6-31 characters
+    #                                            consisting of letters, numbers,
+    #                                            '-' and '_'
+    #           label                          - Label for the virtual machine
+    #           memory                         - Amount of RAM assigned to this
+    #                                            virtual machine
+    #           note                           - Comment that can be set by the
+    #                                            user of the virtual machine
+    #           primary_disk_size              - Disk space for this virtual
+    #                                            machine
+    #           primary_network_id             - ID of the primary network
+    #           rate_limit                     - Max port speed
+    #           required_automatic_backup      - Set to '1' if automatic backups
+    #                                            are required
+    #           required_ip_address_assignment - Set to '1' if you wish to
+    #                                            assign an IP address
+    #                                            automatically
+    #           required_virtual_machine_build - Set to '1' to build virtual
+    #                                            machine automatically
+    #           swap_disk_size                 - Swap space (does not apply to
+    #                                            Windows virtual machines)
+    #           template_id                    - ID for a template from which
+    #                                            the virtual machine will be
+    #                                            built
+    #
+    # Example
+    #     create(
+    #       label:             'testmachine',
+    #       hypervisor_id:     5,
+    #       hostname:          'testmachine',
+    #       memory:            512,
+    #       cpus:              1,
+    #       cpu_shares:        10,
+    #       primary_disk_size: 10,
+    #       template_id:       1
+    #     )
+    #
+    # Returns a Hash.
     def create(options = {})
-      required = [:label, :hostname, :memory, :cpus, :cpu_shares, :primary_disk_size, :template_id]
-      optional = [:hypervisor_id,
-                  :swap_disk_size,
-                  :primary_network_id,
-                  :required_automatic_backup,
-                  :rate_limit,
-                  :required_ip_address_assignment,
-                  :required_virtual_machine_build,
-                  :admin_note,
-                  :note,
-                  :allowed_hot_migrate,
-                  :initial_root_password,
-                  :hypervisor_group_id
-      ]
-      params.required(required).accepts(optional).validate! options
       response = request(:post, '/virtual_machines.json', default_params(options))
       response['virtual_machine']
     end
 
-    # Build a virtual machine
-    #
-    # ==== Params
+    # Public: Build a virtual machine.
     #
-    # * +id*+ - ID of the virtual machine
-    # * +options+ - Params for creating the virtual machine
+    # id      - ID of the virtual machine
+    # options - Params for creating the virtual machine
+    #           :required_startup - Set to '1' to startup virtual machine after
+    #                               building
+    #           :template_id      - ID of the template to be used to build the
+    #                               virtual machine
     #
-    # ==== Options
-    #
-    # * +template_id*+ - ID of the template to be used to build the virtual machine
-    # * +required_startup+ - Set to '1' to startup virtual machine after building
+    # Returns a Hash.
     def build(id, options = {})
-      params.required(:template_id).accepts(:required_startup).validate! options
       response = request(:post, "/virtual_machines/#{id}/build.json", default_params(options))
       response.first[1]
     end
 
-    # Edit a virtual machine
-    #
-    # ==== Params
+    # Public: Edit a virtual machine.
     #
-    # * +id*+ - ID of the virtual machine
-    # * +options+ - Params for creating the virtual machine
+    # id      - ID of the virtual machine
+    # options - Params for creating the virtual machine, see `#create`
     #
-    # ==== Options
-    #
-    # See #create
+    # Returns a Hash.
     def edit(id, options = {})
-      optional = [:label,
-                  :hypervisor_id,
-                  :hostname,
-                  :memory,
-                  :cpus,
-                  :cpu_shares,
-                  :primary_disk_size,
-                  :cpu_shares,
-                  :swap_disk_size,
-                  :primary_network_id,
-                  :required_automatic_backup,
-                  :rate_limit,
-                  :required_ip_address_assignment,
-                  :required_virtual_machine_build,
-                  :admin_note,
-                  :note,
-                  :allowed_hot_migrate,
-                  :template_id,
-                  :initial_root_password
-      ]
-      params.accepts(optional).validate! options
-      request(:put, "/virtual_machines/#{id}.json", default_params(options))
+      response = request(:put, "/virtual_machines/#{id}.json", default_params(options))
+      response['virtual_machine']
     end
 
-    # Change the owner of a virtual machine
+    # Public: Change the owner of a virtual machine.
     #
-    # ==== Params
+    # id      - ID of the virtual machine
+    # user_id - ID of the target User
     #
-    # * +id*+ - ID of the virtual machine
-    # * +user_id*+ - ID of the target User
+    # Returns a Hash.
     def change_owner(id, user_id)
-      response = request(:post, "/virtual_machines/#{id}/change_owner.json", :query => { :user_id => user_id })
+      response = request(:post, "/virtual_machines/#{id}/change_owner.json", query: { user_id: user_id })
       response['virtual_machine']
     end
 
-    # Change the password
+    # Public: Change the password.
     #
-    # ==== Params
+    # id       - ID of the virtual machine
+    # password - New password
     #
-    # * +id*+ - ID of the virtual machine
-    # * +password*+ - New password
+    # Returns a Hash.
     def change_password(id, password)
-      response = request(:post, "/virtual_machines/#{id}/reset_password.json", :query => { :new_password => password })
+      response = request(:post, "/virtual_machines/#{id}/reset_password.json", query: { new_password: password })
       response['virtual_machine']
     end
 
-    # Assigns SSH keys of all administrators and a owner to a virtual machine
+    # Public: Assigns SSH keys of all administrators and a owner to a virtual
+    # machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def set_ssh_keys(id)
       response = request(:post, "/virtual_machines/#{id}/set_ssh_keys.json")
       response['virtual_machine']
     end
 
-    # Migrate a virtual machine to a new hypervisor
-    #
-    # ==== Params
-    #
-    # * +id*+ - ID of the virtual machine
-    # * +options+ - :destination, :cold_migrate_on_rollback
+    # Public: Migrate a virtual machine to a new hypervisor.
     #
-    # ==== Options
+    # id      - ID of the virtual machine
+    # options - A Hash of options:
+    #           :destination              - ID of a hypervisor to which to
+    #                                       migrate the virtual machine
+    #           :cold_migrate_on_rollback - Set to '1' to switch to cold
+    #                                       migration if migration fails
     #
-    # * +destination*+ - ID of a hypervisor to which to migrate the virtual machine
-    # * +cold_migrate_on_rollback+ - Set to '1' to switch to cold migration if migration fails
+    # Returns a Hash.
     def migrate(id, options = {})
-      params.required(:destination).accepts(:cold_migrate_on_rollback).validate! options
-      response = request(:post, "/virtual_machines/#{id}/migrate.json", :query => {:virtual_machine => options} )
+      request(:post, "/virtual_machines/#{id}/migrate.json", query: { virtual_machine: options } )
     end
 
-    # Toggle the VIP status of the virtual machine
+    # Public: Toggle the VIP status of the virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def set_vip(id)
       response = request(:post, "/virtual_machines/#{id}/set_vip.json")
       response['virtual_machine']
     end
 
-    # Delete a virtual machine
+    # Public: Delete a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def delete(id)
       request(:delete, "/virtual_machines/#{id}.json")
     end
 
-    # Resize a virtual machine's memory
-    #
-    # ==== Params
-    #
-    # * +id*+ - ID of the virtual machine
-    # * +options+ - Options for resizing
-    #
-    # * ==== Options
-    #
-    # * +memory*+ - Amount of RAM assigned to this virtual machine
-    # * +cpus*+ - Number of CPUs assigned to the virtual machine
-    # * +cpu_shares*+ - CPU priority for this virtual machine
-    # * +allow_cold_resize*+ - Set to '1' to allow cold resize
+    # Public: Resize a virtual machine's memory.
+    #
+    # id      - ID of the virtual machine
+    # options - Options for resizing:
+    #           :memory            - Amount of RAM assigned to this virtual
+    #                                machine
+    #           :cpus              - Number of CPUs assigned to the virtual
+    #                                machine
+    #           :cpu_shares        - CPU priority for this virtual machine
+    #           :allow_cold_resize - Set to '1' to allow cold resize
+    #
+    # Returns a Hash.
     def resize(id, options = {})
-      raise ArgumentError, "You must specify at least one of the following attributes to resize: :memory, :cpus, :cpu_shares, :allow_cold_resize" if options.empty?
-      params.accepts(:memory, :cpus, :cpu_shares, :allow_cold_resize).validate! options
       response = request(:post, "/virtual_machines/#{id}/resize.json", default_params(options))
       response['virtual_machine']
     end
 
-    # Suspend/Unsuspend a virtual machine
+    # Public: Suspend/Unsuspend a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def suspend(id)
       response = request(:post, "/virtual_machines/#{id}/suspend.json")
       response['virtual_machine']
     end
 
-    # Unlock a virtual machine
+    # Public: Unlock a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def unlock(id)
       response = request(:post, "/virtual_machines/#{id}/unlock.json")
       response['virtual_machine']
     end
 
-    # Boot a virtual machine
+    # Public: Boot a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def startup(id)
       response = request(:post, "/virtual_machines/#{id}/startup.json")
       response['virtual_machine']
     end
 
-    # Shutdown a virtual machine
+    # Public: Shutdown a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def shutdown(id)
       response = request(:post, "/virtual_machines/#{id}/shutdown.json")
       response['virtual_machine']
     end
 
-    # Stop a virtual machine
+    # Public: Stop a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def stop(id)
       response = request(:post, "/virtual_machines/#{id}/stop.json")
       response['virtual_machine']
     end
 
-    # Reboot a virtual machine
+    # Public: Reboot a virtual machine
     #
-    # ==== Params
+    # id       - ID of the virtual machine
+    # recovery - Set to true to reboot in recovery, defaults to false
     #
-    # * +id*+ - ID of the virtual machine
-    # * +recovery+ - Set to true to reboot in recovery, defaults to false
+    # Returns a Hash.
     def reboot(id, recovery=false)
-      response = request(:post, "/virtual_machines/#{id}/reboot.json", {:query => recovery ? {:mode => :recovery} : nil})
+      response = request(:post, "/virtual_machines/#{id}/reboot.json", { query: recovery ? { mode: :recovery } : nil })
       response['virtual_machine']
     end
 
-    # Segregate a virtual machine from another virtual machine
+    # Public: Segregate a virtual machine from another virtual machine.
     #
-    # ==== Params
+    # id           - ID of the virtual machine
+    # target_vm_id - ID of another virtual machine from which it should be
+    #                segregated
     #
-    # * +id*+ - ID of the virtual machine
-    # * +target_vm_id+* - ID of another virtual machine from which it should be segregated
+    # Returns a Hash.
     def segregate(id, target_vm_id)
-      response = request(:post, "/virtual_machines/#{id}/strict_vm.json", default_params(:strict_virtual_machine_id => target_vm_id))
+      response = request(:post, "/virtual_machines/#{id}/strict_vm.json", default_params(strict_virtual_machine_id: target_vm_id))
       response['virtual_machine']
     end
 
-    # Open a console for a virtual machine
+    # Public: Open a console for a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def console(id)
       response = request(:post, "/virtual_machines/#{id}/console.json")
       response['virtual_machine']
     end
 
-    # Get billing statistics for a virtual machine
+    # Public: Get billing statistics for a virtual machine.
     #
-    # ==== Params
+    # id - ID of the virtual machine
     #
-    # * +id*+ - ID of the virtual machine
+    # Returns a Hash.
     def stats(id)
       response = request(:post, "/virtual_machines/#{id}/vm_stats.json")
       response['virtual_machine']

data/lib/squall/whitelist.rb

@@ -1,74 +1,63 @@
 module Squall
   # OnApp Whitelist
   class Whitelist < Base
-
-    # Return a list of all whitelists
+    # Public: Lists all whitelists.
     #
-    # ==== Params
+    # user_id - ID of the user to display whitelists for
     #
-    # * +user_id*+ - ID of the user to display whitelists for
+    # Returns an Array.
     def list(user_id)
       response = request(:get, "/users/#{user_id}/user_white_lists.json")
       response.collect { |user| user['user_white_list'] }
     end
 
-    # Get the details for a whitelist
+    # Public: Get the details for a whitelist.
     #
-    # ==== Params
+    # user_id - ID of the user
+    # id      - ID of the whitelist
     #
-    # * +user_id*+ - ID of the user
-    # * +id*+ - ID of the whitelist
+    # Returns a Hash.
     def show(user_id, id)
       response = request(:get, "/users/#{user_id}/user_white_lists/#{id}.json")
       response['user_white_list']
     end
 
-    # Create a whitelist for a user
-    #
-    # ==== Params
-    #
-    # * +user_id*+ - ID of the user
-    # * +options+ - Params for creating the whitelist
+    # Public: Create a whitelist for a user.
     #
-    # ==== Options
+    # user_id - ID of the user
+    # options - Params for creating the whitelist:
+    #           :ip          - IP to be whitelisted
+    #           :description - Description of the whitelist
     #
-    # * +ip*+ - IP to be whitelisted
-    # * +description+ - Description of the whitelist
+    # Example
     #
-    # ==== Example
+    #     create ip:          192.168.1.1,
+    #            description: "Computer that someone I trust uses"
     #
-    #   create :ip          => 192.168.1.1,
-    #          :description => "Computer that someone I trust uses"
-    def create(user_id, options={})
-      params.required(:ip).accepts(:description).validate!(options)
-      request(:post, "/users/#{user_id}/user_white_lists.json", :query => {:user_white_list => options})
+    # Returns a Hash.
+    def create(user_id, options = {})
+      request(:post, "/users/#{user_id}/user_white_lists.json", query: { user_white_list: options })
     end
 
-    # Edit a whitelist
+    # Public: Edit a whitelist.
     #
-    # ==== Params
+    # user_id - ID of the user
+    # id      - ID of whitelist
+    # options - Params for editing the whitelist, see `#create`
     #
-    # * +user_id*+ - ID of the user
-    # * +id*+ - ID of whitelist
-    # * +options+ - Params for editing the whitelist
-    #
-    # ==== Options
-    #
-    # See #create
-    def edit(user_id, id, options={})
-      params.accepts(:ip, :description).validate!(options)
-      request(:put, "/users/#{user_id}/user_white_lists/#{id}.json", :query => {:user_white_list => options})
+    # Returns a Hash.
+    def edit(user_id, id, options = {})
+      request(:put, "/users/#{user_id}/user_white_lists/#{id}.json", query: { user_white_list: options })
     end
 
-    # Delete a whitelist
+    # Public: Delete a whitelist.
     #
-    # ==== Params
+    # user_id - ID of the user
+    # id      - ID of whitelist
     #
-    # * +user_id*+ - ID of the user
-    # * +id*+ - ID of whitelist
+    # Returns a Hash.
     def delete(user_id, id)
       request(:delete, "/users/#{user_id}/user_white_lists/#{id}.json")
     end
-
   end
 end