prototypes/xci/README.rst

   1 ###########################
   2 OPNFV XCI Developer Sandbox
   3 ###########################
   4
   5 The XCI Developer Sandbox is created by the OPNFV community for the OPNFV
   6 community in order to
   7
   8 - provide means for OPNFV developers to work with OpenStack master branch,
   9   cutting the time it takes to develop new features significantly and testing
  10   them on OPNFV Infrastructure
  11 - enable OPNFV developers to identify bugs earlier, issue fixes faster, and
  12   get feedback on a daily basis
  13 - establish mechanisms to run additional testing on OPNFV Infrastructure to
  14   provide feedback to OpenStack community
  15 - make the solutions we put in place available to other LF Networking Projects
  16   OPNFV works with closely
  17
  18 More information about OPNFV XCI and the sandbox can be seen on
  19 `OPNFV Wiki <https://wiki.opnfv.org/pages/viewpage.action?pageId=8687635>`_.
  20
  21 ===================================
  22 Components of XCI Developer Sandbox
  23 ===================================
  24
  25 The sandbox uses OpenStack projects for VM node creation, provisioning
  26 and OpenStack installation.
  27
  28 - **openstack/bifrost:** Bifrost (pronounced bye-frost) is a set of Ansible
  29   playbooks that automates the task of deploying a base image onto a set
  30   of known hardware using ironic. It provides modular utility for one-off
  31   operating system deployment with as few operational requirements as
  32   reasonably possible. Bifrost supports different operating systems such as
  33   Ubuntu, CentOS, and openSUSE.
  34   More information about this project can be seen on
  35   `Bifrost documentation <https://docs.openstack.org/developer/bifrost/>`_.
  36
  37 - **openstack/openstack-ansible:** OpenStack-Ansible is an official OpenStack
  38   project which aims to deploy production environments from source in a way
  39   that makes it scalable while also being simple to operate, upgrade, and grow.
  40   More information about this project can be seen on
  41   `OpenStack Ansible documentation <https://docs.openstack.org/developer/openstack-ansible/>`_.
  42
  43 - **opnfv/releng:** OPNFV Releng Project provides additional scripts, Ansible
  44   playbooks and configuration options in order for developers to have easy
  45   way of using openstack/bifrost and openstack/openstack-ansible by just
  46   setting couple of environment variables and executing a single script.
  47   More infromation about this project can be seen on
  48   `OPNFV Releng documentation <https://wiki.opnfv.org/display/releng>_`.
  49
  50 ==========
  51 Basic Flow
  52 ==========
  53
  54 Here are the steps that take place upon the execution of the sandbox script
  55 ``xci-deploy.sh``:
  56
  57 1. Sources environment variables in order to set things up properly.
  58 2. Installs ansible on the host where sandbox script is executed.
  59 3. Creates and provisions VM nodes based on the flavor chosen by the user.
  60 4. Configures the host where the sandbox script is executed.
  61 5. Configures the deployment host which the OpenStack installation will
  62    be driven from.
  63 6. Configures the target hosts where OpenStack will be installed.
  64 7. Configures the target hosts as controller(s) and compute(s) nodes.
  65 8. Starts the OpenStack installation.
  66
  67 =====================
  68 Sandbox Prerequisites
  69 =====================
  70
  71 In order to use this sandbox, the host must have certain packages installed.
  72
  73 - libvirt
  74 - python
  75 - pip
  76 - git
  77 - <fix the list with all the dependencies>
  78 - passwordless sudo
  79
  80 The host must also have enough CPU/RAM/Disk in order to host number of VM
  81 nodes that will be created based on the chosen flavor. See the details from
  82 `this link <https://wiki.opnfv.org/display/INF/XCI+Developer+Sandbox#XCIDeveloperSandbox-Prerequisites>`_.
  83
  84 ===========================
  85 Flavors Provided by Sandbox
  86 ===========================
  87
  88 OPNFV XCI Sandbox provides different flavors such as all in one (aio) which
  89 puts much lower requirements on the host machine and full-blown HA.
  90
  91 * aio: Single node which acts as the deployment host, controller and compute.
  92 * mini: One deployment host, 1 controller node and 1 compute node.
  93 * noha: One deployment host, 1 controller node and 2 compute nodes.
  94 * ha: One deployment host, 3 controller nodes and 2 compute nodes.
  95
  96 See the details of the flavors from
  97 `this link <https://wiki.opnfv.org/display/INF/XCI+Developer+Sandbox#XCIDeveloperSandbox-AvailableFlavors>`_.
  98
  99 ==========
 100 How to Use
 101 ==========
 102
 103 Basic Usage
 104 -----------
 105
 106 clone OPNFV Releng repository
 107
 108     git clone https://gerrit.opnfv.org/gerrit/releng.git
 109
 110 change into directory where the sandbox script is located
 111
 112     cd releng/prototypes/xci
 113
 114 execute sandbox script
 115
 116     ./xci-deploy.sh
 117
 118 Issuing above command will start aio sandbox deployment and the sandbox
 119 should be ready between 1,5 and 2 hours depending on the host machine.
 120
 121 Please remember that the user executing the XCI script will need to
 122 have an ssh key available, and stored in $HOME/.ssh directory.
 123 You can generate one by executing
 124
 125     ssh-keygen -t rsa
 126
 127 Advanced Usage
 128 --------------
 129
 130 The flavor to deploy, the versions of upstream components to use can
 131 be configured by developers by setting certain environment variables.
 132 Below example deploys noha flavor using the latest of openstack-ansible
 133 master branch and stores logs in different location than what is configured.
 134
 135 clone OPNFV Releng repository
 136
 137     git clone https://gerrit.opnfv.org/gerrit/releng.git
 138
 139 change into directory where the sandbox script is located
 140
 141     cd releng/prototypes/xci
 142
 143 set the sandbox flavor
 144
 145     export XCI_FLAVOR=noha
 146
 147 set the version to use for openstack-ansible
 148
 149     export OPENSTACK_OSA_VERSION=master
 150
 151 set where the logs should be stored
 152
 153     export LOG_PATH=/home/jenkins/xcilogs
 154
 155 execute sandbox script
 156
 157     ./xci-deploy.sh
 158
 159 ===============
 160 User Variables
 161 ===============
 162
 163 All user variables can be set from command line by exporting them before
 164 executing the script. The current user variables can be seen from
 165 ``releng/prototypes/xci/config/user-vars``.
 166
 167 The variables can also be set directly within the file before executing
 168 the sandbox script.
 169
 170 ===============
 171 Pinned Versions
 172 ===============
 173
 174 As explained above, the users can pick and choose which versions to use. If
 175 you want to be on the safe side, you can use the pinned versions the sandbox
 176 provides. They can be seen from ``releng/prototypes/xci/config/pinned-versions``.
 177
 178 How Pinned Versions are Determined
 179 ----------------------------------
 180
 181 OPNFV runs periodic jobs against upstream projects openstack/bifrost and
 182 openstack/ansible using latest on master and stable/ocata branches,
 183 continuously chasing the HEAD of corresponding branches.
 184
 185 Once a working version is identified, the versions of the upstream components
 186 are then bumped in releng repo.
 187
 188 ==================
 189 XCI developer tips
 190 ==================
 191
 192 It is possible to run XCI in development mode, in order to test the
 193 latest changes. When deploying on this mode, the script will use the working
 194 directories for releng/bifrost/OSA, instead of cloning the whole repositories
 195 on each run.
 196 To enable it, you need to export the different DEV_PATH vars:
 197
 198 - export OPNFV_RELENG_DEV_PATH=/opt/releng/
 199 - export OPENSTACK_BIFROST_DEV_PATH=/opt/bifrost/
 200 - export OPENSTACK_OSA_DEV_PATH=/opt/openstack-ansible/
 201
 202 Please note the trailing slahses.
 203
 204 This will cause the deployment to pick the development copies stored at the
 205 specified directories, and use them instead of cloning those on every run.
 206
 207 ===========================================
 208 Limitations, Known Issues, and Improvements
 209 ===========================================
 210
 211 The list can be seen using `this link <https://jira.opnfv.org/issues/?filter=11616>`_.
 212
 213 =========
 214 Changelog
 215 =========
 216
 217 Changelog can be seen using `this link <https://jira.opnfv.org/issues/?filter=11625>`_.
 218
 219 =======
 220 Testing
 221 =======
 222
 223 Sandbox is continuously tested by OPNFV CI to ensure the changes do not impact
 224 users. In fact, OPNFV CI itself uses the sandbox scripts to run daily platform
 225 verification jobs.
 226
 227 =======
 228 Support
 229 =======
 230
 231 OPNFV XCI issues are tracked on OPNFV JIRA Releng project. If you encounter
 232 and issue or identify a bug, please submit an issue to JIRA using
 233 `this link <https://jira.opnfv.org/projects/RELENG>_`.
 234
 235 If you have questions or comments, you can ask them on ``#opnfv-pharos`` IRC
 236 channel on Freenode.