README: Add guide on raw HTTP layer
Highlight that one can do e.g. `conn.compute.get('/servers')`. You almost certainly *don't want* to do this, but it can be helpful (see: our support for Nova's os-hypervisors API in OSC). The flow of the README is modified slightly so we go sequentially from high-level layers to low-level layers. Rubrics (header-like elements that don't produce anchors or appear in tables of contents) are also added to produce improve information hierarchy. Change-Id: Ifd4a5a2c753f6698fa4384a197e81cc5383ef312 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
parent
6dbc7e9e94
commit
81d60c7874
113
README.rst
113
README.rst
@ -20,6 +20,8 @@ https://docs.openstack.org/openstacksdk/latest/contributor/history.html
|
|||||||
Getting started
|
Getting started
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
|
.. rubric:: Authentication and connection management
|
||||||
|
|
||||||
openstacksdk aims to talk to any OpenStack cloud. To do this, it requires a
|
openstacksdk aims to talk to any OpenStack cloud. To do this, it requires a
|
||||||
configuration file. openstacksdk favours ``clouds.yaml`` files, but can also
|
configuration file. openstacksdk favours ``clouds.yaml`` files, but can also
|
||||||
use environment variables. The ``clouds.yaml`` file should be provided by your
|
use environment variables. The ``clouds.yaml`` file should be provided by your
|
||||||
@ -38,29 +40,43 @@ cloud provider or deployment tooling. An example:
|
|||||||
|
|
||||||
openstacksdk will look for ``clouds.yaml`` files in the following locations:
|
openstacksdk will look for ``clouds.yaml`` files in the following locations:
|
||||||
|
|
||||||
|
* If set, the path indicated by the ``OS_CLIENT_CONFIG_FILE`` environment
|
||||||
|
variable
|
||||||
* ``.`` (the current directory)
|
* ``.`` (the current directory)
|
||||||
* ``$HOME/.config/openstack``
|
* ``$HOME/.config/openstack``
|
||||||
* ``/etc/openstack``
|
* ``/etc/openstack``
|
||||||
|
|
||||||
openstacksdk consists of three layers. Most users will make use of the *proxy*
|
You can create a connection using the ``openstack.connect`` function. The cloud
|
||||||
layer. Using the above ``clouds.yaml``, consider listing servers:
|
name can be either passed directly to this function or specified using the
|
||||||
|
``OS_CLOUD`` environment variable. If you don't have a ``clouds.yaml`` file and
|
||||||
|
instead use environment variables for configuration then you can use the
|
||||||
|
special ``envvars`` cloud name to load configuration from the environment. For
|
||||||
|
example:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
import openstack
|
import openstack
|
||||||
|
|
||||||
# Initialize and turn on debug logging
|
# Initialize connection from a clouds.yaml by passing a cloud name
|
||||||
openstack.enable_logging(debug=True)
|
conn_from_cloud_name = openstack.connect(cloud='mordred')
|
||||||
|
|
||||||
# Initialize connection
|
# Initialize connection from a clouds.yaml using the OS_CLOUD envvar
|
||||||
conn = openstack.connect(cloud='mordred')
|
conn_from_os_cloud = openstack.connect()
|
||||||
|
|
||||||
# List the servers
|
# Initialize connection from environment variables
|
||||||
for server in conn.compute.servers():
|
conn_from_env_vars = openstack.connect(cloud='envvars')
|
||||||
print(server.to_dict())
|
|
||||||
|
|
||||||
openstacksdk also contains a higher-level *cloud* layer based on logical
|
.. note::
|
||||||
operations:
|
|
||||||
|
How this is all achieved is described in more detail `below
|
||||||
|
<openstack.config>`__.
|
||||||
|
|
||||||
|
.. rubric:: The cloud layer
|
||||||
|
|
||||||
|
openstacksdk consists of four layers which all build on top of each other. The
|
||||||
|
highest level layer is the *cloud* layer. Cloud layer methods are available via
|
||||||
|
the top level ``Connection`` object returned by ``openstack.connect``. For
|
||||||
|
example:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
@ -76,8 +92,10 @@ operations:
|
|||||||
for server in conn.list_servers():
|
for server in conn.list_servers():
|
||||||
print(server.to_dict())
|
print(server.to_dict())
|
||||||
|
|
||||||
The benefit of this layer is mostly seen in more complicated operations that
|
The cloud layer is based on logical operations that can potentially touch
|
||||||
take multiple steps and where the steps vary across providers. For example:
|
multiple services. 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:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
@ -101,9 +119,38 @@ take multiple steps and where the steps vary across providers. For example:
|
|||||||
conn.create_server(
|
conn.create_server(
|
||||||
'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
|
'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
|
||||||
|
|
||||||
Finally, there is the low-level *resource* layer. This provides support for the
|
.. rubric:: The proxy layer
|
||||||
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:
|
The next layer is the *proxy* layer. Most users will make use of this layer.
|
||||||
|
The proxy layer is service-specific, so methods will be available under
|
||||||
|
service-specific connection attributes of the ``Connection`` object such as
|
||||||
|
``compute``, ``block_storage``, ``image`` etc. For example:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
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())
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
A list of supported services is given `below <supported-services>`__.
|
||||||
|
|
||||||
|
.. rubric:: The resource layer
|
||||||
|
|
||||||
|
Below this there is the *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 but it can be
|
||||||
|
helpful for operations where you already have a ``Resource`` object to hand.
|
||||||
|
For example:
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
@ -121,6 +168,34 @@ the other layers. You typically will not need to use this directly:
|
|||||||
for server in openstack.compute.v2.server.Server.list(session=conn.compute):
|
for server in openstack.compute.v2.server.Server.list(session=conn.compute):
|
||||||
print(server.to_dict())
|
print(server.to_dict())
|
||||||
|
|
||||||
|
.. rubric:: The raw HTTP layer
|
||||||
|
|
||||||
|
Finally, there is the *raw HTTP* layer. This exposes raw HTTP semantics and
|
||||||
|
is effectively a wrapper around the `requests`__ API with added smarts to
|
||||||
|
handle stuff like authentication and version management. As such, you can use
|
||||||
|
the ``requests`` API methods you know and love, like ``get``, ``post`` and
|
||||||
|
``put``, and expect to receive a ``requests.Response`` object in response
|
||||||
|
(unlike the other layers, which mostly all return objects that subclass
|
||||||
|
``openstack.resource.Resource``). Like the *resource* layer, you will typically
|
||||||
|
not need to use this directly but it can be helpful to interact with APIs that
|
||||||
|
have not or will not be supported by openstacksdk. For example:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
import openstack
|
||||||
|
|
||||||
|
# Initialize and turn on debug logging
|
||||||
|
openstack.enable_logging(debug=True)
|
||||||
|
|
||||||
|
# Initialize connection
|
||||||
|
conn = openstack.connect(cloud='mordred')
|
||||||
|
|
||||||
|
# List servers
|
||||||
|
for server in openstack.compute.get('/servers').json():
|
||||||
|
print(server)
|
||||||
|
|
||||||
|
.. __: https://requests.readthedocs.io/en/latest/
|
||||||
|
|
||||||
.. _openstack.config:
|
.. _openstack.config:
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
@ -145,14 +220,14 @@ environment by running ``openstack.config.loader``. For example:
|
|||||||
|
|
||||||
More information at https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html
|
More information at https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html
|
||||||
|
|
||||||
|
.. _supported-services:
|
||||||
|
|
||||||
Supported services
|
Supported services
|
||||||
------------------
|
------------------
|
||||||
|
|
||||||
The following services are currently supported. A full list of all available
|
The following services are currently supported. A full list of all available
|
||||||
OpenStack service can be found in the `Project Navigator`__.
|
OpenStack service can be found in the `Project Navigator`__.
|
||||||
|
|
||||||
.. __: https://www.openstack.org/software/project-navigator/openstack-components#openstack-services
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Support here does not guarantee full-support for all APIs. It simply means
|
Support here does not guarantee full-support for all APIs. It simply means
|
||||||
@ -302,6 +377,8 @@ OpenStack service can be found in the `Project Navigator`__.
|
|||||||
- ✔
|
- ✔
|
||||||
- ✔ (``openstack.instance_ha``)
|
- ✔ (``openstack.instance_ha``)
|
||||||
|
|
||||||
|
.. __: https://www.openstack.org/software/project-navigator/openstack-components#openstack-services
|
||||||
|
|
||||||
Links
|
Links
|
||||||
-----
|
-----
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user