From ef7b4aca7e3b9fe06bdaa4a9e979bdb02d85a674 Mon Sep 17 00:00:00 2001 From: Victor Morales Date: Thu, 5 Apr 2018 10:12:21 -0700 Subject: Rename doc folder The Jenkins job that triggers the creation of documents looks for docs folder[1], in order to be covered by this job it's necessary to adapt to this convention. [1] https://git.onap.org/ci-management/tree/jjb/doc/doc-templates-rtd.yaml Change-Id: Ieca92084d95b0ef4736223b1ea60cb0f9c688550 Signed-off-by: Victor Morales Issue-ID: DOC-261 --- .gitignore | 3 +- doc/source/conf.py | 40 ------- doc/source/features/configure_execution.rst | 72 ------------- doc/source/features/consuming_scripts.rst | 88 ---------------- doc/source/features/example_usage.rst | 151 --------------------------- doc/source/features/features.rst | 16 --- doc/source/features/openstack.rst | 89 ---------------- doc/source/index.rst | 23 ---- doc/source/install/index.rst | 102 ------------------ doc/source/install/known_issues.rst | 63 ----------- docs/source/conf.py | 40 +++++++ docs/source/features/configure_execution.rst | 72 +++++++++++++ docs/source/features/consuming_scripts.rst | 88 ++++++++++++++++ docs/source/features/example_usage.rst | 151 +++++++++++++++++++++++++++ docs/source/features/features.rst | 16 +++ docs/source/features/openstack.rst | 89 ++++++++++++++++ docs/source/index.rst | 23 ++++ docs/source/install/index.rst | 102 ++++++++++++++++++ docs/source/install/known_issues.rst | 63 +++++++++++ tox.ini | 2 +- 20 files changed, 647 insertions(+), 646 deletions(-) delete mode 100644 doc/source/conf.py delete mode 100644 doc/source/features/configure_execution.rst delete mode 100644 doc/source/features/consuming_scripts.rst delete mode 100644 doc/source/features/example_usage.rst delete mode 100644 doc/source/features/features.rst delete mode 100644 doc/source/features/openstack.rst delete mode 100644 doc/source/index.rst delete mode 100644 doc/source/install/index.rst delete mode 100644 doc/source/install/known_issues.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/features/configure_execution.rst create mode 100644 docs/source/features/consuming_scripts.rst create mode 100644 docs/source/features/example_usage.rst create mode 100644 docs/source/features/features.rst create mode 100644 docs/source/features/openstack.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/install/index.rst create mode 100644 docs/source/install/known_issues.rst diff --git a/.gitignore b/.gitignore index 484ae7d..9a54bc7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ .tox/ -doc/build/ +docs/build/ .vagrant/ *.swp +.DS_Store etc/settings.yaml opt/* tests/installed-software* diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100644 index 906f249..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,40 +0,0 @@ -# -*- coding: utf-8 -*- -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -# implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import os -import sys - -BASE_DIR = os.path.dirname(os.path.abspath(__file__)) -ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) - -sys.path.insert(0, ROOT) -sys.path.insert(0, BASE_DIR) - -# -- General configuration ---------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - 'sphinx.ext.autodoc', - #'sphinx.ext.intersphinx' -] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'ONAP on Vagrant' diff --git a/doc/source/features/configure_execution.rst b/doc/source/features/configure_execution.rst deleted file mode 100644 index df08605..0000000 --- a/doc/source/features/configure_execution.rst +++ /dev/null @@ -1,72 +0,0 @@ -======================= -Modify execution values -======================= - -In order to provide a flexible platform that adjusts to different developer -needs, there are two mechanisms to configure the execution of this project. - -Settings configuration file ---------------------------- - -The first mechanism refers to the process to replace default configuration -values in the settings configuration file. This file needs to be placed into -the *./etc* folder and named *settings.yaml*. It must contain the key/pair -configuration values that will be overriden. - -.. note:: - - There are sample files (e. g. settings.yaml.development and - settings.yaml.testing) placed into the *./etc* folder. Their purpose is to - provide a reference of different configurations. - -.. end - -Configuration values: - -+------------------+-------------------+---------------------------------------+ -| Key | Values | Description | -+==================+===================+=======================================+ -| build_image | "True" or "False" | Determines if the Docker image is | -| | | retrieved from public hub or built | -| | | from source code. | -+------------------+-------------------+---------------------------------------+ -| clone_repo | "True" or "False" | Determines if all the source code | -| | | repositories of a given component are | -| | | cloned locally. | -+------------------+-------------------+---------------------------------------+ -| compile_repo | "True" or "False" | Determines if all the source code | -| | | repositories of a given component are | -| | | going to be compiled. | -+------------------+-------------------+---------------------------------------+ -| enable_oparent | "True" or "False" | Determines if the OParent project | -| | | will be used during the maven | -| | | compilation. | -+------------------+-------------------+---------------------------------------+ -| skip_get_images | "True" or "False" | Determines if the process to build or | -| | | retrieve docker images of a given | -| | | component are going to skipped. | -+------------------+-------------------+---------------------------------------+ -| skip_install | "True" or "False" | Determines if the process to start | -| | | the services of a given component | -| | | will be started. | -+------------------+-------------------+---------------------------------------+ - -Parameters ----------- - -The **skip_get_images** and **skip_install** are the only two configuration -values that can be overriden using *-g* and *-i* respectively by the run scripts -(*./tools/run.sh* and *.\\tools\\Run.ps1*). - -.. note:: - - The script parameters take precendence of the configuration file. - -.. end - -.. code-block:: console - - $ ./tools/run.sh sdc -g - -.. end - diff --git a/doc/source/features/consuming_scripts.rst b/doc/source/features/consuming_scripts.rst deleted file mode 100644 index 4290c25..0000000 --- a/doc/source/features/consuming_scripts.rst +++ /dev/null @@ -1,88 +0,0 @@ -============================== -Using the provisioning scripts -============================== - -Vagrant is a platform that uses prebaked images called -*vagrant boxes* to guarranty that running multiple times a -provisioning script will result in an expected output. This -mechanism is crucial for reducing the number of external factors -during the creation, development and testing of provisioning scripts. -However, it's possible to provide an ONAP development enviroment -without having to install Vagrant tool. This document explains how to -consume the provisioning scripts localed in **./lib** folder to -provision a development environment and the environment variables -that modifies their behavior. - -This project was built on an Ubuntu 14.04 ("Trusty") Operating System, -therefore it's necessary to have an user who has *sudo* permissions to -access to a Bare Metal or Virtual Machine. - -The following instructions retrieve the provisioning scripts and place -them into the */var/onap/* folder. - -.. code-block:: console - - $ sudo apt-get install git -y - $ git clone https://git.onap.org/integration/devtool - $ cd /var/ - $ ln -s ~/devtool/lib/ ./onap - -.. end - -Loading a provisioning script will be based on the desired ONAP -service, for example to setup the development environment for Active -and Available Inventory (AAI) service will be required to load the -*/var/onap/aai* script. - -.. note:: - - The **git_src_folder** environment variable specifies the - source code destination folder, it's default value is */opt/onap/* - but it can be changed only after is loaded the provisioning - scripts. - -.. end - -.. code-block:: console - - # source /var/onap/aai - -.. end - -Lastly, every script has defined a initialization function with -*init_* as prefix. This function is the starting point to provision -the chosen ONAP service. This example uses the *init_aai* function -to provision a AAI Developement environment. - -.. note:: - - The **compile_repo** environment variable defines whether or not - the source code located on the repositories of the service. - Enabling this value can impact the provisioning time of the - service. - -.. end -.. note:: - - **nexus_docker_repo**, **nexus_username** and **nexus_password** - environment variables specify the connectivity to a private Docker - Hub. - -.. end -.. note:: - - **build_image** environment variable allows the Docker images - from source code. Enabling this value can impact the - provisioning time of the service. - -.. end - -.. code-block:: console - - # init_aai - -.. end - -As result, the source code is pulled into */opt/onap/aai/* folder and the -AAI services are up and running with the proper connection to the -Titan Distributed Graph Database. diff --git a/doc/source/features/example_usage.rst b/doc/source/features/example_usage.rst deleted file mode 100644 index 1aae887..0000000 --- a/doc/source/features/example_usage.rst +++ /dev/null @@ -1,151 +0,0 @@ -================================================= -Example usage to bring up a developer environment -================================================= - -In the example, we will bring up a single ONAP component using the Devtool ONAP -tool. - -There are multiple scenarios in which this tool can be made use of by a -developer, they usually fall in the following use cases. - -Use case 1: Use Devtool ONAP to just clone project related source code ----------------------------------------------------------------------- - -In this use case, the developer needs just the source code of the project to work on. - -Since the Devtool ONAP project supports building docker containers and compiling -source files, we need to first edit the settings.yaml file to add key value pairs -indicating we need to only clone repo and not build docker image or compile then. -By default, Devtool ONAP clones repo, but to not run the build process and cloning -docker images, the following are required to be added in the settings file. - -.. code-block:: console - - skip_get_images: "True" - -.. end - -The reason this is done is because as mentioned in the -`configure execution docs. `, -the default values taken are: - -.. code-block:: console - - 'build_image' => 'True', - 'clone_repo' => 'True', - 'compile_repo' => 'False', - 'enable_oparent' => 'True', - 'skip_get_images' => 'False', - 'skip_install' => 'True' - -.. end - -We override them and skip_get_images is given precedence over build_image. - -Use case 2: Use Devtool ONAP to clone project related source code and clone Docker Images ------------------------------------------------------------------------------------------ - -In this use case, the developer needs to clone docker images of the project to work on. - -For this case, we will edit the settings.yaml file to add key value pairs indicating we -need to clone repo and clone docker image from Nexus. - -.. code-block:: console - - build_images: "False" - compile_repo: "True" - skip_get_images: "False" - skip_install: "True" - -.. end - -Use case 3: Use Devtool ONAP to clone project related source code and build Docker Images locally -------------------------------------------------------------------------------------------------- - -In this use case, the developer needs to build docker images of the project to work on. - -For this case, we will edit the settings.yaml file to add key value pairs indicating we need to -clone repo and build docker image locally and not fetch them from Nexus. - -.. code-block:: console - - build_images: "True" - compile_repo: "True" - skip_get_images: "False" - skip_install: "True" - -.. end - -Use case 4: Use Devtool ONAP to clone project related source code and build Docker Images and start services ------------------------------------------------------------------------------------------------------------- - -In this use case, the developer needs to build docker images of the project he or -she wanted to work on and start the services running inside them. - -For this case, we will edit the settings.yaml file to add key value pairs indicating -we need to clone repo, compile repo, build docker image and run the image. - -.. code-block:: console - - build_images: "True" - compile_repo: "True" - skip_get_images: "False" - skip_install: "False" - -.. end - -Once the required changes to the settings file is added, we can use the run.sh -script in tools directory to setup the development environment. - -Example steps for setting up a development environment for VFC project. ------------------------------------------------------------------------ - -In this example we will be using Devtool ONAP to get all the source code of VFC -project and the developer can point the IDE to the cloned repo in the ./opt directory -and start the development process. - -.. code-block:: console - - $ ./tools/run.sh vfc - -.. end - -At the end of the setup process, all the VFC related source code will be present -in the devtool/opt/ directory. The developer can point an IDE to this directory -and start contributing. When the changes are done, the developer can SSH into the VM -running VFC and tests can be executed by running Maven for Java and Tox for Python -from the ~/opt/vfc directory. - -.. code-block:: console - - $ vagrant ssh vfc - $ cd ~/opt/onap/vfc/ - $ tox -e py27 - -.. end - -This way the tool helps the developer to clone repos of a particular project, -without having to manually search for repos and setup an environment. - -Also, if something gets messed up in the VM, the developer can tear down the VM -and spin a fresh one without having to lose the changes made to the source code since -the ./opt files are in sync from the host to the VM. - -.. code-block:: console - - $ vagrant destroy vfc - -.. end - -Testing -------- - -Use the run.sh script to test if the provisioning scripts run without errors. - -And example test to check the number of covered repositories with this tool. - -.. code-block:: console - - $ ./tools/run.sh testing -y -c coverity_repos -s functions - -.. end diff --git a/doc/source/features/features.rst b/doc/source/features/features.rst deleted file mode 100644 index 9055301..0000000 --- a/doc/source/features/features.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _features: - -================= -Advanced features -================= - -.. toctree:: - :maxdepth: 1 - - openstack.rst - consuming_scripts.rst - configure_execution.rst - example_usage.rst - -This chapter explains how to use Devtool ONAP tool for Advanced features -like different providers. diff --git a/doc/source/features/openstack.rst b/doc/source/features/openstack.rst deleted file mode 100644 index f44bc62..0000000 --- a/doc/source/features/openstack.rst +++ /dev/null @@ -1,89 +0,0 @@ -================== -OpenStack Provider -================== - -It's possible to use Vagrant to provision VMs on OpenStack using the -`Vagrant OpenStack Cloud Provider `. -The only requirement for the Cloud provider is to have an Ubuntu Cloud -image accesible to your tenant and a Security Rule that allows to do -SSH into the instance. - -Environment variables ---------------------- - -The usage of environment variables in OpenStack command-line clients -is to avoid repeating some values. These variables have *OS_* as -prefix. This provider will use them for authentication to Keystone -service. - -.. code-block:: console - - export OS_AUTH_URL=http://:5000/v3 - export OS_TENANT_NAME= - export OS_PROJECT_NAME= - export OS_USERNAME= - export OS_PASSWORD= - export OS_REGION_NAME= - export OS_IDENTITY_API_VERSION= - export OS_PROJECT_DOMAIN_ID= - -.. end - -OpenStack Vagrant provider needs additional information about the -name of the image to be used and the networking where the instance -will be provisioned. That information can be passed using the -following variables - -.. code-block:: console - - export OS_IMAGE= - export OS_NETWORK= - export OS_FLOATING_IP_POOL= - export OS_SEC_GROUP= - -.. end - -Tenant setup ------------- - -The *tools/setup_openstack.sh* script can be useful to get an idea -of the process to setup the OpenStack environment with the necessary -requirements. This script depends on the Environment Variables -explained previously. - ----- - -Devstack --------- - -It's possible to use this plugin to provision instances on -`Devstack `. This is -an example of the *local.conf* file that can be used as input -for Devstack - -.. path local.conf -.. code-block:: ini - - [[local|localrc]] - ADMIN_PASSWORD= - DATABASE_PASSWORD= - RABBIT_PASSWORD= - SERVICE_PASSWORD= - SERVICE_TOKEN= - - # Used to only upload the Ubuntu Cloud Image - DOWNLOAD_DEFAULT_IMAGES=False - IMAGE_URLS+="http://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img" - - # (Optional) These values helps to improve the experience deploying and using Devstack - GIT_BASE=https://git.openstack.org - FORCE_CONFIG_DRIVE="True" - disable_service tempest - -.. end - -.. note:: - - There is a validation that checks if the - *vagrant-openstack-provider* plugin is installed raising an error - for those cases when it isn't. diff --git a/doc/source/index.rst b/doc/source/index.rst deleted file mode 100644 index af5777c..0000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -ONAP on Vagrant tool -==================== - -This project collects instructions to setup a development environment -using different providers like VirtualBox, Libvirt or OpenStack. - -.. seealso:: - - You may want to read the `Bootstrap documentation`__ to get an idea of the - concepts. - - __ https://wiki.onap.org/display/DW/ONAP+on+Vagrant - -Table of contents ------------------ - -.. toctree:: - :maxdepth: 2 - - Installation Guide - Known Issues - Advanced Features - diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst deleted file mode 100644 index 62f57e6..0000000 --- a/doc/source/install/index.rst +++ /dev/null @@ -1,102 +0,0 @@ -================== -Installation Guide -================== - -This project collects instructions related to the automatic creation -of a development environment. However, this requires only two -components previous to its execution. These are an automation -building tool (Vagrant) and a provider platform (VirtualBox, Libvirt -and OpenStack). This section explains how to install the most common -set of configuration(Vagrant/VirtualBox) in different Operating -Systems. - -Ubuntu 14.04 ("Trusty") ------------------------ - -.. code-block:: console - - $ wget -q https://releases.hashicorp.com/vagrant/2.0.1/vagrant_2.0.1_x86_64.deb - $ sudo dpkg -i vagrant_2.0.1_x86_64.deb - - $ echo "deb http://download.virtualbox.org/virtualbox/debian trusty contrib" >> /etc/apt/sources.list - $ wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add - - $ wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add - - $ sudo apt-get update -y - $ sudo apt-get install -y virtualbox-5.1 dkms - - $ sudo apt install -y nfs-kernel-server - -.. end - -CentOS ------- - -.. code-block:: console - - $ wget -q https://releases.hashicorp.com/vagrant/2.0.1/vagrant_2.0.1_x86_64.rpm - $ sudo yum install vagrant_2.0.1_x86_64.rpm - - $ wget -q http://download.virtualbox.org/virtualbox/rpm/rhel/virtualbox.repo -P /etc/yum.repos.d - $ sudo yum --enablerepo=epel install dkms - $ wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | rpm --import - - $ sudo yum install -y VirtualBox-5.1 - - $ sudo yum install -y nfs-utils nfs-utils-lib - -.. end - -Mac OS ------- - -.. code-block:: console - - $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - $ brew cask install vagrant - $ brew cask install virtualbox - -.. end - -Windows 7+ (PowerShell v2+) ---------------------------- - -.. code-block:: console - - PS C:\> Set-ExecutionPolicy AllSigned - PS C:\> iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) - PS C:\> choco install vagrant - PS C:\> choco install virtualbox - -.. end - -.. note:: - - Some corporations use Proxy Servers to protect their assets - from security threats. This project uses the Proxy Environment - variables to connect to those servers in order to download the - content required during the setup. The methods to setup these - variables depends on the Operating system that is used. - - * Linux or Mac OS - - .. code-block:: console - - $ export http_proxy= - $ export https_proxy= - $ export no_proxy= - - .. end - - * Windows - - .. code-block:: console - - C:\> setx http_proxy - C:\> setx https_proxy - C:\> setx no_proxy - - .. end - -.. note:: - - Vagrant can be configured to use a different default provider - through the environment variable **VAGRANT_DEFAULT_PROVIDER**. diff --git a/doc/source/install/known_issues.rst b/doc/source/install/known_issues.rst deleted file mode 100644 index 8db55e7..0000000 --- a/doc/source/install/known_issues.rst +++ /dev/null @@ -1,63 +0,0 @@ -============ -Known Issues -============ - -Virtualbox guest additions conflict with shared directories ------------------------------------------------------------ - -If the **vagrant-vbguest** plugin is installed on the host, then an -updated version of the Virtualbox guest additions will be installed -on the guest in the /opt directory. Once this projects Vagrantfile -mounts the ./opt directory on the host to the /opt directory on the -guest during the provisioning process, the guest addtions on the -guest are hidden and subsequent mounts of shared directories with the -host will fail. - -The simplest workaround appears to be uninstalling the -*vagrant-vbguest* plugin on the host system. This has been observed -to work on a Windows 10 host using virtualbox 5.1.26. - -Check if vagrant-vbguest plugin is installed - -- Linux or Mac - -.. code-block:: console - - $ vagrant plugin list -.. end - -- Windows - -.. code-block:: console - - C:\> vagrant plugin list -.. end - -Remove vagrant-vbguest plugin - -- Linux or Mac - -.. code-block:: console - - $ vagrant plugin uninstall vagrant-vbguest -.. end - -- Windows - -.. code-block:: console - - C:\> vagrant plugin uninstall vagrant-vbguest -.. end - - -Network configuration in Windows --------------------------------- - -Some Virtual Machines present a problem in their network configuration so to -make sure the install will work as it should install the virtualbox from the -cmd window with the following command: - -.. code-block:: console - - c:\downloads\VirtualBox-5.1.20-114628-Win.exe -msiparams NETWORKTYPE=NDIS5 -.. end diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..906f249 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +BASE_DIR = os.path.dirname(os.path.abspath(__file__)) +ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) + +sys.path.insert(0, ROOT) +sys.path.insert(0, BASE_DIR) + +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx' +] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'ONAP on Vagrant' diff --git a/docs/source/features/configure_execution.rst b/docs/source/features/configure_execution.rst new file mode 100644 index 0000000..df08605 --- /dev/null +++ b/docs/source/features/configure_execution.rst @@ -0,0 +1,72 @@ +======================= +Modify execution values +======================= + +In order to provide a flexible platform that adjusts to different developer +needs, there are two mechanisms to configure the execution of this project. + +Settings configuration file +--------------------------- + +The first mechanism refers to the process to replace default configuration +values in the settings configuration file. This file needs to be placed into +the *./etc* folder and named *settings.yaml*. It must contain the key/pair +configuration values that will be overriden. + +.. note:: + + There are sample files (e. g. settings.yaml.development and + settings.yaml.testing) placed into the *./etc* folder. Their purpose is to + provide a reference of different configurations. + +.. end + +Configuration values: + ++------------------+-------------------+---------------------------------------+ +| Key | Values | Description | ++==================+===================+=======================================+ +| build_image | "True" or "False" | Determines if the Docker image is | +| | | retrieved from public hub or built | +| | | from source code. | ++------------------+-------------------+---------------------------------------+ +| clone_repo | "True" or "False" | Determines if all the source code | +| | | repositories of a given component are | +| | | cloned locally. | ++------------------+-------------------+---------------------------------------+ +| compile_repo | "True" or "False" | Determines if all the source code | +| | | repositories of a given component are | +| | | going to be compiled. | ++------------------+-------------------+---------------------------------------+ +| enable_oparent | "True" or "False" | Determines if the OParent project | +| | | will be used during the maven | +| | | compilation. | ++------------------+-------------------+---------------------------------------+ +| skip_get_images | "True" or "False" | Determines if the process to build or | +| | | retrieve docker images of a given | +| | | component are going to skipped. | ++------------------+-------------------+---------------------------------------+ +| skip_install | "True" or "False" | Determines if the process to start | +| | | the services of a given component | +| | | will be started. | ++------------------+-------------------+---------------------------------------+ + +Parameters +---------- + +The **skip_get_images** and **skip_install** are the only two configuration +values that can be overriden using *-g* and *-i* respectively by the run scripts +(*./tools/run.sh* and *.\\tools\\Run.ps1*). + +.. note:: + + The script parameters take precendence of the configuration file. + +.. end + +.. code-block:: console + + $ ./tools/run.sh sdc -g + +.. end + diff --git a/docs/source/features/consuming_scripts.rst b/docs/source/features/consuming_scripts.rst new file mode 100644 index 0000000..4290c25 --- /dev/null +++ b/docs/source/features/consuming_scripts.rst @@ -0,0 +1,88 @@ +============================== +Using the provisioning scripts +============================== + +Vagrant is a platform that uses prebaked images called +*vagrant boxes* to guarranty that running multiple times a +provisioning script will result in an expected output. This +mechanism is crucial for reducing the number of external factors +during the creation, development and testing of provisioning scripts. +However, it's possible to provide an ONAP development enviroment +without having to install Vagrant tool. This document explains how to +consume the provisioning scripts localed in **./lib** folder to +provision a development environment and the environment variables +that modifies their behavior. + +This project was built on an Ubuntu 14.04 ("Trusty") Operating System, +therefore it's necessary to have an user who has *sudo* permissions to +access to a Bare Metal or Virtual Machine. + +The following instructions retrieve the provisioning scripts and place +them into the */var/onap/* folder. + +.. code-block:: console + + $ sudo apt-get install git -y + $ git clone https://git.onap.org/integration/devtool + $ cd /var/ + $ ln -s ~/devtool/lib/ ./onap + +.. end + +Loading a provisioning script will be based on the desired ONAP +service, for example to setup the development environment for Active +and Available Inventory (AAI) service will be required to load the +*/var/onap/aai* script. + +.. note:: + + The **git_src_folder** environment variable specifies the + source code destination folder, it's default value is */opt/onap/* + but it can be changed only after is loaded the provisioning + scripts. + +.. end + +.. code-block:: console + + # source /var/onap/aai + +.. end + +Lastly, every script has defined a initialization function with +*init_* as prefix. This function is the starting point to provision +the chosen ONAP service. This example uses the *init_aai* function +to provision a AAI Developement environment. + +.. note:: + + The **compile_repo** environment variable defines whether or not + the source code located on the repositories of the service. + Enabling this value can impact the provisioning time of the + service. + +.. end +.. note:: + + **nexus_docker_repo**, **nexus_username** and **nexus_password** + environment variables specify the connectivity to a private Docker + Hub. + +.. end +.. note:: + + **build_image** environment variable allows the Docker images + from source code. Enabling this value can impact the + provisioning time of the service. + +.. end + +.. code-block:: console + + # init_aai + +.. end + +As result, the source code is pulled into */opt/onap/aai/* folder and the +AAI services are up and running with the proper connection to the +Titan Distributed Graph Database. diff --git a/docs/source/features/example_usage.rst b/docs/source/features/example_usage.rst new file mode 100644 index 0000000..1aae887 --- /dev/null +++ b/docs/source/features/example_usage.rst @@ -0,0 +1,151 @@ +================================================= +Example usage to bring up a developer environment +================================================= + +In the example, we will bring up a single ONAP component using the Devtool ONAP +tool. + +There are multiple scenarios in which this tool can be made use of by a +developer, they usually fall in the following use cases. + +Use case 1: Use Devtool ONAP to just clone project related source code +---------------------------------------------------------------------- + +In this use case, the developer needs just the source code of the project to work on. + +Since the Devtool ONAP project supports building docker containers and compiling +source files, we need to first edit the settings.yaml file to add key value pairs +indicating we need to only clone repo and not build docker image or compile then. +By default, Devtool ONAP clones repo, but to not run the build process and cloning +docker images, the following are required to be added in the settings file. + +.. code-block:: console + + skip_get_images: "True" + +.. end + +The reason this is done is because as mentioned in the +`configure execution docs. `, +the default values taken are: + +.. code-block:: console + + 'build_image' => 'True', + 'clone_repo' => 'True', + 'compile_repo' => 'False', + 'enable_oparent' => 'True', + 'skip_get_images' => 'False', + 'skip_install' => 'True' + +.. end + +We override them and skip_get_images is given precedence over build_image. + +Use case 2: Use Devtool ONAP to clone project related source code and clone Docker Images +----------------------------------------------------------------------------------------- + +In this use case, the developer needs to clone docker images of the project to work on. + +For this case, we will edit the settings.yaml file to add key value pairs indicating we +need to clone repo and clone docker image from Nexus. + +.. code-block:: console + + build_images: "False" + compile_repo: "True" + skip_get_images: "False" + skip_install: "True" + +.. end + +Use case 3: Use Devtool ONAP to clone project related source code and build Docker Images locally +------------------------------------------------------------------------------------------------- + +In this use case, the developer needs to build docker images of the project to work on. + +For this case, we will edit the settings.yaml file to add key value pairs indicating we need to +clone repo and build docker image locally and not fetch them from Nexus. + +.. code-block:: console + + build_images: "True" + compile_repo: "True" + skip_get_images: "False" + skip_install: "True" + +.. end + +Use case 4: Use Devtool ONAP to clone project related source code and build Docker Images and start services +------------------------------------------------------------------------------------------------------------ + +In this use case, the developer needs to build docker images of the project he or +she wanted to work on and start the services running inside them. + +For this case, we will edit the settings.yaml file to add key value pairs indicating +we need to clone repo, compile repo, build docker image and run the image. + +.. code-block:: console + + build_images: "True" + compile_repo: "True" + skip_get_images: "False" + skip_install: "False" + +.. end + +Once the required changes to the settings file is added, we can use the run.sh +script in tools directory to setup the development environment. + +Example steps for setting up a development environment for VFC project. +----------------------------------------------------------------------- + +In this example we will be using Devtool ONAP to get all the source code of VFC +project and the developer can point the IDE to the cloned repo in the ./opt directory +and start the development process. + +.. code-block:: console + + $ ./tools/run.sh vfc + +.. end + +At the end of the setup process, all the VFC related source code will be present +in the devtool/opt/ directory. The developer can point an IDE to this directory +and start contributing. When the changes are done, the developer can SSH into the VM +running VFC and tests can be executed by running Maven for Java and Tox for Python +from the ~/opt/vfc directory. + +.. code-block:: console + + $ vagrant ssh vfc + $ cd ~/opt/onap/vfc/ + $ tox -e py27 + +.. end + +This way the tool helps the developer to clone repos of a particular project, +without having to manually search for repos and setup an environment. + +Also, if something gets messed up in the VM, the developer can tear down the VM +and spin a fresh one without having to lose the changes made to the source code since +the ./opt files are in sync from the host to the VM. + +.. code-block:: console + + $ vagrant destroy vfc + +.. end + +Testing +------- + +Use the run.sh script to test if the provisioning scripts run without errors. + +And example test to check the number of covered repositories with this tool. + +.. code-block:: console + + $ ./tools/run.sh testing -y -c coverity_repos -s functions + +.. end diff --git a/docs/source/features/features.rst b/docs/source/features/features.rst new file mode 100644 index 0000000..9055301 --- /dev/null +++ b/docs/source/features/features.rst @@ -0,0 +1,16 @@ +.. _features: + +================= +Advanced features +================= + +.. toctree:: + :maxdepth: 1 + + openstack.rst + consuming_scripts.rst + configure_execution.rst + example_usage.rst + +This chapter explains how to use Devtool ONAP tool for Advanced features +like different providers. diff --git a/docs/source/features/openstack.rst b/docs/source/features/openstack.rst new file mode 100644 index 0000000..f44bc62 --- /dev/null +++ b/docs/source/features/openstack.rst @@ -0,0 +1,89 @@ +================== +OpenStack Provider +================== + +It's possible to use Vagrant to provision VMs on OpenStack using the +`Vagrant OpenStack Cloud Provider `. +The only requirement for the Cloud provider is to have an Ubuntu Cloud +image accesible to your tenant and a Security Rule that allows to do +SSH into the instance. + +Environment variables +--------------------- + +The usage of environment variables in OpenStack command-line clients +is to avoid repeating some values. These variables have *OS_* as +prefix. This provider will use them for authentication to Keystone +service. + +.. code-block:: console + + export OS_AUTH_URL=http://:5000/v3 + export OS_TENANT_NAME= + export OS_PROJECT_NAME= + export OS_USERNAME= + export OS_PASSWORD= + export OS_REGION_NAME= + export OS_IDENTITY_API_VERSION= + export OS_PROJECT_DOMAIN_ID= + +.. end + +OpenStack Vagrant provider needs additional information about the +name of the image to be used and the networking where the instance +will be provisioned. That information can be passed using the +following variables + +.. code-block:: console + + export OS_IMAGE= + export OS_NETWORK= + export OS_FLOATING_IP_POOL= + export OS_SEC_GROUP= + +.. end + +Tenant setup +------------ + +The *tools/setup_openstack.sh* script can be useful to get an idea +of the process to setup the OpenStack environment with the necessary +requirements. This script depends on the Environment Variables +explained previously. + +---- + +Devstack +-------- + +It's possible to use this plugin to provision instances on +`Devstack `. This is +an example of the *local.conf* file that can be used as input +for Devstack + +.. path local.conf +.. code-block:: ini + + [[local|localrc]] + ADMIN_PASSWORD= + DATABASE_PASSWORD= + RABBIT_PASSWORD= + SERVICE_PASSWORD= + SERVICE_TOKEN= + + # Used to only upload the Ubuntu Cloud Image + DOWNLOAD_DEFAULT_IMAGES=False + IMAGE_URLS+="http://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img" + + # (Optional) These values helps to improve the experience deploying and using Devstack + GIT_BASE=https://git.openstack.org + FORCE_CONFIG_DRIVE="True" + disable_service tempest + +.. end + +.. note:: + + There is a validation that checks if the + *vagrant-openstack-provider* plugin is installed raising an error + for those cases when it isn't. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..af5777c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,23 @@ +ONAP on Vagrant tool +==================== + +This project collects instructions to setup a development environment +using different providers like VirtualBox, Libvirt or OpenStack. + +.. seealso:: + + You may want to read the `Bootstrap documentation`__ to get an idea of the + concepts. + + __ https://wiki.onap.org/display/DW/ONAP+on+Vagrant + +Table of contents +----------------- + +.. toctree:: + :maxdepth: 2 + + Installation Guide + Known Issues + Advanced Features + diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst new file mode 100644 index 0000000..62f57e6 --- /dev/null +++ b/docs/source/install/index.rst @@ -0,0 +1,102 @@ +================== +Installation Guide +================== + +This project collects instructions related to the automatic creation +of a development environment. However, this requires only two +components previous to its execution. These are an automation +building tool (Vagrant) and a provider platform (VirtualBox, Libvirt +and OpenStack). This section explains how to install the most common +set of configuration(Vagrant/VirtualBox) in different Operating +Systems. + +Ubuntu 14.04 ("Trusty") +----------------------- + +.. code-block:: console + + $ wget -q https://releases.hashicorp.com/vagrant/2.0.1/vagrant_2.0.1_x86_64.deb + $ sudo dpkg -i vagrant_2.0.1_x86_64.deb + + $ echo "deb http://download.virtualbox.org/virtualbox/debian trusty contrib" >> /etc/apt/sources.list + $ wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add - + $ wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add - + $ sudo apt-get update -y + $ sudo apt-get install -y virtualbox-5.1 dkms + + $ sudo apt install -y nfs-kernel-server + +.. end + +CentOS +------ + +.. code-block:: console + + $ wget -q https://releases.hashicorp.com/vagrant/2.0.1/vagrant_2.0.1_x86_64.rpm + $ sudo yum install vagrant_2.0.1_x86_64.rpm + + $ wget -q http://download.virtualbox.org/virtualbox/rpm/rhel/virtualbox.repo -P /etc/yum.repos.d + $ sudo yum --enablerepo=epel install dkms + $ wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | rpm --import - + $ sudo yum install -y VirtualBox-5.1 + + $ sudo yum install -y nfs-utils nfs-utils-lib + +.. end + +Mac OS +------ + +.. code-block:: console + + $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + $ brew cask install vagrant + $ brew cask install virtualbox + +.. end + +Windows 7+ (PowerShell v2+) +--------------------------- + +.. code-block:: console + + PS C:\> Set-ExecutionPolicy AllSigned + PS C:\> iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) + PS C:\> choco install vagrant + PS C:\> choco install virtualbox + +.. end + +.. note:: + + Some corporations use Proxy Servers to protect their assets + from security threats. This project uses the Proxy Environment + variables to connect to those servers in order to download the + content required during the setup. The methods to setup these + variables depends on the Operating system that is used. + + * Linux or Mac OS + + .. code-block:: console + + $ export http_proxy= + $ export https_proxy= + $ export no_proxy= + + .. end + + * Windows + + .. code-block:: console + + C:\> setx http_proxy + C:\> setx https_proxy + C:\> setx no_proxy + + .. end + +.. note:: + + Vagrant can be configured to use a different default provider + through the environment variable **VAGRANT_DEFAULT_PROVIDER**. diff --git a/docs/source/install/known_issues.rst b/docs/source/install/known_issues.rst new file mode 100644 index 0000000..8db55e7 --- /dev/null +++ b/docs/source/install/known_issues.rst @@ -0,0 +1,63 @@ +============ +Known Issues +============ + +Virtualbox guest additions conflict with shared directories +----------------------------------------------------------- + +If the **vagrant-vbguest** plugin is installed on the host, then an +updated version of the Virtualbox guest additions will be installed +on the guest in the /opt directory. Once this projects Vagrantfile +mounts the ./opt directory on the host to the /opt directory on the +guest during the provisioning process, the guest addtions on the +guest are hidden and subsequent mounts of shared directories with the +host will fail. + +The simplest workaround appears to be uninstalling the +*vagrant-vbguest* plugin on the host system. This has been observed +to work on a Windows 10 host using virtualbox 5.1.26. + +Check if vagrant-vbguest plugin is installed + +- Linux or Mac + +.. code-block:: console + + $ vagrant plugin list +.. end + +- Windows + +.. code-block:: console + + C:\> vagrant plugin list +.. end + +Remove vagrant-vbguest plugin + +- Linux or Mac + +.. code-block:: console + + $ vagrant plugin uninstall vagrant-vbguest +.. end + +- Windows + +.. code-block:: console + + C:\> vagrant plugin uninstall vagrant-vbguest +.. end + + +Network configuration in Windows +-------------------------------- + +Some Virtual Machines present a problem in their network configuration so to +make sure the install will work as it should install the virtualbox from the +cmd window with the following command: + +.. code-block:: console + + c:\downloads\VirtualBox-5.1.20-114628-Win.exe -msiparams NETWORKTYPE=NDIS5 +.. end diff --git a/tox.ini b/tox.ini index 6ab309f..8511641 100644 --- a/tox.ini +++ b/tox.ini @@ -27,4 +27,4 @@ commands = bash -c "find {toxinidir}/{tests,lib,tools} \ [testenv:docs] deps = sphinx -commands = sphinx-build -W -b html doc/source doc/build/html +commands = sphinx-build -W -b html docs/source docs/build/html -- cgit 1.2.3-korg