1 ###########################
2 OPNFV XCI Developer Sandbox
3 ###########################
5 The XCI Developer Sandbox is created by the OPNFV community for the OPNFV
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
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>`_.
21 ===================================
22 Components of XCI Developer Sandbox
23 ===================================
25 The sandbox uses OpenStack projects for VM node creation, provisioning
26 and OpenStack installation.
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/>`_.
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/>`_.
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>_`.
54 Here are the steps that take place upon the execution of the sandbox script
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
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.
71 In order to use this sandbox, the host must have certain packages installed.
77 - <fix the list with all the dependencies>
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>`_.
84 ===========================
85 Flavors Provided by Sandbox
86 ===========================
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.
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.
96 See the details of the flavors from
97 `this link <https://wiki.opnfv.org/display/INF/XCI+Developer+Sandbox#XCIDeveloperSandbox-AvailableFlavors>`_.
106 clone OPNFV Releng repository
108 git clone https://gerrit.opnfv.org/gerrit/releng.git
110 change into directory where the sandbox script is located
112 cd releng/prototypes/xci
114 execute sandbox script
116 sudo -E ./xci-deploy.sh
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.
124 The flavor to deploy, the versions of upstream components to use can
125 be configured by developers by setting certain environment variables.
126 Below example deploys noha flavor using the latest of openstack-ansible
127 master branch and stores logs in different location than what is configured.
129 clone OPNFV Releng repository
131 git clone https://gerrit.opnfv.org/gerrit/releng.git
133 change into directory where the sandbox script is located
135 cd releng/prototypes/xci
137 set the sandbox flavor
139 export XCI_FLAVOR=noha
141 set the version to use for openstack-ansible
143 export OPENSTACK_OSA_VERSION=master
145 set where the logs should be stored
147 export LOG_PATH=/home/jenkins/xcilogs
149 execute sandbox script
151 sudo -E ./xci-deploy.sh
155 Please encure you always execute the sandbox script using **sudo -E**
156 in order to make the environment variables you set available to the
157 sandbox script or you end up with the default settings.
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``.
167 The variables can also be set directly within the file before executing
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``.
178 How Pinned Versions are Determined
179 ----------------------------------
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.
185 Once a working version is identified, the versions of the upstream components
186 are then bumped in releng repo.
188 ===========================================
189 Limitations, Known Issues, and Improvements
190 ===========================================
192 The list can be seen using `this link <https://jira.opnfv.org/issues/?filter=11616>`_.
198 Changelog can be seen using `this link <https://jira.opnfv.org/issues/?filter=11625>`_.
204 Sandbox is continuously tested by OPNFV CI to ensure the changes do not impact
205 users. In fact, OPNFV CI itself uses the sandbox scripts to run daily platform
212 OPNFV XCI issues are tracked on OPNFV JIRA Releng project. If you encounter
213 and issue or identify a bug, please submit an issue to JIRA using
214 `this link <https://jira.opnfv.org/projects/RELENG>_`.
216 If you have questions or comments, you can ask them on ``#opnfv-pharos`` IRC