Merge "Centralize user documentation"

doc/source/index.rst

@@ -11,7 +11,5 @@ Contents:
    :maxdepth: 1
 
    install/index
-   howto
+   user/index
    contributing
-   troubleshooting
-   vagrant

doc/source/troubleshooting.rst

@@ -1 +0,0 @@
-.. include:: ../../troubleshooting.rst

doc/source/user/howto.rst

@@ -322,10 +322,10 @@ If you wish to include an extra element into the IPA disk image, such as a
 custom hardware manager, you can pass the variable ``ipa_extra_dib_elements``
 as a space-separated list of elements. This defaults to an empty string.
 
-.. include:: deploy/dhcp.rst
+.. include:: dhcp.rst
 
 Use Bifrost with Keystone
 =========================
-.. include:: deploy/keystone.rst
+.. include:: keystone.rst
 
 

doc/source/user/index.rst

@@ -0,0 +1,15 @@
+##################
+Bifrost User Guide
+##################
+
+As bifrost is primarilly intended to be a tool for use by administrators,
+this documentation serves as a blend of both Admin and User documentation.
+
+.. toctree::
+   :maxdepth: 1
+
+   vagrant
+   virsh
+   howto
+   troubleshooting
+

doc/source/user/keystone.rst

@@ -11,10 +11,10 @@ Bifrost execution with Keystone
 ===============================
 
 Ultimately, as bifrost was designed for relatively short-lived
-installations for rapid hardware deployment, the default operating
+installations to facilitate rapid hardware deployment, the default
-mode is referred to as ``noauth`` mode. With that, in order to
+operating mode is referred to as ``noauth`` mode. With that,
-leverage keystone authentication for the roles, one of the
+in order to leverage keystone authentication for the roles,
-following steps need to take place.
+one of the following steps need to take place.
 
 #. Update the role defaults for each role you plan to make use.
    This may not make much sense  for most users, unless they are

doc/source/user/vagrant.rst

@@ -1,19 +1,34 @@
-==============================
+.. _vagrant:
-Vagrant support for developers
-==============================
 
-Bifrost vagrant file for developers can be found in the
+Bifrost via Vagrant
-``tools/vagrant_dev_env`` directory. Running ``vagrant up`` from
+===================
-within this folder will bring up an Ubuntu Trusty box with Bifrost
+
+One of the main user audiences that we've found is for users to utilize
+vagrant in order to build quick development environments, or for their
+environments to facilitate deployments, as the intent is for relatively
+short lived installations.
+
+As such, a virtual machine can be started with vagrant executing the
+following commands::
+
+  cd tools/vagrant_dev_env
+  vagrant up
+
+This will bring up an Ubuntu based virtual machine, with bifrost
 installed.
 
+.. note:: Virtual machine images, as well as all of the software
+          used in bifrost can take some time to install. Typically
+          expect ``vagrant up`` to take at least fifteen minutes if
+          you do not already have the virtual machine image on your
+          machine.
+
 By default, the VM will have three interfaces:
 
 - **eth0** - connected to a NAT network
 - **eth1** - connected to Host-only network named: vboxnet1
 - **eth2** - bridged - adapter must be set in Vagrantfile
 
--------------------------
 Walkthrough done on OS X
 -------------------------
 Setup vagrant by:
@@ -25,7 +40,7 @@ Setup vagrant by:
 
 Configure Vagrant with the correct box::
 
-  vagrant box add ubuntu/trusty64
+  vagrant box add ubuntu/xenial64
 
 Clone bifrost repo::
 
@@ -47,7 +62,6 @@ Boot the VM with::
 
   vagrant up
 
---------------------
 Installation Options
 --------------------
 Ansible is installed within the VM directly from `source

doc/source/user/virsh.rst

@@ -1,10 +1,12 @@
 Deploying with libvirt
 ======================
 
-In order to deploy bifrost with libvirt, but managing baremetal servers, a special
+In order to deploy bifrost with libvirt, in order to support managing
-network config needs to be setup.
+baremetal servers from with-in that libvirt VM, a special network
+configuration is required.
 
 Two networks need to be created:
+
 - default network, that will be a standard virtual network, using NAT.
 - provisioning network, that will be used for PXE boot. As we need to setup
   a dhcp server on bifrost guest, creating a virtual network will give
@@ -14,52 +16,52 @@ Two networks need to be created:
   Please note that you will need to have macvlan enabled on your kernel.
 
 When creating the guest, a minimum of 8GB of memory is needed in order to
-build disk images properly. Also when defining the interfaces for the guest, the two
+build disk images along with run the services to support bifrost.
-networks that have been created need to be attached.
 
-These sample commands will spin up a bifrost vm based on centos:
+When defining the interfaces for the guest, the two networks that have been
+created need to be attached.
 
-virsh net-define --file network/default.xml
+These sample commands will spin up a bifrost vm based on centos::
-virsh net-start default
+
-virsh net-define --file network/br_direct.xml
+  virsh net-define --file tools/virsh_dev_env/network/default.xml
-virsh net-start br_direct
+  virsh net-start default
-virsh define --file vm/baremetal.xml
+  virsh net-define --file tools/virsh_dev_env/network/br_direct.xml
-virsh start baremetal
+  virsh net-start br_direct
-virsh console baremetal
+  virsh define --file tools/virsh_dev_env/vm/baremetal.xml
+  virsh start baremetal
+  virsh console baremetal
 
 When you login into baremetal, the interface for the provisioning
-network will be down. You may need to add an IP manually:
+network will be down. You may need to add an IP manually::
 
-ip addr add <<provisioning_ip_address>>/<<mask>> dev <<interface>>
+  ip addr add <<provisioning_ip_address>>/<<mask>> dev <<interface>>
-ip link set <<interface>> up
+  ip link set <<interface>> up
 
 Where to get guest images
-=========================
+-------------------------
 In order to create the guest VMs, you will need a cloud image
 for the distro you want to deploy. You will need to download the
 guest image on a directory on the host, and then in the template
 for the VM, you can specify it on the disk section, as shown
 in the example template.
 
-Please follow the information on this link to get the images:
+Please see the `OpenStack Image Guide <http://docs.openstack.org/image-guide/obtain-images.html>`_
-
+for options and locations for obtaining guest images.
-http://docs.openstack.org/image-guide/obtain-images.html
 
 Add credentials to guest image
-==============================
+------------------------------
 
 Normally guest images come without user and password, they rely on ssh to
 allow access. In this case, it can be useful to enable ssh access to some
 user from host to guest. A way to do that, is creating a config drive
 and reference it on the template for the guest VM.
 
-A useful script to generate config drives can be found at:
+A useful script to generate config drives can be found
+`here <https://github.com/larsks/virt-utils/blob/master/create-config-drive>`_.
 
-https://github.com/larsks/virt-utils/blob/master/create-config-drive
+Relying on this script, a config drive can be created with::
 
-Relying on this script, a config drive can be created with:
+  create-config-drive -k ~/.ssh/id_rsa.pub config.iso
-
-create-config-drive -k ~/.ssh/id_rsa.pub config.iso
 
 And then this ISO can be referenced on the guest VM template.
 

doc/source/vagrant.rst

@@ -1 +0,0 @@
-.. include:: ../../README.vagrant.rst