Merge "Updated Docs Structure"

18 files changed, 517 insertions, 17 deletions

diff --git a/docs/ci/index.rst b/docs/ci/index.rst
new file mode 100644
index 000000000..da6fc7de1
--- /dev/null
+++ b/docs/ci/index.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _ci-overview:
+
+========
+OPNFV CI
+========
+
+TBD
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   user-guide
+   resources
diff --git a/docs/ci/resources.rst b/docs/ci/resources.rst
new file mode 100644
index 000000000..572852c48
--- /dev/null
+++ b/docs/ci/resources.rst
@@ -0,0 +1,61 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _ci-resources:
+
+============
+CI Resources
+============
+
+CI for OPNFV requires a range of resources in order to meet testing and
+verification needs. Each resource must meet a set of criteria in order
+to be part of CI for an OPNFV release. There are three types of
+resources:
+
+  - Baremetal PODs (PODs)
+  - Virtual PODs (vPODs)
+  - Build Servers
+
+--------------
+Baremetal PODs
+--------------
+
+TBD
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Baremetal PODs Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order of a POD to be considered CI-Ready the following requirements
+must be met:
+
+  #. Pharos Compliant and has a PDF
+  #. Connected to Jenkins
+  #. 24/7 Uptime
+  #. No Development
+  #. No manual intervention
+
+------------
+Virtual PODS
+------------
+
+TBD
+
+~~~~~~~~~~~~
+Requirements
+~~~~~~~~~~~~
+
+TBD
+
+-------------
+Build Servers
+-------------
+
+TBD
+
+~~~~~~~~~~~~
+Requirements
+~~~~~~~~~~~~
+
+TBD
diff --git a/docs/ci/user-guide.rst b/docs/ci/user-guide.rst
new file mode 100644
index 000000000..9c9b74a41
--- /dev/null
+++ b/docs/ci/user-guide.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _ci-user-guide:
+
+=============
+CI User Guide
+=============
+
+TBD
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 000000000..62a828adf
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,17 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _releng:
+
+===================
+Release Engineering
+===================
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   release/index
+   ci/index
+   infra/index
diff --git a/docs/infra/artifacts/docker-hub.rst b/docs/infra/artifacts/docker-hub.rst
new file mode 100644
index 000000000..1da6c474a
--- /dev/null
+++ b/docs/infra/artifacts/docker-hub.rst
@@ -0,0 +1,12 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _docker-hub:
+
+==========
+Docker Hub
+==========
+
+TBD
+
diff --git a/docs/infra/artifacts/index.rst b/docs/infra/artifacts/index.rst
new file mode 100644
index 000000000..28b3b45fb
--- /dev/null
+++ b/docs/infra/artifacts/index.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _artifact-repository:
+
+===================
+Artifact Repository
+===================
+
+TBD
diff --git a/docs/infra/gerrit/user-guide.rst b/docs/infra/gerrit/user-guide.rst
new file mode 100644
index 000000000..3b1c3f807
--- /dev/null
+++ b/docs/infra/gerrit/user-guide.rst
@@ -0,0 +1,9 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _gerrit:
+
+=================
+Gerrit User Guide
+=================
diff --git a/docs/infra/index.rst b/docs/infra/index.rst
new file mode 100644
index 000000000..50c971e75
--- /dev/null
+++ b/docs/infra/index.rst
@@ -0,0 +1,93 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _software-infrastructure:
+
+=======================
+Software Infrastructure
+=======================
+
+OPNFV Software Infrastructure consists of set of components and tools that
+realize OPNFV Continuous Integration (CI) and provide means for community to
+contribute to OPNFV in most efficient way. OPNFV Software Infrastructure
+enables and orchestrates  development, integration and testing activities for
+the components OPNFV consumes from upstream communities and for the development
+work done in scope of OPNFV. Apart from orchestration aspects, providing timely
+feedback that is fit for purpose to the OPNFV community is one of its missions.
+
+CI is the top priority for OPNFV Software Infrastructure. Due to the importance
+the OPNFV community puts into it, the resulting CI machinery is highly
+powerful, capable and runs against distributed hardware infrastructure managed
+by OPNFV Pharos_ Project. The hardware infrastructure OPNFV CI relies on is
+located in 3 different continents, 5+ different countries and 10+ different
+member companies.
+
+OPNFV CI is continuously evolved in order to fulfill the needs and match the
+expectations of the OPNFV community.
+
+OPNFV Software Infrastructure is developed, maintained and operated by OPNFV
+Releng_ Project with the support from Linux Foundation.
+
+Continuous Integration Server
+-----------------------------
+
+Jenkins
+
+.. toctree::
+   :maxdepth: 1
+
+   jenkins/connect-to-jenkins
+   jenkins/user-guide
+   jenkins/jjb-usage
+   jenkins/labels
+
+Source Control and Code Review
+------------------------------
+
+Gerrit
+
+.. toctree::
+   :maxdepth: 1
+
+   gerrit/user-guide
+
+Artifact and Image Repositories
+-------------------------------
+
+Google Storage & Docker Hub
+
+.. toctree::
+   :maxdepth: 1
+
+   artifacts/index
+   artifacts/docker-hub
+
+
+Issue and Bug Tracking
+----------------------
+
+JIRA
+
+.. toctree::
+   :maxdepth:
+
+   jira/user-guide
+
+
+Dashboards and Analytics
+------------------------
+
+  - `Pharos Dashboard`_
+
+  - `Test Results`_
+
+  - `Bitergia Dashboard`_
+
+
+.. _Pharos: https://wiki.opnfv.org/display/pharos/Pharos+Home
+.. _Releng: https://wiki.opnfv.org/display/releng/Releng
+
+.. _Bitergia Dashboard: https://opnfv.biterg.io/
+.. _Pharos Dashboard: https://labs.opnfv.org/
+.. _Test Results: https://testresults.opnfv.org/
diff --git a/docs/infra/jenkins/connect-to-jenkins.rst b/docs/infra/jenkins/connect-to-jenkins.rst
new file mode 100644
index 000000000..e83cadada
--- /dev/null
+++ b/docs/infra/jenkins/connect-to-jenkins.rst
@@ -0,0 +1,187 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _connect-to-jenkins:
+
+================================================
+Connecting OPNFV Community Labs to OPNFV Jenkins
+================================================
+
+.. contents:: Table of Contents
+   :backlinks: none
+
+Abstract
+========
+
+This document describes how to connect resources (servers) located in Linux Foundation (LF) lab
+and labs provided by the OPNFV Community to OPNFV Jenkins.
+
+License
+=======
+Connecting OPNFV Community Labs to OPNFV Jenkins (c) by Fatih Degirmenci (Ericsson AB) and others.
+
+Connecting OPNFV Labs to OPNFV Jenkins document is licensed under a Creative Commons
+Attribution 4.0 International License.
+
+You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>.
+
+
+Version History
+===============
+
++------------+-------------+------------------+---------------------------------------+
+| **Date**   | **Version** | **Author**       | **Comment**                           |
+|            |             |                  |                                       |
++------------+-------------+------------------+---------------------------------------+
+| 2015-05-05 | 0.1.0       | Fatih Degirmenci | First draft                           |
+|            |             |                  |                                       |
++------------+-------------+------------------+---------------------------------------+
+| 2015-09-25 | 1.0.0       | Fatih Degirmenci | Instructions for the                  |
+|            |             |                  | Arno SR1 release                      |
++------------+-------------+------------------+---------------------------------------+
+| 2016-01-25 | 1.1.0       | Jun Li           | Change the format for                 |
+|            |             |                  | new doc toolchain                     |
++------------+-------------+------------------+---------------------------------------+
+| 2016-01-27 | 1.2.0       | Fatih Degirmenci | Instructions for the                  |
+|            |             |                  | Brahmaputra release                   |
++------------+-------------+------------------+---------------------------------------+
+| 2016-05-25 | 1.3.0       | Julien           | Add an additional step after step9 to |
+|            |             |                  | output the correct monit config file  |
++------------+-------------+------------------+---------------------------------------+
+
+Jenkins
+=======
+
+Jenkins is an extensible open source Continuous Integration (CI) server. [1]
+
+Linux Foundation (LF) hosts and operates `OPNFV Jenkins <https://build.opnfv.org/ci/>`_.
+
+Jenkins Slaves
+==============
+
+**Slaves** are computers that are set up to build projects for a **Jenkins Master**.  [2]
+
+Jenkins runs a separate program called "**slave agent**" on slaves.
+When slaves are registered to a master, the master starts distributing load to slaves by
+scheduling jobs to run on slaves if the jobs are set to run on them.  [2]
+
+Term **Node** is used to refer to all machines that are part of Jenkins grid, slaves and
+master. [2]
+
+Two types of slaves are currently connected to OPNFV Jenkins and handling
+different tasks depending on the purpose of connecting the slave.
+
+* Slaves hosted in `LF Lab <https://wiki.opnfv.org/get_started/lflab_hosting#hardware_setup>`_
+* Slaves hosted in `Community Test Labs <https://wiki.opnfv.org/pharos#community_test_labs>`_
+
+The slaves connected to OPNFV Jenkins can be seen using this link:
+https://build.opnfv.org/ci/computer/
+
+Slaves without red cross next to computer icon are fully functional.
+
+Connecting Slaves to OPNFV Jenkins
+==================================
+
+The method that is normally used for connecting slaves to Jenkins requires direct SSH access to
+servers.
+[3] This is the method that is used for connecting slaves hosted in LF Lab.
+
+Connecting slaves using direct SSH access can become a challenge given that OPNFV Project
+has number of different labs provided by community as mentioned in previous section.
+All these labs have different security requirements which can increase the effort
+and the time needed for connecting slaves to Jenkins.
+In order to reduce the effort and the time needed for connecting slaves and streamline the
+process, it has been decided to connect slaves using
+`Java Network Launch Protocol (JNLP) <https://docs.oracle.com/javase/tutorial/deployment/deploymentInDepth/jnlp.html>`_.
+
+Connecting Slaves from LF Lab to OPNFV Jenkins
+----------------------------------------------
+
+Slaves hosted in LF Lab are handled by LF. All the requests and questions regarding
+these slaves should be submitted to `OPNFV LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_.
+
+Connecting Slaves from Community Labs to OPNFV Jenkins
+------------------------------------------------------
+
+As noted in corresponding section, slaves from Community Labs are connected using JNLP. Via JNLP,
+slaves open connection towards Jenkins Master instead of Jenkins Master accessing to them directly.
+
+Servers connecting to OPNFV Jenkins using this method must have access to internet.
+
+Please follow below steps to connect a slave to OPNFV Jenkins.
+
+  1. Create a user named **jenkins** on the machine you want to connect to OPNFV Jenkins and give the user sudo rights.
+  2. Install needed software on the machine you want to connect to OPNFV Jenkins as slave.
+    - openjdk 8
+    - monit
+  3. If the slave will be used for running virtual deployments, Functest, and Yardstick, install below software and make jenkins user the member of the groups.
+    - docker
+    - libvirt
+  4. Create slave root in Jenkins user home directory.
+    ``mkdir -p /home/jenkins/opnfv/slave_root``
+  5. Clone OPNFV Releng Git repository.
+    ``mkdir -p /home/jenkins/opnfv/repos``
+
+    ``cd /home/jenkins/opnfv/repos``
+
+    ``git clone https://gerrit.opnfv.org/gerrit/p/releng.git``
+  6. Contact LF by sending mail to `OPNFV LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_ and request creation of a slave on OPNFV Jenkins. Include below information in your mail.
+    - Slave root (/home/jenkins/opnfv/slave_root)
+    - Public IP of the slave (You can get the IP by executing ``curl http://icanhazip.com/``)
+    - PGP Key (attached to the mail or exported to a key server)
+  7. Once you get confirmation from LF stating that your slave is created on OPNFV Jenkins, check if the firewall on LF is open for the server you are trying to connect to Jenkins.
+    ``cp /home/jenkins/opnfv/repos/releng/utils/jenkins-jnlp-connect.sh /home/jenkins/``
+    ``cd /home/jenkins/``
+    ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n  <slave name on OPNFV Jenkins> -s <the token you received from LF> -f``
+
+     - If you receive an error, follow the steps listed on the command output.
+  8. Run the same script with test(-t) on foreground in order to make sure no problem on connection. You should see **INFO: Connected** in the console log.
+    ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF> -t``
+
+     - If you receive an error similar to the one shown `on this link <http://hastebin.com/ozadagirax.avrasm>`_, you need to check your firewall and allow outgoing connections for the port.
+  9. Kill the Java slave.jar process.
+  10. Run the same script normally without test(-t) in order to get monit script created.
+    ``sudo ./jenkins-jnlp-connect.sh -j /home/jenkins -u jenkins -n <slave name on OPNFV Jenkins> -s <the token you received from LF>``
+  11. Edit monit configuration and enable http interface. The file to edit is /etc/monit/monitrc on Ubuntu systems. Uncomment below lines.
+    set httpd port 2812 and
+        use address localhost  # only accept connection from localhost
+        allow localhost        # allow localhost to connect to the server and
+  12. Restart monit service.
+    - Without systemd:
+
+      ``sudo service monit restart``
+    - With systemd: you have to enable monit service first and then restart it.
+
+      ``sudo systemctl enable monit``
+
+      ``sudo systemctl restart monit``
+  13. Check to see if jenkins comes up as managed service in monit.
+    ``sudo monit status``
+  14. Connect slave to OPNFV Jenkins using monit.
+    ``sudo monit start jenkins``
+  15. Check slave on OPNFV Jenkins to verify the slave is reported as connected.
+    - The slave on OPNFV Jenkins should have some executors in “Idle” state if the connection is successful.
+
+Notes
+==========
+
+PGP Key Instructions
+--------------------
+
+Public PGP Key can be uploaded to public key server so it can be taken from
+there using your mail address. Example command to upload the key to key server is
+
+    ``gpg --keyserver hkp://keys.gnupg.net:80  --send-keys XXXXXXX``
+
+The Public PGP Key can also be attached to the email by storing the key in a file and then
+attaching it to the email.
+
+    ``gpg --export -a '<your email address>' > pgp.pubkey``
+
+References
+==========
+
+* `What is Jenkins <https://wiki.jenkins-ci.org/display/JENKINS/Meet+Jenkins>`_
+* `Jenkins Terminology <https://wiki.jenkins-ci.org/display/JENKINS/Terminology>`_
+* `Jenkins SSH Slaves Plugin <https://wiki.jenkins-ci.org/display/JENKINS/SSH+Slaves+plugin>`_
diff --git a/docs/jenkins-job-builder/opnfv-jjb-usage.rst b/docs/infra/jenkins/jjb-usage.rst
index 062cf8223..2be2598d9 100644
--- a/docs/jenkins-job-builder/opnfv-jjb-usage.rst
+++ b/docs/infra/jenkins/jjb-usage.rst
@@ -1,3 +1,9 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _jjb:
+
 ===========================================
 Creating/Configuring/Verifying Jenkins Jobs
 ===========================================
@@ -16,9 +22,9 @@ Make changes::
     remote: Processing changes: new: 1, refs: 1, done
     remote:
     remote: New Changes:
-    remote:   https://gerrit.opnfv.org/gerrit/51
+    remote:   https://gerrit.opnfv.org/gerrit/<CHANGE_ID>
     remote:
-    To ssh://agardner@gerrit.opnfv.org:29418/releng.git
+    To ssh://YOU@gerrit.opnfv.org:29418/releng.git
      * [new branch]      HEAD -> refs/publish/master
 
 Test with tox::
@@ -29,12 +35,12 @@ Submit the change to gerrit::
 
     git review -v
 
-Follow the link given in the stdoutput to gerrit eg: https://gerrit.opnfv.org/gerrit/"Your_Change_ID"
-the verify job will have completed and you will see Verified +1 jenkins-ci in
-the gerrit ui.
+Follow the link given in the stdoutput to gerrit eg:
+``https://gerrit.opnfv.org/gerrit/<CHANGE_ID>`` the verify job will
+have completed and you will see Verified +1 jenkins-ci in the gerrit ui.
 
 If the changes pass the verify job
-https://build.opnfv.org/ci/view/builder/job/builder-verify-jjb/ ,
+https://build.opnfv.org/ci/job/releng-verify-jjb/ ,
 the patch can be submitited by a committer.
 
 Job Types
@@ -65,8 +71,9 @@ it will reset the verified status to 0. If you want to keep the verified
 status, use **recheck-experimental** in commit message to trigger both
 verify and experimental jobs.
 
-You can look in the releng/INFO file for a list of current committers to add as reviewers to your patch in order to get it
-reviewed and submitted.
+You can look in the releng/INFO file for a list of current committers to
+add as reviewers to your patch in order to get it reviewed and
+submitted.
 
 Or Add the group releng-contributors
 
diff --git a/docs/infra/jenkins/labels.rst b/docs/infra/jenkins/labels.rst
new file mode 100644
index 000000000..6327518af
--- /dev/null
+++ b/docs/infra/jenkins/labels.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _jenkins-labels:
+
+===================
+Jenkins Node Labels
+===================
+
+TBD
diff --git a/docs/infra/jenkins/user-guide.rst b/docs/infra/jenkins/user-guide.rst
new file mode 100644
index 000000000..60236416a
--- /dev/null
+++ b/docs/infra/jenkins/user-guide.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _jenkins-user-guide:
+
+==================
+Jenkins User Guide
+==================
+
+TBD
diff --git a/docs/infra/jira/user-guide.rst b/docs/infra/jira/user-guide.rst
new file mode 100644
index 000000000..5009bc1b0
--- /dev/null
+++ b/docs/infra/jira/user-guide.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _jira-user-guide:
+
+===============
+JIRA User Guide
+===============
+
+TBD
diff --git a/docs/jenkins-job-builder/index.rst b/docs/jenkins-job-builder/index.rst
deleted file mode 100644
index 4d23ade38..000000000
--- a/docs/jenkins-job-builder/index.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-===========================
-Release Engineering Project
-===========================
-
-.. toctree::
-   :numbered:
-   :maxdepth: 2
-
-   opnfv-jjb-usage
diff --git a/docs/release/index.rst b/docs/release/index.rst
new file mode 100644
index 000000000..d7d8acd39
--- /dev/null
+++ b/docs/release/index.rst
@@ -0,0 +1,17 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _release:
+
+===============
+Releasing OPNFV
+===============
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   release-process
+   stable-branch-guide
+   versioning
diff --git a/docs/release/release-process.rst b/docs/release/release-process.rst
new file mode 100644
index 000000000..b88832f95
--- /dev/null
+++ b/docs/release/release-process.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _release-process:
+
+===============
+Release Process
+===============
+
+TBD
diff --git a/docs/release/stable-branch-guide.rst b/docs/release/stable-branch-guide.rst
new file mode 100644
index 000000000..a4710f656
--- /dev/null
+++ b/docs/release/stable-branch-guide.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _stable-branch:
+
+=============
+Stable Branch
+=============
+
+TBD
diff --git a/docs/release/versioning.rst b/docs/release/versioning.rst
new file mode 100644
index 000000000..3257d3bea
--- /dev/null
+++ b/docs/release/versioning.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _versioning:
+
+==========
+Versioning
+==========
+
+TBD