fixes #1434 : How to use vcloud fog services

lib/fog/vcloud/examples/README.md

@@ -0,0 +1,54 @@
+# Using vCloud API via fog
+_contributor @singhgarima_
+
+For more information about fog [README](/README.md), or visit their website
+[fog.io](www.fog.io).
+
+## Vcloud API
+
+Some useful links to get started on the vCloud API:
+
+- [http://www.vmware.com/pdf/vcd_15_api_guide.pdf](http://www.vmware.com/pdf/vcd_15_api_guide.pdf)
+- [vCloud API Programming Guide](http://pubs.vmware.com/vcd-51/index.jsp?topic=%2Fcom.vmware.vcloud.api.doc_51%2FGUID-86CA32C2-3753-49B2-A471-1CE460109ADB.html)
+
+## Terminology
+
+- Organization: An Organization is the fundamental vCloud Director grouping
+  that contains users, the vApps that they create, and the resources the vApps
+  use. It is a top-level container in a cloud that contains one or more
+  Organization Virtual Data Centers (Org vDCs) and Catalog entities. It owns
+  all the virtual resources for a cloud instance and can have many Org vDCs.[1]
+
+- vApp: VMware vApp is a format for packaging and managing applications. A vApp
+  can contain multiple virtual machines.[2]
+
+- VM: A virtualized personal computer environment in which a guest
+  operating system and associated application software can run. Multiple virtual
+  machines can operate on the same managed host machine concurrently.[3]
+
+- Catalogs & Catalog-Items: Catalog is used in organizations for storing content.
+  Example: base images. Each item stored in catalog is referred as catalog item.
+
+- vDC: Virtual Data Center. These are of two kinds provider vDCs (accessible to
+  multiple organizations), and organization vDCs (accessible only by a given
+  organization). In fog we refer to organization vDCs.
+
+- Networks: You can setup various internal networks and assign various internal
+  ip ranges to them
+
+## What is the difference between a virtual appliance and a virtual machine?
+
+A  virtual machine is a tightly isolated software container created to run on
+virtualized platforms. It has four key virtualized resources (CPU, RAM,
+Storage, and Networking); but requires the installation of an Operating System
+and runs on one or more applications. A virtual appliance functions very much
+like a virtual machine, possessing the four key characteristics of
+compatibility, isolation, encapsulation, and hardware independence. However, a
+virtual appliance contains a pre-installed, pre-configured Operating System
+and an application stack optimized to provide a specific set of services.[3]
+
+**References**
+
+- [1] http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1026316
+- [2] http://www.vmware.com/pdf/vsphere4/r40/vsp_40_admin_guide.pdf
+- [3] http://www.vmware.com/technical-resources/virtualization-topics/virtual-appliances/faqs

lib/fog/vcloud/examples/creating_a_connection.md

@@ -0,0 +1,20 @@
+# Creating a connection
+
+      connection = Fog::Compute.new(
+        :provider           => :vcloud,
+        :vcloud_username    => "username@org-name",
+        :vcloud_password    => password,
+        :vcloud_host        => vendor-api-endpoint-host,
+        :vcloud_default_vdc => default_vdc_uri,
+        :connection_options => {
+          :ssl_verify_peer   => false,
+          :omit_default_port => true
+        }
+      )
+
+- Refer to links in [vcloud/examples/README.md](/lib/fog/vcloud/examples/REAME.md)
+  for find various different uris
+- connection_options are passed down to `excon`, which is used by fog to make
+  http requests.
+    - We using `omit_default_port`, as currently excon adds port to host entry
+      in headers, which might not be compatible with various vendors.

lib/fog/vcloud/examples/creating_a_vapp.md

@@ -0,0 +1,17 @@
+# Creating a vApp
+
+      connection.servers.create(
+        :vdc_uri            => vdc-uuid,
+        :catalog_item_uri   => catalog-uuid,
+        :name               => vApp-name,
+        :network_uri        => network-uri,
+        :network_name       => network-name,
+        :connection_options => {
+          :ssl_verify_peer   => false,
+          :omit_default_port => true
+        }
+      )
+
+- Not most of the uris can be found by understanding the vcloud api
+  eg various network information can be retrieved by
+  `connection.servers.service.networks`

lib/fog/vcloud/examples/get_network_information.md

@@ -0,0 +1,10 @@
+# Get network information
+
+- To see all networks list
+
+        connection.servers.service.networks
+
+- To see details of a particular network
+
+        selected_nw = connection.servers.service.networks.detect { |n| n.name == 'Default' }
+        connection.servers.service.get_network(selected_nw.href)

lib/fog/vcloud/examples/get_vapp_information.md

@@ -0,0 +1,10 @@
+# Get network information
+
+- To see all vApps list
+
+        connection.servers.service.vapps
+
+- To see details of a particular vApp
+
+        selected_vapp = connection.servers.service.vapps.detect { |n| n.name == 'vapp-name' }
+        connection.servers.service.get_vapp(selected_vapp.href)

lib/fog/vcloud/examples/more_on_vapps.md

@@ -0,0 +1,23 @@
+# More on vApps
+
+## Checking running or stopped
+
+    selected_vapp = connection.servers.service.vapps.detect { |n| n.name == 'vapp-name' }
+    selected_vapp.on?
+    selected_vapp.off?
+
+## Wait for app to come up or stop
+
+    selected_vapp.wait_for { selected_vapp.on? }
+    selected_vapp.wait_for { selected_vapp.off? }
+
+## Delete vApp
+
+    selected_vapp = connection.servers.service.vapps.detect { |n| n.name == 'vapp-name' }
+    vapp = connection.servers.service.get_vapp(selected_vapp.href)
+    if vapp.on?
+      vapp.service.undeploy selected_vapp.href #undeploy to stop vApp
+      vapp.wait_for { vapp.off? }
+    end
+    vapp.wait_for { vapp.off? } #double check
+    vapp.service.delete_vapp selected_vapp.href