diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 802665fe2..add6094a4 100644
--- a/CONTRIBUTING.rst
+++ b/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 `_ plugin - see
+https://etherpad.openstack.org/p/DiscoverdDevStack for the current status.
+
Writing a Plugin
~~~~~~~~~~~~~~~~
diff --git a/HTTP-API.rst b/HTTP-API.rst
new file mode 100644
index 000000000..0e88e625a
--- /dev/null
+++ b/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/`` initiate hardware introspection for node
+````. 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/`` 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
diff --git a/README.rst b/README.rst
index f4f364ba1..22434e829 100644
--- a/README.rst
+++ b/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 `_ 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 `_
+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:
-Also set *database* option to where you want **ironic-discoverd** SQLite
-database to be placed.
+* ``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;
+
+* ``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
`_
@@ -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
+ * ``uuid`` - Ironic node UUID.
+
+Refer to HTTP-API.rst_ for information on the HTTP API.
+
.. _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/`` initiate hardware discovery for node
- ````. 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/`` 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``
-
-* ``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
+.. _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
- `_.
+* 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
~~~~~~~~~~
diff --git a/tox.ini b/tox.ini
index 342f7e57b..14a46d4a2 100644
--- a/tox.ini
+++ b/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