4bad718783
This is a large and invasive change to the underlying guts. Most casual use should not notice a difference, but advanced users, especially those using the Profile or Authenticator interfaces or making use of pluggable providers will be broken. The overall intent is to align directly on top of the mechanisms that came from os-client-config for config and to use keystoneauth1's Adapter interface to make use of the canonical implementations of such things as service and version discovery. The end goal is that openstacksdk provides the REST interaction layer for python-openstackclient, shade, Ansible and nodepool. Replace profile with openstack.config os-client-config is used by shade and python-openstackclient to read and process configuration. openstacksdk also can use the os-client-config interface, but translates it internally into the Profile object. As os-client-config has been injested into openstack.config, remove Profile and just use the config classes. Make proxy subclass of adapter This gives every service a generic passthrough for REST calls, which means we can map unknown service-type values to a generic proxy. Strip endpoint_filter We're passing Adapters around, not sessions. Doing so means that self.service and endpoint_filter have become unnecessary. Rename _Request.uri to _Request.url This is a stepping-stone to replacing _Request with requests.Request and using requests.Session.prepare_request inside of _prepare_request. Rename service proxy instances to match their official service-type. Aliases are kept for the old versions, but make the canonical versions match the official name. Rename bare_metal to baremetal Rename cluster to clustering Rename block_store to block_storage Rename telemetry to meter Create generic proxies for all services in STA Every service listed in service types authority is an OpenStack service. Even if we don't know about it in SDK, we should at the very least have a low-level Adapter for it so that people can use REST calls while waiting on the SDK to add higher-level constructs. The pypy jobs are happily green. Run them as voting rather than non-voting. Add syntatic sugar alias for making connections Typing: import openstack.connection conn = openstack.connection.Connection(cloud='example') is annoying. This allows: import openstack conn = openstack.connect(cloud='example') Use task_manager and Adapter from shade As a stepping-stone towards shade and sdk codepaths being rationalized, we need to get SDK using the Adapter from shade that submits requests into the TaskManager. For normal operation this is a passthrough/no-op sort of thing, but it's essential for high-volume consumers such as nodepool. This exposes a bunch of places in tests where we're mocking a bit too deeply. We should go back through and fix all of those via requests_mock, but that's WAY too much for today. This was a 'for later' task, but it turns out that the move to Adapter was causing exceptions to be thrown that were not the exceptions that were intended to be caught in the SDK layer, which was causing functional tests of things like GET operations to fail. So it became a today task. Change-Id: I7b46e263a76d84573bdfbbece57b1048764ed939
140 lines
4.3 KiB
ReStructuredText
140 lines
4.3 KiB
ReStructuredText
Getting started with the OpenStack SDK
|
|
======================================
|
|
|
|
For a listing of terms used throughout the SDK, including the names of
|
|
projects and services supported by it, see the :doc:`glossary <../glossary>`.
|
|
|
|
Installation
|
|
------------
|
|
|
|
The OpenStack SDK is available on
|
|
`PyPI <https://pypi.python.org/pypi/openstacksdk>`_ under the name
|
|
**openstacksdk**. To install it, use ``pip``::
|
|
|
|
$ pip install openstacksdk
|
|
|
|
.. _user_guides:
|
|
|
|
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.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
Connect to an OpenStack Cloud <guides/connect>
|
|
Connect to an OpenStack Cloud Using a Config File <guides/connect_from_config>
|
|
Logging <guides/logging>
|
|
Baremetal <guides/baremetal>
|
|
Block Storage <guides/block_storage>
|
|
Clustering <guides/clustering>
|
|
Compute <guides/compute>
|
|
Database <guides/database>
|
|
Identity <guides/identity>
|
|
Image <guides/image>
|
|
Key Manager <guides/key_manager>
|
|
Message <guides/message>
|
|
Meter <guides/meter>
|
|
Network <guides/network>
|
|
Object Store <guides/object_store>
|
|
Orchestration <guides/orchestration>
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
connection
|
|
|
|
Once you have a *Connection* instance, the following services may be exposed
|
|
to you. The combination of your ``CloudConfig`` and the catalog of the cloud
|
|
in question control which services are exposed, but listed below are the ones
|
|
provided by the SDK.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
Baremetal <proxies/baremetal>
|
|
Block Storage <proxies/block_storage>
|
|
Clustering <proxies/clustering>
|
|
Compute <proxies/compute>
|
|
Database <proxies/database>
|
|
Identity v2 <proxies/identity_v2>
|
|
Identity v3 <proxies/identity_v3>
|
|
Image v1 <proxies/image_v1>
|
|
Image v2 <proxies/image_v2>
|
|
Key Manager <proxies/key_manager>
|
|
Load Balancer <proxies/load_balancer_v2>
|
|
Message v1 <proxies/message_v1>
|
|
Message v2 <proxies/message_v2>
|
|
Network <proxies/network>
|
|
Meter <proxies/meter>
|
|
Metric <proxies/metric>
|
|
Object Store <proxies/object_store>
|
|
Orchestration <proxies/orchestration>
|
|
Workflow <proxies/workflow>
|
|
|
|
Resource Interface
|
|
******************
|
|
|
|
The *Resource* layer is a lower-level interface to communicate with OpenStack
|
|
services. While the classes exposed by the *Connection* build a convenience
|
|
layer on top of this, *Resources* can be used directly. However, the most
|
|
common usage of this layer is in receiving an object from a class in the
|
|
*Connection* layer, modifying it, and sending it back into the *Connection*
|
|
layer, such as to update a resource on the server.
|
|
|
|
The following services have exposed *Resource* classes.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
Baremetal <resources/baremetal/index>
|
|
Block Storage <resources/block_storage/index>
|
|
Clustering <resources/clustering/index>
|
|
Compute <resources/compute/index>
|
|
Database <resources/database/index>
|
|
Identity <resources/identity/index>
|
|
Image <resources/image/index>
|
|
Key Management <resources/key_manager/index>
|
|
Load Balancer <resources/load_balancer/index>
|
|
Meter <resources/meter/index>
|
|
Metric <resources/metric/index>
|
|
Network <resources/network/index>
|
|
Orchestration <resources/orchestration/index>
|
|
Object Store <resources/object_store/index>
|
|
Workflow <resources/workflow/index>
|
|
|
|
Low-Level Classes
|
|
*****************
|
|
|
|
The following classes are not commonly used by application developers,
|
|
but are used to construct applications to talk to OpenStack APIs. Typically
|
|
these parts are managed through the `Connection Interface`_, but their use
|
|
can be customized.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
resource
|
|
resource2
|
|
service_filter
|
|
utils
|