diff options
Diffstat (limited to 'docs/source/features')
| -rw-r--r-- | docs/source/features/configure_execution.rst | 72 | ||||
| -rw-r--r-- | docs/source/features/consuming_scripts.rst | 88 | ||||
| -rw-r--r-- | docs/source/features/example_usage.rst | 151 | ||||
| -rw-r--r-- | docs/source/features/features.rst | 16 | ||||
| -rw-r--r-- | docs/source/features/openstack.rst | 89 |
5 files changed, 416 insertions, 0 deletions
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. <https://git.onap.org/integration/devtool/tree/doc/source/features/configure_execution.rst>`, +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/<vfc-subrepo> + $ 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 <https://github.com/ggiamarchi/vagrant-openstack-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://<keystone_ip>:5000/v3 + export OS_TENANT_NAME=<project_or_tenant_name> + export OS_PROJECT_NAME=<project_or_tenant_name> + export OS_USERNAME=<openstack_username> + export OS_PASSWORD=<openstack_password> + export OS_REGION_NAME=<openstack_region_name> + export OS_IDENTITY_API_VERSION=<keystone_version_number> + export OS_PROJECT_DOMAIN_ID=<openstack_domain_name> + +.. 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=<ubuntu_cloud_image_name> + export OS_NETWORK=<neutron_private_network> + export OS_FLOATING_IP_POOL=<neutron_floating_ip_pool> + export OS_SEC_GROUP=<onap-ssh-secgroup> + +.. 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 <https://docs.openstack.org/devstack/latest/>`. 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=<password> + DATABASE_PASSWORD=<password> + RABBIT_PASSWORD=<password> + SERVICE_PASSWORD=<password> + SERVICE_TOKEN=<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. |