[DOCS] Adding Ironic configuration docs to Ansible

install guide

Change-Id: Ic8c5a2638049ab957bc7095071235f84d178fa3f

doc/source/install-guide/configure-ironic-baremetal-node.rst

@@ -0,0 +1,21 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+Deploy a baremetal node kicked with Ironic
+------------------------------------------
+
+.. important::
+
+   You will not have access unless you have a key set within Nova before
+   your Ironic deployment. If you do not have an ssh key readily
+   available, set one up with ``ssh-keygen``.
+
+.. code-block:: bash
+
+    nova keypair-add --pub-key ~/.ssh/id_rsa.pub admin
+
+Now boot a node:
+
+.. code-block:: bash
+
+   nova boot --flavor ${FLAVOR_NAME} --image ${IMAGE_NAME} --key-name admin ${NODE_NAME}
+

doc/source/install-guide/configure-ironic-deployment.rst

@@ -0,0 +1,12 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+OpenStack-Ansible deployment
+----------------------------
+
+#. Modify the environment files and force ``nova-compute`` to run from
+   within a container:
+
+   .. code-block:: bash
+
+      sed -i '/is_metal.*/d' /etc/openstack_deploy/env.d/nova.yml
+

doc/source/install-guide/configure-ironic-flavor.rst

@@ -0,0 +1,30 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+Creating an Ironic flavor
+-------------------------
+
+#. Create a new flavor called ``my-baremetal-flavor``.
+
+   .. note::
+
+      The following example sets the CPU architecture for the newly created
+      flavor to be `x86_64`.
+
+   .. code-block:: bash
+
+      nova flavor-create ${FLAVOR_NAME} ${FLAVOR_ID} ${FLAVOR_RAM} ${FLAVOR_DISK} ${FLAVOR_CPU}
+      nova flavor-key ${FLAVOR_NAME} set cpu_arch=x86_64
+      nova flavor-key ${FLAVOR_NAME} set capabilities:boot_option="local"
+
+.. note::
+
+   The flavor and nodes should match when enrolling into Ironic.
+   See the documentation on flavors for more information:
+   http://docs.openstack.org/openstack-ops/content/flavors.html
+
+After successfully deploying the ironic node on subsequent boots, the instance
+will boot from your local disk as first preference. This will speed up the deployed
+node's boot time. The alternative, if this is not set, will mean the ironic node will
+attempt to PXE boot first, which will allow for operator-initiated image updates and
+other operations. The operational reasoning and building an environment to support this
+use case is not covered here.

doc/source/install-guide/configure-ironic-images.rst

@@ -0,0 +1,66 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+Building Ironic images
+----------------------
+
+Images using the ``diskimage-builder`` must be built outside of a container.
+For this process, use one of the physical hosts within the environment.
+
+#. Install the necessary packages:
+
+   .. code-block:: bash
+
+      apt-get install -y qemu uuid-runtime curl
+
+#. Install the ``disk-imagebuilder`` client:
+
+   .. code-block:: bash
+
+      pip install diskimage-builder --isolated
+
+   .. important::
+
+      Only use the ``--isolated`` flag if you are building on a node that
+      has already been deployed by OpenStack-Ansible as pip will not
+      allow the external package to be resolved.
+
+#. Optional: Force the ubuntu ``image-create`` process to use a modern kernel:
+
+   .. code-block:: bash
+
+      echo 'linux-image-generic-lts-xenial:' > /usr/local/share/diskimage-builder/elements/ubuntu/package-installs.yaml
+
+#. Create Ubuntu ``initramfs``:
+
+   .. code-block:: bash
+
+      disk-image-create ironic-agent ubuntu -o ${IMAGE_NAME}
+
+#. Upload the created deploy images into the Image Service:
+
+   .. code-block:: bash
+
+      # Upload the deploy image kernel
+      glance image-create --name ${IMAGE_NAME}.kernel --visibility public --disk-format aki --container-format aki < ${IMAGE_NAME}.kernel
+
+      # Upload the user image initramfs
+      glance image-create --name ${IMAGE_NAME}.initramfs --visibility public --disk-format ari --container-format ari < ${IMAGE_NAME}.initramfs
+
+#. Create Ubuntu user image:
+
+   .. code-block:: bash
+
+      disk-image-create ubuntu baremetal localboot local-config dhcp-all-interfaces grub2 -o ${IMAGE_NAME}
+
+#. Upload the created user images into the Image Service:
+
+   .. code-block:: bash
+
+      # Upload the user image vmlinuz and store uuid
+      VMLINUZ_UUID="$(glance image-create --name ${IMAGE_NAME}.vmlinuz --visibility public --disk-format aki --container-format aki  < ${IMAGE_NAME}.vmlinuz | awk '/\| id/ {print $4}')"
+
+      # Upload the user image initrd and store uuid
+      INITRD_UUID="$(glance image-create --name ${IMAGE_NAME}.initrd --visibility public --disk-format ari --container-format ari  < ${IMAGE_NAME}.initrd | awk '/\| id/ {print $4}')"
+
+      # Create image
+      glance image-create --name ${IMAGE_NAME} --visibility public --disk-format qcow2 --container-format bare --property kernel_id=${VMLINUZ_UUID} --property ramdisk_id=${INITRD_UUID} < ${IMAGE_NAME}.qcow2

doc/source/install-guide/configure-ironic-neutron.rst

@@ -0,0 +1,22 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+Setup a Neutron network for use Ironic
+--------------------------------------
+
+In the general case, the Neutron network can be a simple flat network. However,
+in a complex case, this can be whatever you need and want. Ensure
+you adjust the deployment accordingly. The following is an example:
+
+
+.. code-block:: bash
+
+    neutron net-create cleaning-net --shared \
+                                    --provider:network_type flat \
+                                    --provider:physical_network ironic-net
+
+    neutron subnet-create ironic-net 172.19.0.0/22 --name ironic-subnet
+                                                   --ip-version=4 \
+                                                   --allocation-pool start=172.19.1.100,end=172.19.1.200 \
+                                                   --enable-dhcp \
+                                                   --dns-nameservers list=true 8.8.4.4 8.8.8.8
+

doc/source/install-guide/configure-ironic-nodes.rst

@@ -0,0 +1,52 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+Enroll Ironic nodes
+-------------------
+
+#. From the utility container, enroll a new baremetal node by executing the following:
+
+   .. code-block:: bash
+
+      # Source credentials
+      . ~/openrc
+
+      # Create the node
+      NODE_HOSTNAME="myfirstnodename"
+      IPMI_ADDRESS="10.1.2.3"
+      IPMI_USER="my-ipmi-user"
+      IPMI_PASSWORD="my-ipmi-password"
+      KERNEL_IMAGE=$(glance image-list | awk "/${IMAGE_NAME}.kernel/ {print \$2}")
+      INITRAMFS_IMAGE=$(glance image-list | awk "/${IMAGE_NAME}.initramfs/ {print \$2}")
+      ironic node-create \
+            -d agent_ipmitool \
+            -i ipmi_address="${IPMI_ADDRESS}" \
+            -i ipmi_username="${IPMI_USER}" \
+            -i ipmi_password="${IPMI_PASSWORD}" \
+            -i deploy_ramdisk="${INITRAMFS_IMAGE}" \
+            -i deploy_kernel="${KERNEL_IMAGE}" \
+            -n ${NODE_HOSTNAME}
+
+      # Create a port for the node
+      NODE_MACADDRESS="aa:bb:cc:dd:ee:ff"
+      ironic port-create \
+            -n $(ironic node-list | awk "/${NODE_HOSTNAME}/ {print \$2}") \
+            -a ${NODE_MACADDRESS}
+
+      # Associate an image to the node
+      ROOT_DISK_SIZE_GB=40
+      ironic node-update $(ironic node-list | awk "/${IMAGE_NAME}/ {print \$2}") add \
+          driver_info/deploy_kernel=$KERNEL_IMAGE \
+          driver_info/deploy_ramdisk=$INITRAMFS_IMAGE \
+          instance_info/deploy_kernel=$KERNEL_IMAGE \
+          instance_info/deploy_ramdisk=$INITRAMFS_IMAGE \
+          instance_info/root_gb=${ROOT_DISK_SIZE_GB}
+
+      # Add node properties
+      # The property values used here should match the hardware used
+      ironic node-update $(ironic node-list | awk "/${NODE_HOSTNAME}/ {print \$2}") add \
+          properties/cpus=48 \
+          properties/memory_mb=254802 \
+          properties/local_gb=80 \
+          properties/size=3600 \
+          properties/cpu_arch=x86_64 \
+          properties/capabilities=memory_mb:254802,local_gb:80,cpu_arch:x86_64,cpus:48,boot_option:local

doc/source/install-guide/configure-ironic.rst

@@ -0,0 +1,28 @@
+`Home <index.html>`_ OpenStack-Ansible Installation Guide
+
+Configuring the ironic service (optional)
+-----------------------------------------
+
+.. note::
+
+   This feature is experimental at this time and it has not been fully production
+   tested yet. This implementation instructions assume that Ironic is being deployed
+   as the sole hypervisor for the region.
+
+.. toctree::
+
+   configure-ironic-deployment.rst
+   configure-ironic-neutron.rst
+   configure-ironic-images.rst
+   configure-ironic-flavor.rst
+   configure-ironic-nodes.rst
+   configure-ironic-baremetal-node.rst
+
+Ironic is an OpenStack project which provisions bare metal (as opposed to virtual)
+machines by leveraging common technologies such as PXE boot and IPMI to cover a wide
+range of hardware, while supporting pluggable drivers to allow vendor-specific
+functionality to be added.
+
+OpenStack’s Ironic project makes physical servers as easy to provision as
+virtual machines in a cloud, which in turn will open up new avenues for enterprises
+and service providers.

doc/source/install-guide/configure.rst

@@ -11,6 +11,7 @@ Chapter 4. Deployment configuration
    configure-creds.rst
    configure-hypervisor.rst
    configure-nova.rst
+   configure-ironic.rst
    configure-glance.rst
    configure-cinder.rst
    configure-swift.rst

releasenotes/notes/ironic-integration-264c4ed622a3a04e.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - Experimental support has been added to allow the deployment of the
+    OpenStack Bare Metal Service (Ironic). Details for how to set it up
+    are available in the `OpenStack-Ansible Install Guide for Ironic
+    <http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-ironic.html>`_.