Browse Source

Documentation update

* Split away HTTP API and make sure usage info is enough for users
* Drop release notes for unsupported 0.2
* Various link updates and small fixes
* Forward-port 1.0.1 release notes

Change-Id: Ifa2b306d4a6fff19abc1565dabe7f6609363dc08
changes/52/165852/2
Dmitry Tantsur 8 years ago
parent
commit
358c113e7a
  1. 8
      CONTRIBUTING.rst
  2. 100
      HTTP-API.rst
  3. 190
      README.rst
  4. 2
      tox.ini

8
CONTRIBUTING.rst

@ -18,7 +18,7 @@ Basics
* Note the branch you're proposing changes to. ``master`` is the current focus
of development, use ``stable/VERSION`` for proposing an urgent fix, where
``VERSION`` is the current stable series. E.g. at the moment of writing the
stable branch is ``stable/0.2``.
stable branch is ``stable/1.0``.
* Please file a launchpad_ blueprint for any significant code change and a bug
for any significant bug fix.
@ -41,7 +41,7 @@ Next checkout and create environments::
tox
Repeat *tox* command each time you need to run tests. If you don't have Python
interpreter of one of supported versions (currently 2.7 and 3.3), use
interpreter of one of supported versions (currently 2.7 and 3.4), use
``-e`` flag to select only some environments, e.g.
::
@ -64,6 +64,10 @@ Run the service with::
Of course you may have to modify ``example.conf`` to match your OpenStack
environment.
You can develop and test **ironic-discoverd** using
`DevStack <http://docs.openstack.org/developer/devstack/>`_ plugin - see
https://etherpad.openstack.org/p/DiscoverdDevStack for the current status.
Writing a Plugin
~~~~~~~~~~~~~~~~

100
HTTP-API.rst

@ -0,0 +1,100 @@
HTTP API
--------
By default **ironic-discoverd** listens on ``0.0.0.0:5050``, port
can be changed in configuration. Protocol is JSON over HTTP.
The HTTP API consist of these endpoints:
Start Introspection
~~~~~~~~~~~~~~~~~~~
``POST /v1/introspection/<UUID>`` initiate hardware introspection for node
``<UUID>``. All power management configuration for this node needs to be done
prior to calling the endpoint (except when `Setting IPMI Credentials`_).
Requires X-Auth-Token header with Keystone token for authentication.
Optional parameters:
* ``new_ipmi_password`` if set, **ironic-discoverd** will try to set IPMI
password on the machine to this value. Power credentials validation will be
skipped and manual power on will be required. See `Setting IPMI
credentials`_ for details.
* ``new_ipmi_username`` provides new IPMI user name in addition to password
set by ``new_ipmi_password``. Defaults to current ``ipmi_username`` in
node ``driver_info`` field.
Response:
* 202 - accepted discovery request
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
Get Introspection Status
~~~~~~~~~~~~~~~~~~~~~~~~
``GET /v1/introspection/<UUID>`` get hardware discovery status.
Requires X-Auth-Token header with Keystone token for authentication.
Response:
* 200 - OK
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
Response body: JSON dictionary with keys:
* ``finished`` (boolean) whether discovery is finished
* ``error`` error string or ``null``
Ramdisk Callback
~~~~~~~~~~~~~~~~
``POST /v1/continue`` internal endpoint for the discovery ramdisk to post
back discovered data. Should not be used for anything other than implementing
the ramdisk. Request body: JSON dictionary with at least these keys:
* ``cpus`` number of CPU
* ``cpu_arch`` architecture of the CPU
* ``memory_mb`` RAM in MiB
* ``local_gb`` hard drive size in GiB
* ``interfaces`` dictionary filled with data from all NIC's, keys being
interface names, values being dictionaries with keys:
* ``mac`` MAC address
* ``ip`` IP address
* ``boot_interface`` optional MAC address of the NIC that the machine
PXE booted from either in standard format ``11:22:33:44:55:66`` or
in *PXELinux* ``BOOTIF`` format ``01-11-22-33-44-55-66``.
* ``block_devices`` optional block devices information for
``root_device_hint`` plugin, dictionary with keys:
* ``serials`` list of serial numbers of block devices.
.. note::
This list highly depends on enabled plugins, provided above are
expected keys for the default set of plugins. See Plugins_ for details.
Response:
* 200 - OK
* 400 - bad request
* 403 - node is not on introspection
* 404 - node cannot be found or multiple nodes found
Response body: JSON dictionary. If `Setting IPMI Credentials`_ is requested,
body will contain the following keys:
* ``ipmi_setup_credentials`` boolean ``True``
* ``ipmi_username`` new IPMI user name
* ``ipmi_password`` new IPMI password
.. _Setting IPMI Credentials: https://github.com/stackforge/ironic-discoverd#setting-ipmi-credentials
.. _Plugins: https://github.com/stackforge/ironic-discoverd#plugins

190
README.rst

@ -40,7 +40,7 @@ Usual hardware introspection flow is as follows:
at this step.
* Operator sends nodes on introspection either manually using
**ironic-discoverd** `HTTP API`_ or again via `Tuskar UI`_.
**ironic-discoverd** API (see Usage_) or again via `Tuskar UI`_.
* On receiving node UUID **ironic-discoverd**:
@ -59,46 +59,58 @@ Usual hardware introspection flow is as follows:
case of SSH driver),
* fills missing node properties with received data and creates missing ports.
* Separate `HTTP API`_ can be used to query introspection results for a given
node.
* Separate API (see Usage_) can be used to query introspection results
for a given node.
Starting DHCP server and configuring PXE boot environment is not part of this
package and should be done separately.
.. _instack-undercloud: https://openstack.redhat.com/Deploying_an_RDO_Undercloud_with_Instack
.. _instack-undercloud: https://www.rdoproject.org/Deploying_an_RDO_Undercloud_with_Instack
Installation
------------
**ironic-discoverd** is available as an RPM from Fedora 22 repositories or from
Juno RDO_ for Fedora 20, 21 and EPEL 7. It will be installed and preconfigured
if you used instack-undercloud_ to build your undercloud.
Juno (and later) `RDO <https://www.rdoproject.org/>`_ for Fedora 20, 21
and EPEL 7. It will be installed and preconfigured if you used
instack-undercloud_ to build your undercloud.
Otherwise after enabling required repositories install it using::
yum install openstack-ironic-discoverd
To install only Python packages (including the client), use::
yum install python-ironic-discoverd
Alternatively (e.g. if you need the latest version), you can install package
from PyPI_ (you may want to use virtualenv to isolate your environment)::
pip install ironic-discoverd
The third way for RPM-based distros is to use `ironic-discoverd copr`_ which
contains **unstable** git snapshots of **ironic-discoverd**.
.. _RDO: https://openstack.redhat.com/
.. _ironic-discoverd copr: https://copr.fedoraproject.org/coprs/divius/ironic-discoverd/
Finally, there is a `DevStack <http://docs.openstack.org/developer/devstack/>`_
plugin for **ironic-discoverd** - see
https://etherpad.openstack.org/p/DiscoverdDevStack for the current status.
Configuration
~~~~~~~~~~~~~
Copy ``example.conf`` to some permanent place
(``/etc/ironic-discoverd/discoverd.conf`` is what is used in the RPM).
Fill in at least configuration values with names starting with ``os_`` and
``identity_uri``. They configure how **ironic-discoverd** authenticates
with Keystone and checks authentication of clients.
Fill in at least these configuration values:
* ``os_username``, ``os_password``, ``os_tenant_name`` - Keystone credentials
to use when accessing other services and check client authentication tokens;
* ``os_auth_url``, ``identity_uri`` - Keystone endpoints for validating
authentication tokens and checking user roles;
* ``database`` - where you want **ironic-discoverd** SQLite database
to be placed;
Also set *database* option to where you want **ironic-discoverd** SQLite
database to be placed.
* ``dnsmasq_interface`` - interface on which ``dnsmasq`` (or another DHCP
service) listens for PXE boot requests (defaults to ``br-ctlplane`` which is
a sane default for TripleO_ based installations but is unlikely to work for
other cases).
See comments inside `example.conf
<https://github.com/stackforge/ironic-discoverd/blob/master/example.conf>`_
@ -118,7 +130,8 @@ As for PXE boot environment, you'll need:
ramdisk-image-create -o discovery fedora ironic-discoverd-ramdisk
You need diskimage-builder_ 0.1.38 or newer to do it.
You need diskimage-builder_ 0.1.38 or newer to do it (using the latest one
is always advised).
* You need PXE boot server (e.g. *dnsmasq*) running on **the same** machine as
**ironic-discoverd**. Don't do any firewall configuration:
@ -215,6 +228,11 @@ CLI tool is based on OpenStackClient_ with prefix
$ openstack baremetal introspection start UUID [--new-ipmi-password=PWD [--new-ipmi-username=USER]]
* ``uuid`` - Ironic node UUID;
* ``new_ipmi_username`` and ``new_ipmi_password`` - if these are set,
**ironic-discoverd** will switch to manual power on and assigning IPMI
credentials on introspection. See `Setting IPMI Credentials`_ for details.
* **Query introspection status**:
``get_status(uuid)``
@ -223,96 +241,13 @@ CLI tool is based on OpenStackClient_ with prefix
$ openstack baremetal introspection status UUID
.. _OpenStackClient: http://docs.openstack.org/developer/python-openstackclient/
HTTP API
~~~~~~~~
By default **ironic-discoverd** listens on ``0.0.0.0:5050``, port
can be changed in configuration. Protocol is JSON over HTTP.
The HTTP API consist of these endpoints:
* ``POST /v1/introspection/<UUID>`` initiate hardware discovery for node
``<UUID>``. All power management configuration for this node needs to be done
prior to calling the endpoint.
Requires X-Auth-Token header with Keystone token for authentication.
Optional parameters:
* ``new_ipmi_password`` if set, **ironic-discoverd** will try to set IPMI
password on the machine to this value. Power credentials validation will be
skipped and manual power on will be required. See `Setting IPMI
credentials`_ for details.
* ``new_ipmi_username`` provides new IPMI user name in addition to password
set by ``new_ipmi_password``. Defaults to current ``ipmi_username`` in
node ``driver_info`` field.
Response:
* 202 - accepted discovery request
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
* ``GET /v1/introspection/<UUID>`` get hardware discovery status.
Requires X-Auth-Token header with Keystone token for authentication.
Response:
* 200 - OK
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
Response body: JSON dictionary with keys:
* ``uuid`` - Ironic node UUID.
* ``finished`` (boolean) whether discovery is finished
* ``error`` error string or ``null``
Refer to HTTP-API.rst_ for information on the HTTP API.
* ``POST /v1/continue`` internal endpoint for the discovery ramdisk to post
back discovered data. Should not be used for anything other than implementing
the ramdisk. Request body: JSON dictionary with at least these keys:
* ``cpus`` number of CPU
* ``cpu_arch`` architecture of the CPU
* ``memory_mb`` RAM in MiB
* ``local_gb`` hard drive size in GiB
* ``interfaces`` dictionary filled with data from all NIC's, keys being
interface names, values being dictionaries with keys:
* ``mac`` MAC address
* ``ip`` IP address
* ``boot_interface`` optional MAC address of the NIC that the machine
PXE booted from either in standard format ``11:22:33:44:55:66`` or
in *PXELinux* ``BOOTIF`` format ``01-11-22-33-44-55-66``.
* ``block_devices`` optional block devices information for
``root_device_hint`` plugin, dictionary with keys:
* ``serials`` list of serial numbers of block devices.
.. note::
This list highly depends on enabled plugins, provided above are
expected keys for the default set of plugins. See Plugins_ for details.
Response:
* 200 - OK
* 400 - bad request
* 403 - node is not on introspection
* 404 - node cannot be found or multiple nodes found
Response body: JSON dictionary. If `Setting IPMI Credentials`_ is requested,
body will contain the following keys:
* ``ipmi_setup_credentials`` boolean ``True``
* ``ipmi_username`` new IPMI user name
* ``ipmi_password`` new IPMI password
.. _OpenStackClient: http://docs.openstack.org/developer/python-openstackclient/
.. _HTTP-API.rst: https://github.com/stackforge/ironic-discoverd/blob/master/HTTP-API.rst
.. _HTTP API: https://github.com/stackforge/ironic-discoverd/blob/master/HTTP-API.rst
Setting IPMI Credentials
~~~~~~~~~~~~~~~~~~~~~~~~
@ -373,9 +308,15 @@ Here are some plugins that can be additionally enabled:
``root_device_hint``
gathers block devices from ramdisk and exposes root device in multiple
runs.
``edeploy``
plugin for `eDeploy hardware detection and classification utilities`_,
requires a `special ramdisk`__.
Refer to CONTRIBUTING.rst_ for information on how to write your own plugin.
.. _eDeploy hardware detection and classification utilities: https://pypi.python.org/pypi/hardware
__ https://github.com/rdo-management/instack-undercloud/tree/master/elements/ironic-discoverd-ramdisk-instack
Release Notes
-------------
@ -418,9 +359,8 @@ See `1.1.0 release tracking page`_ for details.
**Other Changes**
* Experimental plugin ``edeploy`` to use with
`eDeploy hardware detection and classification utilities
<https://pypi.python.org/pypi/hardware>`_.
* Experimental plugin ``edeploy`` to use with `eDeploy hardware detection and
classification utilities`_.
See `eDeploy blueprint`_ for details.
@ -429,6 +369,8 @@ See `1.1.0 release tracking page`_ for details.
* Serious authentication issues were fixed, ``keystonemiddleware`` is a new
requirement.
* Basic support for i18n via oslo.i18n.
**Known Issues**
.. _1.1.0 release tracking page: https://bugs.launchpad.net/ironic-discoverd/+milestone/1.1.0
@ -443,6 +385,14 @@ users are advised to upgrade.
See `1.0.0 release tracking page`_ for details.
**1.0.1 release**
This maintenance fixed serious problem with authentication and unfortunately
brought new upgrade requirements:
* Dependency on *keystonemiddleware*;
* New configuration option ``identity_uri``, defaulting to localhost.
**Upgrade notes**
Action required:
@ -530,29 +480,7 @@ Action recommended:
~~~~~~~~~~
0.2 series is designed to work with OpenStack Juno release.
The major changes are:
**API**
* Authentication via Keystone for ``/v1/discover``.
* Expect ``interfaces`` instead of ``macs`` in post-back from the ramdisk
**[version 0.2.1]**.
* If ``interfaces`` is present, only add ports for NIC's with IP address set
**[version 0.2.1]**.
* ``/v1/discover`` now does some sync sanity checks **[version 0.2.2]**.
* Nodes will be always put into maintenance mode before discovery
**[version 0.2.1]**.
**Configuration**
* Periodic firewall update is now configurable.
* On each start-up make several attempts to check that Ironic is available
**[version 0.2.2]**.
**Misc**
* Simple client in ``ironic_discoverd.client``.
* Preliminary supported for Python 3.3 (real support depends on Eventlet).
Not supported any more.
0.1 Series
~~~~~~~~~~

2
tox.ini

@ -20,7 +20,7 @@ deps =
-r{toxinidir}/plugin-requirements.txt
commands =
flake8 ironic_discoverd
doc8 README.rst CONTRIBUTING.rst
doc8 README.rst CONTRIBUTING.rst HTTP-API.rst
[flake8]
max-complexity=15

Loading…
Cancel
Save