docs/planning.md
# Planning
This document explains how to get started using OpenStack Tuskar with Fog.
## Starting irb console
Start by executing the following command:
```bash
irb
```
Once `irb` has launched you need to require the Fog library.
If using Ruby 1.8.x execute:
```ruby
require 'rubygems'
require 'fog/openstack'
```
If using Ruby 1.9.x execute:
```ruby
require 'fog/openstack'
```
## Create Service
Next, create a connection to Tuskar:
```ruby
service = Fog::OpenStack.new({
:service => :planning, # OpenStack Fog service
:openstack_username => USERNAME, # Your OpenStack Username
:openstack_api_key => PASSWORD, # Your OpenStack Password
:openstack_auth_url => 'http://YOUR_OPENSTACK_ENDPOINT:PORT/v2.0/tokens'
: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 `Fog::OpenStack::Planning.new` object supports a number of methods that wrap individual HTTP requests to the Tuskar API.
To see a list of requests supported by the planning service:
```ruby
service.requests
```
This returns:
```ruby
[
:list_roles,
:list_plans,
:get_plan_templates,
:get_plan,
:patch_plan,
:create_plan,
:delete_plan,
:add_role_to_plan,
:remove_role_from_plan
]
```
#### Example Request
To request a list of plans:
```ruby
response = service.list_plans
```
This returns in the following `Excon::Response`:
```ruby
#<Excon::Response:0x007f141e045ab8
@data=
{
:body=>
[
{
"created_at"=>"2014-09-26T20:23:14.222815",
"description"=>"Development testing cloud",
"name"=>"dev-cloud",
"parameters"=>
[
{
"default"=>"guest",
"description"=>"The password for RabbitMQ",
"hidden"=>true,
"label"=>nil,
"name"=>"compute-1 => =>RabbitPassword",
"value"=>"secret-password"
},
{
"default"=>"default",
"description"=>"description",
"hidden"=>true,
"label"=>nil,
"name"=>"name",
"value"=>"value"
}
],
"roles"=>
[
{
"description"=>"OpenStack hypervisor node. Can be wrapped in a ResourceGroup for scaling.\n",
"name"=>"compute",
"uuid"=>"b7b1583c-5c80-481f-a25b-708ed4a39734",
"version"=>1
}
],
"updated_at"=>nil,
"uuid"=>"53268a27-afc8-4b21-839f-90227dd7a001"
}
],
:headers=>{},
:status=>200
},
@body="",
@headers={},
@status=nil,
@remote_ip=nil,
@local_port=nil,
@local_address=nil
>
```
To view the status of the response:
```ruby
response.status
```
**Note**: Fog is aware of the valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.
To view response headers:
```ruby
response.headers
```
This will return hash similar to:
```ruby
{
"X-Account-Bytes-Used"=>"2563554",
"Date"=>"Thu, 21 Feb 2013 21:57:02 GMT",
"X-Account-Meta-Temp-Url-Key"=>"super_secret_key",
"X-Timestamp"=>"1354552916.82056",
"Content-Length"=>"0",
"Content-Type"=>"application/json; charset=utf-8",
"X-Trans-Id"=>"txe934924374a744c8a6c40dd8f29ab94a",
"Accept-Ranges"=>"bytes",
"X-Account-Container-Count"=>"7",
"X-Account-Object-Count"=>"5"
}
```
[//]: # (TODO: Specify URL to rubydoc.info when OpenStack Planning service is part of release and pages are built)
To learn more about `Fog::OpenStack::Planning.new` request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog). 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`, `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>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>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>
</table>
The remainder of this document details the model abstraction.
## Additional Resources
* [Tuskar API](http://docs.openstack.org/developer/tuskar/)
* [more resources and feedback](common/resources.md)