openstack/openstacksdk
Code Issues Proposed changes

The Compute User Guide

Browse Source 
The beginning of the compute user guide.

This also begins the simplification of the examples, makes them
more specific, and adds testing.

Change-Id: Ic4bac2fe30601c196b03ce73b2dd04a916231f33
Partial-Bug: #1487269
Partial-Bug: #1419012
Partial-Bug: #1466180
This commit is contained in:
Everett Toews 2015-08-21 15:37:14 -05:00
parent 8cbd70dca7
commit 7e98020b83
31 changed files with 492 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/code/connection.py
View File

@ -1,6 +0,0 @@
from openstack import connection
conn = connection.Connection(auth_url="http://openstack:5000/v3",
project_name="big_project",
username="SDK_user",
password="Super5ecretPassw0rd")

31
doc/source/contributors/clouds.yaml
View File

@ -1,21 +1,4 @@
clouds:
fone:
region_name: boneville
default_domain: 'Valley'
identity_api_version: 3
auth:
auth_url: http://172.20.1.112:5000/v3/
project_name: cowrace
username: fonebone
password: thorn
phoney:
region_name: barrelhaven
identity_api_version: 2
auth:
auth_url: http://172.20.1.112:5000/v2.0/
project_name: dragonslayer
username: phoneybone
password: gold
test_cloud:
region_name: RegionOne
auth:
@ -23,3 +6,17 @@ clouds:
username: demo
password: secrete
project_name: demo
hp:
cloud: hp
auth:
username: joe
password: joes-password
project_name: joe-tenant1
region_name: region-b.geo-1
rackspace:
cloud: rackspace
auth:
username: joe
password: joes-password
project_name: 123123
region_name: IAD

1
doc/source/users/examples Symbolic link
View File

@ -0,0 +1 @@
../../../examples/

50
doc/source/users/examples.rst
View File

@ -1,50 +0,0 @@
OpenStack SDK Examples
======================
An effort has been made to provide some useful examples to try out the
SDK. These examples reside in the examples directory of the project.
The examples use an authentication configuration that is very similar
to the configuration used for most OpenStack clients.
Configuration
-------------
Most of the examples use a common argument parser to collect
authentication information to run requests. The authentication may come
from the OS prefixed environment variables similar to the ones used in many
client libraries or you may use
`os-client-config <https://pypi.python.org/pypi/os-client-config>`_.
To use the OS prefixed environment variables, set up something similar to
the following.::
export OS_REGION_NAME=Manhattan
export OS_PROJECT_NAME=beasties
export OS_IDENTITY_API_VERSION=2.0
export OS_PASSWORD=horovitz
export OS_AUTH_URL=https://127.0.0.1:5000/v2.0/
export OS_USERNAME=adrock
To use os-client-config, create a clouds.yaml file, which typically resides in
~/.config/openstack/clouds.yaml to store authentication and preference
information. If you are using os-client-config, you can use the OS_CLOUD
environment variable or use the --os-cloud command line option to specify
the cloud you want to use.::
export OS_CLOUD=miked
Running
-------
Once you have a configuration, most examples can be run by calling them
directly. For example, the list example can be run by just passing it the
name of the resource you want to list::
python examples/list.py openstack/compute/v2/flavor.py
The example code uses some logic to parse the file name and generate a
resource class name. That may not work if the resource class name does
not match the file name. If that is the case, you will need to specify
the resource module name::
python examples/list.py openstack.network.v2.floating_ip.FloatingIP

8
doc/source/users/guides/block_store.rst
View File

@ -1,9 +1,9 @@
Using OpenStack Block Store
===========================
Before working with ``block_store``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Block Store service, you'll need to create a
connection to your OpenStack cloud by following the :doc:`connect` user
guide. This will provide you with the ``conn`` variable used in the examples
below.
.. TODO(thowe): Implement this guide

8
doc/source/users/guides/cdn.rst
View File

@ -1,9 +1,9 @@
Using OpenStack CDN
===================
Before working with ``cdn``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Content Distribution Network (CDN) service, you'll
need to create a connection to your OpenStack cloud by following the
:doc:`connect` user guide. This will provide you with the ``conn`` variable
used in the examples below.
.. TODO(thowe): Implement this guide

71
doc/source/users/guides/compute.rst
View File

@ -1,9 +1,72 @@
Using OpenStack Compute
=======================
Before working with ``compute``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
Before working with the Compute service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. literalinclude:: /code/connection.py
.. contents:: Table of Contents
:local:
.. TODO(thowe): Implement this guide
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.
.. literalinclude:: ../examples/compute/list.py
:pyobject: list_servers
Full example: `compute resource list`_
List Images
-----------
An **image** is the operating system you want to use for your server.
.. literalinclude:: ../examples/compute/list.py
:pyobject: list_images
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.
.. literalinclude:: ../examples/compute/list.py
:pyobject: list_flavors
Full example: `compute resource list`_
List Networks
-------------
A **network** provides connectivity to servers.
.. literalinclude:: ../examples/network/list.py
:pyobject: list_networks
Full example: `network resource list`_
Create Server
-------------
At minimum, a server requires a name, an image, a flavor, and a network on
creation. Once you've discovered these attributes by listing them as above,
you can create a server.
Servers take time to boot so we call ``wait_for_server`` to wait
for it to become active.
.. literalinclude:: ../examples/compute/create.py
:pyobject: create_server
Full example: `compute resource create`_
.. _compute resource list: http://git.openstack.org/cgit/stackforge/python-openstacksdk/tree/examples/compute/list.py
.. _network resource list: http://git.openstack.org/cgit/stackforge/python-openstacksdk/tree/examples/network/list.py
.. _compute resource create: http://git.openstack.org/cgit/stackforge/python-openstacksdk/tree/examples/compute/create.py

45
doc/source/users/guides/connect.rst Normal file
View File

@ -0,0 +1,45 @@
Connect
=======
In order to work with an OpenStack cloud you first need to create a
:class:`~openstack.connection.Connection` to it using your credentials. A
:class:`~openstack.connection.Connection` can be
created in 3 ways, using the class itself, a file, or environment variables.
If this is your first time using the SDK, we recommend simply using the
class itself as illustrated below.
.. note:: To get your credentials
`Download the OpenStack RC file <http://docs.openstack.org/cli-reference/content/cli_openrc.html#openrc-dashboard>`_.
Create Connection
-----------------
To create a connection you need a :class:`~openstack.profile.Profile` and a
:class:`~openstack.connection.Connection`.
.. literalinclude:: ../examples/connect.py
:language: python
:lines: 32-44
The :class:`~openstack.profile.Profile` sets your preferences for each
service. You will pass it the region of the OpenStack cloud that this
connection will use.
The :class:`~openstack.connection.Connection` is a context for a connection
to an OpenStack cloud. You will primarily use it to set the
:class:`~openstack.profile.Profile` and authentication information with the
``auth_args`` parameter. You can also set the ``user_agent`` to something that
describes your application (e.g. ``my-web-app/1.3.4``).
Full example at `connect.py <http://git.openstack.org/cgit/stackforge/python-openstacksdk/tree/examples/connect.py>`_
.. note:: To enable logging, see the :doc:`logging` user guide.
Next
----
Now that you can create a connection, continue with the :ref:`user_guides`
to work with an OpenStack service.
As an alternative to creating a :class:`~openstack.connection.Connection`
using the class itself, you can connect using a file or environment
variables. See the :doc:`connect_from_config` user guide.

71
doc/source/users/guides/connect_from_config.rst Normal file
View File

@ -0,0 +1,71 @@
Connect From Config
===================
In order to work with an OpenStack cloud you first need to create a
:class:`~openstack.connection.Connection` to it using your credentials. A
:class:`~openstack.connection.Connection` can be
created in 3 ways, using the class itself (see :doc:`connect`), a file, or
environment variables as illustrated below. The SDK uses
`os-client-config <http://git.openstack.org/cgit/openstack/os-client-config/tree/README.rst>`_
to handle the configuration.
.. note:: To get your credentials
`Download the OpenStack RC file <http://docs.openstack.org/cli-reference/content/cli_openrc.html#openrc-dashboard>`_.
Create Connection From A File
-----------------------------
Default Location
****************
To create a connection from a file you need a YAML file to contain the
configuration and the :py:func:`~openstack.connection.from_config`
function.
.. literalinclude:: ../../contributors/clouds.yaml
:language: yaml
To look for a configuration file called ``clouds.yaml`` in the default
locations:
* Current Directory
* ~/.config/openstack
* /etc/openstack
call :py:func:`~openstack.connection.from_config` with an object that has
the name of the cloud configuration to use.
.. literalinclude:: ../examples/connect.py
:language: python
:lines: 23-30
.. note:: To enable logging, set ``debug=True`` in the ``Opts`` object.
User Defined Location
*********************
To look for 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 :py:func:`~openstack.connection.from_config` with an object that has
the name of the cloud configuration to use.
.. literalinclude:: ../examples/connect.py
:language: python
:lines: 23-30
.. note:: To enable logging, set ``debug=True`` in the ``Opts`` object.
.. Create Connection From Environment Variables
--------------------------------------------
TODO(etoews): Document when https://bugs.launchpad.net/os-client-config/+bug/1489617
is fixed.
Next
----
Now that you can create a connection, continue with the :ref:`user_guides`
for an OpenStack service.

7
doc/source/users/guides/database.rst
View File

@ -1,9 +1,8 @@
Using OpenStack Database
========================
Before working with ``database``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Database service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. TODO(thowe): Implement this guide

7
doc/source/users/guides/identity.rst
View File

@ -1,9 +1,8 @@
Using OpenStack Identity
========================
Before working with ``identity``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Identity service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. TODO(thowe): Implement this guide

7
doc/source/users/guides/image.rst
View File

@ -1,9 +1,8 @@
Using OpenStack Image
=====================
Before working with ``image``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Image service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. TODO(thowe): Implement this guide

12
doc/source/users/guides/key_management.rst
View File

@ -1,9 +1,9 @@
Using OpenStack KeyManagement
=============================
Using OpenStack Key Management
==============================
Before working with ``key_management``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Key Management service, you'll need to create a
connection to your OpenStack cloud by following the :doc:`connect` user
guide. This will provide you with the ``conn`` variable used in the examples
below.
.. TODO(thowe): Implement this guide

7
doc/source/users/guides/metric.rst
View File

@ -1,9 +1,8 @@
Using OpenStack Metric
======================
Before working with ``metric``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Metric service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. TODO(thowe): Implement this guide

7
doc/source/users/guides/network.rst
View File

@ -1,9 +1,8 @@
Using OpenStack Network
=======================
Before working with ``network``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Network service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. TODO(thowe): Implement this guide

11
doc/source/users/guides/object_store.rst
View File

@ -1,12 +1,15 @@
Using OpenStack Object Store
============================
The Object Store API operates on two things: containers and objects.
Before working with the Object Store service, you'll need to create a
connection to your OpenStack cloud by following the :doc:`connect` user
guide. This will provide you with the ``conn`` variable used in the examples
below.
Before working with ``object_store``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. contents:: Table of Contents
:local:
.. literalinclude:: /code/connection.py
The primary resources of the Object Store service are containers and objects.
Working with Containers
-----------------------

8
doc/source/users/guides/orchestration.rst
View File

@ -1,9 +1,9 @@
Using OpenStack Orchestration
=============================
Before working with ``orchestration``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Orchestration service, you'll need to create a
connection to your OpenStack cloud by following the :doc:`connect` user
guide. This will provide you with the ``conn`` variable used in the examples
below.
.. TODO(thowe): Implement this guide

7
doc/source/users/guides/telemetry.rst
View File

@ -1,9 +1,8 @@
Using OpenStack Telemetry
=========================
Before working with ``telemetry``, you'll need to obtain a
:class:`~openstack.connection.Connection` object like so.
.. literalinclude:: /code/connection.py
Before working with the Telemetry service, you'll need to create a connection
to your OpenStack cloud by following the :doc:`connect` user guide. This will
provide you with the ``conn`` variable used in the examples below.
.. TODO(thowe): Implement this guide

27
doc/source/users/guides/usage.rst
View File

@ -1,27 +0,0 @@
.. TODO(briancurtin): turn this into a full guide on the Connection class
.. TODO(briancurtin): cover user_agent setting
=====
Usage
=====
To use openstacksdk in a project::
from openstack import connection
from openstack import profile
# First, specify your profile
prof = profile.Profile()
prof.set_region('network', 'zion')
# Second, create a connection
conn = connection.Connection(profile=prof,
auth_url='http://172.20.1.108:5000/v3',
project_name='hacker',
username='neo',
password='bluepill')
# Finally, access your desired services
network = conn.network.find_network("matrix")
if network is None:
network = conn.network.create_network(name="matrix")

12
doc/source/users/index.rst
View File

@ -13,6 +13,8 @@ The OpenStack SDK is available on
$ pip install openstacksdk
.. _user_guides:
User Guides
-----------
@ -23,7 +25,8 @@ approach, this is where you'll want to begin.
.. toctree::
:maxdepth: 1
Connecting to an OpenStack Cloud <guides/usage>
Connect to an OpenStack Cloud <guides/connect>
Connect to an OpenStack Cloud Using a Config File <guides/connect_from_config>
Logging <guides/logging>
Block Store <guides/block_store>
CDN <guides/cdn>
@ -38,13 +41,6 @@ approach, this is where you'll want to begin.
Orchestration <guides/orchestration>
Telemetry <guides/telemetry>
It may also be useful to try out some working code examples:
.. toctree::
:maxdepth: 1
examples
API Documentation
-----------------

0
examples/compute/__init__.py Normal file
View File

28
examples/compute/create.py Normal file
View File

@ -0,0 +1,28 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
Create resources with the Compute service.
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
def create_server(conn, name, image, flavor, network):
print("Create Server:")
server = conn.compute.create_server(name=name, image=image,
flavor=flavor,
networks=[{"uuid": network.id}])
conn.compute.wait_for_server(server)
print(server)

37
examples/compute/find.py Normal file
View File

@ -0,0 +1,37 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
Find a resource from the Compute service.
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
def find_image(conn):
print("Find Image:")
image = conn.compute.find_image("fedora-20.x86_64")
print(image)
return image
def find_flavor(conn):
print("Find Flavor:")
flavor = conn.compute.find_flavor("m1.small")
print(flavor)
return flavor

38
examples/compute/list.py Normal file
View File

@ -0,0 +1,38 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
List resources from the Compute service.
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
def list_servers(conn):
print("List Servers:")
for server in conn.compute.servers():
print(server)
def list_images(conn):
print("List Images:")
for image in conn.compute.images():
print(image)
def list_flavors(conn):
print("List Flavors:")
for flavor in conn.compute.flavors():
print(flavor)

44
examples/connect.py Normal file
View File

@ -0,0 +1,44 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
Connect to an OpenStack cloud.
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
from openstack import connection
from openstack import profile
class Opts(object):
def __init__(self, cloud='hp', debug=False):
self.cloud = cloud
self.debug = debug
def create_connection_from_config():
return connection.from_config(Opts(cloud='test_cloud'))
def create_connection(auth_url, region, project_name, username, password):
prof = profile.Profile()
prof.set_region(profile.Profile.ALL, region)
return connection.Connection(
profile=prof,
user_agent='examples',
auth_url=auth_url,
project_name=project_name,
username=username,
password=password
)

27
examples/network/find.py Normal file
View File

@ -0,0 +1,27 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
Find a resource from the Network service.
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
def find_network(conn):
print("Find Network:")
network = conn.network.find_network("public")
print(network)
return network

24
examples/network/list.py Normal file
View File

@ -0,0 +1,24 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
"""
List resources from the Network service.
For a full guide see TODO(etoews):link to docs on developer.openstack.org
"""
def list_networks(conn):
print("List Networks:")
for network in conn.network.networks():
print(network)

0
openstack/tests/examples/__init__.py Normal file
View File

44
openstack/tests/examples/test_compute.py Normal file
View File

@ -0,0 +1,44 @@
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import unittest
from examples.compute import create
from examples.compute import find
from examples.compute import list
from examples import connect
from examples.network import find as network_find
from examples.network import list as network_list
class TestCompute(unittest.TestCase):
"""Test the compute examples
The purpose of these tests is to ensure the examples run without erring
out.
"""
@classmethod
def setUpClass(cls):
cls.conn = connect.create_connection_from_config()
def test_compute(self):
list.list_servers(self.conn)
list.list_images(self.conn)
list.list_flavors(self.conn)
network_list.list_networks(self.conn)
image = find.find_image(self.conn)
flavor = find.find_flavor(self.conn)
network = network_find.find_network(self.conn)
create.create_server(self.conn, 'example', image, flavor, network)

2
openstack/transport.py
View File

@ -129,7 +129,7 @@ from openstack import exceptions
#: Default value for the HTTP User-Agent header. The default includes the
#: version information of the SDK as well as ``requests``, Python,
#: and the operating system.
USER_AGENT = "python-openstacksdk/%s %s" % (
USER_AGENT = "openstacksdk/%s %s" % (
openstack.__version__, requests.utils.default_user_agent())
_logger = logging.getLogger(__name__)

4
tox.ini
View File

@ -11,6 +11,10 @@ setenv =
deps = -r{toxinidir}/test-requirements.txt
commands = ostestr {posargs}
[testenv:examples]
setenv = OS_TEST_PATH=./openstack/tests/examples
passenv = OS_*
[functionalbase]
setenv = OS_TEST_PATH=./openstack/tests/functional
passenv = OS_*