openstack/bifrost
Code Issues Proposed changes

Re-arrange documentation for clearer first experience

Browse Source 
1. Expand the table of contents on the landing page to 3 levels of depth.
   There is no need to save space there, and an expanded table of contents
   allows much easier navigation.
2. Move testing environment information to the new contributor guide instead
   of being hidden inside of "How To".
3. Move "Advanced Topics" category in the installation guide one level up
   to make it more prominent (and visible in the landing page).

Includes a small ordering fix in the manual testing on the VMs guide: VM
configuration has to go first.

Change-Id: I7cadb268aedde381dc37ef610baac44bb2e8650a
This commit is contained in:
Dmitry Tantsur 2020-01-28 12:49:18 +01:00
parent fdeefa810f
commit 42d9b08431
6 changed files with 83 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/source/contributing.rst
View File

@ -1,4 +0,0 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

14
doc/source/contributor/index.rst Normal file
View File

@ -0,0 +1,14 @@
============
Contributing
============
.. include:: ../../../CONTRIBUTING.rst
------------
Other Topics
------------
.. toctree::
:maxdepth: 1
testenv

63
doc/source/contributor/testenv.rst Normal file
View File

@ -0,0 +1,63 @@
===================
Testing Environment
===================
Execute local testing
=====================
A simple ``scripts/test-bifrost.sh`` script can be utilized to install
pre-requisite software packages, Ansible, and then execute the
``test-bifrost-create-vm.yaml`` and ``test-bifrost.yaml`` playbooks in order
to provide a single step testing mechanism.
``playbooks/test-bifrost-create-vm.yaml`` creates one or more VMs for
testing and saves out a baremetal.json file which is used by
``playbooks/test-bifrost.yaml`` to execute the remaining roles. Two
additional roles are invoked by this playbook which enables Ansible to
connect to the new nodes by adding them to the inventory, and then
logging into the remote machine via the user's ssh host key. Once
that has successfully occurred, additional roles will unprovision the
host(s) and delete them from ironic.
Command::
scripts/test-bifrost.sh
Note:
- Cleaning mode is explicitly disabled in the ``test-bifrost.yaml``
playbook due to the fact that is an IO-intensive operation that can
take a great deal of time.
- In order to cap requirements for installation, an ``upper_constraints_file``
setting is defined. This is consuming the ``UPPER_CONSTRAINTS_FILE`` env
var by default, to properly integrate with CI systems, and will default
to ``/opt/stack/requirements/upper-constraints.txt`` file if not present.
Manually test with Virtual Machines
===================================
Bifrost supports using virtual machines to emulate the hardware.
It is assumed you have an SSH server running on the host machine. The
``agent_ssh`` driver, used by ironic with VM testing, will need to use
SSH to control the virtual machines.
An SSH key is generated for the ``ironic`` user when testing. The
ironic conductor will use this key to connect to the host machine and
run virsh commands.
#. Set ``testing`` to *true* in the
``playbooks/inventory/group_vars/target`` file.
#. You may need to adjust the value for ``ssh_public_key_path``.
#. Execute the ``ansible-playbook -vvvv -i inventory/target
test-bifrost-create-vm.yaml`` command to create a test virtual
machine.
#. Run the install step, as documented in :doc:`/install/index`, however
adding ``-e testing=true`` to the Ansible command line.
#. Set the environment variable of ``BIFROST_INVENTORY_SOURCE`` to the
path to the JSON file, which by default has been written to
/tmp/baremetal.json.
#. Run the enrollment step, as documented above, using the CSV file
you created in the previous step.
#. Run the deployment step, as documented above.

4
doc/source/index.rst
View File

@ -9,8 +9,8 @@ Contents
--------
.. toctree::
:maxdepth: 1
:maxdepth: 3
install/index
user/index
contributing
contributor/index

4
doc/source/install/index.rst
View File

@ -26,6 +26,9 @@ Supported operating systems:
* Fedora 22
* openSUSE Leap 42.1, 42.2
If you want to try Bifrost on a virtual environment, see
:doc:`/contributor/testenv`.
============
Installation
============
@ -266,6 +269,7 @@ If you would like to install the ironic staging drivers, simply pass
ansible-playbook -K -vvvv -i inventory/target install.yaml -e staging_drivers_include=true
===============
Advanced Topics
===============

60
doc/source/user/howto.rst
View File

@ -249,66 +249,6 @@ If the hosts need to be re-deployed, the dynamic redeploy playbook may be used::
This playbook will undeploy the hosts, followed by a deployment, allowing
a configurable timeout for the hosts to transition in each step.
Execute local testing
=====================
A simple ``scripts/test-bifrost.sh`` script can be utilized to install
pre-requisite software packages, Ansible, and then execute the
``test-bifrost-create-vm.yaml`` and ``test-bifrost.yaml`` playbooks in order
to provide a single step testing mechanism.
``playbooks/test-bifrost-create-vm.yaml`` creates one or more VMs for
testing and saves out a baremetal.json file which is used by
``playbooks/test-bifrost.yaml`` to execute the remaining roles. Two
additional roles are invoked by this playbook which enables Ansible to
connect to the new nodes by adding them to the inventory, and then
logging into the remote machine via the user's ssh host key. Once
that has successfully occurred, additional roles will unprovision the
host(s) and delete them from ironic.
Command::
scripts/test-bifrost.sh
Note:
- Cleaning mode is explicitly disabled in the ``test-bifrost.yaml``
playbook due to the fact that is an IO-intensive operation that can
take a great deal of time.
- In order to cap requirements for installation, an ``upper_constraints_file``
setting is defined. This is consuming the ``UPPER_CONSTRAINTS_FILE`` env
var by default, to properly integrate with CI systems, and will default
to ``/opt/stack/requirements/upper-constraints.txt`` file if not present.
Manually test with Virtual Machines
===================================
Bifrost supports using virtual machines to emulate the hardware.
It is assumed you have an SSH server running on the host machine. The
``agent_ssh`` driver, used by ironic with VM testing, will need to use
SSH to control the virtual machines.
An SSH key is generated for the ``ironic`` user when testing. The
ironic conductor will use this key to connect to the host machine and
run virsh commands.
#. Set ``testing`` to *true* in the
``playbooks/inventory/group_vars/target`` file.
#. You may need to adjust the value for ``ssh_public_key_path``.
#. Run the install step, as documented above, however adding ``-e
testing=true`` to the Ansible command line.
#. Execute the ``ansible-playbook -vvvv -i inventory/target
test-bifrost-create-vm.yaml`` command to create a test virtual
machine.
#. Set the environment variable of ``BIFROST_INVENTORY_SOURCE`` to the
path to the JSON file, which by default has been written to
/tmp/baremetal.json.
#. Run the enrollment step, as documented above, using the CSV file
you created in the previous step.
#. Run the deployment step, as documented above.
Deployment and configuration of operating systems
=================================================