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
- Flexible Openstack APIs integration
- Standardized Openstack APIs: Based upon API-ref
- Multiple Service versions and Microversions
- On demand services - Auto loads required versions
- Low dependency - Use standard Net/HTTP and JSON gem only
- I/O format choice: JSON or Ruby structures 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 relies on standard Net/HTTP library.
No other gems are required besides 'json'.
Not having to use the help of a more complex HTTP framework is a choice that reduces dependencies.
Meanwhile a better reason would be because Openstack offers a common modus operandi across all APIs.
The authentication process provides a Service Catalog serving all available APIs entry points.
APIs Definitions
The rich variety of OpenStack projects requires lots of Application Program Interfaces to handle.
Maintaining and extending those APIs implies a structural complexity challenge.
Therefore the more automated the process, the better.
Thanks to the help of Phoenix project OpenStack API-ref
providing the latest standard of OpenStack APIs.
The APIs interface definitions are generated automatically from the API-ref reference manuals (misty-builder) which
allows:
- More consistent APIs
- More recent APIs definitions
- Easier addition of a new service's API
[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',
:domain => 'default',
:project => 'admin',
:project_domain_id => '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 is authenticated by the identity server (bootstrap) and is provided with a service catalog. When an OpenStack API service is required, the catalog entry's endpoint is used and the service is dynamically called.
Each service name (i.e. compute
) is the object handling API requests.
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
application_catalog: murano, versions: ["v1"]
alarming: aodh, versions: ["v2"]
backup: freezer, versions: ["v1"]
baremetal: ironic, microversion: v1
block_storage: cinder, versions: ["v2", "v1"], microversion: v3
clustering: senlin, versions: ["v1"]
compute: nova, microversion: v2.1
container_infrastructure_management: magnum, microversion: v1
data_processing: sahara, versions: ["v1.1"]
data_protection_orchestration: karbor, versions: ["v1"]
database: trove, versions: ["v1.0"]
domain_name_server: designate, versions: ["v2"]
identity: keystone, versions: ["v3", "v2.0"]
image: glance, versions: ["v2", "v1"]
load_balancer: octavia, versions: ["v2.0"]
messaging: zaqar, versions: ["v2"]
metering: ceilometer, versions: ["v2"]
networking: neutron, versions: ["v2.0"]
nfv_orchestration: tacker, versions: ["v1.0"]
object_storage: swift, versions: ["v1"]
orchestration: heat, versions: ["v1"]
search: searchlight, versions: ["v1"]
shared_file_systems: manila, microversion: v2
Prefixes
A shorter name can be used to call a service only if it's unique among all services.
For instance net
or network
can be used instead of networking
.
Meanwhile data
doesn't work because it's ambiguous between data_processing
and data_protection_orchestration
Aliases
dns
is an alias fordomain_name_server
volume
is an alias forblock_storage
Openstack service name
Different service names can be used for a specific Openstack Service by using the :service_names option (see below).
Requests
The #requests method provides the available requests for a service, for example:
openstack.compute.requests
=> [:add_a_single_tag,
:add_associate_fixed_ip_addfixedip_action_deprecated,
:add_associate_floating_ip_addfloatingip_action_deprecated,
:add_flavor_access_to_tenant_addtenantaccess_action,
:add_host,
:add_network,
:add_security_group_to_a_server_addsecuritygroup_action,
:associate_host_deprecated,
:attach_a_volume_to_an_instance,
:bulk_delete_floating_ips,
:capacities,
:change_administrative_password_changepassword_action,
:check_tag_existence,
:clear_admin_password,
:confirm_resized_server_confirmresize_action,
:create_agent_build,
:create_aggregate,
:create_allocate_floating_ip_address,
:create_assisted_volume_snapshots,
:create_cell,
:create_cloudpipe,
:create_console,
.../...
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:password
Password for user. Cannot be used together with:token
.:token
User provided token, overrides all user and password parameters.:context
Bypass the authentication by providing a proper context withtoken id
,service catalog
andexpire date
. Overrides all user and password parameters
Example:{:context => { :token => token_id, :catalog => service_catalog, :expires => expire_date }}
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 MRI 2.4.1
- Ruby MRI 2.4.0
- Ruby MRI 2.3.4
- Ruby MRI 2.3.3
- Ruby MRI 2.3.2
- Ruby MRI 2.3.1
- Ruby MRI 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.