Merge "Update documentation to deploy Ironic Inspector with DevStack"

CONTRIBUTING.rst

@@ -76,14 +76,28 @@ Of course you may have to modify ``example.conf`` to match your OpenStack
 environment.
 
 You can develop and test **ironic-inspector** using DevStack - see
-`DevStack Support`_ for the current status.
+`Deploying Ironic Inspector with DevStack`_ for the current status.
 
-DevStack Support
-~~~~~~~~~~~~~~~~
+Deploying Ironic Inspector with DevStack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `DevStack <http://docs.openstack.org/developer/devstack/>`_ provides a way to
-quickly build full OpenStack development environment with requested
-components. There is a plugin for installing **ironic-inspector** on DevStack.
+quickly build a full OpenStack development environment with requested
+components. There is a plugin for installing **ironic-inspector** in DevStack.
+Installing **ironic-inspector** requires a machine running Ubuntu 14.04 (or
+later) or Fedora 23 (or later). Make sure this machine is fully up to date and
+has the latest packages installed before beginning this process.
+
+Download DevStack::
+
+    git clone https://git.openstack.org/openstack-dev/devstack.git
+    cd devstack
+
+
+Create ``local.conf`` file with minimal settings required to
+enable both the **ironic** and the **ironic-inspector**. You can start with the
+`Example local.conf`_ and extend it as needed.
+
 
 Example local.conf
 ------------------
@@ -104,20 +118,57 @@ Notes
 * Network configuration is pretty sensitive, better not to touch it
   without deep understanding.
 
-* This configuration disables Heat and Cinder, adjust it if you need these
-  services.
+* This configuration disables **heat**, **cinder** and **tempest**, adjust it
+  if you need these services.
+
+Start the install::
+
+    ./stack.sh
 
 Usage
 -----
 
-Start introspection for a node manually::
+After installation is complete, you can source ``openrc`` in your shell, and
+then use the OpenStack CLI to manage your DevStack::
+
+    source openrc admin demo
+
+Show DevStack screens::
+
+    screen -x stack
+
+To exit screen, hit ``CTRL-a d``.
+
+List baremetal nodes::
+
+    openstack baremetal node list
+
+Bring the node to manageable state::
+
+    openstack baremetal node manage <NodeID>
+
+Inspect the node::
+
+    openstack baremetal node inspect <NodeID>
+
+.. note::
+    The deploy driver used must support the inspect interface. See also the
+    `Ironic Python Agent
+    <http://docs.openstack.org/developer/ironic/drivers/ipa.html#ipa>`_.
+
+A node can also be inspected using the following command. However, this will
+not affect the provision state of the node::
+
+    openstack baremetal introspection start <NodeID>
+
+Check inspection status::
+
+    openstack baremetal introspection status <NodeID>
 
-    source devstack/openrc admin admin
-    openstack baremetal introspection start <UUID>
+Optionally, get the inspection data::
 
-Then check status via API::
+    openstack baremetal introspection data save <NodeID>
 
-    openstack baremetal introspection status <UUID>
 
 Writing a Plugin
 ~~~~~~~~~~~~~~~~

devstack/example.local.conf

@@ -1,25 +1,61 @@
 [[local|localrc]]
+# Credentials
+# Reference: http://docs.openstack.org/developer/devstack/configuration.html
+ADMIN_PASSWORD=password
+DATABASE_PASSWORD=$ADMIN_PASSWORD
+RABBIT_PASSWORD=$ADMIN_PASSWORD
+SERVICE_PASSWORD=$ADMIN_PASSWORD
+SERVICE_TOKEN=$ADMIN_PASSWORD
+SWIFT_HASH=$ADMIN_PASSWORD
+
+# Enable Neutron which is required by Ironic and disable nova-network.
 disable_service n-net n-novnc
 enable_service neutron q-svc q-agt q-dhcp q-l3 q-meta
+
+# Enable Swift for agent_* drivers
 enable_service s-proxy s-object s-container s-account
-disable_service heat h-api h-api-cfn h-api-cw h-eng
-disable_service cinder c-sch c-api c-vol
 
+# Enable Ironic, Ironic Inspector plugins
 enable_plugin ironic https://github.com/openstack/ironic
 enable_plugin ironic-inspector https://github.com/openstack/ironic-inspector
 
-IRONIC_BAREMETAL_BASIC_OPS=True
+# Disable services
+disable_service horizon
+disable_service heat h-api h-api-cfn h-api-cw h-eng
+disable_service cinder c-sch c-api c-vol
+disable_service tempest
+
+# Swift temp URL's are required for agent_* drivers.
+SWIFT_ENABLE_TEMPURLS=True
+
+# Create 2 virtual machines to pose as Ironic's baremetal nodes.
 IRONIC_VM_COUNT=2
 IRONIC_VM_SPECS_RAM=1024
+IRONIC_VM_SPECS_DISK=10
+IRONIC_BAREMETAL_BASIC_OPS=True
+DEFAULT_INSTANCE_TYPE=baremetal
+
+# Enable Ironic drivers.
+IRONIC_ENABLED_DRIVERS=fake,agent_ipmitool,pxe_ipmitool
+
+# This driver should be in the enabled list above.
+IRONIC_DEPLOY_DRIVER=agent_ipmitool
 
 IRONIC_BUILD_DEPLOY_RAMDISK=False
 IRONIC_INSPECTOR_BUILD_RAMDISK=False
 
 VIRT_DRIVER=ironic
 
-LOGDAYS=1
-LOGFILE=~/logs/stack.sh.log
-SCREEN_LOGDIR=~/logs/screen
-
-DEFAULT_INSTANCE_TYPE=baremetal
 TEMPEST_ALLOW_TENANT_ISOLATION=False
+
+# By default, DevStack creates a 10.0.0.0/24 network for instances.
+# If this overlaps with the hosts network, you may adjust with the
+# following.
+NETWORK_GATEWAY=10.1.0.1
+FIXED_RANGE=10.1.0.0/24
+
+# Log all output to files
+LOGDAYS=1
+LOGFILE=$HOME/logs/stack.sh.log
+SCREEN_LOGDIR=$HOME/logs/screen
+IRONIC_VM_LOG_DIR=$HOME/ironic-bm-logs