From 358c113e7a7425165f8a64307d17ab7c10f6e66c Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Thu, 19 Mar 2015 15:29:24 +0100 Subject: [PATCH] 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 --- CONTRIBUTING.rst | 8 +- HTTP-API.rst | 100 ++++++++++++++++++++++++ README.rst | 192 +++++++++++++++-------------------------------- tox.ini | 2 +- 4 files changed, 167 insertions(+), 135 deletions(-) create mode 100644 HTTP-API.rst 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