fog-zj 0.1.28

data/docs/getting_started.md

@@ -0,0 +1,82 @@
+# Getting Started with Fog and OpenStack
+
+This document explains how to get started using Fog with [OpenStack](http://openstack.org)
+
+## Requirements
+
+### Ruby
+
+Fog officially supports Ruby 2.0.0, 1.9.3, 1.9.2, and 1.8.7 (also known as Matz Ruby Interpreter or MRI). While not officially supported, fog has been known to work with Rubinus and JRuby.
+
+Ruby 2.0.0 is suggested for new projects. For information on installing Ruby please refer to the [Ruby download page](http://www.ruby-lang.org/en/downloads/).
+
+### RubyGems
+
+RubyGems is required to access the Fog gem. For information on installing RubyGems, please refer to [RubyGems download page](http://rubygems.org/pages/download).
+
+### Bundler (optional)
+
+Bundler helps manage gem dependencies and is recommended for new projects. For more information about bundler, please refer to the [bundler documentation](http://gembundler.com/).
+
+## Installation
+
+To install Fog-Openstack via RubyGems run the following command:
+
+    $ gem install fog-openstack
+
+To install Fog via Bundler add `gem 'fog'` to your `Gemfile`. This is a sample `Gemfile` to install Fog:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'fog-openstack'
+```
+
+After creating your `Gemfile` execute the following command to install the libraries:
+
+	bundle install
+
+## Next Steps
+
+Now that you have installed Fog and obtained your credentials, you are ready to begin exploring the capabilities of the Rackspace Open Cloud and Fog using `irb`.
+
+Start by executing the following command:
+
+	irb
+
+Once `irb` has launched you will need to require the Fog library.
+
+If using Ruby 1.8.x execute the following command:
+
+```ruby
+require 'rubygems'
+require 'fog/openstack'
+```
+
+If using Ruby 1.9.x execute the following command:
+
+```ruby
+require 'fog/openstack'
+```
+
+You should now be able to execute the following command to see a list of services Fog provides for the Rackspace Open Cloud:
+
+```ruby
+Fog::OpenStack.services
+```
+
+These services can be explored in further depth in the following documents:
+
+* [Compute](compute.md)
+* [Introspection](introspection.md)
+* [Metering](metering.md)
+* [Network](network.md)
+* [NFV](nfv.md)
+* [Orchestration](orchestration.md)
+* [Planning](planning.md)
+* [Shared File System](shared_file_system.md)
+* [Storage (Swift)](storage.md)
+* [Workflow](workflow.md)
+
+## Additional Resources
+[resources and feedback](common/resources.md)

data/docs/introspection.md

@@ -0,0 +1,251 @@
+# Introspection
+
+This document explains how to get started using introspection with
+fog-openstack.
+
+Please also refer to the
+[Getting Started with Fog and the OpenStack](getting_started.md) document.
+
+Introspection service is implemented by the OpenStack ironic-inspector project.
+Introspection is strongly related to the Baremetal service (Ironic project).
+Effectively, Instrospection communicates and operates on nodes defined by the
+Baremetal layer (Ironic).
+
+# OpenStack setup
+
+## The catalog
+For the fog-openstack's introspection service to work, the corresponding
+service must be defined in the OpenStack catalog.
+
+```bash
+openstack catalog show inspector
++-----------+-----------------------------------------+
+| Field     | Value                                   |
++-----------+-----------------------------------------+
+| endpoints | regionOne                               |
+|           |   publicURL: http://192.0.2.1:5050/v1   |
+|           |   internalURL: http://192.0.2.1:5050/v1 |
+|           |   adminURL: http://192.0.2.1:5050/v1    |
+|           |                                         |
+| name      | inspector                               |
+| type      | introspection                           |
++-----------+-----------------------------------------+
+```
+
+Depending on the OpenStack release, the introspection service might be installed
+but not defined yet in the catalog. In such case, you must add the service and
+corresponding endpoints to create the catalog entry:
+
+```bash
+source ./stackrc
+openstack service create --name inspector --description "OpenStack Introspection" introspection
+openstack endpoint create --region regionOne inspector --publicurl http://example.com:5050/v1 --internalurl http://example.com:5050/v1 --adminurl http://example.com:5050/v1
+```
+
+## The introspection timeout
+The default timeout value after which introspection is considered failed is set
+by an 1 hour (3600 s) default. Although in production environment, baremetal
+introspection requires time, testing in virtual environment doesn't, this is why
+if you are in the latter case the timeout value can be reduced for speeding
+results:
+
+```bash
+sudo openstack-config --set /etc/ironic-inspector/inspector.conf DEFAULT timeout 300
+```
+
+# Work flow
+Assuming Baremetal nodes have been defined (imported), a usual work-flow might
+consist of:
+* Start introspection
+* Check introspection status or abort introspection
+* Retrieve introspection data
+* optionally, pre-defined DSL based rules can be defined and applied during
+  introspection.
+
+For more details about this process please refer to
+http://docs.openstack.org/developer/ironic-inspector/workflow.html
+
+
+Using 'irb', we start with authentication:
+
+```ruby
+@user     = "admin"
+@project  = "admin"
+@password = "secret"
+@base_url = "http://keystone.example.com:5000/v3/auth/tokens"
+
+require 'rubygems'
+require 'fog/openstack'
+
+@connection_params = {
+  :openstack_auth_url     => @base_url,
+  :openstack_username     => @user,
+  :openstack_api_key      => @password,
+  :openstack_project_name => @project,
+  :openstack_domain_id    => "default"
+}
+```
+## Baremetal node introspection
+
+### Baremetal nodes
+
+Find the available Baremetal nodes.
+
+```ruby
+iron = Fog::Baremetal::OpenStack.new(@connection_params)
+
+nodes = iron.node_list
+```
+
+### Start introspection
+
+Let's start introspection using the first available node.
+
+Note: To be introspected, a node must be in "manage" state. If needed, use Baremetal Service
+to change the state with set_node_provision_state.
+
+For more information, please refer to
+http://docs.openstack.org/developer/ironic/deploy/install-guide.html#hardware-inspection
+
+```ruby
+node_id = nodes.body["nodes"][0]["uuid"]
+inspector = Fog::Introspection::OpenStack.new(@connection_params)
+
+introspection1 = inspector.create_introspection(node_id)
+```
+If everything went well the status returned by the request must be 202 which
+means accepted:
+```ruby
+introspection1.status
+=> 202
+```
+
+### Check introspection status
+
+To check the status of the introspection:
+```ruby
+inspector.get_introspection(node_id)
+```
+
+The body returned has 2 fields:
+* finished: A boolean, set to true if introspection process is finished
+* error: A null string unless an error occurred or the process was canceled by
+  the operator (in case introspection was aborted)
+
+### Abort an ongoing introspection
+
+To abort a node introspection:
+```ruby
+inspector.abort_introspection(node_id)
+```
+
+### Retrieve introspected data
+
+```ruby
+inspector.get_introspection_details(node_id)
+```
+The response body will provide a *very* long list of information about the node.
+
+## DSL rules
+
+### Create rules
+
+```ruby
+rule_set1 = {
+  "description" => "Successful Rule",
+  "actions"     => [
+    {
+      "action" => "set-attribute",
+      "path"   => "/extra/rule_success",
+      "value"  => "yes"
+    }
+  ],
+  "conditions"  => [
+    {
+      "field" => "memory_mb",
+      "op"    => "ge",
+      "value" => 256
+    },
+    {
+      "field" => "local_gb",
+      "op"    => "ge",
+      "value" => 1
+    }
+  ]
+}
+
+rule_set2 = {
+  "description" => "Failing Rule",
+  "actions"     => [
+    {
+      "action" => "set-attribute",
+      "path"   => "/extra/rule_success",
+      "value"  => "no"
+    },
+    {
+      "action"  => "fail",
+      "message" => "This rule should not have run"
+    }
+  ],
+  "conditions"  => [
+    {
+      "field" => "memory_mb",
+      "op"    => "lt",
+      "value" => 42
+    },
+    {
+      "field" => "local_gb",
+      "op"    => "eq",
+      "value" => 0
+    }
+  ],
+}
+
+inspector.create_rules(rule_set1)
+inspector.create_rules(rule_set2)
+```
+
+### List all rules
+
+```ruby
+inspector.list_rules.body
+=> {"rules"=>
+  [{"description"=>"Successful Rule",
+    "links"=>[{"href"=>"/v1/rules/4bf1bf40-d30f-4f31-a970-f0290d7e751b", "rel"=>"self"}],
+    "uuid"=>"4bf1bf40-d30f-4f31-a970-f0290d7e751b"},
+   {"description"=>"Failing Rule",
+    "links"=>[{"href"=>"/v1/rules/0d6e6687-3f69-4c14-8cab-ea6ada78036f", "rel"=>"self"}],
+    "uuid"=>"0d6e6687-3f69-4c14-8cab-ea6ada78036f"}]}
+```
+
+### Show rules details
+
+```ruby
+inspector.get_rules('0d6e6687-3f69-4c14-8cab-ea6ada78036f').body
+=> {"actions"=>
+  [{"action"=>"set-attribute", "path"=>"/extra/rule_success", "value"=>"no"},
+   {"action"=>"fail", "message"=>"This rule should not have run"}],
+ "conditions"=>[{"field"=>"memory_mb", "op"=>"lt", "value"=>42}, {"field"=>"local_gb", "op"=>"eq", "value"=>0}],
+ "description"=>"Failing Rule",
+ "links"=>[{"href"=>"/v1/rules/0d6e6687-3f69-4c14-8cab-ea6ada78036f", "rel"=>"self"}],
+ "uuid"=>"0d6e6687-3f69-4c14-8cab-ea6ada78036f"}
+```
+
+### Delete a specific rules set
+
+```ruby
+inspector.delete_rules'0d6e6687-3f69-4c14-8cab-ea6ada78036f')
+inspector.list_rules.body
+=> {"rules"=>
+  [{"description"=>"Successful Rule",
+    "links"=>[{"href"=>"/v1/rules/4bf1bf40-d30f-4f31-a970-f0290d7e751b", "rel"=>"self"}],
+    "uuid"=>"4bf1bf40-d30f-4f31-a970-f0290d7e751b"}]}
+```
+
+### Destroys all rules
+
+```ruby
+inspector.delete_rules_all
+inspector.list_rules.body
+=> {"rules"=>[]}
+```

data/docs/metering.md

@@ -0,0 +1,43 @@
+# OpenStack Metering (Ceilometer)
+
+This document explains how to get started using OpenStack Metering (Ceilometer) with Fog. It assumes you have read the [Getting Started with Fog and the OpenStack](getting_started.md) document.
+
+Fog uses the [OpenStack Metering API](http://docs.openstack.org/developer/ceilometer/webapi/v2.html).
+
+## Metering Service
+
+Get a handle on the Metering service:
+
+```ruby
+service = Fog::Metering::OpenStack.new({
+  :openstack_auth_url  => 'http://KEYSTONE_HOST:KEYSTONE_PORT/v2.0/tokens', # OpenStack Keystone endpoint
+  :openstack_username  => OPEN_STACK_USER,                                  # Your OpenStack Username
+  :openstack_tenant    => OPEN_STACK_TENANT,                                # Your tenant id
+  :openstack_api_key   => OPEN_STACK_PASSWORD,                              # Your OpenStack Password
+  :connection_options  => {}                                                # Optional
+})
+```
+
+## Events
+
+* `service.events([<query_filter>])`: Return a list of events.
+* `service.events.find_by_id(<message_id>)`: Return the event matching message_id, or nil if no such event exists.
+
+### Filter events example
+
+Return events newer than 2016-03-17T09:59:44.606000.
+
+```ruby
+query_filter = [{
+  'field' => 'start_timestamp',
+  'op'    => 'gt',
+  'value' => '2016-03-17T09:59:44.606000'
+}]
+
+service.events(query_filter)
+```
+
+## Resources
+
+* `service.resources`: Return a list of resources.
+* `service.resources.find_by_id(<resource_id>)`: Return the resource matching resource_id, or nil if no such resource exists.

data/docs/network.md

@@ -0,0 +1,238 @@
+# Network (Neutron)
+
+This document explains how to get started using OpenStack Network (Neutron) with Fog. It assumes you have read the [Getting Started with Fog and OpenStack](getting_started.md) document.
+
+## Starting irb console
+
+Start by executing the following command:
+```
+irb
+```
+Once `irb` has launched you need to require the Fog library by executing:
+```
+require 'fog/openstack'
+```
+## Create Service
+
+Next, create a connection to the Network Service:
+```
+service = Fog::Network::OpenStack.new(
+	:openstack_auth_url     => 'http://KEYSTONE_HOST:KEYSTONE_PORT/v3/auth/tokens', # OpenStack Keystone v3 endpoint
+	:openstack_username     => OPEN_STACK_USER,                                     # Your OpenStack Username
+	:openstack_domain_name  => OPEN_STACK_DOMAIN,                                   # Your OpenStack Domain name
+	:openstack_project_name => OPEN_STACK_PROJECT,                                  # Your OpenStack Project name
+	:openstack_api_key      => OPEN_STACK_PASSWORD,                                 # Your OpenStack Password
+	:connection_options     => {}                                                   # Optional
+)
+```
+
+Read more about the [Optional Connection Parameters](common/connection_params.md)
+
+## Fog Abstractions
+
+Fog provides both a **model** and **request** abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient `ActiveModel` like interface.
+
+### Request Layer
+
+The request abstraction maps directly to the [OpenStack Network API](http://developer.openstack.org/api-ref-networking-v2.html). It provides the most efficient interface to the OpenStack Network service.
+
+To see a list of requests supported by the service:
+```
+service.requests
+```
+
+This returns:
+```
+:list_networks, :create_network, :delete_network, :get_network, :update_network,
+:list_ports, :create_port, :delete_port, :get_port, :update_port,
+:list_subnets, :create_subnet, :delete_subnet, :get_subnet, :update_subnet,
+:list_floating_ips, :create_floating_ip, :delete_floating_ip, :get_floating_ip, :associate_floating_ip, :disassociate_floating_ip,
+:list_routers, :create_router, :delete_router, :get_router, :update_router, :add_router_interface, :remove_router_interface,
+:list_lb_pools, :create_lb_pool, :delete_lb_pool, :get_lb_pool, :get_lb_pool_stats, :update_lb_pool,
+:list_lb_members, :create_lb_member, :delete_lb_member, :get_lb_member, :update_lb_member,
+:list_lb_health_monitors, :create_lb_health_monitor, :delete_lb_health_monitor, :get_lb_health_monitor, :update_lb_health_monitor, :associate_lb_health_monitor, :disassociate_lb_health_monitor,
+:list_lb_vips, :create_lb_vip, :delete_lb_vip, :get_lb_vip, :update_lb_vip,
+:list_vpn_services, :create_vpn_service, :delete_vpn_service, :get_vpn_service, :update_vpn_service,
+:list_ike_policies, :create_ike_policy, :delete_ike_policy, :get_ike_policy, :update_ike_policy,
+:list_ipsec_policies, :create_ipsec_policy, :delete_ipsec_policy, :get_ipsec_policy, :update_ipsec_policy,
+:list_ipsec_site_connections, :create_ipsec_site_connection, :delete_ipsec_site_connection, :get_ipsec_site_connection, :update_ipsec_site_connection,
+:list_rbac_policies, :create_rbac_policy, :delete_rbac_policy, :get_rbac_policy, :update_rbac_policy,
+:create_security_group, :delete_security_group, :get_security_group, :list_security_groups,
+:create_security_group_rule, :delete_security_group_rule, :get_security_group_rule, :list_security_group_rules,
+:set_tenant, :get_quotas, :get_quota, :update_quota, :delete_quota
+```
+
+#### Example Request
+
+To request a list of networks:
+```
+response = service.list_networks
+```
+This returns in the following `Excon::Response`:
+```
+#<Excon::Response:0x007fd20d34e0e0
+  @data={
+    :body=>{"networks"=>[
+      {"id"=>"f9c54735-a230-443e-9379-b87f741cc1b1", "name"=>"Public", "subnets"=>["db50da7f-1248-43d2-aa30-1c10da0d380d"], "shared"=>true, "status"=>"ACTIVE", "tenant_id"=>"a51fd915", "provider_network_type"=>"vlan", "router:external"=>false, "admin_state_up"=>true},
+      {"id"=>"e624a36d-762b-481f-9b50-4154ceb78bbb", "name"=>"network_1", "subnets"=>["2e4ec6a4-0150-47f5-8523-e899ac03026e"], "shared"=>false, "status"=>"ACTIVE", "admin_state_up"=>true, "tenant_id"=>"f8b26a6032bc47718a7702233ac708b9"}]},
+    :status=>200,
+    :headers=>{}},
+  @body={"networks"=>[
+    {"id"=>"f9c54735-a230-443e-9379-b87f741cc1b1", "name"=>"Public", "subnets"=>["db50da7f-1248-43d2-aa30-1c10da0d380d"], "shared"=>true, "status"=>"ACTIVE", "tenant_id"=>"a51fd915", "provider_network_type"=>"vlan", "router:external"=>false, "admin_state_up"=>true},
+    {"id"=>"e624a36d-762b-481f-9b50-4154ceb78bbb", "name"=>"network_1", "subnets"=>["2e4ec6a4-0150-47f5-8523-e899ac03026e"], "shared"=>false, "status"=>"ACTIVE", "admin_state_up"=>true, "tenant_id"=>"f8b26a6032bc47718a7702233ac708b9"}]},
+  @headers={},
+  @status=200,
+  @remote_ip=nil,
+  @local_port=nil,
+  @local_address=nil
+>
+```
+To view the status of the response:
+```
+response.status
+```
+**Note**: Fog is aware of valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.
+
+To view response body:
+```
+response.body
+```
+This will return:
+```
+{"networks"=>[
+  {"id"=>"f9c54735-a230-443e-9379-b87f741cc1b1", "name"=>"Public", "subnets"=>["db50da7f-1248-43d2-aa30-1c10da0d380d"], "shared"=>true, "status"=>"ACTIVE", "tenant_id"=>"a51fd915", "provider_network_type"=>"vlan", "router:external"=>false, "admin_state_up"=>true},
+  {"id"=>"e624a36d-762b-481f-9b50-4154ceb78bbb", "name"=>"network_1", "subnets"=>["2e4ec6a4-0150-47f5-8523-e899ac03026e"], "shared"=>false, "status"=>"ACTIVE", "admin_state_up"=>true, "tenant_id"=>"f8b26a6032bc47718a7702233ac708b9"}]
+}
+```
+To learn more about Network request methods refer to [rdoc](http://www.rubydoc.info/gems/fog-openstack/Fog/Network/OpenStack/Real). To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon).
+
+### Model Layer
+
+Fog models behave in a manner similar to `ActiveModel`. Models will generally respond to `create`, `save`,  `persisted?`, `destroy`, `reload` and `attributes` methods. Additionally, fog will automatically create attribute accessors.
+
+Here is a summary of common model methods:
+
+<table>
+	<tr>
+		<th>Method</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td>create</td>
+		<td>
+			Accepts hash of attributes and creates object.<br>
+			Note: creation is a non-blocking call and you will be required to wait for a valid state before using resulting object.
+		</td>
+	</tr>
+	<tr>
+		<td>save</td>
+		<td>Saves object.<br>
+		Note: not all objects support updating object.</td>
+	</tr>
+	<tr>
+		<td>persisted?</td>
+		<td>Returns true if the object has been persisted.</td>
+	</tr>
+	<tr>
+		<td>destroy</td>
+		<td>
+			Destroys object.<br>
+			Note: this is a non-blocking call and object deletion might not be instantaneous.
+		</td>
+	<tr>
+		<td>reload</td>
+		<td>Updates object with latest state from service.</td>
+	<tr>
+		<td>ready?</td>
+		<td>Returns true if object is in a ready state and able to perform actions. This method will raise an exception if object is in an error state.</td>
+	</tr>
+	<tr>
+		<td>attributes</td>
+		<td>Returns a hash containing the list of model attributes and values.</td>
+	</tr>
+		<td>identity</td>
+		<td>
+			Returns the identity of the object.<br>
+			Note: This might not always be equal to object.id.
+		</td>
+	</tr>
+	<tr>
+		<td>wait_for</td>
+		<td>This method periodically reloads model and then yields to specified block until block returns true or a timeout occurs.</td>
+	</tr>
+</table>
+
+To see a list of collections supported by the service:
+```
+service.collections
+```
+This returns:
+```
+:networks, :ports, :subnets, :floating_ips, :routers,
+:lb_pools, :lb_members, :lb_health_monitors, :lb_vips,
+:vpn_services, :ike_policies, :ipsec_policies, :ipsec_site_connections,
+:rbac_policies, :security_groups, :security_group_rules
+```
+
+#### Example Request
+
+To request a collection of networks:
+```
+networks = service.networks
+```
+This returns in the following `Fog::OpenStack::Model`:
+```
+<Fog::Network::OpenStack::Networks
+  filters={}
+  [<Fog::Network::OpenStack::Network
+      id="f9c54735-a230-443e-9379-b87f741cc1b1",
+      name="Public",
+      subnets=        <Fog::Network::OpenStack::Subnets
+        filters={}
+        [<Fog::Network::OpenStack::Subnet ... >]
+      >,
+      shared=true,
+      status="ACTIVE",
+      admin_state_up=true,
+      tenant_id="a51fd915",
+      provider_network_type="vlan",
+      provider_physical_network=nil,
+      provider_segmentation_id=nil,
+      router_external=false
+    >,
+                <Fog::Network::OpenStack::Network
+      id="e624a36d-762b-481f-9b50-4154ceb78bbb",
+      name="network_1",
+      subnets=        <Fog::Network::OpenStack::Subnets
+        filters={}
+        []
+      >,
+      shared=false,
+      status="ACTIVE",
+      admin_state_up=true,
+      tenant_id="f8b26a6032bc47718a7702233ac708b9",
+      provider_network_type=nil,
+      provider_physical_network=nil,
+      provider_segmentation_id=nil,
+      router_external=nil
+    >
+  ]
+>
+```
+
+To access the name of the first network:
+```
+networks.first.name
+```
+This will return:
+```
+"Public"
+```
+## Examples
+
+Example code using Network can be found [here](https://github.com/fog/fog-openstack/tree/master/lib/fog/openstack/examples/network).
+
+## Additional Resources
+
+* [OpenStack Network API](http://developer.openstack.org/api-ref-networking-v2.html)
+* [more resources and feedback](common/resources.md)