Introduction
Misty is a HTTP client for OpenStack APIs, aiming to be fast and to provide a flexible and at same time exhaustive APIs experience.
Features
- Exhaustive and latest Openstack APIs
- Multiple Service versions
- Microversions
- Based upon Net/HTTP
- Minimalistic gem dependencies - Only json is required
- Dynamic services by autoloading only required service's version
- Token automatically refreshed when expired
- Raw JSON or Ruby format for queries and responses
- Persistent HTTP connections (default since HTTP 1.1 anyway) but for the authentication bootstrapping
- Direct HTTP Methods for custom needs
A solid KISS
For REST transactions, Misty uses only Net/HTTP from the Ruby Standard Library. So besides 'json', no other gem are
required.
Because OpenStack authentication and Service Catalog management are very specific and shared by all the APIs, once taken
care of, there is no need for a complex HTTP framework.
This offers a solid foundation with reduced dependencies.
APIs Definitions
The rich variety of OpenStack projects requires lots of Application Program Interfaces to handle.
Maintaining and extending those APIs is a structural complexity challenge.
Therefore the more automated the process, the better.
Thanks to the help of Phoenix project, the OpenStack API-ref [1] provides standardization of the OpenStack APIs.
The APIs can be processed almost automatically from the API-ref reference manuals (misty-builder).
This allows:
- More consistent APIs using automated control
- More recent APIs definitions
- Easier to add APIs
[1] https://developer.openstack.org/api-guide/quick-start/
Install & Use
Fetch and install
gem install misty
Quick start
require 'misty'
auth_v3 = {
:url => "http://localhost:5000",
:user => "admin",
:password => "secret",
:project => "admin",
:domain => "default"
}
openstack = Misty::Cloud.new(:auth => auth_v3)
puts openstack.compute.list_servers.body
puts openstack.compute.list_flavors.body
networks = openstack.network.list_networks
network_id = networks.body["networks"][0]['id']
network = openstack.network.show_network_details(network_id)
puts network.body
Services
Once the Misty::Cloud object is created, the Openstack services can be used.
The Cloud object authenticates against the identity server (bootstrap process) and obtains the service catalog. When an OpenStack API service is used, its endpoint is determined from the catalog and the service is dynamically called by Misty so only the services used are loaded.
The service generic name, such as compute
, is used to submit requests with an OpenStack service API.
openstack = Misty::Cloud.new(:auth => { ... })
openstack.compute.list_servers
openstack.network.list_networks
openstack.network.create_network("network": {"name": "my-network"})
To obtain the list of supported services:
require 'misty'
puts Misty.services
Which produces the equivalent of the following:
name | project | versions |
---|---|---|
alarming | aodh | ["v2"] |
baremetal | ironic | ["v1"] |
block_storage | cinder | ["v3", "v1"] |
clustering | senlin | ["v1"] |
compute | nova | ["v2.1"] |
container | magnum | ["v1"] |
data_processing | sahara | ["v1.1"] |
data_protection | karbor | ["v1"] |
database | trove | ["v1.0"] |
dns | designate | ["v2"] |
identity | keystone | ["v3", "v2.0"] |
image | glance | ["v2", "v1"] |
messaging | zaqar | ["v2"] |
metering | ceilometer | ["v2"] |
network | neutron | ["v2.0"] |
object_storage | swift | ["v1"] |
orchestration | heat | ["v1"] |
search | searchlight | ["v1"] |
shared_file_systems | manila | ["v2"] |
- Notes
When an Openstack service requires a different service name, the :service_names option can be used (see below).
The #requests method provides the available requests for a service, for example:
openstack.compute.requests
Setup
Authentication information parameter
The URL and credentials details are necessary to authenticate with the identity server (Keystone).
The credentials are a combination of "id" and "name" used to uniquely identify projects, users and their domains. When using only the name, a domain must be specified to guarantee a unique record from the Identity service.
The following parameters can be used:
:domain_id
Domain id used for authentication scope
Default:"default"
:domain
Domain name used for authentication scope
Default:"Default"
:project_id
Project id:project
Project name:project_domain_id
Project domain id:project_domain
Project domain name:tenant_id
Tenant id, used only for Keystone v2.0:tenant
Tenant name, used only for Keystone v2.0:user_id
User id:user
User name:user_domain_id
User domain id:user_domain
User domain name
Keystone v3
Keystone v3 is default recommended version:
auth = {
:url => "http://localhost:5000",
:user => "admin",
:user_domain => "default",
:password => "secret",
:project => "admin",
:project_domain => "default"
}
}
Alternatively, using IDs:
auth = {
:url => "http://localhost:5000",
:user_id => "48985e6b8da145699d411f12a3459fca",
:password => "secret",
:project_id => "8e1e232f6cbb4116bbef715d8a0afe6e",
}
}
Keystone v2.0
Provide the tenant details, Misty will detect it's using v2.0 for authentication:
auth = {
:url => "http://localhost:5000",
:user => "admin",
:password => "secret",
:tenant => "admin",
}
Logging parameters
- :log_file
File name and path for log file.
Value is file path or IO object - Default is./misty.log
.
For example: use STDOUT for terminal output or alternatively use '/dev/null' to avoid the logs entirely. - :log_level
Value is Fixnum - Default is 1 (Logger::INFO) - See Logger from Ruby standard Library
openstack = Misty::Cloud.new(:auth => auth, :content_type => :ruby, :log_file => STDOUT)
Global parameters
The following options are applied to each service unless specifically provided for a service.
- :region_id
Type: String
Default: "regionOne" - :interface
Type: String
Allowed values: "public", "internal", "admin"
Default: "public" - :ssl_verify_mode
When using SSL mode (defined by URI scheme => "https://")
Type: Boolean
Default:true
- :content_type
Format of the body of the successful HTTP responses to be JSON or Ruby structures.
Type: Symbol
Allowed values::json
,:ruby
Default::ruby
Services Options
Each service can get parameters to be specified.
openstack = Misty::Cloud.new(:auth => auth, :identity => {}, :compute => {})
The following options are available:
- :api_version
Type: String
Default: The latest supported version - See Misty.services for other versions. - :base_path
Allows to force the base path for every URL requests.
Type: String - :base_url
Allows to force the base URL for every requests.
Type: String - :interface
Allows to provide an alternate interface. Allowed values are "public", "internal" or "admin"
Type: String
Default: Determined from global value - :region_id
Type: String
Default: Determined from global value - :service_names
Allows to use a difference name for the service. For instance "identity3" for the identity service.
Type: String
Default: Determined from Misty.services - :ssl_verify_mode
Type: Boolean
Default: Determined from global value - :version
Version to be used when microversion is supported by the service.
Type: String
Allowed values: "CURRENT", "LATEST", "SUPPORTED", or a version number such as "2.0" or "3"
Default:"CURRENT"
Example:
openstack = Misty::Cloud.new(:auth => auth, :log_level => 0, :identity => {:region_id => "regionTwo"}, :compute => {:version => "2.27", :interface => "admin"})
Direct REST HTTP Methods
To send requests directly use the 'get', 'delete', 'post' and 'put' methods directly:
openstack.network.post("/v2.0/qos/policies/48985e6b8da145699d411f12a3459fca/dscp_marking_rules", data)
Requirements
Ruby versions tested
- Ruby 2.4.0
- Ruby 2.3.3
- Ruby 2.3.0
Contributing
Contributors are welcome and must adhere to the Contributor covenant code of conduct.
Please submit issues/bugs and patches on the Misty repository.
Copyright
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ - See LICENSE for details.