cc2014fec1
This patch updates/adds the contributor documentation to follow the guidelines of the Ussuri cycle community goal[1]. [1] https://governance.openstack.org/tc/goals/selected/ussuri/project-ptl-and-contrib-docs.html Story: #2007236 Task: #38524 Change-Id: If5d20838a653687a142134a9645254d9c51dba78
120 lines
3.8 KiB
ReStructuredText
120 lines
3.8 KiB
ReStructuredText
Python bindings to the OpenStack Heat API
|
|
=========================================
|
|
|
|
This is a client for OpenStack Heat API. There's a Python API (the
|
|
:mod:`heatclient` module), a `python-openstackclient`_ plugin for command-line
|
|
use, and a legacy command-line script (installed as :program:`heat`).
|
|
|
|
==========
|
|
Python API
|
|
==========
|
|
|
|
In order to use the python api directly, you must first obtain an auth
|
|
token and identify which endpoint you wish to speak to::
|
|
|
|
>>> tenant_id = 'b363706f891f48019483f8bd6503c54b'
|
|
>>> heat_url = 'http://heat.example.org:8004/v1/%s' % tenant_id
|
|
>>> auth_token = '3bcc3d3a03f44e3d8377f9247b0ad155'
|
|
|
|
Once you have done so, you can use the API like so::
|
|
|
|
>>> from heatclient.client import Client
|
|
>>> heat = Client('1', endpoint=heat_url, token=auth_token)
|
|
|
|
Alternatively, you can create a client instance using the keystoneauth session API::
|
|
|
|
>>> from keystoneauth1 import loading
|
|
>>> from keystoneauth1 import session
|
|
>>> from heatclient import client
|
|
>>> loader = loading.get_plugin_loader('password')
|
|
>>> auth = loader.load_from_options(auth_url=AUTH_URL,
|
|
... username=USERNAME,
|
|
... password=PASSWORD,
|
|
... project_id=PROJECT_ID)
|
|
>>> sess = session.Session(auth=auth)
|
|
>>> heat = client.Client('1', session=sess)
|
|
>>> heat.stacks.list()
|
|
|
|
If you have PROJECT_NAME instead of a PROJECT_ID, use the project_name
|
|
parameter. Similarly, if your cloud uses keystone v3 and you have a DOMAIN_NAME
|
|
or DOMAIN_ID, provide it as `user_domain_(name|id)` and if you are using a
|
|
PROJECT_NAME also provide the domain information as `project_domain_(name|id)`.
|
|
|
|
For more information on keystoneauth API, see `Using Sessions`_.
|
|
|
|
.. _Using Sessions: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
|
|
|
|
Reference
|
|
---------
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
ref/index
|
|
ref/v1/index
|
|
|
|
============================
|
|
OpenStackClient Command Line
|
|
============================
|
|
|
|
The preferred way of accessing Heat via the command line is using the
|
|
python-heatclient's plugin for `python-openstackclient`_. Heat commands are
|
|
available through the ``openstack`` CLI command when both python-heatclient and
|
|
python-openstackclient are installed.
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
cli/index
|
|
|
|
.. _python-openstackclient: https://docs.openstack.org/python-openstackclient
|
|
|
|
========================
|
|
Legacy Command-line Tool
|
|
========================
|
|
|
|
The ``heat`` command is provided as a legacy CLI option. Users should prefer
|
|
using the python-openstackclient plugin via the ``openstack`` command instead.
|
|
|
|
In order to use the CLI, you must provide your OpenStack username,
|
|
password, tenant, and auth endpoint. Use the corresponding
|
|
configuration options (``--os-username``, ``--os-password``,
|
|
``--os-tenant-id``, and ``--os-auth-url``) or set them in environment
|
|
variables::
|
|
|
|
export OS_USERNAME=user
|
|
export OS_PASSWORD=pass
|
|
export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b
|
|
export OS_AUTH_URL=http://auth.example.com:5000/v2.0
|
|
|
|
The command line tool will attempt to reauthenticate using your
|
|
provided credentials for every request. You can override this behavior
|
|
by manually supplying an auth token using ``--heat-url`` and
|
|
``--os-auth-token``. You can alternatively set these environment
|
|
variables::
|
|
|
|
export HEAT_URL=http://heat.example.org:8004/v1/b363706f891f48019483f8bd6503c54b
|
|
export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
|
|
|
|
Once you've configured your authentication parameters, you can run
|
|
``heat help`` to see a complete listing of available commands.
|
|
|
|
Man Pages
|
|
---------
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
man/heat
|
|
|
|
|
|
For Contributors
|
|
================
|
|
|
|
* If you are a new contributor to python-heatclient please refer: :doc:`contributor/contributing`
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
contributor/contributing
|