fog 1.10.0 → 1.10.1

data/lib/fog/digitalocean/examples/getting_started.md

@@ -0,0 +1,106 @@
+# Getting started: the compute service
+
+You'll need a DigitalOcean account and API key to use this provider.
+
+Get one from http://www.digitalocean.com.
+
+To generate the API key, login to the DigitalOcean web panel and go to 
+'My Settings -> API Access -> Generate a new API key'.
+
+Write down the Client Key and API Key, you'll need both to use the service.
+
+
+## Connecting, retrieving and managing server objects
+
+Before we start, I guess it will be useful to the reader to know
+that Fog servers are 'droplets' in DigitalOcean's parlance. 
+'Server' is the Fog way to name VMs, and we have
+respected that in the DigitalOcean's Fog provider.
+
+First, create a connection to the host:
+
+```ruby
+require 'fog'
+
+do = Fog::Compute.new({
+  :provider => 'DigitalOcean',
+  :digitalocean_api_key   => 'poiuweoruwoeiuroiwuer', # your API key here
+  :digitalocean_client_id => 'lkjasoidfuoiu'          # your client key here
+})
+```
+
+## Listing servers
+
+Listing servers and attributes:
+
+```ruby
+docean.servers.each do |server|
+  # remember, servers are droplets
+  server.id
+  server.name
+  server.state
+  server.backups_enabled
+  server.image_id
+  server.flavor_id # server 'size' in DigitalOcean's API parlance
+  server.region_id
+end
+```
+
+## Server creation and life-cycle management
+
+Creating a new server (droplet):
+
+```ruby
+server = docean.servers.create :name => 'foobar',
+                               # use the first image listed
+                               :image_id  => docean.images.first.id,
+                               # use the first flavor listed
+                               :flavor_id => docean.flavors.first.id,
+                               # use the first region listed 
+                               :region_id => docean.regions.first.id
+```
+
+The server is automatically started after that.
+
+We didn't pay attention when choosing the flavor, image and region used
+but you can easily list them too, and then decide:
+
+```ruby
+docean.images.each do |image|
+  image.id
+  image.name
+  image.distribution
+end
+
+docean.flavors.each do |flavor|
+  flavor.id
+  flavor.name
+end
+
+docean.regions.each do |region|
+  region.id
+  region.name
+end
+
+```
+
+Rebooting a server:
+
+```ruby
+server = docean.servers.first
+server.reboot
+```
+
+Power cycle a server:
+
+```ruby
+server.power_cycle
+```
+
+Destroying the server:
+
+```ruby
+server.destroy
+```
+
+

data/lib/fog/digitalocean/models/compute/flavor.rb

@@ -0,0 +1,14 @@
+require 'fog/core/model'
+
+module Fog
+  module Compute
+    class DigitalOcean
+      class Flavor < Fog::Model
+        
+        identity  :id
+        attribute :name
+
+      end
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/flavors.rb

@@ -0,0 +1,25 @@
+require 'fog/core/collection'
+require 'fog/digitalocean/models/compute/flavor'
+
+module Fog
+  module Compute
+    class DigitalOcean
+
+      class Flavors < Fog::Collection
+        model Fog::Compute::DigitalOcean::Flavor
+
+        def all
+          load service.list_flavors.body['sizes']
+        end
+
+        def get(id)
+          all.find { |f| f.id == id }
+        rescue Fog::Errors::NotFound
+          nil
+        end
+
+      end
+
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/image.rb

@@ -0,0 +1,15 @@
+require 'fog/core/model'
+
+module Fog
+  module Compute
+    class DigitalOcean
+      class Image < Fog::Model
+        
+        identity  :id
+        attribute :name
+        attribute :distribution
+
+      end
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/images.rb

@@ -0,0 +1,25 @@
+require 'fog/core/collection'
+require 'fog/digitalocean/models/compute/image'
+
+module Fog
+  module Compute
+    class DigitalOcean
+
+      class Images < Fog::Collection
+        model Fog::Compute::DigitalOcean::Image
+
+        def all
+          load service.list_images.body['images']
+        end
+
+        def get(id)
+          all.find { |f| f.id == id }
+        rescue Fog::Errors::NotFound
+          nil
+        end
+
+      end
+
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/region.rb

@@ -0,0 +1,14 @@
+require 'fog/core/model'
+
+module Fog
+  module Compute
+    class DigitalOcean
+      class Region < Fog::Model
+        
+        identity  :id
+        attribute :name
+
+      end
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/regions.rb

@@ -0,0 +1,25 @@
+require 'fog/core/collection'
+require 'fog/digitalocean/models/compute/region'
+
+module Fog
+  module Compute
+    class DigitalOcean
+
+      class Regions < Fog::Collection
+        model Fog::Compute::DigitalOcean::Region
+
+        def all
+          load service.list_regions.body['regions']
+        end
+
+        def get(id)
+          all.find { |f| f.id == id }
+        rescue Fog::Errors::NotFound
+          nil
+        end
+
+      end
+
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/server.rb

@@ -0,0 +1,150 @@
+require 'fog/compute/models/server'
+
+module Fog
+  module Compute
+    class DigitalOcean
+
+      # A DigitalOcean Droplet
+      #
+      class Server < Fog::Compute::Server
+        
+        identity  :id
+        attribute :name
+       	attribute :state,	:aliases => 'status'
+        attribute :image_id
+        attribute :region_id
+        attribute :flavor_id,         :aliases => 'size_id'
+        # Not documented in their API, but
+        # available nevertheless
+        attribute :ip_address
+        attribute :backups_active
+
+        # Reboot the server (soft reboot).
+        #
+        # The preferred method of rebooting a server.
+        def reboot
+          requires :id
+          service.reboot_server self.id
+        end
+
+        # Reboot the server (hard reboot).
+        #
+        # Powers the server off and then powers it on again.
+        def power_cycle
+          requires :id
+          service.power_cycle_server self.id
+        end
+
+        # Shutdown the server
+        #
+        # Sends a shutdown signal to the operating system.
+        # The server consumes resources while powered off
+        # so you are still charged.
+        #
+        # @see https://www.digitalocean.com/community/questions/am-i-charged-while-my-droplet-is-in-a-powered-off-state
+        def shutdown
+          requires :id
+          service.shutdown_server self.id
+        end
+
+        # Power off the server
+        #
+        # Works as a power switch.
+        # The server consumes resources while powered off
+        # so you are still charged.
+        # 
+        # @see https://www.digitalocean.com/community/questions/am-i-charged-while-my-droplet-is-in-a-powered-off-state
+        def stop
+          requires :id
+          service.power_off_server self.id
+        end
+
+        # Power on the server.
+        #
+        # The server consumes resources while powered on
+        # so you will be charged.
+        #
+        # Each time a server is spun up, even if for a few seconds, 
+        # it is charged for an hour.
+        #
+        def start
+          requires :id
+          service.power_on_server self.id
+        end
+
+        # Creates the server (not to be called directly).
+        #
+        # Usually called by Fog::Collection#create
+        #
+        #   do = Fog::Compute.new({
+        #     :provider => 'DigitalOcean',
+        #     :digitalocean_api_key   => 'key-here',      # your API key here
+        #     :digitalocean_client_id => 'client-id-here' # your client key here
+        #   })
+        #   do.servers.create :name => 'foobar',
+        #                     :image_id  => image_id_here,
+        #                     :flavor_id => flavor_id_here,
+        #                     :region_id => region_id_here
+        # 
+        # @return [Boolean]
+        def save
+          raise Fog::Errors::Error.new('Resaving an existing object may create a duplicate') if persisted?
+          requires :name, :flavor_id, :image_id, :region_id
+
+          options = {}
+          if attributes[:ssh_key_ids]
+            options[:ssh_key_ids] = attributes[:ssh_key_ids] 
+          end
+          data = service.create_server name, 
+                                       flavor_id, 
+                                       image_id, 
+                                       region_id,
+                                       options
+          merge_attributes(data.body['droplet'])
+          true
+        end
+
+        # Destroy the server, freeing up the resources.
+        # 
+        # DigitalOcean will stop charging you for the resources
+        # the server was using.
+        #
+        # Once the server has been destroyed, there's no way
+        # to recover it so the data is irrecoverably lost.
+        #
+        # IMPORTANT: As of 2013/01/31, you should wait some time to
+        # destroy the server after creating it. If you try to destroy
+        # the server too fast, the destroy event may be lost and the
+        # server will remain running and consuming resources, so 
+        # DigitalOcean will keep charging you.
+        # Double checked this with DigitalOcean staff and confirmed 
+        # that it's the way it works right now.
+        #
+        # Double check the server has been destroyed!
+        def destroy
+          requires :id
+          service.destroy_server id
+        end
+
+        # Checks whether the server status is 'active'.
+        #
+        # The server transitions from 'new' to 'active' sixty to ninety
+        # seconds after creating it (time varies and may take more
+        # than 90 secs).
+        #
+        # @return [Boolean]
+        def ready?
+          state == 'active'
+        end
+
+        # DigitalOcean API does not support updating server state
+        def update
+          msg = 'DigitalOcean servers do not support updates'
+          raise NotImplementedError.new(msg)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/servers.rb

@@ -0,0 +1,27 @@
+require 'fog/core/collection'
+require 'fog/digitalocean/models/compute/server'
+
+module Fog
+  module Compute
+    class DigitalOcean
+
+      class Servers < Fog::Collection
+        model Fog::Compute::DigitalOcean::Server
+
+        def all(filters = {})
+          load service.list_servers.body['droplets']
+        end
+
+        def get(id)
+          if server = service.get_server_details(id).body['droplet']
+            new server
+          end
+        rescue Fog::Errors::NotFound
+          nil
+        end
+
+      end
+
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/ssh_key.rb

@@ -0,0 +1,28 @@
+module Fog
+  module Compute
+    class DigitalOcean 
+      class SshKey < Fog::Model
+
+        identity :id
+
+        attribute :name
+        attribute :ssh_pub_key
+
+        def save
+          requires :name, :ssh_pub_key
+
+          merge_attributes(service.create_ssh_key(name, ssh_pub_key).body['ssh_key'])
+          true
+        end
+
+        def destroy
+          requires :id
+
+          service.destroy_ssh_key id
+          true
+        end
+
+      end
+    end
+  end
+end

data/lib/fog/digitalocean/models/compute/ssh_keys.rb

@@ -0,0 +1,27 @@
+require 'fog/digitalocean/models/compute/ssh_key'
+
+module Fog
+  module Compute
+    class DigitalOcean 
+      class SshKeys < Fog::Collection
+
+        identity :href
+
+        model Fog::Compute::DigitalOcean::SshKey
+
+        def all
+          data = service.list_ssh_keys.body['ssh_keys']
+          load(data)
+        end
+
+        def get(uri)
+          if data = service.get_ssh_key(uri)
+            new(data.body)
+          end
+        rescue Fog::Errors::NotFound
+          nil
+        end
+      end
+    end
+  end
+end