docs: Add intro doc to user guide
This is essentially a repeat of content from the recently updated README. We simply duplicate it rather than using complicated includes because $effort. Change-Id: If41a6b2d43d00e5bd78f6b2bd5bf33fa4a5d38d5 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane
parent
85a2f10159
commit
f280f7cdd6
@ -1,9 +1,10 @@
|
||||
=================================
|
||||
Contributing to the OpenStack SDK
|
||||
=================================
|
||||
|
||||
This section of documentation pertains to those who wish to contribute to the
|
||||
development of this SDK. If you're looking for documentation on how to use
|
||||
the SDK to build applications, please see the `user <../user>`_ section.
|
||||
the SDK to build applications, refer to the `user <../user>`_ section.
|
||||
|
||||
About the Project
|
||||
-----------------
|
||||
@ -30,22 +31,24 @@ Contacting the Developers
|
||||
-------------------------
|
||||
|
||||
IRC
|
||||
***
|
||||
~~~
|
||||
|
||||
The developers of this project are available in the
|
||||
`#openstack-sdks <http://webchat.freenode.net?channels=%23openstack-sdks>`_
|
||||
channel on Freenode. This channel includes conversation on SDKs and tools
|
||||
within the general OpenStack community, including OpenStackClient as well
|
||||
as occasional talk about SDKs created for languages outside of Python.
|
||||
The developers of this project are available in the `#openstack-sdks`__ channel
|
||||
on Freenode. This channel includes conversation on SDKs and tools within the
|
||||
general OpenStack community, including OpenStackClient as well as occasional
|
||||
talk about SDKs created for languages outside of Python.
|
||||
|
||||
.. __: http://webchat.freenode.net?channels=%23openstack-sdks
|
||||
|
||||
Email
|
||||
*****
|
||||
~~~~~
|
||||
|
||||
The `openstack-discuss <mailto:openstack-discuss@openstack.org?subject=[sdk]%20Question%20about%20openstacksdk>`_
|
||||
mailing list fields questions of all types on OpenStack. Using the
|
||||
``[sdk]`` filter to begin your email subject will ensure
|
||||
The `openstack-discuss`__ mailing list fields questions of all types on
|
||||
OpenStack. Using the ``[sdk]`` filter to begin your email subject will ensure
|
||||
that the message gets to SDK developers.
|
||||
|
||||
.. __: mailto:openstack-discuss@openstack.org?subject=[sdk]%20Question%20about%20openstacksdk
|
||||
|
||||
Coding Standards
|
||||
----------------
|
||||
|
||||
|
||||
@ -1,12 +1,13 @@
|
||||
Welcome to the OpenStack SDK!
|
||||
=============================
|
||||
============
|
||||
openstacksdk
|
||||
============
|
||||
|
||||
This documentation is split into three sections:
|
||||
|
||||
* an :doc:`installation <install/index>` guide
|
||||
* a section for :doc:`users <user/index>` looking to build applications
|
||||
* An :doc:`installation <install/index>` guide
|
||||
* A section for :doc:`users <user/index>` looking to build applications
|
||||
which make use of OpenStack
|
||||
* a section for those looking to :doc:`contribute <contributor/index>`
|
||||
* A section for those looking to :doc:`contribute <contributor/index>`
|
||||
to this project
|
||||
|
||||
Installation
|
||||
@ -33,8 +34,6 @@ For Contributors
|
||||
|
||||
contributor/index
|
||||
|
||||
.. include:: ../../README.rst
|
||||
|
||||
General Information
|
||||
-------------------
|
||||
|
||||
|
||||
@ -1,12 +1,18 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
==================
|
||||
Installation guide
|
||||
==================
|
||||
|
||||
At the command line::
|
||||
The OpenStack SDK is available on `PyPI`__ under the name **openstacksdk**. To
|
||||
install it, use ``pip``:
|
||||
|
||||
$ pip install openstacksdk
|
||||
.. code-block:: bash
|
||||
|
||||
Or, if you have virtualenv wrapper installed::
|
||||
$ pip install openstacksdk
|
||||
|
||||
$ mkvirtualenv openstacksdk
|
||||
$ pip install openstacksdk
|
||||
To check the installed version you can call the module with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python -m openstack version
|
||||
|
||||
.. __: https://pypi.org/project/openstacksdk
|
||||
|
||||
@ -34,9 +34,9 @@ Config Files
|
||||
`openstacksdk` will look for a file called `clouds.yaml` in the following
|
||||
locations:
|
||||
|
||||
* Current Directory
|
||||
* ~/.config/openstack
|
||||
* /etc/openstack
|
||||
* ``.`` (the current directory)
|
||||
* ``$HOME/.config/openstack``
|
||||
* ``/etc/openstack``
|
||||
|
||||
The first file found wins.
|
||||
|
||||
|
||||
102
doc/source/user/guides/intro.rst
Normal file
102
doc/source/user/guides/intro.rst
Normal file
@ -0,0 +1,102 @@
|
||||
===============
|
||||
Getting started
|
||||
===============
|
||||
|
||||
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:: yaml
|
||||
|
||||
clouds:
|
||||
mordred:
|
||||
region_name: Dallas
|
||||
auth:
|
||||
username: 'mordred'
|
||||
password: XXXXXXX
|
||||
project_name: 'demo'
|
||||
auth_url: 'https://identity.example.com'
|
||||
|
||||
More information on configuring openstacksdk can be found in
|
||||
:doc:`/user/config/configuration`.
|
||||
|
||||
Given sufficient configuration, you can use openstacksdk to interact with your
|
||||
cloud. 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
|
||||
|
||||
import openstack
|
||||
|
||||
# Initialize and turn on debug logging
|
||||
openstack.enable_logging(debug=True)
|
||||
|
||||
# Initialize connection
|
||||
conn = openstack.connect(cloud='mordred')
|
||||
|
||||
# Upload an image to the cloud
|
||||
image = conn.create_image(
|
||||
'ubuntu-trusty', filename='ubuntu-trusty.qcow2', wait=True)
|
||||
|
||||
# Find a flavor with at least 512M of RAM
|
||||
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 address for it.
|
||||
conn.create_server(
|
||||
'my-server', image=image, flavor=flavor, wait=True, auto_ip=True)
|
||||
|
||||
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:
|
||||
|
||||
.. 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())
|
||||
@ -1,22 +1,14 @@
|
||||
Getting started with the OpenStack SDK
|
||||
======================================
|
||||
=======================
|
||||
Using the OpenStack SDK
|
||||
=======================
|
||||
|
||||
This section of documentation pertains to those who wish to use this SDK in
|
||||
their own application. If you're looking for documentation on how to contribute
|
||||
to or extend the SDK, refer to the `contributor <../contributor>`_ section.
|
||||
|
||||
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.org/project/openstacksdk>`_ under the name
|
||||
**openstacksdk**. To install it, use ``pip``::
|
||||
|
||||
$ pip install openstacksdk
|
||||
|
||||
To check the installed version you can call the module with ::
|
||||
|
||||
$ python -m openstack version
|
||||
|
||||
.. _user_guides:
|
||||
|
||||
User Guides
|
||||
@ -29,6 +21,7 @@ approach, this is where you'll want to begin.
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Introduction <guides/intro>
|
||||
Configuration <config/index>
|
||||
Connect to an OpenStack Cloud <guides/connect>
|
||||
Connect to an OpenStack Cloud Using a Config File <guides/connect_from_config>
|
||||
@ -167,7 +160,7 @@ can be customized.
|
||||
utils
|
||||
|
||||
Presentations
|
||||
=============
|
||||
-------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user