Installation guide

The OpenStack SDK is available on PyPI under the name openstacksdk. To install it, use pip:

$ pip install openstacksdk

To check the installed version you can call the module with:

$ python -m openstack version

Using the OpenStack SDK

This section of documentation pertains to those who wish to use this SDK in their own application. If you're looking for documentation on how to contribute to or extend the SDK, refer to the contributor section.

For a listing of terms used throughout the SDK, including the names of projects and services supported by it, see the glossary.

User Guides

These guides walk you through how to make use of the libraries we provide to work with each OpenStack service. If you're looking for a cookbook approach, this is where you'll want to begin.

Getting started

openstacksdk aims to talk to any OpenStack cloud. To do this, it requires a configuration file. openstacksdk favours clouds.yaml files, but can also use environment variables. The clouds.yaml file should be provided by your cloud provider or deployment tooling. An example:

clouds:


 mordred:


   region_name: Dallas


   auth:


     username: 'mordred'


     password: XXXXXXX


     project_name: 'demo'


     auth_url: 'https://identity.example.com'

More information on configuring openstacksdk can be found in Configuring OpenStack SDK Applications.

Given sufficient configuration, you can use openstacksdk to interact with your cloud. openstacksdk consists of three layers. Most users will make use of the proxy layer. Using the above clouds.yaml, consider listing servers:

import openstack
# Initialize and turn on debug logging
openstack.enable_logging(debug=True)
# Initialize connection
conn = openstack.connect(cloud='mordred')
# List the servers
for server in conn.compute.servers():


    print(server.to_dict())

openstacksdk also contains a higher-level cloud layer based on logical operations:

import openstack
# Initialize and turn on debug logging
openstack.enable_logging(debug=True)
# Initialize connection
conn = openstack.connect(cloud='mordred')
# List the servers
for server in conn.list_servers():


    print(server.to_dict())

The benefit of this layer is mostly seen in more complicated operations that take multiple steps and where the steps vary across providers. For example:

import openstack
# Initialize and turn on debug logging
openstack.enable_logging(debug=True)
# Initialize connection
conn = openstack.connect(cloud='mordred')
# Upload an image to the cloud
image = conn.create_image(


    'ubuntu-trusty', filename='ubuntu-trusty.qcow2', wait=True)
# Find a flavor with at least 512M of RAM
flavor = conn.get_flavor_by_ram(512)
# Boot a server, wait for it to boot, and then do whatever is needed
# to get a public IP address for it.
conn.create_server(


    'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)

Finally, there is the low-level resource layer. This provides support for the basic CRUD operations supported by REST APIs and is the base building block for the other layers. You typically will not need to use this directly:

import openstack
import openstack.config.loader
import openstack.compute.v2.server
# Initialize and turn on debug logging
openstack.enable_logging(debug=True)
# Initialize connection
conn = openstack.connect(cloud='mordred')
# List the servers
for server in openstack.compute.v2.server.Server.list(session=conn.compute):


    print(server.to_dict())

Using os-client-config

Configuring OpenStack SDK Applications

Environment Variables

openstacksdk honors all of the normal OS_* variables. It does not provide backwards compatibility to service-specific variables such as NOVA_USERNAME.

If you have OpenStack environment variables set, openstacksdk will produce a cloud config object named envvars containing your values from the environment. If you don't like the name envvars, that's ok, you can override it by setting OS_CLOUD_NAME.

Service specific settings, like the nova service type, are set with the default service type as a prefix. For instance, to set a special service_type for trove set

export OS_DATABASE_SERVICE_TYPE=rax:database

Config Files

openstacksdk will look for a file called clouds.yaml in the following locations:

The first file found wins.

You can also set the environment variable OS_CLIENT_CONFIG_FILE to an absolute path of a file to look for and that location will be inserted at the front of the file search list.

The keys are all of the keys you'd expect from OS_* - except lower case and without the OS prefix. So, region name is set with region_name.

Service specific settings, like the nova service type, are set with the default service type as a prefix. For instance, to set a special service_type for trove (because you're using Rackspace) set:

database_service_type: 'rax:database'

Site Specific File Locations

In addition to ~/.config/openstack and /etc/openstack - some platforms have other locations they like to put things. openstacksdk will also look in an OS specific config dir

USER_CONFIG_DIR is different on Linux, OSX and Windows.

SITE_CONFIG_DIR is different on Linux, OSX and Windows.

An example config file is probably helpful:

clouds:


  mtvexx:


    profile: https://vexxhost.com


    auth:


      username: mordred@inaugust.com


      password: XXXXXXXXX


      project_name: mordred@inaugust.com


    region_name: ca-ymq-1


    dns_api_version: 1


  mordred:


    region_name: RegionOne


    auth:


      username: 'mordred'


      password: XXXXXXX


      project_name: 'shade'


      auth_url: 'https://montytaylor-sjc.openstack.blueboxgrid.com:5001/v2.0'


  infra:


    profile: rackspace


    auth:


      username: openstackci


      password: XXXXXXXX


      project_id: 610275


    regions:


    - DFW


    - ORD


    - IAD

You may note a few things. First, since auth_url settings are silly and embarrassingly ugly, known cloud vendor profile information is included and may be referenced by name or by base URL to the cloud in question if the cloud serves a vendor profile. One of the benefits of that is that auth_url isn't the only thing the vendor defaults contain. For instance, since Rackspace lists rax:database as the service type for trove, openstacksdk knows that so that you don't have to. In case the cloud vendor profile is not available, you can provide one called clouds-public.yaml, following the same location rules previously mentioned for the config files.

regions can be a list of regions. When you call get_all_clouds, you'll get a cloud config object for each cloud/region combo.

As seen with dns_service_type, any setting that makes sense to be per-service, like service_type or endpoint or api_version can be set by prefixing the setting with the default service type. That might strike you funny when setting service_type and it does me too - but that's just the world we live in.

Auth Settings

Keystone has auth plugins - which means it's not possible to know ahead of time which auth settings are needed. openstacksdk sets the default plugin type to password, which is what things all were before plugins came about. In order to facilitate validation of values, all of the parameters that exist as a result of a chosen plugin need to go into the auth dict. For password auth, this includes auth_url, username and password as well as anything related to domains, projects and trusts.

API Settings

The following settings are passed to keystoneauth and are common to all services.

Splitting Secrets

In some scenarios, such as configuration management controlled environments, it might be easier to have secrets in one file and non-secrets in another. This is fully supported via an optional file secure.yaml which follows all the same location rules as clouds.yaml. It can contain anything you put in clouds.yaml and will take precedence over anything in the clouds.yaml file.

# clouds.yaml
clouds:


  internap:


    profile: internap


    auth:


      username: api-55f9a00fb2619


      project_name: inap-17037


    regions:


    - ams01


    - nyj01
# secure.yaml
clouds:


  internap:


    auth:


      password: XXXXXXXXXXXXXXXXX

SSL Settings

When the access to a cloud is done via a secure connection, openstacksdk will always verify the SSL cert by default. This can be disabled by setting verify to False. In case the cert is signed by an unknown CA, a specific cacert can be provided via cacert. WARNING: verify will always have precedence over cacert, so when setting a CA cert but disabling verify, the cloud cert will never be validated.

Client certs are also configurable. cert will be the client cert file location. In case the cert key is not included within the client cert file, its file location needs to be set via key.

# clouds.yaml
clouds:


  regular-secure-cloud:


    auth:


      auth_url: https://signed.cert.domain:5000


      ...


  unknown-ca-with-client-cert-secure-cloud:


    auth:


      auth_url: https://unknown.ca.but.secure.domain:5000


      ...


    key: /home/myhome/client-cert.key


    cert: /home/myhome/client-cert.crt


    cacert: /home/myhome/ca.crt


  self-signed-insecure-cloud:


    auth:


      auth_url: https://self.signed.cert.domain:5000


      ...


    verify: False

Note for parity with openstack command-line options the insecure boolean is also recognised (with the opposite semantics to verify; i.e. True ignores certificate failures). This should be considered deprecated for verify.

Cache Settings

Changed in version 1.0.0: Previously, caching was managed exclusively in the cloud layer. Starting in openstacksdk 1.0.0, caching is moved to the proxy layer. As the cloud layer depends on the proxy layer in 1.0.0, this means both layers can benefit from the cache.

Authenticating and accessing resources on a cloud is often expensive. It is therefore quite common that applications will wish to do some client-side caching of both credentials and cloud resources. To facilitate this, openstacksdk supports caching credentials and resources using the system keyring and dogpile.cache, respectively.

TIP:

Caching in enabled or disabled globally, rather than on a cloud-by-cloud basis. This is done by setting configuring the``cache`` top-level key. Caching of authentication tokens can be configured using the following settings:

For example, to configure caching of authentication tokens.

cache:


  auth: true

Caching of resources can be configured using the following settings:

For example, to configure caching with the dogpile.cache.memory backend with a 1 hour expiration.

cache:


  expiration_time: 3600

To configure caching with the dogpile.cache.memory backend with a 1 hour expiration but only for requests to the OpenStack Compute service's /servers API:

cache:


  expirations:


    servers: 3600

To configure caching with the dogpile.cache.pylibmc backend with a 1 hour expiration time and a memcached server running on your localhost.

cache:


  expiration_time: 3600


  arguments:


    url:


    - 127.0.0.1

To configure caching with the dogpile.cache.pylibmc backend with a 1 hour expiration time, a memcached server running on your localhost, and multiple per-resource cache expiration times.

cache:


  class: dogpile.cache.pylibmc


  expiration_time: 3600


  arguments:


    url:


      - 127.0.0.1


  expiration:


    server: 5


    flavor: -1


    compute.servers: 5


    compute.flavors: -1


    image.images: 5

Finally, if the cache key is undefined, a null cache is enabled meaning caching is effectively disabled.

NOTE:

MFA Support

MFA support requires a specially prepared configuration file. In this case a combination of two different authorization plugins is used with their individual requirements to the specified parameters.

clouds:


  mfa:


    auth_type: "v3multifactor"


    auth_methods:


      - v3password


      - v3totp


    auth:


      auth_url: https://identity.cloud.com


      username: user


      user_id: uid


      password: XXXXXXXXX


      project_name: project


      user_domain_name: udn


      project_domain_name: pdn

IPv6

IPv6 is the future, and you should always use it if your cloud supports it and if your local network supports it. Both of those are easily detectable and all friendly software should do the right thing.

However, sometimes a cloud API may return IPv6 information that is not useful to a production deployment. For example, the API may provide an IPv6 address for a server, but not provide that to the host instance via metadata (configdrive) or standard IPv6 autoconfiguration methods (i.e. the host either needs to make a bespoke API call, or otherwise statically configure itself).

For such situations, you can set the force_ipv4, or OS_FORCE_IPV4 boolean environment variable. For example:

clouds:


  mtvexx:


    profile: vexxhost


    auth:


      username: mordred@inaugust.com


      password: XXXXXXXXX


      project_name: mordred@inaugust.com


    region_name: ca-ymq-1


    dns_api_version: 1


  monty:


    profile: fooprovider


    force_ipv4: true


    auth:


      username: mordred@inaugust.com


      password: XXXXXXXXX


      project_name: mordred@inaugust.com


    region_name: RegionFoo

The above snippet will tell client programs to prefer the IPv4 address and leave the public_v6 field of the Server object blank for the fooprovider cloud . You can also set this with a client flag for all clouds:

client:


  force_ipv4: true

Per-region settings

Sometimes you have a cloud provider that has config that is common to the cloud, but also with some things you might want to express on a per-region basis. For instance, Internap provides a public and private network specific to the user in each region, and putting the values of those networks into config can make consuming programs more efficient.

To support this, the region list can actually be a list of dicts, and any setting that can be set at the cloud level can be overridden for that region.

clouds:


  internap:


    profile: internap


    auth:


      password: XXXXXXXXXXXXXXXXX


      username: api-55f9a00fb2619


      project_name: inap-17037


    regions:


    - name: ams01


      values:


        networks:


        - name: inap-17037-WAN1654


          routes_externally: true


        - name: inap-17037-LAN6745


    - name: nyj01


      values:


        networks:


        - name: inap-17037-WAN1654


          routes_externally: true


        - name: inap-17037-LAN6745

Setting Precedence

Some settings are redundant, e.g. project-name and project-id both specify the project. In a conflict between redundant settings, the _name clouds.yaml option (or equivalent -name CLI option and _NAME environment variable) will be used.

Some environment variables or commandline flags can override the settings from clouds.yaml. These are:

Similarly, if one of the above settings is specified in clouds.yaml as part of the auth section as well as the main section, the auth settings will be overridden. For example in this config section, note that project is specified multiple times:

clouds:


  mtvexx:


    profile: https://vexxhost.com


    auth:


      username: mordred@inaugust.com


      password: XXXXXXXXX


      project_name: mylessfavoriteproject


      project_id: 0bedab75-898c-4521-a038-0b4b71c41bed


    region_name: ca-ymq-1


    project_name: myfavoriteproject


    project_id: 2acf9403-25e8-479e-a3c6-d67540c424a4

In the above example, the project_id configuration values will be ignored in favor of the project_name configuration values, and the higher-level project will be chosen over the auth-specified project. So the actual project used will be `myfavoriteproject`.

Examples

auth

Password-based authentication (project-scoped)

example:


    auth:


        auth_url: http://example.com/identity


        password: password


        project_domain_id: default


        project_name: admin


        user_domain_id: default


        username: admin


    region_name: RegionOne

Password-based authentication (domain-scoped)

example:


    auth:


        auth_url: http://example.com/identity


        domain_id: default


        password: password


        username: admin


    region_name: RegionOne

Password-based authentication (trust-scoped)

example-trust:


    auth:


        auth_url: http://example.com/identity


        password: password


        username: admin


        trust_id: 95946f9eef864fdc993079d8fe3e5747


    region_name: RegionOne

Password-based authentication (system-scoped)

example-system:


    auth:


        auth_url: http://example.com/identity


        password: password


        system_scope: all


        username: admin


    region_name: RegionOne

Application credential-based authentication

example-appcred:


    auth:


        auth_url: http://example.com/identity


        application_credential_id: 9da0a8da3d394d09bf49dfc27014d254


        application_credential_secret: pKfDSvUOFwO2t2_XxCajAFhzCKAVHI7yfqPb6xjshVDnMUHF7ifju8gMdhHTI4Eo56UP_hEc8ssmgA1NNtKMpA


    auth_type: v3applicationcredential


    region_name: RegionOne

Token-based authentication

example-token:


    auth:


        auth_url: http://example.com/identity


        token: gAAAAABl32ptw2PN6L9JyBeO16PwQU1SrdMUvUz8Eon7LC2PFItdGRWFpOkK0qwH3JkukTuEM5qbYK9ucowRXET1RBMjZlfVpUa8Nz3qjQdzXw7pBKH4w1e4tekvDCOKfn15ZoujBOvdGqgtpW-febVGaW9oJzf6R3WTMDxWz3YRJjmiOBpwcN8


        project_id: 1fd93a4455c74d2ea94b929fc5f0e488


    auth_type: v3token


    region_name: RegionOne

NOTE:

TOTP-based authentication

example-totp:


    auth:


        auth_url: http://example.com/identity


        passcode: password


        project_domain_id: default


        project_name: admin


        user_domain_id: default


        username: admin


    auth_type: v3totp


    region_name: RegionOne

NOTE:

OAuth1-based authentication

example-oauth:


    auth:


        auth_url: http://example.com/identity


        consumer_key: foo


        consumer_secret: secret


        access_key: bar


        access_secret: secret


    auth_type: v3oauth1


    region_name: RegionOne

Using openstack.config in an Application

Usage

The simplest and least useful thing you can do is:

python -m openstack.config.loader

Which will print out whatever if finds for your config. If you want to use it from python, which is much more likely what you want to do, things like:

Get a named cloud.

import openstack.config
cloud_region = openstack.config.OpenStackConfig().get_one(


    'internap', region_name='ams01')
print(cloud_region.name, cloud_region.region, cloud_region.config)

Or, get all of the clouds.

import openstack.config
cloud_regions = openstack.config.OpenStackConfig().get_all()
for cloud_region in cloud_regions:


    print(cloud_region.name, cloud_region.region, cloud_region.config)

argparse

If you're using openstack.config from a program that wants to process command line options, there is a registration function to register the arguments that both openstack.config and keystoneauth know how to deal with - as well as a consumption argument.

import argparse
import openstack
parser = argparse.ArgumentParser()
cloud = openstack.connect(options=parser)

Vendor Support

OpenStack presents deployers with many options, some of which can expose differences to end users. os-client-config tries its best to collect information about various things a user would need to know. The following is a text representation of the vendor related defaults os-client-config knows about.

Default Values

These are the default behaviors unless a cloud is configured differently.

AURO

https://api.auro.io:5000/v2.0

Betacloud

https://api-1.betacloud.de:5000

Binero

https://auth.binero.cloud:5000/v3

Catalyst

https://api.cloud.catalyst.net.nz:5000/v2.0

City Cloud

https://%(region_name)s.citycloud.com:5000/v3/

ConoHa

https://identity.%(region_name)s.conoha.io

DreamCompute

https://iad2.dream.io:5000

Open Telekom Cloud

https://iam.%(region_name)s.otc.t-systems.com/v3

ELASTX

https://ops.elastx.cloud:5000/v3

Enter Cloud Suite

https://api.entercloudsuite.com/v2.0

Fuga

https://identity.api.fuga.io:5000

Internap

https://identity.api.cloud.inap.com/v2.0

Limestone Networks

https://auth.cloud.lstn.net:5000/v3

OVH

https://auth.cloud.ovh.net/v3

Rackspace

https://identity.api.rackspacecloud.com/v2.0/

auth:


  username: myusername


  api_key: myapikey
auth_type: rackspace_apikey

SWITCHengines

https://keystone.cloud.switch.ch:5000/v3

Ultimum

https://console.ultimum-cloud.com:5000/v2.0

UnitedStack

https://identity.api.ustack.com/v3

VEXXHOST

http://auth.vexxhost.net

Zetta

https://identity.api.zetta.io/v3

Network Config

There are several different qualities that networks in OpenStack might have that might not be able to be automatically inferred from the available metadata. To help users navigate more complex setups, os-client-config allows configuring a list of network metadata.

clouds:


  amazing:


    networks:


    - name: blue


      routes_externally: true


    - name: purple


      routes_externally: true


      default_interface: true


    - name: green


      routes_externally: false


    - name: yellow


      routes_externally: false


      nat_destination: true


    - name: chartreuse


      routes_externally: false


      routes_ipv6_externally: true


    - name: aubergine


      routes_ipv4_externally: false


      routes_ipv6_externally: true

Every entry must have a name field, which can hold either the name or the id of the network.

routes_externally is a boolean field that labels the network as handling north/south traffic off of the cloud. In a public cloud this might be thought of as the "public" network, but in private clouds it's possible it might be an RFC1918 address. In either case, it's provides IPs to servers that things not on the cloud can use. This value defaults to false, which indicates only servers on the same network can talk to it.

routes_ipv4_externally and routes_ipv6_externally are boolean fields to help handle routes_externally in the case where a network has a split stack with different values for IPv4 and IPv6. Either entry, if not given, defaults to the value of routes_externally.

default_interface is a boolean field that indicates that the network is the one that programs should use. It defaults to false. An example of needing to use this value is a cloud with two private networks, and where a user is running ansible in one of the servers to talk to other servers on the private network. Because both networks are private, there would otherwise be no way to determine which one should be used for the traffic. There can only be one default_interface per cloud.

nat_destination is a boolean field that indicates which network floating ips should be attached to. It defaults to false. Normally this can be inferred by looking for a network that has subnets that have a gateway_ip. But it's possible to have more than one network that satisfies that condition, so the user might want to tell programs which one to pick. There can be only one nat_destination per cloud.

nat_source is a boolean field that indicates which network floating ips should be requested from. It defaults to false. Normally this can be inferred by looking for a network that is attached to a router. But it's possible to have more than one network that satisfies that condition, so the user might want to tell programs which one to pick. There can be only one nat_source per cloud.

API Reference

'block_storage_endpoint_override': 'http://...'

'interface': 'public'

Connect

In order to work with an OpenStack cloud you first need to create a Connection to it using your credentials. A Connection can be created in 3 ways, using the class itself, Config Files, or Environment Variables. It is recommended to always use Config Files as the same config can be used across tools and languages.

Create Connection

To create a Connection instance, use the connect() factory function.

Full example at connect.py

NOTE:

Next

Now that you can create a connection, continue with the User Guides to work with an OpenStack service.

Connect From Config

In order to work with an OpenStack cloud you first need to create a Connection to it using your credentials. A Connection can be created in 3 ways, using the class itself (see Connect), a file, or environment variables as illustrated below. The SDK uses os-client-config to handle the configuration.

Create Connection From A File

Default Location

To create a connection from a file you need a YAML file to contain the configuration.

clouds:


  devstack:


    auth:


      auth_url: http://xxx.xxx.xxx.xxx/identity


      password: password


      project_domain_id: default


      project_name: demo


      user_domain_id: default


      username: demo


    identity_api_version: '3'


    region_name: RegionOne


    volume_api_version: '3'


  devstack-admin:


    auth:


      auth_url: http://xxx.xxx.xxx.xxx/identity


      password: password


      project_domain_id: default


      project_name: admin


      user_domain_id: default


      username: admin


    identity_api_version: '3'


    region_name: RegionOne


    volume_api_version: '3'


  devstack-alt:


    auth:


      auth_url: http://xxx.xxx.xxx.xxx/identity


      password: password


      project_domain_id: default


      project_name: alt_demo


      user_domain_id: default


      username: alt_demo


    identity_api_version: '3'


    region_name: RegionOne


    volume_api_version: '3'
example:


  image_name: cirros-0.5.2-x86_64-disk


  flavor_name: m1.small

To use a configuration file called clouds.yaml in one of the default locations:

call from_config(). The from_config function takes three optional arguments:

NOTE:

User Defined Location

To use a configuration file in a user defined location set the environment variable OS_CLIENT_CONFIG_FILE to the absolute path of a file.:

export OS_CLIENT_CONFIG_FILE=/path/to/my/config/my-clouds.yaml

and call from_config() with the cloud_name of the cloud configuration to use, .

Next

Now that you can create a connection, continue with the User Guides for an OpenStack service.

Logging

NOTE:

openstacksdk uses Python Logging. As openstacksdk is a library, it does not configure logging handlers automatically, expecting instead for that to be the purview of the consuming application.

Simple Usage

For consumers who just want to get a basic logging setup without thinking about it too deeply, there is a helper method. If used, it should be called before any other openstacksdk functionality.

import openstack
openstack.enable_logging()

The stream parameter controls the stream where log message are written to. It defaults to sys.stdout which will result in log messages being written to STDOUT. It can be set to another output stream, or to None to disable logging to the console.

The path parameter sets up logging to log to a file. By default, if path is given and stream is not, logging will only go to path.

You can combine the path and stream parameters to log to both places simultaneously.

To log messages to a file called openstack.log and the console on stdout:

import sys
import openstack
openstack.enable_logging(


    debug=True, path='openstack.log', stream=sys.stdout)

openstack.enable_logging also sets up a few other loggers and squelches some warnings or log messages that are otherwise uninteresting or unactionable by an openstacksdk user.

Advanced Usage

openstacksdk logs to a set of different named loggers.

Most of the logging is set up to log to the root openstack logger. There are additional sub-loggers that are used at times, primarily so that a user can decide to turn on or off a specific type of logging. They are listed below.

HTTP Tracing

HTTP Interactions are handled by keystoneauth. If you want to enable HTTP tracing while using openstacksdk and are not using openstack.enable_logging, set the log level of the keystoneauth logger to DEBUG.

For more information see https://docs.openstack.org/keystoneauth/latest/using-sessions.html#logging

Python Logging

Python logging is a standard feature of Python and is documented fully in the Python Documentation, which varies by version of Python.

For more information on Python Logging for Python v2, see https://docs.python.org/2/library/logging.html.

For more information on Python Logging for Python v3, see https://docs.python.org/3/library/logging.html.

Statistics reporting

openstacksdk can report statistics on individual API requests/responses in several different formats.

Note that metrics will be reported only when corresponding client libraries (statsd for 'statsd' reporting, influxdb for influxdb, etc.). If libraries are not available reporting will be silently ignored.

statsd

statsd can be configured via configuration entries or environment variables.

A global metrics entry defines defaults for all clouds. Each cloud can specify a metrics section to override variables; this may be useful to separate results reported for each cloud.

metrics:


  statsd:


    host: __statsd_server_host__


    port: __statsd_server_port__


    prefix: __statsd_prefix__ (default 'openstack.api')
clouds:


  a-cloud:


    auth:


     ...


    metrics:


      statsd:


        prefix: 'openstack.api.a-cloud'

If the STATSD_HOST or STATSD_PORT environment variables are set, they will be taken as the default values (and enable statsd reporting if no other configuration is specified).

InfluxDB

InfluxDB is supported via configuration in the metrics field. Similar to statsd, each cloud can provide it's own metrics section to override any global defaults.

metrics:


  influxdb:


    host: __influxdb_server_host__


    port: __influxdb_server_port__


    use_udp: __True|False__


    username: __influxdb_auth_username__


    password: __influxdb_auth_password__


    database: __influxdb_db_name__


    measurement: __influxdb_measurement_name__


    timeout: __infludb_requests_timeout__
clouds:


  ..

InfluxDB reporting allows setting additional tags into the metrics based on the selected cloud.

clouds:


  my_cloud:


    profile: some_profile


    ...


    additional_metric_tags:


      environment: production

prometheus

The prometheus support does not read from config, and does not run an http service since OpenstackSDK is a library. It is expected that an application that uses OpenstackSDK and wants request stats be collected will pass a prometheus_client.CollectorRegistry to collector_registry.

Microversions

As openstacksdk rolls out support for consuming microversions, it will do so on a call by call basis as needed. Just like with major versions, openstacksdk should have logic to handle each microversion for a given REST call it makes, with the following rules in mind:

NOTE:

Using OpenStack Baremetal

Before working with the Bare Metal service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

The primary resource of the Bare Metal service is the node.

Below are a few usage examples. For a reference to all the available methods, see Baremetal API.

CRUD operations

List Nodes

A node is a bare metal machine.

Full example: baremetal resource list

Provisioning operations

Provisioning actions are the main way to manipulate the nodes. See Bare Metal service states documentation for details.

Manage and inspect Node

Managing a node in the enroll provision state validates the management (IPMI, Redfish, etc) credentials and moves the node to the manageable state. Managing a node in the available state moves it to the manageable state. In this state additional actions, such as configuring RAID or inspecting, are available.

Inspecting a node detects its properties by either talking to its BMC or by booting a special ramdisk.

Full example: baremetal provisioning

Provide Node

Providing a node in the manageable provision state makes it available for deployment.

Full example: baremetal provisioning

Using OpenStack Block Storage

Before working with the Block Storage service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Using OpenStack Clustering

Before working with the Clustering service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used by all examples in this guide.

The primary abstractions/resources of the Clustering service are:

Working with Profile Types

A profile is a template used to create and manage nodes, i.e. objects exposed by other OpenStack services. A profile encodes the information needed for node creation in a property named spec.

List Profile Types

To examine the known profile types:

Full example: manage profile type

Get Profile Type

To get the details about a profile type, you need to provide the name of it.

Full example: manage profile type

Managing Profiles

A profile type can be treated as the meta-type of a Profile object. A registry of profile types is built when the Cluster service starts. When creating a Profile object, you will indicate the profile type used in its spec property.

List Profiles

To examine the list of profiles:

When listing profiles, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage profile

Create Profile

When creating a profile, you will provide a dictionary with keys and values specified according to the profile type referenced.

Optionally, you can specify a metadata keyword argument that contains some key-value pairs to be associated with the profile.

Full example: manage profile

Find Profile

To find a profile based on its name or ID:

The Cluster service doesn't allow updating the spec of a profile. The only way to achieve that is to create a new profile.

Full example: manage profile

Get Profile

To get a profile based on its name or ID:

Full example: manage profile

Update Profile

After a profile is created, most of its properties are immutable. Still, you can update a profile's name and/or metadata.

The Cluster service doesn't allow updating the spec of a profile. The only way to achieve that is to create a new profile.

Full example: manage profile

Delete Profile

A profile can be deleted after creation, provided that it is not referenced by any active clusters or nodes. If you attempt to delete a profile that is still in use, you will get an error message.

Managing Clusters

Clusters are first-class citizens in Senlin service design. A cluster is defined as a collection of homogeneous objects. The "homogeneous" here means that the objects managed (aka. Nodes) have to be instantiated from the same "profile type".

List Clusters

To examine the list of receivers:

When listing clusters, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage cluster

Create Cluster

When creating a cluster, you will provide a dictionary with keys and values according to the cluster type referenced.

Optionally, you can specify a metadata keyword argument that contains some key-value pairs to be associated with the cluster.

Full example: manage cluster

Get Cluster

To get a cluster based on its name or ID:

Full example: manage cluster

Find Cluster

To find a cluster based on its name or ID:

Full example: manage cluster

Update Cluster

After a cluster is created, most of its properties are immutable. Still, you can update a cluster's name and/or params.

Full example: manage cluster

Delete Cluster

A cluster can be deleted after creation, When there are nodes in the cluster, the Senlin engine will launch a process to delete all nodes from the cluster and destroy them before deleting the cluster object itself.

Add Nodes to Cluster

Add some existing nodes into the specified cluster.

Remove Nodes from Cluster

Remove nodes from specified cluster.

Replace Nodes in Cluster

Replace some existing nodes in the specified cluster.

Cluster Scale Out

Inflate the size of a cluster.

Cluster Scale In

Shrink the size of a cluster.

Cluster Resize

Resize of cluster.

Attach Policy to Cluster

Once a policy is attached (bound) to a cluster, it will be enforced when related actions are performed on that cluster, unless the policy is (temporarily) disabled on the cluster

Detach Policy from Cluster

Once a policy is attached to a cluster, it can be detached from the cluster at user's request.

Cluster Check

Check cluster health status, Cluster members can be check.

Cluster Recover

To restore a specified cluster, members in the cluster will be checked.

Managing Nodes

Node is a logical object managed by the Senlin service. A node can be a member of at most one cluster at any time. A node can be an orphan node which means it doesn't belong to any clusters.

List Nodes

To examine the list of Nodes:

When listing nodes, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage node

Create Node

When creating a node, you will provide a dictionary with keys and values according to the node type referenced.

Optionally, you can specify a metadata keyword argument that contains some key-value pairs to be associated with the node.

Full example: manage node

Get Node

To get a node based on its name or ID:

Full example: manage node

Find Node

To find a node based on its name or ID:

Full example: manage node

Update Node

After a node is created, most of its properties are immutable. Still, you can update a node's name and/or params.

Full example: manage node

Delete Node

A node can be deleted after creation, provided that it is not referenced by any active clusters. If you attempt to delete a node that is still in use, you will get an error message.

Full example: manage node

Check Node

If the underlying physical resource is not healthy, the node will be set to ERROR status.

Full example: manage node

Recover Node

To restore a specified node.

Working with Policy Types

A policy is a template that encodes the information needed for specifying the rules that are checked/enforced before/after certain actions are performed on a cluster. The rules are encoded in a property named spec.

List Policy Types

To examine the known policy types:

Full example: manage policy type

Get Policy Type

To retrieve the details about a policy type, you need to provide the name of it.

Full example: manage policy type

Managing Policies

A policy type can be treated as the meta-type of a Policy object. A registry of policy types is built when the Cluster service starts. When creating a Policy object, you will indicate the policy type used in its spec property.

List Policies

To examine the list of policies:

When listing policies, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage policy

Create Policy

When creating a policy, you will provide a dictionary with keys and values according to the policy type referenced.

Optionally, you can specify a metadata keyword argument that contains some key-value pairs to be associated with the policy.

Full example: manage policy

Find Policy

To find a policy based on its name or ID:

Full example: manage policy

Get Policy

To get a policy based on its name or ID:

Full example: manage policy

Update Policy

After a policy is created, most of its properties are immutable. Still, you can update a policy's name and/or metadata.

The Cluster service doesn't allow updating the spec of a policy. The only way to achieve that is to create a new policy.

Full example: manage policy

Delete Policy

A policy can be deleted after creation, provided that it is not referenced by any active clusters or nodes. If you attempt to delete a policy that is still in use, you will get an error message.

Managing Receivers

Receivers are the event sinks associated to senlin clusters. When certain events (or alarms) are seen by a monitoring software, the software can notify the senlin clusters of those events (or alarms). When senlin receives those notifications, it can automatically trigger some predefined operations with preset parameter values.

List Receivers

To examine the list of receivers:

When listing receivers, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage receiver

Create Receiver

When creating a receiver, you will provide a dictionary with keys and values according to the receiver type referenced.

Optionally, you can specify a metadata keyword argument that contains some key-value pairs to be associated with the receiver.

Full example: manage receiver

Get Receiver

To get a receiver based on its name or ID:

Full example: manage receiver

Find Receiver

To find a receiver based on its name or ID:

Full example: manage receiver

Update Receiver

After a receiver is created, most of its properties are immutable. Still, you can update a receiver's name and/or params.

Full example: manage receiver

Delete Receiver

A receiver can be deleted after creation, provided that it is not referenced by any active clusters. If you attempt to delete a receiver that is still in use, you will get an error message.

Working with Actions

An action is an abstraction of some logic that can be executed by a worker thread. Most of the operations supported by Senlin are executed asynchronously, which means they are queued into database and then picked up by certain worker thread for execution.

List Actions

To examine the list of actions:

When listing actions, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage action

Get Action

To get a action based on its name or ID:

Working with Events

An event is a record generated during engine execution. Such an event captures what has happened inside the senlin-engine. The senlin-engine service generates event records when it is performing some actions or checking policies.

List Events

To examine the list of events:

When listing events, you can specify the sorting option using the sort parameter and you can do pagination using the limit and marker parameters.

Full example: manage event

Get Event

To get a event based on its name or ID:

Using OpenStack Compute

Before working with the Compute service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

The primary resource of the Compute service is the server.

List Servers

A server is a virtual machine that provides access to a compute instance being run by your cloud provider.

Full example: compute resource list

List Images

An image is the operating system you want to use for your server.

Full example: compute resource list

List Flavors

A flavor is the resource configuration for a server. Each flavor is a unique combination of disk, memory, vCPUs, and network bandwidth.

Full example: compute resource list

List Networks

A network provides connectivity to servers.

Full example: network resource list

Create Key Pair

A key pair is the public key and private key of public–key cryptography. They are used to encrypt and decrypt login information when connecting to your server.

Full example: compute resource create

Create Server

At minimum, a server requires a name, an image, a flavor, and a network on creation. You can discover the names and IDs of these attributes by listing them as above and then using the find methods to get the appropriate resources.

Ideally you'll also create a server using a keypair so you can login to that server with the private key.

Servers take time to boot so we call wait_for_server to wait for it to become active.

Full example: compute resource create

Using OpenStack Database

Before working with the Database service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Using OpenStack DNS

Before working with the DNS service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

The primary resource of the DNS service is the server.

List Zones

Zone is a logical grouping of DNS records for a domain, allowing for the centralized management of DNS resources, including domain names, nameservers, and DNS queries.

Full example: dns resource list

List Recordsets

Recordsets allow for the centralized management of various DNS records within a Zone, helping to define how a domain responds to different types of DNS queries.

Full example: dns resource list

Create Zone

Create a zone. It allows users to define and manage the DNS namespace for a particular domain.

Full example: dns resource list

Create Recordset

Create a recordset. It accepts several parameters that define the DNS record's properties and sends an API request to OpenStack to create the recordset within a specified DNS zone.

Full example: dns resource list

Delete Zone

Delete a zone. It allows users to completely delete the DNS management for a specified domain.

Full example: dns resource list

Delete Recordset

Delete a recordset.

Full example: dns resource list

Find Zone

The find_zone function searches for and returns a DNS zone by its name using a given connection object.

Full example: dns resource list

Find Recordset

The find_recordset function searches for a DNS recordset with a specific name and type within a given zone. If multiple recordsets with the same name exist, the record type can be specified to find the exact match.

Full example: dns resource list

Using OpenStack Identity

Before working with the Identity service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

The OpenStack Identity service is the default identity management system for OpenStack. The Identity service authentication process confirms the identity of a user and an incoming request by validating a set of credentials that the user supplies. Initially, these credentials are a user name and password or a user name and API key. When the Identity service validates user credentials, it issues an authentication token that the user provides in subsequent requests. An authentication token is an alpha-numeric text string that enables access to OpenStack APIs and resources. A token may be revoked at any time and is valid for a finite duration.

List Users

A user is a digital representation of a person, system, or service that uses OpenStack cloud services. The Identity service validates that incoming requests are made by the user who claims to be making the call. Users have a login and can access resources by using assigned tokens. Users can be directly assigned to a particular project and behave as if they are contained in that project.

Full example: identity resource list

List Credentials

Credentials are data that confirms the identity of the user. For example, user name and password, user name and API key, or an authentication token that the Identity service provides.

Full example: identity resource list

List Projects

A project is a container that groups or isolates resources or identity objects.

Full example: identity resource list

List Domains

A domain is an Identity service API v3 entity and represents a collection of projects and users that defines administrative boundaries for the management of Identity entities. Users can be granted the administrator role for a domain. A domain administrator can create projects, users, and groups in a domain and assign roles to users and groups in a domain.

Full example: identity resource list

List Groups

A group is an Identity service API v3 entity and represents a collection of users that are owned by a domain. A group role granted to a domain or project applies to all users in the group. Adding users to, or removing users from, a group respectively grants, or revokes, their role and authentication to the associated domain or project.

Full example: identity resource list

List Services

A service is an OpenStack service, such as Compute, Object Storage, or Image service, that provides one or more endpoints through which users can access resources and perform operations.

Full example: identity resource list

List Endpoints

An endpoint is a network-accessible address, usually a URL, through which you can access a service.

Full example: identity resource list

List Regions

A region is an Identity service API v3 entity and represents a general division in an OpenStack deployment. You can associate zero or more sub-regions with a region to make a tree-like structured hierarchy.

Full example: identity resource list

Using OpenStack Image

Before working with the Image service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

The primary resource of the Image service is the image.

List Images

An image is a collection of files for a specific operating system that you use to create or rebuild a server. OpenStack provides pre-built images. You can also create custom images, or snapshots, from servers that you have launched. Images come in different formats and are sometimes called virtual machine images.

Full example: image resource list

Create Image

Create an image by uploading its data and setting its attributes.

Full example: image resource create

Create Image via interoperable image import process

Create an image then use interoperable image import process to download data from a web URL.

For more information about the image import process, please check interoperable image import

Full example: image resource import

Downloading an Image with stream=True

As images are often very large pieces of data, storing their entire contents in the memory of your application can be less than desirable. A more efficient method may be to iterate over a stream of the response data.

By choosing to stream the response content, you determine the chunk_size that is appropriate for your needs, meaning only that many bytes of data are read for each iteration of the loop until all data has been consumed. See requests.Response.iter_content() for more information.

When you choose to stream an image download, openstacksdk is no longer able to compute the checksum of the response data for you. This example shows how you might do that yourself, in a very similar manner to how the library calculates checksums for non-streamed responses.

Downloading an Image with stream=False

If you wish to download an image's contents all at once and to memory, simply set stream=False, which is the default.

Full example: image resource download

Delete Image

Delete an image.

Full example: image resource delete

Using OpenStack Key Manager

Before working with the Key Manager service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

NOTE:

Create a Secret

The Key Manager service allows you to create new secrets by passing the attributes of the Secret to the create_secret() method.

List Secrets

Once you have stored some secrets, they are available for you to list via the secrets() method. This method returns a generator, which yields each Secret.

The secrets() method can also make more advanced queries to limit the secrets that are returned.

Get Secret Payload

Once you have received a Secret, you can obtain the payload for it by passing the secret's id value to the secrets() method. Use the secret_id attribute when making this request.

Using OpenStack Message

Before working with the Message service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Using OpenStack Network

Before working with the Network service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

The primary resource of the Network service is the network.

List Networks

A network is an isolated Layer 2 networking segment. There are two types of networks, project and provider networks. Project networks are fully isolated and are not shared with other projects. Provider networks map to existing physical networks in the data center and provide external network access for servers. Only an OpenStack administrator can create provider networks. Networks can be connected via routers.

Full example: network resource list

List Subnets

A subnet is a block of IP addresses and associated configuration state. Subnets are used to allocate IP addresses when new ports are created on a network.

Full example: network resource list

List Ports

A port is a connection point for attaching a single device, such as the NIC of a server, to a network. The port also describes the associated network configuration, such as the MAC and IP addresses to be used on that port.

Full example: network resource list

List Security Groups

A security group acts as a virtual firewall for servers. It is a container for security group rules which specify the type of network traffic and direction that is allowed to pass through a port.

Full example: network resource list

List Routers

A router is a logical component that forwards data packets between networks. It also provides Layer 3 and NAT forwarding to provide external network access for servers on project networks.

Full example: network resource list

List Network Agents

A network agent is a plugin that handles various tasks used to implement virtual networks. These agents include neutron-dhcp-agent, neutron-l3-agent, neutron-metering-agent, and neutron-lbaas-agent, among others.

Full example: network resource list

Create Network

Create a project network and subnet. This network can be used when creating a server and allows the server to communicate with others servers on the same project network.

Full example: network resource create

Open a Port

When creating a security group for a network, you will need to open certain ports to allow communication via them. For example, you may need to enable HTTPS access on port 443.

Full example: network security group create

Accept Pings

In order to ping a machine on your network within a security group, you will need to create a rule to allow inbound ICMP packets.

Full example: network security group create

Delete Network

Delete a project network and its subnets.

Full example: network resource delete

Using OpenStack Object Store

Before working with the Object Store service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

The primary resources of the Object Store service are containers and objects.

Working with Containers

Listing Containers

To list existing containers, use the containers() method.

>>> for cont in conn.object_store.containers():
...     print cont
...
openstack.object_store.v1.container.Container: {u'count': 5,
u'bytes': 500, u'name': u'my container'}
openstack.object_store.v1.container.Container: {u'count': 0,
u'bytes': 0, u'name': u'empty container'}
openstack.object_store.v1.container.Container: {u'count': 100,
u'bytes': 1000000, u'name': u'another container'}

The containers method returns a generator which yields Container objects. It handles pagination for you, which can be adjusted via the limit argument. By default, the containers method will yield as many containers as the service will return, and it will continue requesting until it receives no more.

>>> for cont in conn.object_store.containers(limit=500):
...     print(cont)
...
<500 Containers>
... another request transparently made to the Object Store service
<500 more Containers>
...

Creating Containers

To create a container, use the create_container() method.

>>> cont = conn.object_store.create_container(name="new container")
>>> cont
openstack.object_store.v1.container.Container: {'name': u'new container'}

Working with Container Metadata

To get the metadata for a container, use the get_container_metadata() method. This method either takes the name of a container, or a Container object, and it returns a Container object with all of its metadata attributes set.

>>> cont = conn.object_store.get_container_metadata("new container")
openstack.object_store.v1.container.Container: {'content-length': '0',
'x-container-object-count': '0', 'name': u'new container',
'accept-ranges': 'bytes',
'x-trans-id': 'tx22c5de63466e4c05bb104-0054740c39',
'date': 'Tue, 25 Nov 2014 04:57:29 GMT',
'x-timestamp': '1416889793.23520', 'x-container-read': '.r:mysite.com',
'x-container-bytes-used': '0', 'content-type': 'text/plain; charset=utf-8'}

To set the metadata for a container, use the set_container_metadata() method. This method takes a Container object. For example, to grant another user write access to this container, you can call set_container_metadata passing it the Container to update and keyward argument key/value pairs representing the metadata name and value to set.

>>> acl = "big_project:another_user"
>>> conn.object_store.set_container_metadata(cont, write_ACL=acl)
openstack.object_store.v1.container.Container: {'content-length': '0',
'x-container-object-count': '0',
'name': u'my new container', 'accept-ranges': 'bytes',
'x-trans-id': 'txc3ee751f971d41de9e9f4-0054740ec1',
'date': 'Tue, 25 Nov 2014 05:08:17 GMT',
'x-timestamp': '1416889793.23520', 'x-container-read': '.r:mysite.com',
'x-container-bytes-used': '0', 'content-type': 'text/plain; charset=utf-8',
'x-container-write': 'big_project:another_user'}

Working with Objects

Objects are held in containers. From an API standpoint, you work with them using similarly named methods, typically with an additional argument to specify their container.

Listing Objects

To list the objects that exist in a container, use the objects() method.

If you have a Container object, you can pass it to objects.

>>> print cont.name
pictures
>>> for obj in conn.object_store.objects(cont):
...     print obj
...
openstack.object_store.v1.container.Object:
{u'hash': u'0522d4ccdf9956badcb15c4087a0c4cb',
u'name': u'pictures/selfie.jpg', u'bytes': 15744,
'last-modified': u'2014-10-31T06:33:36.618640',
u'last_modified': u'2014-10-31T06:33:36.618640',
u'content_type': u'image/jpeg', 'container': u'pictures',
'content-type': u'image/jpeg'}
...

Similar to the containers() method, objects returns a generator which yields Object objects stored in the container. It also handles pagination for you, which you can adjust with the limit parameter, otherwise making each request for the maximum that your Object Store will return.

If you have the name of a container instead of an object, you can also pass that to the objects method.

>>> for obj in conn.object_store.objects("pictures".decode("utf8"),


                                         limit=100):
...     print obj
...
<100 Objects>
... another request transparently made to the Object Store service
<100 more Objects>

Getting Object Data

Once you have an Object, you get the data stored inside of it with the get_object_data() method.

>>> print ob.name
message.txt
>>> data = conn.object_store.get_object_data(ob)
>>> print data
Hello, world!

Additionally, if you want to save the object to disk, the download_object() convenience method takes an Object and a path to write the contents to.

>>> conn.object_store.download_object(ob, "the_message.txt")

Uploading Objects

Once you have data you'd like to store in the Object Store service, you use the upload_object() method. This method takes the data to be stored, along with at least an object name and the container it is to be stored in.

>>> hello = conn.object_store.upload_object(container="messages",


                                            name="helloworld.txt",


                                            data="Hello, world!")
>>> print hello
openstack.object_store.v1.container.Object: {'content-length': '0',
'container': u'messages', 'name': u'helloworld.txt',
'last-modified': 'Tue, 25 Nov 2014 17:39:29 GMT',
'etag': '5eb63bbbe01eeed093cb22bb8f5acdc3',
'x-trans-id': 'tx3035d41b03334aeaaf3dd-005474bed0',
'date': 'Tue, 25 Nov 2014 17:39:28 GMT',
'content-type': 'text/html; charset=UTF-8'}

Working with Object Metadata

Working with metadata on objects is identical to how it's done with containers. You use the get_object_metadata() and set_object_metadata() methods.

The metadata attributes to be set can be found on the Object object.

>>> secret.delete_after = 300
>>> secret = conn.object_store.set_object_metadata(secret)

We set the delete_after value to 500 seconds, causing the object to be deleted in 300 seconds, or five minutes. That attribute corresponds to the X-Delete-After header value, which you can see is returned when we retrieve the updated metadata.

>>> conn.object_store.get_object_metadata(ob)
openstack.object_store.v1.container.Object: {'content-length': '11',
'container': u'Secret Container',
'name': u'selfdestruct.txt', 'x-delete-after': 300,
'accept-ranges': 'bytes', 'last-modified': 'Tue, 25 Nov 2014 17:50:45 GMT',
'etag': '5eb63bbbe01eeed093cb22bb8f5acdc3',
'x-timestamp': '1416937844.36805',
'x-trans-id': 'tx5c3fd94adf7c4e1b8f334-005474c17b',
'date': 'Tue, 25 Nov 2014 17:50:51 GMT', 'content-type': 'text/plain'}

Using OpenStack Orchestration

Before working with the Orchestration service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Using OpenStack Shared File Systems

Before working with the Shared File System service, you'll need to create a connection to your OpenStack cloud by following the Connect user guide. This will provide you with the conn variable used in the examples below.

Table of Contents

List Availability Zones

A Shared File System service availability zone is a failure domain for your shared file systems. You may create a shared file system (referred to simply as shares) in a given availability zone, and create replicas of the share in other availability zones.

Share Instances

Administrators can list, show information for, explicitly set the state of, and force-delete share instances.

Get Share Instance

Shows details for a single share instance.

Reset Share Instance Status

Explicitly updates the state of a share instance.

Delete Share Instance

Force-deletes a share instance.

Resize Share

Shared File System shares can be resized (extended or shrunk) to a given size. For details on resizing shares, refer to the Manila docs.

List Share Group Snapshots

A share group snapshot is a point-in-time, read-only copy of the data that is contained in a share group. You can list all share group snapshots

Get Share Group Snapshot

Show share group snapshot details

List Share Group Snapshot Members

Lists all share group snapshots members.

Create Share Group Snapshot

Creates a snapshot from a share group.

Reset Share Group Snapshot

Reset share group snapshot state.

Update Share Group Snapshot

Updates a share group snapshot.

Delete Share Group Snapshot

Deletes a share group snapshot.

List Share Metadata

Lists all metadata for a given share.

Get Share Metadata Item

Retrieves a specific metadata item from a shares metadata by its key.

Create Share Metadata

Creates share metadata.

Update Share Metadata

Updates metadata of a given share.

Delete Share Metadata

Deletes a specific metadata item from a shares metadata by its key. Can specify multiple keys to be deleted.

Manage Share

Manage a share with Manila.

Unmanage Share

Unmanage a share from Manila.

Testing

The SDK provides a number of utilities to help you test your applications.

Testing applications using OpenStack SDK

Fakes

The fakes module exists to help application developers using the OpenStack SDK to unit test their applications. It provides a number of helper utilities to generate fake Resource and Proxy instances. These fakes do not require an established connection and allow you to validate that your application using valid attributes and methods for both Resource and Proxy instances.

>>> from openstack.compute.v2 import server
>>> from openstack.test import fakes
>>> fakes.generate_fake_resource(server.Server)
openstack.compute.v2.server.Server(...)

>>> from openstack.compute.v2 import server
>>> from openstack.test import fakes
>>> fakes.generate_fake_resources(server.Server, count=3)
<generator object generate_fake_resources at 0x7f075dc65040>

>>> import functools
>>> from openstack.compute import compute_service
>>> from openstack.compute.v2 import server
>>> from openstack.test import fakes
>>> # create the fake proxy
>>> fake_compute_proxy = fakes.generate_fake_proxy(
...    compute_service.ComputeService,
... )
>>> # configure return values for various proxy APIs
>>> # note that this will generate new fake resources on each invocation
>>> fake_compute_proxy.get_server.side_effect = functools.partial(
...     fakes.generate_fake_resource,
...     server.Server,
... )
>>> fake_compute_proxy.servers.side_effect = functools.partial(
...     fakes.generate_fake_resources,
...     server.Server,
... )
>>> fake_compute_proxy.servers()
<generator object generate_fake_resources at 0x7f92768dc040>
>>> fake_compute_proxy.serverssss()
Traceback (most recent call last):


  File "<stdin>", line 1, in <module>


  File "/usr/lib64/python3.11/unittest/mock.py", line 653, in __getattr__


    raise AttributeError("Mock object has no attribute %r" % name)
AttributeError: Mock object has no attribute 'serverssss'. Did you mean: 'server_ips'?

API Documentation

Service APIs are exposed through a two-layered approach. The classes exposed through our Connection interface are the place to start if you're an application developer consuming an OpenStack cloud. The Resource interface is the layer upon which the Connection is built, with Connection methods accepting and returning Resource objects.

The Cloud Abstraction layer has a data model.

Data Model

openstacksdk has a very strict policy on not breaking backwards compatibility ever. However, with the data structures returned from OpenStack, there are places where the resource structures from OpenStack are returned to the user somewhat directly, leaving an openstacksdk user open to changes/differences in result content.

To combat that, openstacksdk 'normalizes' the return structure from OpenStack in many places, and the results of that normalization are listed below. Where openstacksdk performs normalization, a user can count on any fields declared in the docs as being completely safe to use - they are as much a part of openstacksdk's API contract as any other Python method.

Some OpenStack objects allow for arbitrary attributes at the root of the object. openstacksdk will pass those through so as not to break anyone who may be counting on them, but as they are arbitrary openstacksdk can make no guarantees as to their existence. As part of normalization, openstacksdk will put any attribute from an OpenStack resource that is not in its data model contract into an attribute called 'properties'. The contents of properties are defined to be an arbitrary collection of key value pairs with no promises as to any particular key ever existing.

If a user passes strict=True to the openstacksdk constructor, openstacksdk will not pass through arbitrary objects to the root of the resource, and will instead only put them in the properties dict. If a user is worried about accidentally writing code that depends on an attribute that is not part of the API contract, this can be a useful tool. Keep in mind all data can still be accessed via the properties dict, but any code touching anything in the properties dict should be aware that the keys found there are highly user/cloud specific. Any key that is transformed as part of the openstacksdk data model contract will not wind up with an entry in properties - only keys that are unknown.

The location field

A Location defines where a resource lives. It includes a cloud name and a region name, an availability zone as well as information about the project that owns the resource.

The project information may contain a project ID, or a combination of one or more of a project name with a domain name or ID. If a project ID is present, it should be considered correct.

Some resources do not carry ownership information with them. For those, the project information will be filled in from the project the user currently has a token for.

Some resources do not have information about availability zones, or may exist region wide. Those resources will have None as their availability zone.

Location = dict(


    cloud=str(),


    region_name=str(),


    zone=str() or None,


    project=dict(


        id=str() or None,


        name=str() or None,


        domain_id=str() or None,


        domain_name=str() or None,


    )
)

Connection Interface

A Connection instance maintains your cloud config, session and authentication information providing you with a set of higher-level interfaces to work with OpenStack services.

Connection

The Connection class is the primary interface to the Python SDK. It maintains a context for a connection to a region of a cloud provider. The Connection has an attribute to access each OpenStack service.

At a minimum, the Connection class needs to be created with a config or the parameters to build one.

While the overall system is very flexible, there are four main use cases for different ways to create a Connection.

Creating the Connection

Using config settings

For users who want to create a Connection making use of named clouds in clouds.yaml files, OS_ environment variables and python keyword arguments, the openstack.connect() factory function is the recommended way to go:

import openstack
conn = openstack.connect(cloud='example', region_name='earth1')

If the application in question is a command line application that should also accept command line arguments, an argparse.Namespace can be passed to openstack.connect() that will have relevant arguments added to it and then subsequently consumed by the constructor:

import argparse
import openstack
options = argparse.ArgumentParser(description='Awesome OpenStack App')
conn = openstack.connect(options=options)

Using only keyword arguments

If the application wants to avoid loading any settings from clouds.yaml or environment variables, use the Connection constructor directly. As long as the cloud argument is omitted or None, the Connection constructor will not load settings from files or the environment.

NOTE:

from openstack import connection
conn = connection.Connection(


    region_name='example-region',


    auth={


        'auth_url': 'https://auth.example.com',


        'username': 'amazing-user',


        'password': 'super-secret-password',


        'project_id': '33aa1afc-03fe-43b8-8201-4e0d3b4b8ab5',


        'user_domain_id': '054abd68-9ad9-418b-96d3-3437bb376703',


    },


    compute_api_version='2',


    identity_interface='internal',
)

Per-service settings as needed by keystoneauth1.adapter.Adapter such as api_version, service_name, and interface can be set, as seen above, by prefixing them with the official service-type name of the service. region_name is a setting for the entire CloudRegion and cannot be set per service.

From existing authenticated Session

For applications that already have an authenticated Session, simply passing it to the Connection constructor is all that is needed:

from openstack import connection
conn = connection.Connection(


    session=session,


    region_name='example-region',


    compute_api_version='2',


    identity_interface='internal',
)

From oslo.conf CONF object

For applications that have an oslo.config CONF object that has been populated with keystoneauth1.loading.register_adapter_conf_options in groups named by the OpenStack service's project name, it is possible to construct a Connection with the CONF object and an authenticated Session.

NOTE:

from keystoneauth1 import loading as ks_loading
from openstack import connection
from oslo_config import cfg
CONF = cfg.CONF
group = cfg.OptGroup('neutron')
ks_loading.register_session_conf_options(CONF, group)
ks_loading.register_auth_conf_options(CONF, group)
ks_loading.register_adapter_conf_options(CONF, group)
CONF()
auth = ks_loading.load_auth_from_conf_options(CONF, 'neutron')
sess = ks_loading.load_session_from_conf_options(CONF, 'neutron', auth=auth)
conn = connection.Connection(


    session=sess,


    oslo_conf=CONF,
)

This can then be used with an appropriate configuration file.

[neutron]
region_name = RegionOne
auth_strategy = keystone
project_domain_name = Default
project_name = service
user_domain_name = Default
password = password
username = neutron
auth_url = http://10.0.110.85/identity
auth_type = password
service_metadata_proxy = True
default_floating_pool = public

You may also wish to configure a service user. As discussed in the Keystone documentation, service users are users with specific roles that identify the user as a service. The use of service users can avoid issues caused by the expiration of the original user's token during long running operations, as a fresh token issued for the service user will always accompany the user's token, which may have expired.

from keystoneauth1 import loading as ks_loading
from keystoneauth1 import service_token
from oslo_config import cfg
import openstack
from openstack import connection
CONF = cfg.CONF
neutron_group = cfg.OptGroup('neutron')
ks_loading.register_session_conf_options(CONF, neutron_group)
ks_loading.register_auth_conf_options(CONF, neutron_group)
ks_loading.register_adapter_conf_options(CONF, neutron_group)
service_group = cfg.OptGroup('service_user')
ks_loading.register_session_conf_options(CONF, service_group)
ks_loading.register_auth_conf_options(CONF, service_group)
CONF()
user_auth = ks_loading.load_auth_from_conf_options(CONF, 'neutron')
service_auth = ks_loading.load_auth_from_conf_options(CONF, 'service_user')
auth = service_token.ServiceTokenAuthWrapper(user_auth, service_auth)
sess = ks_loading.load_session_from_conf_options(CONF, 'neutron', auth=auth)
conn = connection.Connection(


    session=sess,


    oslo_conf=CONF,
)

This will necessitate an additional section in the configuration file used.

[service_user]
auth_strategy = keystone
project_domain_name = Default
project_name = service
user_domain_name = Default
password = password
username = nova
auth_url = http://10.0.110.85/identity
auth_type = password

From existing CloudRegion

If you already have an CloudRegion you can pass it in instead:

from openstack import connection
import openstack.config
config = openstack.config.get_cloud_region(


    cloud='example',


    region_name='earth',
)
conn = connection.Connection(config=config)

Using the Connection

Services are accessed through an attribute named after the service's official service-type.

List

An iterator containing a list of all the projects is retrieved in this manner:

projects = conn.identity.projects()

Find or create

If you wanted to make sure you had a network named 'zuul', you would first try to find it and if that fails, you would create it:

network = conn.network.find_network("zuul")
if network is None:


    network = conn.network.create_network(name="zuul")

Additional information about the services can be found in the Service Proxies documentation.

from_config

Connection Object

conn = openstack.connect(cloud='example')
# Work normally
servers = conn.list_servers()
conn2 = conn.connect_as(username='different-user', password='')
# Work as different-user
servers = conn2.list_servers()

cloud = openstack.connect(cloud='example')
# Work normally
servers = cloud.list_servers()
cloud2 = cloud.connect_as_project('different-project')
# Work in different-project
servers = cloud2.list_servers()

{'network_type': 'vlan', 'segmentation_id': 'vlan1'}

[


    {


        "ip_address": "10.29.29.13",


        "subnet_id": "a78484c4-c380-4b47-85aa-21c51a2d8cbd",


    },


    ...,
]

[


    {


        "ip_address": "23.23.23.1",


        "mac_address": "fa:16:3e:c4:cd:3f",


    },


    ...,
]

[{"opt_name": "opt name1", "opt_value": "value1"}, ...]

[


    {


        "subnet_id": "8ca37218-28ff-41cb-9b10-039601ea7e6b",


        "ip_address": "192.168.10.2",


    }
]

[{"start": "192.168.199.2", "end": "192.168.199.254"}]

["8.8.8.7", "8.8.8.8"]

[


    {"destination": "0.0.0.0/0", "nexthop": "123.456.78.9"},


    {"destination": "192.168.0.0/24", "nexthop": "192.168.0.1"},
]

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{


    'availability_zone': 'nova',


    'metadata': {'cpu_allocation_ratio': '1.0'},
}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

"[?last_name==`Smith`] | [?other.gender]==`Female`]"

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}

{'last_name': 'Smith', 'other': {'gender': 'Female'}}