Misty is a HTTP client for OpenStack APIs, aiming to be slick and dynamic.

Misty handles OpenStack APIs requests as transparently as possible by:

• Directly submitting request to Openstack Service endpoints
• Or by using APIs Schema defined functions which are dynamically extracted from OpenStackAPI reference.

• Standardized OpenStack APIs: Based upon API-ref offering flexibility to easily integrate new OpenStack services. Any request can be overridden or completed
• Microversions & Legacy Versions
• Transparent request data handling and response data format of choice: JSON or Hash
• Custom HTTP Methods for special needs
• And also: Lazy service loading, Low gem dependency (use only Net/HTTP and JSON), Persistent HTTP connections (default since HTTP 1.1 anyway)

The current list of Openstack services supported, can be obtained from Misty.services is:

application_catalog: murano, versions: ["v1"]
alarming: aodh, versions: ["v2"]
backup: freezer, versions: ["v1"]
baremetal: ironic, versions: ["v1"], microversion: 1.32
block_storage: cinder, versions: ["v3", "v2", "v1"], microversion: 3.44
clustering: senlin, versions: ["v1"]
compute: nova, versions: ["v2.1"], microversion: 2.60
container_infrastructure_management: magnum, versions: ["v1"], microversion: 1.4
container_service: zun, versions: ["v1"]
data_processing: sahara, versions: ["v1.1"]
data_protection_orchestration: karbor, versions: ["v1"]
database: trove, versions: ["v1.0"]
dns: designate, versions: ["v2"]
event: panko, versions: ["v2"]
identity: keystone, versions: ["v3", "v2.0"]
image: glance, versions: ["v2", "v1"]
instance_ha: masakari, versions: ["v1.0"]
key_manager: barbican, versions: ["v1"]
load_balancer: octavia, versions: ["v2.0"]
metric: gnocchi, versions: ["v1"]
messaging: zaqar, versions: ["v2"]
metering: ceilometer, versions: ["v2"]
monitoring: monasca, versions: ["v2.0"]
network: neutron, versions: ["v2.0"]
nfv_orchestration: tacker, versions: ["v1.0"]
object_storage: swift, versions: ["v1"]
orchestration: heat, versions: ["v1"]
placement: placement, versions: ["v2.1"], microversion: 2.60
reservation: blazar, versions: ["v1"]
resource_optimization: watcher, versions: ["v1"]
search: searchlight, versions: ["v1"]
shared_file_systems: manila, versions: ["v2"], microversion: 2.40
workflow: mistral, versions: ["v2"]

Fetch and install

gem install misty

Create a Misty::Cloud object with mandatory :auth parameter such as:

require 'misty'
cloud = Misty::Cloud.new(
  :auth => {
    :url                => 'http://localhost:5000',
    :user               => 'admin',
    :password           => 'secret',
    :domain             => 'default',
    :project            => 'admin',
    :project_domain_id  => 'default'
  })

Then requets can be made against OpenStack services:

  servers = cloud.compute.list_servers.body
  networks = cloud.network.list_networks
  first_network_id = networks.body['networks'][0]['id']
  first_network = cloud.network.show_network_details(first_network_id)
  network = Misty::Helper.to_json(:network => {:name => 'misty-example'})
  cloud.network.create_network(network)
  v1 = cloud.baremetal.show_v1_api

To provide the maximum flexibility, there are 4 levels of configuration which are always propagated from top to bottom.

• The Cloud global defaults
• The Cloud global parameters
• The service level parameters
• The request level ephemeral parameters

No global parameters provided, the defaults are applied.

cloud = Misty::Cloud.new(:auth => { ... })

Some provided global parameters, which override respective global and apply at service level.

cloud = Misty::Cloud.new(:auth => { ... }, :log_file => './misty.log', :headers => {"x-tra:" => "value"})

Provided service level parameters are applied for all service requests.
Some such as the headers are cumulative.
Others such as the microversion feature, don't have global definition.

cloud = Misty::Cloud.new(:auth => { ... }, compute {:version => 2.60})
# All following requests are going to be with version 2.60, unless overridden at request level
cloud.compute.list_servers

And finally, at requests level, provided parameters are ephemeral

cloud = Misty::Cloud.new(:auth => { ... })
cloud.compute(:version => 'latest', :content_type => :json, :headers => {"key" => "value"}).list_servers
# Back to defaults (since there are no global or service level parameters provided)
cloud.compute.list_servers

Openstack Identity service Keystone version 3 is the default, version 2.0, although deprecated, is also available. Keystone v3 can handle v2.0 and v3 for authentications and services. V3 relies on the concept of domains and projects while V2 credentials use tenant. Authentication are assumed against v3 unless a tenant is used in the credentials.

The following parameters can be used: To authenticate with credentials details:

• :context - Allow to provide already authenticated context(catalog, token, expiry time). Used for v2.0 only. Exclusive with other parameters.
• :domain_id - Domain id, default: "default"
• :domain - Domain name, default: "Default"
• :password - User password. Exclusive with :token.
• :project_id - Project id
• :project - Project name
• :project_domain_id - Project domain id
• :project_domain - Project domain name
• :ssl_verify_mode - Boolean flag for SSL client verification. SSL is defined when URI scheme => "https://".
• :tenant_id - Tenant id, used for v2.0 only.
• :tenant - Tenant name, used for v2.0 only.
• :token - Allow to provide unscoped token.
• :user_id - User id
• :user - User name
• :user_domain_id - User domain id
• :user_domain - User domain name

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.

auth = {
  :url            => 'http://localhost:5000',
  :user           => 'admin',
  :user_domain    => 'default',
  :password       => 'secret',
  :project        => 'admin',
  :project_domain => 'default'
  }
}
cloud = Misty::Cloud.new(:auth => auth_v3)
# The API requests are of course specific to this version:
cloud.identity.list_projects

Using IDs:

auth = {
  :url        => 'http://localhost:5000',
  :user_id    => '48985e6b8da145699d411f12a3459fca',
  :password   => 'secret',
  :project_id => '8e1e232f6cbb4116bbef715d8a0afe6e',
  }
}

Or alternatively using a context

context = { :context => { :token => token_id, :catalog => service_catalog, :expires => expire_date } }
cloud = Misty::Cloud.new(:auth => context)

By providing tenant details Misty will detect it's using v2.0 for authentication:

auth = {
  :url      => 'http://localhost:5000',
  :user     => 'admin',
  :password => 'secret',
  :tenant   => 'admin',
}
cloud = Misty::Cloud.new(:auth => auth_v2)
# The API requests are of course specific to this version:
cloud.identity.list_tenants

It's possible to authenticate against Keystone V3 and use the identity service v2.0, for instance: In which case API set for v2.0 applies: tenants are available but not the projects.

cloud = Misty::Cloud.new(:auth => auth_v3)
cloud.identity(:api_version => 'v2.0')

The configuration parameters used to initialize Misty::Cloud are global. They are optionals and Misty::Config defaults are applied if not specified.

• :auth - Authentication credentials hash containing 'auth_url' and user context. See Misty::Auth.
• :content_type - HTTP responses body format. :json or :hash structures. Default is Misty::Config::CONTENT_TYPE (:hash).
• :headers - Hash of extra HTTP headers to be applied to all services
• :interface - Endpoint interface, allowed values are: "public", "internal", "admin". Default is Misty::Config::INTERFACE ('public').
• :log_file - Log destination, Value is either file path (./misty.log) or IO object (SDOUT). Default is '/dev/null'
• :log_level - Value is Fixnum - Default is 1 (Logger::INFO) - See Logger from Ruby standard Library
• :region - Alternative Region name. Default is Misty::Config::REGION ('regionOne')
• :ssl_verify_mode - Boolean flag for SSL client verification. Applies when URI scheme is SSL ("https://"). Default is Misty::Config::SSL_VERIFY_MODE (true) See Misty::Config for more details

The following parameters which are global defined can also be changed at the service level.

• :content_type - Overridden
• :headers - Cumulative
• :interface - Overridden
• :region - Overridden

The following parameters are specific to the service level:

• :api_version - String for specifying Openstack API service version to use. Default is latest supported version.
• :base_path - Allows to force the base path for every URL requests. Default is endpoint's path.
• :endpoint - Overrides service endpoint discovery by providing url.
• :service_name - Provides alternative service name for endpoint discovery. Allowed values: 'latest', or a version number such as '2.10'

The following parameters can be changed at a service's request level.

• :content_type - Overridden
• :headers - Cumulative
• :version - Version to be used when microversion is supported by the service. Default: none

Headers are cumulative when applied at any level, Cloud level, Service level and/or finally at service's request level.

HTTP headers can effectively be optionally added to any request. An Header object must be created and passed as the last parameter of a request.

container_header = {
  'x-container-meta-web-listings' => false,
  'x-container-meta-quota-count'  => "",
  'x-container-meta-quota-bytes'  => nil,
  'x-versions-location'           => "",
  'x-container-meta-web-index'    => ""
}

cloud = Misty::Cloud.new{:auth { ... }}
cloud.object_storage.create_update_or_delete_container_metadata(container_name, container_header)

Initialize cloud with different options, and for the identify service, override respective global values

cloud = Misty::Cloud.new(:auth => { ... }, region_id => 'regionOne', :log_level => 0, {identity => {region_id => 'regionTwo', :interface => 'admin'})

At Request level, provide specific options like the microversion

cloud.compute(:version => '2.27', :content_type => :json).list_servers

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 network because it's not ambiguous. Meanwhile data doesn't work because it's ambiguous between data_processing and data_protection_orchestration

• domain_name_server is an alias for dns
• volume is an alias for block_storage

The exhaustive list of requests, extracted from the current service API's and cumulated with Misty service defined requests if any, is available as follow:

cloud.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,

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)

heat_template = {
  "files": {},
  "disable_rollback": true,
  "parameters": {
    "flavor": "m1.tiny"
  },
  "stack_name": "test_stack",
  "template": {
    "heat_template_version": "2013-05-23",
    "description": "Template to test heat",
    "parameters": {
      "flavor": {
        "default": "m1.small",
        "type": "string"
      }
    },
    "resources": {
      "hello_world": {
        "type": "OS::Nova::Server",
        "properties": {
          "flavor": { "get_param": "flavor" },
          "image": "50fd6f2b-d9f0-41b6-b0a9-4482bfe61914",
          "user_data": "/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
        }
      }
    }
  },
  "timeout_mins": 60
}

require 'misty'
require 'pp'
cloud = Misty::Cloud.new(:auth => { ... })
data_heat_template = Misty::Helper.to_json(heat_template)
response = cloud.orchestration.create_stack(data_heat_template)
id = response.body['stack']['id']
stack = cloud.orchestration.show_stack_details('test_stack', id)
pp stack.body

cloud = Misty::Cloud.new(:auth => { ... })
pp cloud.compute.versions
=> [{"status"=>"SUPPORTED",
"updated"=>"2011-01-21T11:33:21Z",
"links"=>[{"href"=>"http://192.0.2.1:8774/v2/", "rel"=>"self"}],
"min_version"=>"",
"version"=>"",
"id"=>"v2.0"},
{"status"=>"CURRENT",
"updated"=>"2013-07-23T11:33:21Z",
"links"=>[{"href"=>"http://192.0.2.1:8774/v2.1/", "rel"=>"self"}],
"min_version"=>"2.1",
"version"=>"2.53",
"id"=>"v2.1"}]

cloud.compute(:version => '2.25')
data_keypair = Misty::Helper.to_json('keypair': {'name': 'admin-keypair'})
admin_keypair = cloud.compute.create_or_import_keypair(data_keypair)
user_id = admin_keypair.body['keypair']['user_id']
keypairs = cloud.compute.list_keypairs
pp keypairs.body

Nova version 2.10+, a keypair name can be filtered by user_id

user_id=1e50c2f0995446fd9b135a1a549cabdb
cloud.compute(:version => '2.10').show_keypair_details("admin-keypair?user_id=#{user_id}")

With Nova version 2.2+, the type field is also returned when showing keypair details

cloud.compute(:version => '2.2')
pp admin_keypair.body
=> {'keypair'=>
    {'public_key'=>
      'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDjenEe7B87OQHYjZAdJWmaY13mF0N3VooviHypEXaSDfEmFj4GinXorKD0kdXAL30orT0wgAVtpAvRhH2iFTPF2VKCdq4VMzLuai60e3oB3vsTWdZQIJtvaW0mpTNVUQKczbFhRFUi4CNsAijjmGJJgxhihd6rAfynFtalLO0yNn3dKtEMbsvs7KeMxT9SXbfLmEXD4reAK/WXQBVjrEjJIgpC3+SXOO6vsavaOTFu7/Nbha/p4g4yJ3rHUU+7lj79a7iy0sNeExBSZ2aKTq7FQ5XDmtZjjpUeas16kMMX5HdxISYkbq3QnG9iTrIy+GEAYKkZPzhuAa76Qpze35aV Generated-by-Nova\n',
     'user_id'=>'1e50c2f0995446fd9b135a1a549cabdb',
     'name'=>'admin-keypair',
     'deleted'=>false,
     'created_at'=>'2016-11-23T01:23:53.000000',
     'updated_at'=>nil,
     'fingerprint'=>'4e:db:2d:bd:93:70:01:b8:61:17:96:23:e0:78:e2:69',
     'deleted_at'=>nil,
     'type'=>'ssh',
     'id'=>8}}

Driver Vendor Passthru (drivers) has 2 methods call with same name. One for Node Vendor Passthru and one for Drivers Passthru. They are respectively associated with the methods #call_a_vendor_method and #call_a_driver_method.

• Ruby MRI 2.5.1
• Ruby MRI 2.4.4
• Ruby MRI 2.3.7

Contributors are welcome and must adhere to the Contributor covenant code of conduct.

Please submit issues/bugs and patches on the Misty repository.

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ - See LICENSE for details.