Add initial Python SDK docs to user guide
Initial addition of Python SDK content to user's guide. Describes how an end-user can employ the Python bindings to automate tasks. This initial commit adds info on: - How to authenticate with Identity, Commpute, Image, and Network clients - How to manage images Change-Id: Ie8c4120acc7739c0bc4bddd99ffdbfbfbe241e0f
This commit is contained in:
Lorin Hochstein
Diane Fleming
parent
a02a29af61
commit
689de3f4e8
@ -44,6 +44,17 @@
|
||||
commands.</para>
|
||||
</abstract>
|
||||
<revhistory>
|
||||
<revision>
|
||||
<date>2013-12-30</date>
|
||||
<revdescription>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Added the OpenStack Python SDK
|
||||
chapter.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
</revision>
|
||||
<revision>
|
||||
<date>2013-10-17</date>
|
||||
<revdescription>
|
||||
@ -69,7 +80,8 @@
|
||||
<revdescription>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>First edition of this document.</para>
|
||||
<para>First edition of this
|
||||
document.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
@ -79,6 +91,7 @@
|
||||
<xi:include href="../common/ch_using_openstack_overview.xml"/>
|
||||
<xi:include href="ch_dashboard.xml"/>
|
||||
<xi:include href="ch_cli.xml"/>
|
||||
<xi:include href="ch_sdk.xml"/>
|
||||
<xi:include href="../common/app_command_reference.xml"/>
|
||||
<xi:include href="../common/app_support.xml"/>
|
||||
</book>
|
||||
|
||||
@ -7,7 +7,7 @@
|
||||
xmlns:raxm="http://docs.rackspace.com/api/metadata" version="5.0"
|
||||
xml:id="ch_dashboard">
|
||||
<info>
|
||||
<title>Dashboard</title>
|
||||
<title>OpenStack dashboard</title>
|
||||
</info>
|
||||
<para>As a cloud end user, you can use the OpenStack dashboard to
|
||||
provision your own resources within the limits set by
|
||||
|
||||
18
doc/user-guide/ch_sdk.xml
Normal file
18
doc/user-guide/ch_sdk.xml
Normal file
@ -0,0 +1,18 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="ch_sdk">
|
||||
<info>
|
||||
<title>OpenStack Python SDK</title>
|
||||
</info>
|
||||
<para>Use the OpenStack Python Software Development Kit (SDK) to
|
||||
write Python automation scripts that create and manage resources
|
||||
in your OpenStack cloud. The SDK implements Python bindings to the
|
||||
OpenStack API, which enables you to perform automation tasks in
|
||||
Python by making calls on Python objects rather than making REST
|
||||
calls directly. All OpenStack command-line tools are implemented
|
||||
using the Python SDK.</para>
|
||||
<xi:include href="section_sdk_install.xml"/>
|
||||
<xi:include href="section_sdk_authenticate.xml"/>
|
||||
<xi:include href="section_sdk_manage_images.xml"/>
|
||||
</chapter>
|
||||
22
doc/user-guide/section_sdk_auth_glance.xml
Normal file
22
doc/user-guide/section_sdk_auth_glance.xml
Normal file
@ -0,0 +1,22 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="sdk_auth_glance">
|
||||
<title>Authenticate against an Image Service endpoint</title>
|
||||
<para>To authenticate against an Image Service endpoint, instantiate
|
||||
a <link
|
||||
xlink:href="http://docs.openstack.org/developer/python-glanceclient/api/glanceclient.v2.client.html#glanceclient.v2.client.Client"
|
||||
> glanceclient.v2.client.Client</link> object:</para>
|
||||
<programlisting language="python">from os import environ as env
|
||||
import glanceclient.v2.client as glclient
|
||||
import keystoneclient.v2_0.client as ksclient
|
||||
|
||||
keystone = ksclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
password=env['OS_PASSWORD'],
|
||||
tenant_name=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'])
|
||||
glance_endpoint = keystone.service_catalog.url_for(service_type='image')
|
||||
glance = glclient.Client(glance_endpoint, token=keystone.auth_token)</programlisting>
|
||||
</section>
|
||||
38
doc/user-guide/section_sdk_auth_keystone.xml
Normal file
38
doc/user-guide/section_sdk_auth_keystone.xml
Normal file
@ -0,0 +1,38 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="sdk_auth_keystone">
|
||||
<title>Authenticate against an Identity Service endpoint</title>
|
||||
<para>To authenticate against the Identity Service v2.0 endpoint,
|
||||
instantiate a <link
|
||||
xlink:href="http://docs.openstack.org/developer/python-keystoneclient/api/keystoneclient.v2_0.client.html#keystoneclient.v2_0.client.Client"
|
||||
> keystoneclient.v_20.client.Client</link> object:</para>
|
||||
<programlisting language="python">from os import environ as env
|
||||
import keystoneclient.v2_0.client as ksclient
|
||||
keystone = ksclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
password=env['OS_PASSWORD'],
|
||||
tenant_name=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'])</programlisting>
|
||||
<para>After you instantiate a <classname>Client</classname> object,
|
||||
you can retrieve the token by accessing its
|
||||
<literal>auth_token</literal> attribute object:</para>
|
||||
<programlisting language="python">import keystoneclient.v2_0.client as ksclient
|
||||
keystone = ksclient.Client(...)
|
||||
print keystone.auth_token</programlisting>
|
||||
<para>If the Openstack cloud is configured to use public-key
|
||||
infrastructure (PKI) tokens, the Python script output looks
|
||||
something like this:</para>
|
||||
<screen><computeroutput>MIIQUQYJKoZIhvcNAQcCoIIQQjCCED4CAQExCTAHBgUrDgMCGjCCDqcGCSqGSIb3DQEHAaCCDpgE
|
||||
gg6UeyJhY2Nlc3MiOiB7InRva2VuIjogeyJpc3N1ZWRfYXQiOiAiMjAxMy0xMC0yMFQxNjo1NjoyNi
|
||||
4zNTg2MjUiLCAiZXhwaXJlcyI6ICIyMDEzLTEwLTIxVDE2OjU2OjI2WiIsICJpZCI6ICJwbGFjZWhv
|
||||
...
|
||||
R3g14FJ0BxtTPbo6WarZ+sA3PZwdgIDyGNI-0Oqv-8ih4gJC9C6wBCel1dUXJ0Mn7BN-SfuxkooVk6
|
||||
e090bcKjTWet3CC8IEj7a6LyLRVTdvmKGA5-pgp2mS5fb3G2mIad4Zeeb-zQn9V3Xf9WUGxuiVu1Hn
|
||||
fhuUpJT-s9mU7+WEC3-8qkcBjEpqVCvMpmM4INI=</computeroutput></screen>
|
||||
<note>
|
||||
<para>This example shows a subset of a PKI token. A complete token
|
||||
is over 5000 characters long.</para>
|
||||
</note>
|
||||
</section>
|
||||
31
doc/user-guide/section_sdk_auth_neutron.xml
Normal file
31
doc/user-guide/section_sdk_auth_neutron.xml
Normal file
@ -0,0 +1,31 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="sdk_auth_neutron">
|
||||
<title>Authenticate against a Networking endpoint</title>
|
||||
<para>To authenticate against a Networking endpoint, instantiate a
|
||||
<classname>neutronclient.v_2_0.client.Client</classname>
|
||||
object:</para>
|
||||
<programlisting language="python">from os import environ as env
|
||||
from neutronclient.v2_0 import client as neutronclient
|
||||
neutron = neutronclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
password=env['OS_PASSWORD'],
|
||||
tenant_name=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'])</programlisting>
|
||||
|
||||
<para>You can also authenticate by explicitly specifying the
|
||||
endpoint and token:</para>
|
||||
<programlisting language="python">from os import environ as env
|
||||
import keystoneclient.v2_0.client as ksclient
|
||||
from neutronclient.v2_0 import client as neutronclient
|
||||
keystone = ksclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
password=env['OS_PASSWORD'],
|
||||
tenant_name=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'])
|
||||
endpoint_url = keystone.service_catalog.url_for(service_type='network')
|
||||
token = keystone.auth_token
|
||||
neutron = neutronclient.Client(endpoint_url=endpoint_url, token=token)</programlisting>
|
||||
</section>
|
||||
72
doc/user-guide/section_sdk_auth_nova.xml
Normal file
72
doc/user-guide/section_sdk_auth_nova.xml
Normal file
@ -0,0 +1,72 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="sdk_auth_nova">
|
||||
<title>Authenticate against a Compute endpoint</title>
|
||||
<para>To authenticate against a Compute endpoint, instantiate a
|
||||
<link
|
||||
xlink:href="http://docs.openstack.org/developer/python-novaclient/api/novaclient.v1_1.client.html#novaclient.v1_1.client.Client"
|
||||
> novaclient.v_1_1.client.Client</link> object:</para>
|
||||
<programlisting language="python">from os import environ as env
|
||||
import novaclient.v1_1.client as nvclient
|
||||
nova = nvclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
api_key=env['OS_PASSWORD'],
|
||||
project_id=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'])</programlisting>
|
||||
<para>Alternatively, you can instantiate a
|
||||
<classname>novaclient.client.Client</classname> object and pass
|
||||
the version number:</para>
|
||||
<programlisting language="python">from os import environ as env
|
||||
import novaclient
|
||||
nova = novaclient.client.Client("1.1", auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
api_key=env['OS_PASSWORD'],
|
||||
project_id=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'])</programlisting>
|
||||
<para>If you authenticate against an endpoint that uses a custom
|
||||
authentication back-end, you must load the authentication plug-in
|
||||
and pass it to the constructor.</para>
|
||||
<para>The Rackspace Public Cloud is an OpenStack deployment that
|
||||
uses a custom authentication back-end. To authenticate against
|
||||
this cloud, you must install the <link
|
||||
xlink:href="https://pypi.python.org/pypi/rackspace-novaclient/">
|
||||
rackspace-novaclient</link> library that contains the Rackspace
|
||||
authentication plug-in, called <literal>rackspace</literal>. The
|
||||
following Python code shows the additional modifications required
|
||||
to instantiate a <classname>Client</classname> object that can
|
||||
authenticate against the Rackspace custom authentication
|
||||
back-end.</para>
|
||||
<programlisting language="python">import novaclient.auth_plugin
|
||||
import novaclient.v1_1.client as nvclient
|
||||
from os import environ as env
|
||||
auth_system = 'rackspace'
|
||||
auth_plugin = novaclient.auth_plugin.load_plugin('rackspace')
|
||||
nova = nvclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
api_key=env['OS_PASSWORD'],
|
||||
project_id=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'],
|
||||
auth_system='rackspace',
|
||||
auth_plugin=auth_plugin)</programlisting>
|
||||
<para>If you set the <literal>OS_AUTH_SYSTEM</literal> environment
|
||||
variable, check for this variable in your Python script to
|
||||
determine whether you need to load a custom authentication
|
||||
back-end:</para>
|
||||
<programlisting language="python">import novaclient.auth_plugin
|
||||
import novaclient.v1_1.client as nvclient
|
||||
from os import environ as env
|
||||
auth_system = os.get('OS_AUTH_SYSTEM')
|
||||
if auth_system and auth_system != "keystone":
|
||||
auth_plugin = novaclient.auth_plugin.load_plugin(auth_system)
|
||||
else:
|
||||
auth_plugin = None
|
||||
nova = nvclient.Client(auth_url=env['OS_AUTH_URL'],
|
||||
username=env['OS_USERNAME'],
|
||||
api_key=env['OS_PASSWORD'],
|
||||
project_id=env['OS_TENANT_NAME'],
|
||||
region_name=env['OS_REGION_NAME'],
|
||||
auth_system=auth_system,
|
||||
auth_plugin=auth_plugin)</programlisting>
|
||||
</section>
|
||||
22
doc/user-guide/section_sdk_authenticate.xml
Normal file
22
doc/user-guide/section_sdk_authenticate.xml
Normal file
@ -0,0 +1,22 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sdk_auth">
|
||||
<title>Authentication</title>
|
||||
<para>You must authenticate against an OpenStack endpoint before you can
|
||||
use OpenStack services. Each project uses a slightly different syntax for doing
|
||||
authentication.</para>
|
||||
<para>You must typically authenticate against a specific version of
|
||||
a service. For example, a client might need to authenticate
|
||||
against the Identity Service v2.0.</para>
|
||||
<para>Python scripts that use the OpenStack SDK must have access to the
|
||||
credentials contained in the
|
||||
<link linkend="cli_openrc">OpenStack RC file</link>. Because credentials
|
||||
are sensitive information, do not include them in your scripts. This guide
|
||||
assumes that users source the <filename>openrc.sh</filename> file and access
|
||||
the credentials by using the environment variables in the Python scripts.</para>
|
||||
<xi:include href="section_sdk_auth_keystone.xml"/>
|
||||
<xi:include href="section_sdk_auth_glance.xml"/>
|
||||
<xi:include href="section_sdk_auth_nova.xml" />
|
||||
<xi:include href="section_sdk_auth_neutron.xml" />
|
||||
</section>
|
||||
14
doc/user-guide/section_sdk_install.xml
Normal file
14
doc/user-guide/section_sdk_install.xml
Normal file
@ -0,0 +1,14 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="sdk_install">
|
||||
<title>Install the OpenStack SDK</title>
|
||||
<para>Each OpenStack project has its own Python library. These
|
||||
libraries are bundled with the command-line clients. For example,
|
||||
the Python bindings for the Compute API are bundled with the
|
||||
<package>python-novaclient</package> package.</para>
|
||||
<para>For details about how to install the clients, see <link
|
||||
linkend="install_clients">install the OpenStack command-line
|
||||
clients</link>.</para>
|
||||
</section>
|
||||
111
doc/user-guide/section_sdk_manage_images.xml
Normal file
111
doc/user-guide/section_sdk_manage_images.xml
Normal file
@ -0,0 +1,111 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
||||
xml:id="sdk_manage_images">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>Manage images</title>
|
||||
<section xml:id="sdk-glance-image-list">
|
||||
<title>List images</title>
|
||||
<para>To list the available images, call the <methodname>
|
||||
glanceclient.v2.images.Controller.list</methodname>
|
||||
method:</para>
|
||||
<programlisting language="python">import glanceclient.v2.client as glclient
|
||||
glance = glclient.Client(...)
|
||||
images = glance.images.list()</programlisting>
|
||||
<para>The <methodname>images</methodname> method returns a Python
|
||||
generator, as shown in the following interaction with the Python
|
||||
interpreter:</para>
|
||||
<screen>
|
||||
<prompt>>>></prompt> <userinput>images = glance.images.list()</userinput>
|
||||
<prompt>>>></prompt> <userinput>images</userinput>
|
||||
<computeroutput><generator object list at 0x105e9c2d0></computeroutput>
|
||||
<prompt>>>></prompt> <userinput>list(images)</userinput>
|
||||
<computeroutput>[{u'checksum': u'f8a2eeee2dc65b3d9b6e63678955bd83',
|
||||
u'container_format': u'ami',
|
||||
u'created_at': u'2013-10-20T14:28:10Z',
|
||||
u'disk_format': u'ami',
|
||||
u'file': u'/v2/images/dbc9b2db-51d7-403d-b680-3f576380b00c/file',
|
||||
u'id': u'dbc9b2db-51d7-403d-b680-3f576380b00c',
|
||||
u'kernel_id': u'c002c82e-2cfa-4952-8461-2095b69c18a6',
|
||||
u'min_disk': 0,
|
||||
u'min_ram': 0,
|
||||
u'name': u'cirros-0.3.1-x86_64-uec',
|
||||
u'protected': False,
|
||||
u'ramdisk_id': u'4c1c9b4f-3fe9-425a-a1ec-1d8fd90b4db3',
|
||||
u'schema': u'/v2/schemas/image',
|
||||
u'size': 25165824,
|
||||
u'status': u'active',
|
||||
u'tags': [],
|
||||
u'updated_at': u'2013-10-20T14:28:11Z',
|
||||
u'visibility': u'public'},
|
||||
{u'checksum': u'69c33642f44ca552ba4bb8b66ad97e85',
|
||||
u'container_format': u'ari',
|
||||
u'created_at': u'2013-10-20T14:28:09Z',
|
||||
u'disk_format': u'ari',
|
||||
u'file': u'/v2/images/4c1c9b4f-3fe9-425a-a1ec-1d8fd90b4db3/file',
|
||||
u'id': u'4c1c9b4f-3fe9-425a-a1ec-1d8fd90b4db3',
|
||||
u'min_disk': 0,
|
||||
u'min_ram': 0,
|
||||
u'name': u'cirros-0.3.1-x86_64-uec-ramdisk',
|
||||
u'protected': False,
|
||||
u'schema': u'/v2/schemas/image',
|
||||
u'size': 3714968,
|
||||
u'status': u'active',
|
||||
u'tags': [],
|
||||
u'updated_at': u'2013-10-20T14:28:10Z',
|
||||
u'visibility': u'public'},
|
||||
{u'checksum': u'c352f4e7121c6eae958bc1570324f17e',
|
||||
u'container_format': u'aki',
|
||||
u'created_at': u'2013-10-20T14:28:08Z',
|
||||
u'disk_format': u'aki',
|
||||
u'file': u'/v2/images/c002c82e-2cfa-4952-8461-2095b69c18a6/file',
|
||||
u'id': u'c002c82e-2cfa-4952-8461-2095b69c18a6',
|
||||
u'min_disk': 0,
|
||||
u'min_ram': 0,
|
||||
u'name': u'cirros-0.3.1-x86_64-uec-kernel',
|
||||
u'protected': False,
|
||||
u'schema': u'/v2/schemas/image',
|
||||
u'size': 4955792,
|
||||
u'status': u'active',
|
||||
u'tags': [],
|
||||
u'updated_at': u'2013-10-20T14:28:09Z',
|
||||
u'visibility': u'public'}]</computeroutput></screen>
|
||||
</section>
|
||||
<section xml:id="sdk-glance-image-get">
|
||||
<title>Get image by ID</title>
|
||||
<para>To retrieve an image object from its ID, call the
|
||||
<methodname>
|
||||
glanceclient.v2.images.Controller.get</methodname>
|
||||
method:</para>
|
||||
<programlisting language="python">import glanceclient.v2.client as glclient
|
||||
image_id = 'c002c82e-2cfa-4952-8461-2095b69c18a6'
|
||||
glance = glclient.Client(...)
|
||||
image = glance.images.get(image_id)</programlisting>
|
||||
</section>
|
||||
<section xml:id="sdk-nova-image-find">
|
||||
<title>Get image by name</title>
|
||||
<para>The Image Service Python bindings do not support the
|
||||
retrieval of an image object by name. However, the Compute
|
||||
Python bindings enable you to get an image object by name. To
|
||||
get an image object by name, call the <methodname>
|
||||
novaclient.v1_1.images.ImageManager.find</methodname>
|
||||
method:</para>
|
||||
<programlisting language="python">import novaclient.v1_1.client as nvclient
|
||||
name = "cirros"
|
||||
nova = nvclient.Client(...)
|
||||
image = nova.images.find(name=name)</programlisting>
|
||||
</section>
|
||||
<section xml:id="sdk-glance-image-upload">
|
||||
<title>Upload an image</title>
|
||||
<para>To upload an image, call the <methodname>
|
||||
glanceclient.v2.images.ImageManager.create</methodname>
|
||||
method:</para>
|
||||
<programlisting language="python">import glanceclient.v2.client as glclient
|
||||
imagefile = "/tmp/myimage.img"
|
||||
glance = glclient.Client(...)
|
||||
with open(imagefile) as fimage:
|
||||
glance.images.create(name="myimage", is_public=True, disk_format="qcow2",
|
||||
container_format="bare", data=fimage)</programlisting>
|
||||
</section>
|
||||
</section>
|
||||
Loading…
Reference in New Issue
Block a user