Improve README to provide example of Resource usage
Provide a simple "hello world" example that includes details on using the 'Resource' subclasses. References to 'clouds.yaml' are also moved earlier in the doc since this is a pretty essential part of using openstacksdk. Change-Id: I6e7e6b5d9f54ec15b8e886b78649b50e02d38fc4 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane
parent
5b4f36b78c
commit
85a2f10159
149
README.rst
149
README.rst
@ -1,3 +1,4 @@
|
||||
============
|
||||
openstacksdk
|
||||
============
|
||||
|
||||
@ -10,48 +11,73 @@ It also contains an abstraction interface layer. Clouds can do many things, but
|
||||
there are probably only about 10 of them that most people care about with any
|
||||
regularity. If you want to do complicated things, the per-service oriented
|
||||
portions of the SDK are for you. However, if what you want is to be able to
|
||||
write an application that talks to clouds no matter what crazy choices the
|
||||
deployer has made in an attempt to be more hipster than their self-entitled
|
||||
narcissist peers, then the Cloud Abstraction layer is for you.
|
||||
write an application that talks to any OpenStack cloud regardless of
|
||||
configuration, then the Cloud Abstraction layer is for you.
|
||||
|
||||
More information about its history can be found at
|
||||
More information about the history of openstacksdk can be found at
|
||||
https://docs.openstack.org/openstacksdk/latest/contributor/history.html
|
||||
|
||||
openstack
|
||||
=========
|
||||
Getting started
|
||||
---------------
|
||||
|
||||
List servers using objects configured with the ``clouds.yaml`` file:
|
||||
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:
|
||||
|
||||
.. code-block:: python
|
||||
.. code-block:: yaml
|
||||
|
||||
import openstack
|
||||
clouds:
|
||||
mordred:
|
||||
region_name: Dallas
|
||||
auth:
|
||||
username: 'mordred'
|
||||
password: XXXXXXX
|
||||
project_name: 'demo'
|
||||
auth_url: 'https://identity.example.com'
|
||||
|
||||
# Initialize and turn on debug logging
|
||||
openstack.enable_logging(debug=True)
|
||||
openstacksdk will look for ``clouds.yaml`` files in the following locations:
|
||||
|
||||
# Initialize cloud
|
||||
conn = openstack.connect(cloud='mordred')
|
||||
* ``.`` (the current directory)
|
||||
* ``$HOME/.config/openstack``
|
||||
* ``/etc/openstack``
|
||||
|
||||
for server in conn.compute.servers():
|
||||
print(server.to_dict())
|
||||
|
||||
Cloud Layer
|
||||
===========
|
||||
|
||||
``openstacksdk`` contains a higher-level layer based on logical operations.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import openstack
|
||||
|
||||
# Initialize and turn on debug logging
|
||||
openstack.enable_logging(debug=True)
|
||||
|
||||
for server in conn.list_servers():
|
||||
print(server.to_dict())
|
||||
|
||||
The benefit is mostly seen in more complicated operations that take multiple
|
||||
steps and where the steps vary across providers:
|
||||
openstacksdk consists of three layers. Most users will make use of the *proxy*
|
||||
layer. Using the above ``clouds.yaml``, consider listing servers:
|
||||
|
||||
.. 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())
|
||||
|
||||
openstacksdk also contains a higher-level *cloud* layer based on logical
|
||||
operations:
|
||||
|
||||
.. 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.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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -61,7 +87,6 @@ steps and where the steps vary across providers:
|
||||
openstack.enable_logging(debug=True)
|
||||
|
||||
# Initialize connection
|
||||
# Cloud configs are read with openstack.config
|
||||
conn = openstack.connect(cloud='mordred')
|
||||
|
||||
# Upload an image to the cloud
|
||||
@ -72,14 +97,37 @@ steps and where the steps vary across providers:
|
||||
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 for it.
|
||||
# to get a public IP address for it.
|
||||
conn.create_server(
|
||||
'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
|
||||
|
||||
openstack.config
|
||||
================
|
||||
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:
|
||||
|
||||
``openstack.config`` will find cloud configuration for as few as 1 clouds and
|
||||
.. code-block:: python
|
||||
|
||||
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())
|
||||
|
||||
.. _openstack.config:
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
openstacksdk uses the ``openstack.config`` module to parse configuration.
|
||||
``openstack.config`` will find cloud configuration for as few as one cloud and
|
||||
as many as you want to put in a config file. It will read environment variables
|
||||
and config files, and it also contains some vendor specific default values so
|
||||
that you don't have to know extra info to use OpenStack
|
||||
@ -88,32 +136,17 @@ that you don't have to know extra info to use OpenStack
|
||||
* If you have environment variables, you will get a cloud named `envvars`
|
||||
* If you have neither, you will get a cloud named `defaults` with base defaults
|
||||
|
||||
Sometimes an example is nice.
|
||||
You can view the configuration identified by openstacksdk in your current
|
||||
environment by running ``openstack.config.loader``. For example:
|
||||
|
||||
Create a ``clouds.yaml`` file:
|
||||
.. code-block:: bash
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
clouds:
|
||||
mordred:
|
||||
region_name: Dallas
|
||||
auth:
|
||||
username: 'mordred'
|
||||
password: XXXXXXX
|
||||
project_name: 'shade'
|
||||
auth_url: 'https://identity.example.com'
|
||||
|
||||
Please note: ``openstack.config`` will look for a file called ``clouds.yaml``
|
||||
in the following locations:
|
||||
|
||||
* Current Directory
|
||||
* ``~/.config/openstack``
|
||||
* ``/etc/openstack``
|
||||
$ python -m openstack.config.loader
|
||||
|
||||
More information at https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html
|
||||
|
||||
Links
|
||||
=====
|
||||
-----
|
||||
|
||||
* `Issue Tracker <https://storyboard.openstack.org/#!/project/openstack/openstacksdk>`_
|
||||
* `Code Review <https://review.opendev.org/#/q/status:open+project:openstack/openstacksdk,n,z>`_
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user