summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/images/arch-layout-test.pngbin0 -> 220515 bytes
-rw-r--r--docs/images/xci-basic-flow.pngbin0 -> 271248 bytes
-rw-r--r--docs/index.rst25
-rw-r--r--docs/xci-user-guide.rst374
4 files changed, 393 insertions, 6 deletions
diff --git a/docs/images/arch-layout-test.png b/docs/images/arch-layout-test.png
new file mode 100644
index 00000000..1a5f82b2
--- /dev/null
+++ b/docs/images/arch-layout-test.png
Binary files differ
diff --git a/docs/images/xci-basic-flow.png b/docs/images/xci-basic-flow.png
new file mode 100644
index 00000000..75b88e0e
--- /dev/null
+++ b/docs/images/xci-basic-flow.png
Binary files differ
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..35663e1c
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,25 @@
+.. _xci-overview:
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Fatih Degirmenci (fatih.degirmenci@ericsson.com)
+
+**************************************
+Cross Community Continuous Integration
+**************************************
+
+Contents:
+
+.. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ xci-overview.rst
+ xci-user-guide.rst
+ xci-developer-guide.rst
+ xci-wow.rst
+
+Indices and Tables
+==================
+
+* :ref:`search`
diff --git a/docs/xci-user-guide.rst b/docs/xci-user-guide.rst
index 0552f4e0..bc309465 100644
--- a/docs/xci-user-guide.rst
+++ b/docs/xci-user-guide.rst
@@ -4,12 +4,374 @@
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) Fatih Degirmenci (fatih.degirmenci@ericsson.com)
-==============
-XCI User Guide
-==============
+======================
+Sandbox and User Guide
+======================
-This document will contain the details of the sandbox and user guide.
+The Sandbox
+===========
-Introduction
-============
+Users and developers need to have an easy way to bring up an environment that
+fits to their purpose in a simple way in order to spend time on features they
+are developing, bugs they are fixing, trying things out, for learning purposes
+or just for fun rather than dealing with the tools and mechanisms used for
+creating and provisioning nodes, installing different components they do not
+intend to touch, and so on.
+We also have reality. For example, not all users and developers have full Pharos
+baremetal PODs or powerful machines waiting for them to use while doing their
+work or want to use different Linux distributions due to different reasons.
+It is important to take these into account and provide different configuration
+options for the sandbox based on the requirements the people have on the
+environment they will be using.
+
+Based on the observations we made and the feedback we received from the OPNFV
+users and the developers, XCI Team has created a sandbox that is highly
+configurable, simple and at the same time capable to provide a realistic
+environment for the people to do their work. The sandbox makes it possible to
+bring up the complete environment with a single command and offers variety of
+options to change how the stack should be deployed. The configuration of the
+sandbox is as easy as setting few environment variables.
+
+The sandbox provides
+
+* automated way to bring up and tear down complete stack
+* various flavors to pick and use
+* support for different Linux distributions
+* multiple OPNFV scenarios to install
+* ability to select different versions of upstream components to base the work on
+* ability to enable additional OpenStack services or disable others
+
+One last point to highlight here is that the XCI itself uses the sandbox for
+development and test purposes so it is continuously tested to ensure it works
+for XCI and for the users and the developers who are using it for different
+purposes.
+
+Components of the Sandbox
+===================================
+
+The sandbox uses OpenStack projects for VM node creation, provisioning
+and OpenStack installation. XCI Team provides playbooks, roles, and scripts
+to ensure the components utilized by the sandbox work in a way that serves
+the users in best possible way.
+
+* **openstack/bifrost:** Bifrost (pronounced bye-frost) is a set of Ansible
+ playbooks that automates the task of deploying a base image onto a set
+ of known hardware using ironic. It provides modular utility for one-off
+ operating system deployment with as few operational requirements as
+ reasonably possible. Bifrost supports different operating systems such as
+ Ubuntu, CentOS, and openSUSE.
+ More information about this project can be seen on
+ `Bifrost documentation <https://docs.openstack.org/developer/bifrost/>`_.
+
+* **openstack/openstack-ansible:** OpenStack-Ansible is an official OpenStack
+ project which aims to deploy production environments from source in a way
+ that makes it scalable while also being simple to operate, upgrade, and grow.
+ More information about this project can be seen on
+ `OpenStack Ansible documentation <https://docs.openstack.org/developer/openstack-ansible/>`_.
+
+* **opnfv/releng-xci:** OPNFV Releng Project provides additional scripts, Ansible
+ playbooks and configuration options in order for developers to have easy
+ way of using openstack/bifrost and openstack/openstack-ansible by just
+ setting couple of environment variables and executing a single script.
+ More infromation about this project can be seen on
+ `OPNFV Releng documentation <https://wiki.opnfv.org/display/releng>`_.
+
+Sandbox Flavors
+===============
+
+XCI Developer Sandbox provides 4 different configurations (flavors) that can be
+deployed using VM nodes.
+
+Available flavors are listed on the table below.
+
++------------------+------------------------+---------------------+-------------------------+
+| Flavor | Number of VM Nodes | VM Specs Per Node | Time Estimates |
++==================+========================+=====================+=========================+
+| All in One (aio) | | 1 VM Node | | vCPUs: 8 | | Provisioning: 10 mins |
+| | | controller & compute | | RAM: 12GB | | Deployment: 90 mins |
+| | | on single/same node | | Disk: 80GB | | Total: 100 mins |
+| | | 1 compute node | | NICs: 1 | | |
++------------------+------------------------+---------------------+-------------------------+
+| Mini | | 3 VM Nodes | | vCPUs: 6 | | Provisioning: 12 mins |
+| | | 1 deployment node | | RAM: 12GB | | Deployment: 65 mins |
+| | | 1 controller node | | Disk: 80GB | | Total: 77 mins |
+| | | 1 compute node | | NICs: 1 | | |
++------------------+------------------------+---------------------+-------------------------+
+| No HA | | 4 VM Nodes | | vCPUs: 6 | | Provisioning: 12 mins |
+| | | 1 deployment node | | RAM: 12GB | | Deployment: 70 mins |
+| | | 1 controller node | | Disk: 80GB | | Total: 82 mins |
+| | | 2 compute nodes | | NICs: 1 | | |
++------------------+------------------------+---------------------+-------------------------+
+| HA | | 6 VM Nodes | | vCPUs: 6 | | Provisioning: 15 mins |
+| | | 1 deployment node | | RAM: 12GB | | Deployment: 105 mins |
+| | | 3 controller nodes | | Disk: 80GB | | Total: 120 mins |
+| | | 2 compute nodes | | NICs: 1 | | |
++------------------+------------------------+---------------------+-------------------------+
+
+
+The specs for VMs are configurable and the more vCPU/RAM the better.
+
+Estimated times listed above are provided as guidance and they might vary
+depending on
+
+* the physical (or virtual) host where the sandbox is run
+* the specs of the VM nodes
+* the Linux distribution
+* whether the boot images are recreated or not
+* installed/activated OpenStack services
+* internet connection bandwidth
+
+Flavor Layouts
+--------------
+
+All flavors are created and deployed based on the upstream OpenStack Ansible (OSA)
+guidelines.
+
+Network configuration on the nodes are same no matter which flavor is used.
+The VMs are attached to default libvirt network and has single NIC where VLANs
+are created on. Different Linux bridges for management, storage and tunnel
+networks are created on these VLANs.
+
+Use of more *production-like* network setup with multiple interfaces is in the
+backlog.
+
+For storage, Cinder with NFS backend is used. Work to enable CEPH is currently
+ongoing.
+
+The differences between the flavors are documented below.
+
+**All in One**
+
+As shown on the table in previous section, this flavor consists of single
+node. All the OpenStack services, including compute run on the same node.
+
+The flavor All in One (aio) is deployed based on the process described on
+upstream documentation. Please check `OpenStack Ansible Developer Quick Start <https://docs.openstack.org/openstack-ansible/pike/contributor/quickstart-aio.html>`_ for details.
+
+**Mini/No HA/HA**
+
+These flavors consist of multiple nodes.
+
+* **opnfv**: This node is used for driving the installation towards target nodes
+ in order to ensure the deployment process is isolated from the physical host
+ and always done on clean machine.
+* **controller**: OpenStack control plane runs on this node.
+* **compute**: OpenStack compute service runs on this node.
+
+Please see the diagram below for the host and service layout for these
+flavors.
+
+.. image:: images/arch-layout-test.png
+ :scale: 75 %
+
+User Guide
+==========
+
+Prerequisites
+-------------
+
+* A machine with sufficient CPU/RAM/Disk based on the chosen flavor
+* Ubuntu 16.04, OpenSUSE Leap 42.3, or CentOS 7
+* CPU/motherboard that supports hardware-assisted virtualization
+* Passwordless sudo
+* An SSH key generated for your user (ie ~/.ssh/id_rsa)
+* Packages to install
+
+ * git
+ * python 2.7
+ * pip
+ * libvirt
+
+How to Use
+----------
+
+**Basic Usage**
+
+1. If you don't have one already, generate an SSH key in $HOME/.ssh
+
+ | ``ssh-keygen -t rsa``
+
+2. Clone OPNFV releng-xci repository
+
+ | ``git clone https://gerrit.opnfv.org/gerrit/releng-xci.git``
+
+3. Change into directory where the sandbox script is located
+
+ | ``cd releng-xci/xci``
+
+4. Execute the sandbox script
+
+ | ``./xci-deploy.sh``
+
+Issuing above command will start the sandbox deployment using the default
+flavor ``aio`` and the verified versions of upstream components.
+(`pinned-versions <https://git.opnfv.org/releng-xci/tree/xci/config/pinned-versions>`_).
+The sandbox should be ready between 1,5 and 2 hours depending on the host
+machine.
+
+After the script finishes execution, you can login to ``opnfv`` host and start
+using your new deployment.
+
+The openrc file will be available on ``opnfv`` host in ``$HOME``.
+
+**Advanced Usage**
+
+The flavor to deploy and the versions of upstream components to use can
+be configured by the users by setting certain environment variables.
+Below example deploys noha flavor using the latest of openstack-ansible
+master branch and stores logs in different location than what is set as
+default.
+
+1. If you don't have one already, generate an SSH key in $HOME/.ssh
+
+ | ``ssh-keygen -t rsa``
+
+2. Clone OPNFV releng-xci repository
+
+ | ``git clone https://gerrit.opnfv.org/gerrit/releng-xci.git``
+
+3. Change into directory where the sandbox script is located
+
+ | ``cd releng-xci/xci``
+
+4. Set the sandbox flavor
+
+ | ``export XCI_FLAVOR=noha``
+
+5. Set the version to use for openstack-ansible
+
+ | ``export OPENSTACK_OSA_VERSION=master``
+
+6. Set where the logs should be stored
+
+ | ``export LOG_PATH=/home/jenkins/xcilogs``
+
+7. Execute the sandbox script
+
+ | ``./xci-deploy.sh``
+
+Please note that changing the version to use may result in unexpected
+behaviors, especially if it is changed to ``master``. If you are not
+sure about how good the version you intend to use, it is advisable to
+use the pinned versions instead.
+
+**Verifying the Basic Operation**
+
+You can verify the basic operation using the commands below.
+
+1. Login to opnfv host
+
+ | ``ssh root@192.168.122.2``
+
+2. Source openrc file
+
+ | ``source openrc``
+
+3. Issue OpenStack commands
+
+ | ``openstack service list``
+
+You can also access to the Horizon UI by using the URL, username, and
+the password displayed on your console upon the completion of the
+deployment.
+
+**Debugging Tips**
+
+If ``xci-deploy.sh`` fails midway through and you happen to fix whatever
+problem it was that caused the failure in the first place, please run
+the script again. Do not attempt to continue the deployment using helper
+scripts such as ``bifrost-provision.sh``.
+
+Look at various logs in ``$LOG_PATH`` directory. (default one is /tmp/.xci-deploy-env/opnfv/logs)
+
+Behind the Scenes
+-----------------
+
+Here are the steps that take place upon the execution of the sandbox script
+``xci-deploy.sh``:
+
+1. Sources environment variables in order to set things up properly.
+2. Installs ansible on the host where sandbox script is executed.
+3. Creates and provisions VM nodes based on the flavor chosen by the user.
+4. Configures the host where the sandbox script is executed.
+5. Configures the deployment host which the OpenStack installation will
+ be driven from.
+6. Configures the target hosts where OpenStack will be installed.
+7. Configures the target hosts as controller(s) and compute(s) nodes.
+8. Starts the OpenStack installation.
+
+.. image:: images/xci-basic-flow.png
+ :scale: 75 %
+
+User Variables
+--------------
+
+All user variables can be set from command line by exporting them before
+executing the script. The current user variables can be seen from
+`user-vars <https://git.opnfv.org/releng-xci/tree/xci/config/user-vars>`_
+file located in releng-xci repository.
+
+The variables can also be set directly within the file before executing
+the sandbox script. If you do this, you need to set ``$RELENG_DEV_PATH``
+environment variable where the releng-xci repo is located on your host which
+you modified the files in.
+
+| ``export RELENG_DEV_PATH=/path/to/releng-xci/``
+
+Pinned Versions
+---------------
+
+As explained earlier, the users can pick and choose which versions to use. If
+you want to be on the safe side, you can use the pinned versions the sandbox
+provides. They can be seen from
+`pinned-versions <https://git.opnfv.org/releng-xci/tree/xci/config/pinned-versions>`_.
+
+OPNFV runs periodic jobs against upstream projects openstack/bifrost and
+openstack/openstack-ansible using latest on master branch, continuously
+chasing upstream to find well working version.
+
+Once a working version is identified, the versions of the upstream components
+are then bumped in releng-xci repo.
+
+Further Information
+-------------------
+
+If you intend to use the sandbox in more advanced ways or if you are developing
+XCI itself or an OPNFV scenario, please refer to
+:ref:`XCI Developer Guide <xci-developer-guide>`.
+
+Limitations, Known Issues, and Improvements
+===========================================
+
+The complete list can be seen using `this link <https://jira.opnfv.org/issues/?filter=11616>`_.
+
+Changelog
+=========
+
+Changelog can be seen using `this link <https://jira.opnfv.org/issues/?filter=11625>`_.
+
+Testing
+=======
+
+Sandbox is continuously tested by OPNFV XCI to ensure the changes do not impact
+users. In fact, OPNFV XCI itself uses the sandbox to ensure it is always in
+working state..
+
+Support
+=======
+
+OPNFV XCI issues are tracked on OPNFV JIRA Releng project. If you encounter
+and issue or identify a bug, please submit an issue to JIRA using
+`this link <https://jira.opnfv.org/projects/RELENG>`_. Please label the issue
+you are submitting with ``xci`` label.
+
+If you have questions or comments, you can ask them on ``#opnfv-pharos`` IRC
+channel on Freenode.
+
+References
+==========
+
+* `Bifrost Documentation <https://docs.openstack.org/bifrost/latest/>`_
+* `OpenStack Ansible Documentation <https://docs.openstack.org/openstack-ansible/latest/>`_
+* `OPNFV Releng Documentation <https://wiki.opnfv.org/display/releng>`_