Add Ironic User Guide

Add a User guide, Initial chapters to cover introduction, architecture
diagrams, terminology for Ironic service.

Change-Id: I08faac6204aa412e330362133eb14241f3c21b34

4 files changed, 121 insertions, 0 deletions

diff --git a/doc/source/deploy/userguide.rst b/doc/source/deploy/userguide.rst
new file mode 100644
index 000000000..9a03ef650
--- /dev/null
+++ b/doc/source/deploy/userguide.rst
@@ -0,0 +1,110 @@
+

+=======================

+Introduction to Ironic

+=======================

+|

+     Ironic is an OpenStack project which provisions physical hardware as opposed to virtual machines.

+     Ironic provides several reference drivers which leverage common technologies like PXE and IPMI, to

+     cover a wide range of hardware. Ironic's pluggable driver architecture also allows vendor-specific

+     drivers to be added for improved performance or functionality not provided by reference drivers.

+|

+     If one thinks of traditional hypervisor functionality (e.g., creating a VM, enumerating virtual devices, managing

+     the power state, loading an OS onto the 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.

+|

+|

+     Openstack's Ironic project makes physical servers as easy to provision as virtual machines in cloud, which in turn will

+     open up new avenues for enterprises and service providers.

+|

+     Ironic's driver will replace the Nova "bare metal" driver of Grizzly, Havana and Icehouse releases. It is targeting inclusion

+     in the OpenStack Juno release. See https://wiki.openstack.org/wiki/Baremetal for more information.

+|

+|

+Why Provision Bare Metal

+==========================

+|

+     Here are a few use-cases for bare metal (physical server) provisioning in cloud; there are doubtless many more interesting ones.

+|

+|

+        High-performance computing clusters

+|

+        Computing tasks that require access to hardware devices which can't be virtualized

+|

+        Database hosting (some databases run poorly in a hypervisor)

+|

+        Single tenant, dedicated hardware for performance, security, dependability and other regulatory requirements

+|

+        Or, rapidly deploying a cloud infrastructure

+|

+|

+Conceptual Architecture

+========================

+|

+     The following diagram shows the relationships and how all services come into play during the provisioning of a

+     physical server.

+|

+.. figure:: ../images/conceptual_architecture.gif

+   :alt: ConceptualArchitecture

+|

+|

+Logical Architecture

+=====================

+|

+     The Ironic service is composed of the following components,

+|

+|

+     A RESTful API service, by which operators and other services may interact with the managed bare metal servers.

+|

+|

+     A Conductor service, which does the bulk of the work. Functionality is exposed via the API service.

+     The Conductor and API services communicate via RPC.

+|

+|

+     A Message Queue

+|

+|

+     A Database for storing the state of the Conductor and Drivers.

+|

+|

+

+.. figure:: ../images/logical_architecture.gif

+   :alt: Logical Architecture

+|

+|

+Key Technologies for Bare Metal Hosting

+===========================================

+|

+PXE

+-----

+|

+Preboot Execution Environment (PXE) is part of the Wired for Management (WfM) specification developed by Intel and Microsoft.

+The PXE enables system's BIOS and network interface card (NIC) to bootstrap a computer from the network in place of a disk. Bootstrapping is the process by which a system loads the OS into local memory so that it can be executed by the processor.

+This capability of allowing a system to boot over a network simplifies server deployment and server management for administrators.

+

+|

+DHCP

+------

+|

+Dynamic Host Configuration Protocol (DHCP) is a standardized networking protocol used on Internet Protocol (IP) networks for dynamically distributing network configuration parameters, such as IP addresses for interfaces and services.

+Using PXE, the BIOS uses DHCP to obtain an IP address for the network interface and to locate the server that stores the network bootstrap program (NBP).

+

+|

+NBP

+------

+|

+Network Bootstrap Program (NBP) is equivalent to GRUB (GRand Unified Bootloader) or LILO (LInux LOader) - loaders which are traditionally used in local booting. Like the boot program in a hard drive environment, the NBP is responsible for loading the OS kernel into memory so that the OS can be bootstrapped over a network.

+

+|

+TFTP

+------

+|

+        Trivial File Transfer Protocol (TFTP) is a simple file transfer protocol that is generally used for automated transfer of configuration or boot files between machines in a local environment.

+In a PXE environment, TFTP is used to download NBP over the network using information from the DHCP server.

+

+|

+IPMI

+------

+|

+Intelligent Platform Management Interface (IPMI) is a standardized computer system interface used by system administrators for out-of-band management of computer systems and monitoring of their operation.

+It is a method to manage systems that may be unresponsive or powered off by using only a network connection to the hardware rather than to an operating system.

+

diff --git a/doc/source/images/conceptual_architecture.gif b/doc/source/images/conceptual_architecture.gif
new file mode 100644
index 000000000..dd75e79a3
--- /dev/null
+++ b/doc/source/images/conceptual_architecture.gif
diff --git a/doc/source/images/logical_architecture.gif b/doc/source/images/logical_architecture.gif
new file mode 100644
index 000000000..40d6679e6
--- /dev/null
+++ b/doc/source/images/logical_architecture.gif
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4d6ecc95d..2164ca824 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -76,6 +76,17 @@ Python API Quick Reference
   dev/drivers
   dev/conductor
 
+Admin Guide
+=======================
+
+Overview
+----------
+
+.. toctree::
+  :maxdepth: 1
+
+  deploy/userguide
+
 Indices and tables
 ==================