From a0a013c9277656e1ad7d961e60f9789d2cffd4c9 Mon Sep 17 00:00:00 2001 From: Devananda van der Veen Date: Tue, 15 Apr 2014 12:08:13 -0700 Subject: [PATCH] Some minor clean up of various doc pages * simplify the links on index.rst * update the main description on the index page * move install/ironic-install under deploy/ * rename ironic-install to install-guide * rename userguide to user-guide * clarify a few things in the install-guide Change-Id: Ic6eff035df42d0c3fa78f54eac7ad8322ebb0afc --- .../install-guide.rst} | 53 +++++++------- .../deploy/{userguide.rst => user-guide.rst} | 1 + doc/source/dev/common.rst | 3 - doc/source/dev/db.rst | 2 +- doc/source/dev/drivers.rst | 6 ++ doc/source/index.rst | 71 +++++-------------- doc/source/webapi/v1.rst | 6 +- 7 files changed, 57 insertions(+), 85 deletions(-) rename doc/source/{install/ironic-install.rst => deploy/install-guide.rst} (88%) rename doc/source/deploy/{userguide.rst => user-guide.rst} (97%) diff --git a/doc/source/install/ironic-install.rst b/doc/source/deploy/install-guide.rst similarity index 88% rename from doc/source/install/ironic-install.rst rename to doc/source/deploy/install-guide.rst index 4c8caf5d98..e7bef559ff 100644 --- a/doc/source/install/ironic-install.rst +++ b/doc/source/deploy/install-guide.rst @@ -1,8 +1,11 @@ -.. _ironic-install: +.. _install-guide: -=========================== -Bare Metal Service Overview -=========================== +===================================== +Bare Metal Service Installation Guide +===================================== + +Service Overview +================ The Bare Metal Service is a collection of components that provides support to manage and provision physical machines. @@ -25,22 +28,25 @@ The Bare Metal Service includes the following components: ipmi or ssh; provisions/deploys/decommissions bare metal nodes. - Ironic client. A command-line interface (CLI) for interacting with the Bare Metal Service. -- Database. Stores node-related information. You can set the database - backend type and location, - but it is typically set to use the same database backend as the - Compute Service. + +Additionally, the Bare Metal Servive has certain external dependencies, which are +very similar to other OpenStack Services: + +- A database to store hardware information and state. You can set the database + backend type and location. A simple approach is to use the same database + backend as the Compute Service. Another approach is to use a separate + database backend to further isolate bare metal resources (and associated + metadata) from users. - A queue. A central hub for passing messages. It should use the same implementation as that of the Compute Service (typically RabbitMQ). -============================== -Install the Bare Metal Service -============================== +Install and Configure Prerequisites +=================================== -The Bare Metal Service is a collection of components that provides support -to manage and -provision physical machines. You can configure these components to run on -separate nodes or the same node. In this guide, the components run on one node, -typically the Compute Service's compute node. +The Bare Metal Service is a collection of components that provides support to +manage and provision physical machines. You can configure these components to +run on separate nodes or the same node. In this guide, the components run on +one node, typically the Compute Service's compute node. This section shows you how to install and configure the components. @@ -93,14 +99,13 @@ MySQL database that is used by other OpenStack services. Install the Bare Metal Service ------------------------------ -#. Install these packages:: +#. Install from packages:: # Available in Ubuntu 14.04 (trusty) apt-get install ironic-api ironic-conductor python-ironicclient - Configure the Bare Metal Service --------------------------------- +================================ The Bare Metal Service is configured via its configuration file. This file is typically located at ``/etc/ironic/ironic.conf``. @@ -114,8 +119,7 @@ configured for your needs. Configure the location of the database via the ``connection`` option. In the following, replace IRONIC_DBPASSWORD with the password of your ``ironic`` - user, and replace - DB_IP with the IP address where the DB server is located:: + user, and replace DB_IP with the IP address where the DB server is located:: [database] ... @@ -239,11 +243,10 @@ configured for your needs. Configure Compute Service to use the Bare Metal Service -------------------------------------------------------- +======================================================= The Compute Service needs to be configured to use the Bare Metal Service's -driver. -The configuration file for the Compute Service is typically located at +driver. The configuration file for the Compute Service is typically located at ``/etc/nova/nova.conf``. *This configuration file must be modified on the Compute Service's controller nodes and compute nodes.* @@ -319,7 +322,7 @@ Compute Service's controller nodes and compute nodes.* PXE Setup --------- -On the Bare Metal Service node where ``ironic-conductor`` is running, +On the Bare Metal Service node(s) where ``ironic-conductor`` is running, PXE needs to be set up. #. Make sure these directories exist:: diff --git a/doc/source/deploy/userguide.rst b/doc/source/deploy/user-guide.rst similarity index 97% rename from doc/source/deploy/userguide.rst rename to doc/source/deploy/user-guide.rst index 9a03ef650d..dfa547f3d6 100644 --- a/doc/source/deploy/userguide.rst +++ b/doc/source/deploy/user-guide.rst @@ -1,3 +1,4 @@ +.. _user-guide: ======================= Introduction to Ironic diff --git a/doc/source/dev/common.rst b/doc/source/dev/common.rst index 142b88cab4..da0dbd0f5f 100644 --- a/doc/source/dev/common.rst +++ b/doc/source/dev/common.rst @@ -1,5 +1,3 @@ -.. _common: - ============================ Common Modules and Utilities ============================ @@ -8,7 +6,6 @@ Common Modules and Utilities ../api/ironic.common.driver_factory ../api/ironic.common.exception ../api/ironic.common.hash_ring - ../api/ironic.common.images ../api/ironic.common.states ../api/ironic.common.utils diff --git a/doc/source/dev/db.rst b/doc/source/dev/db.rst index ea4b55126c..656b6e27e8 100644 --- a/doc/source/dev/db.rst +++ b/doc/source/dev/db.rst @@ -1,7 +1,7 @@ .. _db: ============ -DB API Layer +Database API ============ .. toctree:: diff --git a/doc/source/dev/drivers.rst b/doc/source/dev/drivers.rst index 8571f63352..0800ede5c9 100644 --- a/doc/source/dev/drivers.rst +++ b/doc/source/dev/drivers.rst @@ -8,12 +8,18 @@ The IPMITool driver provides an interface to the command-line `ipmitool`_ utility, whereas the IPMINative driver provides an interface to the newer `pyghmi`_ python library. +The SSH driver provides an interface to control the power state of virtual +machines used in our test environments. + +The SeaMicro driver provides an enhanced interface for SeaMicro hardware. + .. toctree:: ../api/ironic.drivers.base ../api/ironic.drivers.pxe ../api/ironic.drivers.modules.ipminative ../api/ironic.drivers.modules.ipmitool ../api/ironic.drivers.modules.pxe + ../api/ironic.drivers.modules.seamicro ../api/ironic.drivers.modules.ssh .. _ipmitool: http://ipmitool.sourceforge.net/ diff --git a/doc/source/index.rst b/doc/source/index.rst index ae9eca3406..b8feff4dc3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,68 +16,43 @@ VM, and so on), then Ironic may be thought of as a *hypervisor API* gluing together multiple drivers, each of which implement some portion of that functionality with respect to physical hardware. -For an in-depth look at the project's scope and structure, see the -:doc:`dev/architecture` page. +Ironic should be considered Beta quality as of the Icehouse release, and will +make the best effort to maintain backwards compatibility from this point +forward. Release notes are available here: +https://wiki.openstack.org/wiki/Ironic/ReleaseNotes/Icehouse +The developer documentation provided here is continually kept up-to-date based +on the latest code, and may not represent the state of our APIs at any given +release. -Status: Alpha Quality -===================== +Developer Guide +=============== -Ironic is targeting inclusion in the OpenStack Icehouse release. The current -codebase should be considered "alpha" quality. All major functional components -exist but there are many known bugs which will prevent general use at this -time. Additionally, usage documentation still needs to be written. - -If you are looking for the preceding baremetal service, which was included in -OpenStack Grizzly and Havana releases, please see Nova's `Baremetal driver`_. - -.. TODO -.. - installation -.. - configuration -.. - DB and AMQP -.. - API and Conductor services -.. - integration with other OS services -.. - any driver-specific configuration -.. - hardware enrollment -.. - manual vs automatic -.. - hw plugins - - -Developer Documentation -======================= - -Overview --------- +Introduction +------------ .. toctree:: :maxdepth: 1 dev/architecture dev/contributing + +.. toctree:: dev/dev-quickstart -Client API Reference --------------------- +API References +-------------- .. toctree:: :maxdepth: 1 webapi/v1 - -Python API Quick Reference --------------------------- - -.. toctree:: - :maxdepth: 1 - - dev/api dev/common dev/db dev/drivers - dev/conductor Admin Guide -======================= +=========== Overview ---------- @@ -85,15 +60,8 @@ Overview .. toctree:: :maxdepth: 1 - deploy/userguide - -Install Guide -------------- - -.. toctree:: - :maxdepth: 1 - - install/ironic-install + deploy/user-guide + deploy/install-guide Indices and tables ================== @@ -101,6 +69,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - - -.. _Baremetal Driver: https://wiki.openstack.org/wiki/Baremetal diff --git a/doc/source/webapi/v1.rst b/doc/source/webapi/v1.rst index b9ba6dd33f..f551e0e656 100644 --- a/doc/source/webapi/v1.rst +++ b/doc/source/webapi/v1.rst @@ -1,6 +1,6 @@ -============ - V1 Web API -============ +===================== + RESTful Web API (v1) +===================== Chassis =======