diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ci/index.rst | 10 | ||||
| -rw-r--r-- | docs/ci/resources.rst | 84 | ||||
| -rw-r--r-- | docs/ci/tables/ci-baremetal-servers.rst | 148 | ||||
| -rw-r--r-- | docs/ci/tables/ci-build-servers.rst | 31 | ||||
| -rw-r--r-- | docs/ci/tables/ci-labels.rst | 13 | ||||
| -rw-r--r-- | docs/ci/tables/ci-virtual-servers.rst | 164 | ||||
| -rw-r--r-- | docs/ci/tables/none-ci-servers.rst | 53 | ||||
| -rw-r--r-- | docs/ci/user-guide.rst | 100 | ||||
| -rw-r--r-- | docs/conf.py | 10 | ||||
| -rw-r--r-- | docs/infra/index.rst | 2 | ||||
| -rw-r--r-- | docs/infra/jenkins/connect-to-jenkins.rst | 156 | ||||
| -rw-r--r-- | docs/infra/jenkins/jjb-usage.rst | 10 | ||||
| -rw-r--r-- | docs/release/index.rst | 2 | ||||
| -rw-r--r-- | docs/release/release-automation.rst | 163 |
14 files changed, 859 insertions, 87 deletions
diff --git a/docs/ci/index.rst b/docs/ci/index.rst index da6fc7de1..445552a82 100644 --- a/docs/ci/index.rst +++ b/docs/ci/index.rst @@ -8,11 +8,17 @@ OPNFV CI ======== -TBD +OPNFV continuous integration (CI) is ran on a variety of :doc:`hardware <resources>` +connected to Jenkins and mangaged through YAML files in the `Releng`_ +repository. These YAML files are read by `Jenkins Job Builder`_ to +generate and upload Jenkins jobs to the server. See the :doc:`User Guide +<user-guide>` for resources on getting started with CI for your project. .. toctree:: - :numbered: :maxdepth: 2 user-guide resources + +.. _Releng: https://gerrit.opnfv.org/gerrit/admin/repos/releng +.. _Jenkins Job Builder: https://docs.openstack.org/infra/jenkins-job-builder/ diff --git a/docs/ci/resources.rst b/docs/ci/resources.rst index 572852c48..b4efe9704 100644 --- a/docs/ci/resources.rst +++ b/docs/ci/resources.rst @@ -13,49 +13,81 @@ 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 (PODs) +- Virtual PODs (vPODs) +- Build Servers + + +.. _ci-resources-baremetal-pods: --------------- Baremetal PODs -------------- -TBD +Baremetal PODs are used to deploy OPNFV on to baremetal hardware through +one of the installer projects. They enable the full range of scenarios +to be deployed and tested. -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Baremetal PODs Requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**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 +#. Pharos Compliant and has a PDF +#. Connected to Jenkins +#. 24/7 Uptime +#. No Development +#. No manual intervention ------------- -Virtual PODS +.. include:: tables/ci-baremetal-servers.rst + + +.. _ci-resources-virtual-pods: + +Virtual PODs ------------ -TBD +Virtual PODs are used to deploy OPNFV in a virtualized environment +generally on top of KVM through libvirt. -~~~~~~~~~~~~ -Requirements -~~~~~~~~~~~~ +**Requirements** -TBD +#. Have required virtualization packages installed +#. Meet the Pharos resource specification for virtual PODs +#. Connected to Jenkins +#. 24/7 Uptime + +.. include:: tables/ci-virtual-servers.rst + +.. _ci-resources-build-servers: -------------- Build Servers ------------- -TBD +Build servers are used to build project, run basic verifications (such +as unit tests and linting), and generate documentation. + +**Requirements** + +#. Have required `packages_` installed +#. 24/7 Uptime +#. Connected to Jenkins + +.. include:: tables/ci-build-servers.rst + +.. _dev-resources: + +===================== +Development Resources +===================== + +.. include:: tables/none-ci-servers.rst + +.. _ci-lables: + +=================== +CI Resources Labels +=================== -~~~~~~~~~~~~ -Requirements -~~~~~~~~~~~~ +.. include:: tables/ci-labels.rst -TBD +.. _packages: https://wiki.opnfv.org/display/INF/Continuous+Integration#ContinuousIntegration-BuildServers diff --git a/docs/ci/tables/ci-baremetal-servers.rst b/docs/ci/tables/ci-baremetal-servers.rst new file mode 100644 index 000000000..cccf75092 --- /dev/null +++ b/docs/ci/tables/ci-baremetal-servers.rst @@ -0,0 +1,148 @@ +.. 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 + +.. list-table:: CI Servers for Baremetal Deployment + :header-rows: 1 + :stub-columns: 1 + + * - Node + - Usage + - Jumphost OS / Version + - PDF + - IDF + * - `arm-pod9 <https://build.opnfv.org/ci/computer/arm-pod9>`_ + - Armband + - Ubuntu 16.04 + - `PDF <https://git.opnfv.org/pharos/plain/labs/arm/pod9.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/arm/idf-pod9.yaml>`__ + * - `arm-pod10 <https://build.opnfv.org/ci/computer/arm-pod10>`_ + - Fuel + - Ubuntu 16.04 + - `PDF <https://git.opnfv.org/pharos/plain/labs/arm/pod10.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/arm/idf-pod10.yaml>`__ + * - `ericsson-pod1 <https://build.opnfv.org/ci/computer/ericsson-pod1>`_ + - Fuel + - Ubuntu 16.04 + - `PDF <https://git.opnfv.org/pharos/plain/labs/ericsson/pod1.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/ericsson/idf-pod1.yaml>`__ + * - `ericsson-pod2 <https://build.opnfv.org/ci/computer/ericsson-pod2>`_ + - XCI + - Ubuntu 16.04 + - `PDF <https://git.opnfv.org/pharos/plain/labs/ericsson/pod2.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/ericsson/idf-pod2.yaml>`__ + * - `flex-pod1 <https://build.opnfv.org/ci/computer/flex-pod1>`_ + - Yardstick + - + - PDF + - IDF + * - `flex-pod2 <https://build.opnfv.org/ci/computer/flex-pod2>`_ + - Apex + - + - PDF + - IDF + * - `huawei-pod1 <https://build.opnfv.org/ci/computer/huawei-pod1>`_ + - Compass4NFV + - + - `PDF <https://git.opnfv.org/pharos/plain/labs/huawei/pod1.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/huawei/idf-pod1.yaml>`__ + * - `huawei-pod2 <https://build.opnfv.org/ci/computer/huawei-pod2>`_ + - Compass4NFV + - Ubuntu 14.04 + - PDF + - IDF + * - `huawei-pod3 <https://build.opnfv.org/ci/computer/huawei-pod3>`_ + - Yardstick + - Ubuntu 14.04 + - PDF + - IDF + * - `huawei-pod4 <https://build.opnfv.org/ci/computer/huawei-pod4>`_ + - Dovetail + - + - PDF + - IDF + * - `huawei-pod6 <https://build.opnfv.org/ci/computer/huawei-pod6>`_ + - + - Ubuntu 14.04 + - PDF + - IDF + * - `huawei-pod7 <https://build.opnfv.org/ci/computer/huawei-pod7>`_ + - Dovetail + - Ubuntu 14.04 + - PDF + - IDF + * - `huawei-pod8 <https://build.opnfv.org/ci/computer/huawei-pod8>`_ + - Compass4NFV + - Ubuntu 16.04 (aarch64) + - PDF + - IDF + * - `huawei-pod12 <https://build.opnfv.org/ci/computer/huawei-pod12>`_ + - JOID + - Ubuntu 16.04 + - PDF + - IDF + * - `intel-pod10 <https://build.opnfv.org/ci/computer/intel-pod10>`_ + - KVMforNFV + - CentOS 7 + - PDF + - IDF + * - `intel-pod11 <https://build.opnfv.org/ci/computer/intel-pod11>`_ + - Apex + - + - PDF + - IDF + * - `intel-pod12 <https://build.opnfv.org/ci/computer/intel-pod12>`_ + - VSPerf + - CentOS 7 + - PDF + - IDF + * - `intel-pod17 <https://build.opnfv.org/ci/computer/intel-pod17>`_ + - Airship + - + - PDF + - IDF + * - `intel-pod18 <https://build.opnfv.org/ci/computer/intel-pod18>`_ + - Airship + - + - PDF + - IDF + * - `lf-pod1 <https://build.opnfv.org/ci/computer/lf-pod1>`_ + - Apex + - CentOS 7 + - `PDF <https://git.opnfv.org/pharos/plain/labs/lf/pod1.yaml>`__ + - IDF + * - `lf-pod2 <https://build.opnfv.org/ci/computer/lf-pod2>`_ + - Fuel + - CentOS 7 + - `PDF <https://git.opnfv.org/pharos/plain/labs/lf/pod2.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/lf/idf-pod2.yaml>`__ + * - `unh-pod1 <https://build.opnfv.org/ci/computer/unh-pod1>`_ + - Auto + - Ubuntu 16.04 (aarch64) + - PDF + - IDF + * - `zte-pod1 <https://build.opnfv.org/ci/computer/zte-pod1>`_ + - + - + - `PDF <https://git.opnfv.org/pharos/plain/labs/zte/pod1.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/zte/idf-pod1.yaml>`__ + * - `zte-pod2 <https://build.opnfv.org/ci/computer/zte-pod2>`_ + - + - + - `PDF <https://git.opnfv.org/pharos/plain/labs/zte/pod2.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/zte/idf-pod2.yaml>`__ + * - `zte-pod3 <https://build.opnfv.org/ci/computer/zte-pod3>`_ + - + - + - `PDF <https://git.opnfv.org/pharos/plain/labs/zte/pod3.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/zte/idf-pod3.yaml>`__ + * - `zte-pod4 <https://build.opnfv.org/ci/computer/zte-pod4>`_ + - + - + - PDF + - IDF + * - `zte-pod9 <https://build.opnfv.org/ci/computer/zte-pod9>`_ + - + - + - `PDF <https://git.opnfv.org/pharos/plain/labs/zte/pod9.yaml>`__ + - `IDF <https://git.opnfv.org/pharos/plain/labs/zte/idf-pod9.yaml>`__ diff --git a/docs/ci/tables/ci-build-servers.rst b/docs/ci/tables/ci-build-servers.rst new file mode 100644 index 000000000..b2f4893e3 --- /dev/null +++ b/docs/ci/tables/ci-build-servers.rst @@ -0,0 +1,31 @@ +.. 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 + +.. list-table:: CI Build Servers + :header-rows: 1 + :stub-columns: 1 + + * - Node + - Architecture + - OS + - Contact + * - `arm-build3 <https://build.opnfv.org/ci/computer/arm-build3>`_ + - aarch64 + - CentOS 7.4 + - `Armband ENEA Team`_ + * - `arm-build4 <https://build.opnfv.org/ci/computer/arm-build4>`_ + - aarch64 + - Ubuntu 16.04 + - `Armband ENEA Team`_ + * - `lf-build5 <https://build.opnfv.org/ci/computer/lf-build5>`_ + - x86_64 + - Ubuntu 18.04 + - `Linux Foundation`_ + * - `lf-build6 <https://build.opnfv.org/ci/computer/lf-build6>`_ + - x86_64 + - CentOS 8 + - `Linux Foundation`_ + +.. _Linux Foundation: helpdesk@opnfv.org +.. _Armband ENEA Team: armband@enea.com diff --git a/docs/ci/tables/ci-labels.rst b/docs/ci/tables/ci-labels.rst new file mode 100644 index 000000000..2865cc22f --- /dev/null +++ b/docs/ci/tables/ci-labels.rst @@ -0,0 +1,13 @@ +.. 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-resource: Resource devoted to CI +:ci-pod: POD devoted to CI +:opnfv-build: Node is for builds - independent of OS +:opnfv-build-centos: Node is for builds needing CentOS +:opnfv-build-centos-arm: Node is for ARM builds on CentOS +:opnfv-build-ubuntu: Node is for builds needing Ubuntu +:opnfv-build-ubuntu-arm: Node is for ARM builds on Ubuntu +:{installer}-baremetal: POD is devoted to {installer} for baremetal deployments +:{installer}-virtual: Server is devoted to {installer} for virtual deployments diff --git a/docs/ci/tables/ci-virtual-servers.rst b/docs/ci/tables/ci-virtual-servers.rst new file mode 100644 index 000000000..e87c46396 --- /dev/null +++ b/docs/ci/tables/ci-virtual-servers.rst @@ -0,0 +1,164 @@ +.. 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 + +.. list-table:: CI Servers for Virtual Deployment + :header-rows: 1 + :stub-columns: 1 + + * - Node + - Architecture + - OS + - Contact + * - `arm-virtual2 <https://build.opnfv.org/ci/computer/arm-virtual2>`_ + - aarch64 + - Ubuntu 16.04 + - `Armband ENEA Team`_ + * - `arm-virtual3 <https://build.opnfv.org/ci/computer/arm-virtual3>`_ + - aarch64 + - Ubuntu 16.04 + - `Xuan Jia` + * - `arm-virtual4 <https://build.opnfv.org/ci/computer/arm-virtual4>`_ + - aarch64 + - Ubuntu 16.04 + - `Xuan Jia` + * - `ericsson-virtual-pod1bl01 <https://build.opnfv.org/ci/computer/ericsson-virtual-pod1bl01>`_ + - x86_64 + - CentOS 7 + - + * - `ericsson-virtual1 <https://build.opnfv.org/ci/computer/ericsson-virtual1>`_ + - x86_64 + - Ubuntu 16.04 + - + * - `ericsson-virtual2 <https://build.opnfv.org/ci/computer/ericsson-virtual2>`_ + - x86_64 + - Ubuntu 16.04 + - + * - `ericsson-virtual3 <https://build.opnfv.org/ci/computer/ericsson-virtual3>`_ + - x86_64 + - Ubuntu 16.04 + - + * - `ericsson-virtual4 <https://build.opnfv.org/ci/computer/ericsson-virtual4>`_ + - x86_64 + - Ubuntu 16.04 + - + * - `ericsson-virtual5 <https://build.opnfv.org/ci/computer/ericsson-virtual5>`_ + - x86_64 + - Ubuntu 16.04 + - + * - `huawei-virtual1 <https://build.opnfv.org/ci/computer/huawei-virtual1>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `huawei-virtual2 <https://build.opnfv.org/ci/computer/huawei-virtual2>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `huawei-virtual3 <https://build.opnfv.org/ci/computer/huawei-virtual3>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `huawei-virtual4 <https://build.opnfv.org/ci/computer/huawei-virtual4>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `huawei-virtual5 <https://build.opnfv.org/ci/computer/huawei-virtual5>`_ + - x86_64 + - + - + * - `huawei-virtual6 <https://build.opnfv.org/ci/computer/huawei-virtual6>`_ + - x86_64 + - Ubuntu 16.04 + - + * - `huawei-virtual7 <https://build.opnfv.org/ci/computer/huawei-virtual7>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `huawei-virtual8 <https://build.opnfv.org/ci/computer/huawei-virtual8>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `huawei-virtual9 <https://build.opnfv.org/ci/computer/huawei-virtual9>`_ + - x86_64 + - Ubuntu 14.04 + - + * - `intel-virtual3 <https://build.opnfv.org/ci/computer/intel-virtual3>`_ + - x86_64 + - + - + * - `intel-virtual11 <https://build.opnfv.org/ci/computer/intel-virtual11>`_ + - x86_64 + - + - + * - `intel-virtual12 <https://build.opnfv.org/ci/computer/intel-virtual12>`_ + - x86_64 + - + - + * - `intel-virtual13 <https://build.opnfv.org/ci/computer/intel-virtual13>`_ + - x86_64 + - + - + * - `intel-virtual14 <https://build.opnfv.org/ci/computer/intel-virtual14>`_ + - x86_64 + - + - + * - `intel-virtual15 <https://build.opnfv.org/ci/computer/intel-virtual15>`_ + - x86_64 + - + - + * - `intel-virtual16 <https://build.opnfv.org/ci/computer/intel-virtual16>`_ + - x86_64 + - + - + * - `lf-virtual1 <https://build.opnfv.org/ci/computer/lf-virtual1>`_ + - x86_64 + - Ubuntu 14.04 + - `Linux Foundation`_ + * - `lf-virtual2 <https://build.opnfv.org/ci/computer/lf-virtual2>`_ + - x86_64 + - CentOS 7 + - `Linux Foundation`_ + * - `lf-virtual3 <https://build.opnfv.org/ci/computer/lf-virtual3>`_ + - x86_64 + - CentOS 7 + - `Linux Foundation`_ + * - `ool-virtual1 <https://build.opnfv.org/ci/computer/ool-virtual1>`_ + - x86_64 + - + - + * - `ool-virtual2 <https://build.opnfv.org/ci/computer/ool-virtual2>`_ + - x86_64 + - + - + * - `ool-virtual3 <https://build.opnfv.org/ci/computer/ool-virtual3>`_ + - x86_64 + - + - + * - `zte-virtual1 <https://build.opnfv.org/ci/computer/zte-virtual1>`_ + - x86_64 + - + - + * - `zte-virtual2 <https://build.opnfv.org/ci/computer/zte-virtual2>`_ + - x86_64 + - + - + * - `zte-virtual3 <https://build.opnfv.org/ci/computer/zte-virtual3>`_ + - x86_64 + - + - + * - `zte-virtual4 <https://build.opnfv.org/ci/computer/zte-virtual4>`_ + - x86_64 + - + - + * - `zte-virtual5 <https://build.opnfv.org/ci/computer/zte-virtual5>`_ + - x86_64 + - + - + * - `zte-virtual6 <https://build.opnfv.org/ci/computer/zte-virtual6>`_ + - x86_64 + - + - + +.. _Armband ENEA Team: armband@enea.com +.. _Linux Foundation: helpdesk@opnfv.org +.. _Xuan Jia: jason.jiaxuan@gmail.com' diff --git a/docs/ci/tables/none-ci-servers.rst b/docs/ci/tables/none-ci-servers.rst new file mode 100644 index 000000000..48cf97b50 --- /dev/null +++ b/docs/ci/tables/none-ci-servers.rst @@ -0,0 +1,53 @@ +.. 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 + +.. list-table:: Baremetal Development Servers + :header-rows: 1 + :stub-columns: 1 + + * - Node + - Usage + - Jumphost OS / Version + - PDF + - IDF + * - cacti-pod1 + - + - + - + - + * - cengn-pod1 + - + - + - + - + * - itri-pod1 + - + - + - + - + * - lf-pod4 + - + - + - + - + * - lf-pod5 + - + - + - + - + * - nokia-pod1 + - + - + - + - + * - ool-pod1 + - + - + - + - + * - bii-pod1 + - + - + - + - diff --git a/docs/ci/user-guide.rst b/docs/ci/user-guide.rst index 9c9b74a41..a56a3a1b0 100644 --- a/docs/ci/user-guide.rst +++ b/docs/ci/user-guide.rst @@ -8,4 +8,102 @@ CI User Guide ============= -TBD +Structure of the Releng Repository +---------------------------------- + +jjb/<projects> + Individual project CI configurations. + +jjb/global + Collection of JJB defaults and templates shared by all projects. + +global-jjb/ + Git submodule pointing to `Global-JJB`_, which provides a variety of + common `CI jobs`_ such as ReadTheDocs + (RTD) builds. + +docs/ + This documentation. + +releases/ + Release configuration files for creating stable branches and tagging + repositories and related automation scripts. + +utils/ + Collection of common utilities used by projects + +utils/build-server-ansible + Ansible configuration for managing build servers. This is where + projects can add packages they need for their CI to the servers. + + +CI Setup +-------- + +Basic Setup +~~~~~~~~~~~ + +All projects are required to have a **+1 Verified** vote in Gerrit in +order to merge their code. As a new project that comes in may not yet +know how they want to setup CI, they can pass this validation by +configuring a 'no-op' job to run against their changesets. + +1. Clone the `Releng`_ repository, using the *Clone with commit-msg + hook* command under the *SSH* tab (displayed after logging in and + uploading an SSH key): + + .. note:: + <gerrit username> in the command below will be your username in + Gerrit when viewing the command on the website. + + For example:: + + git clone "ssh://<gerrit username>@gerrit.opnfv.org:29418/releng" && \ + scp -p -P 29418 <gerrit username>@gerrit.opnfv.org:hooks/commit-msg "releng/.git/hooks/" + + +2. Create a project directory under the *jjb/* directory, and an intial + project YAML file:: + + mkdir jjb/myproject + touch jjb/myproject/myproject-ci-jobs.yaml + +3. Modify the project YAML file to add the basic validation job:: + + $EDITOR jjb/myproject/myproject-ci-jobs.yaml + + :: + + --- + - project: + name: myproject + project: + - '{name}' + jobs: + - '{project}-verify-basic' + +Docker Builds +~~~~~~~~~~~~~ + +Docker build are managed through the **jjb/releng/opnfv-docker.yaml** +file. Modify this file with your project details to enable docker builds +on merges and tags to your project repository:: + + --- + - project: + name: opnfv-docker' + + [...] + + dockerrepo: + [...] + - 'myproject': + project: 'myproject' + <<: *master + +.. _Jenkins Job Builder: https://docs.openstack.org/infra/jenkins-job-builder/ +.. _Releng: https://gerrit.opnfv.org/gerrit/admin/repos/releng +.. _Global-JJB: https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/index.html +.. _CI jobs: https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/index.html#global-jjb-templates +.. _opnfvdocs: https://docs.opnfv.org/en/latest/how-to-use-docs/index.html +.. _support.linuxfoundation.org: https://jira.linuxfoundation.org/plugins/servlet/theme/portal/2/create/145 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..6cfaf6985 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,10 @@ +project = 'Releng' +extensions = [ + 'sphinx.ext.autosectionlabel' +] +html_theme = "piccolo_theme" +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 4 +numfig = True +numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', + 'code-block': 'Listing %s', 'section': 'Section %s'} diff --git a/docs/infra/index.rst b/docs/infra/index.rst index 50c971e75..248e8230c 100644 --- a/docs/infra/index.rst +++ b/docs/infra/index.rst @@ -70,7 +70,7 @@ Issue and Bug Tracking JIRA .. toctree:: - :maxdepth: + :maxdepth: 1 jira/user-guide diff --git a/docs/infra/jenkins/connect-to-jenkins.rst b/docs/infra/jenkins/connect-to-jenkins.rst index e83cadada..8c5218659 100644 --- a/docs/infra/jenkins/connect-to-jenkins.rst +++ b/docs/infra/jenkins/connect-to-jenkins.rst @@ -111,60 +111,108 @@ Servers connecting to OPNFV Jenkins using this method must have access to intern 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. +#. Create a user named **jenkins** on the machine you want to connect to + OPNFV Jenkins and give the user sudo rights. + +#. Install needed software on the machine you want to connect to OPNFV + Jenkins as slave. + + - openjdk 8 + - monit + +#. 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 + +#. Create slave root in Jenkins user home directory. + + ``mkdir -p /home/jenkins/opnfv/slave_root`` + +5. Clone OPNFV Releng Git repository. + + .. code:: + + mkdir -p /home/jenkins/opnfv/repos + cd /home/jenkins/opnfv/repos + git clone https://gerrit.opnfv.org/gerrit/p/releng.git + +#. Contact LF by creating a ticket to `Connect my 3rd party CI/Lab + <https://jira.linuxfoundation.org/servicedesk/customer/portal/2/create/135>`_ + Include the following information in your ticket. + + - 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) + +#. 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. + + .. code:: + + 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. + +#. 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. + +#. Kill the Java slave.jar process. + +#. 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>`` + +#. Edit monit configuration and enable http interface. The file to edit + is /etc/monit/monitrc on Ubuntu systems. Uncomment below lines. + + .. code:: + + set httpd port 2812 and + use address localhost # only accept connection from localhost + allow localhost # allow localhost to connect to the server and + +#. Restart monit service. + + - Without systemd: + + ``sudo service monit restart`` + + - With systemd: you have to enable monit service first and then restart it. + + .. code:: + + sudo systemctl enable monit + sudo systemctl restart monit + +#. Check to see if jenkins comes up as managed service in monit. + + ``sudo monit status`` + +#. Connect slave to OPNFV Jenkins using monit. + + ``sudo monit start jenkins`` + +#. 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 -------------------- @@ -172,12 +220,12 @@ 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`` +``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`` +``gpg --export -a '<your email address>' > pgp.pubkey`` References ========== diff --git a/docs/infra/jenkins/jjb-usage.rst b/docs/infra/jenkins/jjb-usage.rst index 2be2598d9..d467dbe8a 100644 --- a/docs/infra/jenkins/jjb-usage.rst +++ b/docs/infra/jenkins/jjb-usage.rst @@ -10,7 +10,7 @@ Creating/Configuring/Verifying Jenkins Jobs Clone and setup the repo:: - git clone ssh://YOU@gerrit.opnfv.org:29418/releng + git clone --recursive ssh://YOU@gerrit.opnfv.org:29418/releng cd releng git review -s @@ -29,7 +29,13 @@ Make changes:: Test with tox:: - tox -v -ejjb + tox -e jjb + +.. note:: You can also test the jobs under a single jjb directory by + specifying the directory. For example to test only the releng jobs, you + could run: + + tox -e jjb -- jjb/global:jjb/global-jjb:jjb/releng Submit the change to gerrit:: diff --git a/docs/release/index.rst b/docs/release/index.rst index d7d8acd39..e814bec02 100644 --- a/docs/release/index.rst +++ b/docs/release/index.rst @@ -9,9 +9,9 @@ Releasing OPNFV =============== .. toctree:: - :numbered: :maxdepth: 2 release-process + release-automation stable-branch-guide versioning diff --git a/docs/release/release-automation.rst b/docs/release/release-automation.rst new file mode 100644 index 000000000..213e5ad3b --- /dev/null +++ b/docs/release/release-automation.rst @@ -0,0 +1,163 @@ +.. 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-automation: + +================== +Release Automation +================== + +This page describes how projects can take advantage of the release +automation introduced in Fraser for creating their stable branch, and +stable branch Jenkins jobs. + +It also describes the structures of the ``releases`` directory and the +associated scripts. + +Stable Branch Creation +---------------------- + +If your project participated in the last release (beginning with +Euphrates), perform the following steps: + +#. Copy your project's release file to the new release directory. For + example:: + + cp releases/euphrates/apex.yaml releases/fraser/apex.yaml + +#. For projects who are participating the in the stable release process for + the first time, you can either copy a different project's file and + changing the values to match your project, or use the following + template, replacing values marked with ``<`` and ``>``: + + .. code-block:: yaml + + --- + project: <opnfv-project-name> + project-type: <opnfv-project-type> + release-model: stable + + branches: + - name: stable/<release> + location: + <project-repo>: <git-sha1> + +#. Modify the file, replacing the previous stable branch name with the + new release name, and the commit the branch will start at. For + example: + + .. code-block:: yaml + + branches: + - name: stable/fraser + location: + apex: <git-full-sha1> + +#. If your project contains multiple repositories, add them to the list + of branches. They can also be added later if more time is needed + before the stable branch window closes. + + .. code-block:: yaml + + branches: + - name: stable/fraser + location: + apex: <git-sha1> + - name: stable/fraser + location: + apex-puppet-tripleo: <git-sha1> + +#. Git add, commit, and git-review the changes. A job will be triggered + to verify the commit exists on the branch, and the yaml file follows + the scheme listed in ``releases/schema.yaml`` + +#. Once the commit has been reviewed and merged by Releng, a job will + be triggered to create the stable branch Jenkins jobs under + ``jjb/``. + + +Stable Release Tagging +---------------------- + +TBD + +Release File Fields +------------------- + +The following is a description of fields in the Release file, which are +verified by the scheme file at ``releases/schema.yaml`` + +project + Project team in charge of the release. + +release-model + Release model the project follows. + + One of: stable, non-release + +project-type + Classification of project within OPNFV. + + One of: installer, feature, testing, tools, infra + +upstream + (Optional) Upstream OpenStack project assocated with this project. + +releases + List of released versions for the project. + + version + Version of the release, must be in the format ``opnfv-X.Y.Z``. + + location + Combination of repository and git hash to locate the release + version. + + Example:: + + opnfv-project: f15d50c2009f1f865ac6f4171347940313727547 + +branches + List of stable branches for projects following the ``stable`` release-model. + + name + Stable branch name. Must start with the string ``stable/`` + + location + Same syntax as ``location`` under ``releases`` + +release-notes + Link to release notes for the projects per-release. + + +Scripts +------- + +* ``create_branch.py -f <RELEASE_FILE>`` + + Create branches in Gerrit listed in the release file. + + Must be ran from the root directory of the releng repository as the + release name is extracted from the subdirectory under ``releases/`` + + The Gerrit server can be changed by creating a ``~/releases.cfg`` + file with the following content:: + + [gerrit] + url=http://gerrit.example.com + + This will override the default configuration of using the OPNFV + Gerrit server at https://gerrit.opnfv.org, and is primarily used for + testing. + +* ``create_jobs.py -f <RELEASE_FILE>`` + + Modifies the jenkins job files for a project to add the stable branch + stream. Assumes the jenkins jobs are found in the releng repository + under ``jjb/<project>/`` + +* ``verify_schema -s <SCHEMA_FILE> -y <YAML_FILE>`` + + Verifies the yaml file matches the specified jsonschema formatted + file. Used to verify the release files under ``releases/`` |