Add documentation to Ironic driver

Add minimal documentation to README file.

Change-Id: I0525835d9b5a5e833f9134f2f558b921993c682b

contrib/ironic/ironic-fa-deploy/README.rst

@@ -1,5 +1,81 @@
 Fuel Agent driver for Ironic
 ============================
 
-Fuel Agent driver adds possibility to use Fuel Agent as deploy agent
-for Ironic.
+``ironic-fa-deploy`` package adds support of Fuel Agent to OpenStack Ironic.
+Ironic [#]_ is baremetal provisioning service with support of multiple hardware
+types. Ironic architecture is able to work with deploy agents. Deploy agent
+is a service that does provisioning tasks on the node side. Deploy agent should
+be integrated into bootstrap ramdisk image.
+``ironic-fa-deploy`` contains pluggable drivers code for Ironic that uses
+Fuel Agent as deploy agent. Current implementation requires and tested with
+Ironic Liberty release.
+There are two drivers: ``fuel_ipmitool`` and ``fuel_ssh``. ``fuel_ipmitool``
+uses "ipmitool" utility for node power control and management via standard
+Ironic interfaces and Fuel Agent via Ironic deploy driver's interface.
+``fuel_ssh`` intended for virtual developers' environments.
+
+Node enrollment process with Fuel Agent
+---------------------------------------
+
+``fuel_ipmitool`` driver used in example.
+
+1. Enable the driver, add ``fuel_ipmitool`` to the list of ``enabled_drivers``
+   in ``[DEFAULT]`` section of ``/etc/ironic/ironic.conf``.
+
+2. Generate RSA key pair for SSH access to bootstrap system on the node.
+
+3. Create bootstrap files with Fuel Agent via ``fuel-bootstrap-image-builder``
+   script from ``fuel-main`` [#]_ project, public key should be injected into
+   bootstrap system. We should obtain three files as result: kernel, initrd
+   image and root FS image.
+
+4. Upload kernel, initrd image and root FS image to the Glance image service.
+
+.. note:: Fuel Agent driver requires OpenStack Swift or Ceph RADOS Gateway
+          as Glance backend.
+
+5. Create a node in Ironic with ``fuel_ipmitool`` driver and associate port
+   with the node::
+
+    ironic node-create -d fuel_ipmitool
+
+    ironic port-create -n <node uuid> -a <MAC address>
+
+6. Set IPMI address and credentials as described in the Ironic documentation
+   [#]_.
+
+7. Set Fuel Agent related driver's parameters for the node::
+
+    ironic node-update <node uuid> add driver_info/deploy_kernel=KERNEL \
+           driver_info/deploy_ramdisk=INITRD \
+           driver_info/deploy_squashfs=ROOTFS \
+           driver_info/fuel_key_filename=PRIVATE_KEY
+
+Replace KERNEL, INITRD, ROOTFS with Glance UUIDs of deploy images, PRIVATE_KEY
+with path to private key file.
+
+8. Place disks scheme in Nailgun format to the metadata of Glance instance
+   image with ``mos_disk_info`` key, example::
+
+    glance image-update <image uuid> --property mos_disk_info='[{"name": "sda",
+       "extra": [], "free_space": 11000, "type": "disk", "id": "vda",
+       "size": 11000, "volumes": [{"mount": "/", "type": "partition",
+       "file_system": "ext4", "size": 10000}]}]'
+
+After steps above the node is ready for deploying. User can invoke
+``nova boot`` command for deploying an instance image.
+
+
+TODO:
+
+* Add custom boot interface and refactor the drivers code with boot
+  interface [#]_.
+
+* Add cleaning support.
+
+* Add RAID support via Ironic RAID interface.
+
+.. [#] https://wiki.openstack.org/wiki/Ironic
+.. [#] https://github.com/openstack/fuel-main
+.. [#] http://docs.openstack.org/developer/ironic/deploy/install-guide.html
+.. [#] https://specs.openstack.org/openstack/ironic-specs/specs/4.2/new-boot-interface.html