osm-tests/README.md

   1 # README: Vagrant sandbox for Robot tests
   2
   3 Copyright 2020 Telefónica Investigación y Desarrollo S.A.U.
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7     http://www.apache.org/licenses/LICENSE-2.0
   8 Unless required by applicable law or agreed to in writing, software
   9 distributed under the License is distributed on an "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  11 See the License for the specific language governing permissions and
  12 limitations under the License.
  13
  14 ## HOW TO USE IT (TL;DR)
  15
  16 1. Prepare your local environment:
  17    1. Upload all required images to your VIM (e.g. `openstack image create ...`).
  18       - Hint: you can download first all relevant testing images from OSM by:
  19         ```bash
  20         cd images
  21         ./download_images.sh
  22         ```
  23    2. Add the corresponding VIM target to your OSM (`osm vim-create ...`).
  24 2. Provide credentials for your VIM+OSM environment:
  25    - Create/Edit `localconfig/envconfig.rc` (and `localconfig/envprovisioning.sh` if needed).
  26      - HINT: First time, use `localconfig/TEMPLATE-envconfig.rc` and (if needed) `localconfig/TEMPLATE-envprovisioning.sh` as templates.
  27 3. (OPTIONAL) In case you needed to apply a specific Devops patch-set, define it at `baseconfig/patchconfig.rc`.
  28 4. Start the sandbox for its first time provisioning with `vagrant up`.
  29 5. Do `vagrant ssh` to enter in the VM.
  30 6. Run your first test:
  31    ```bash
  32    cd robot
  33    robot -d /vagrant/results testsuite/hackfest_basic.robot
  34    ```
  35
  36 **TIP:** In case your needed to use the latest version of OSM client from master instead of the latest stable version, simply do:
  37
  38 ```bash
  39 export OSM_CLIENT_VERSION=master
  40 vagrant up
  41 ```
  42
  43 **Please use this option with caution, and only when absolutely required**.
  44
  45 ## INTRODUCTION
  46
  47 This Vagrant sandbox provides a simple self-contained environment suitable for running consistently E2E tests with OSM.
  48
  49 Using this sandbox for local E2E testing has a number of advantages:
  50
  51 - It enables the end user to run and validate easily in your local environment the set of Robot tests available in ETSI OSM and enables you to contribute back more easily.
  52 - It provides a well-known software environment, with all the required dependencies properly pre-validated.
  53 - It guarantees that there are no hardcoded dependencies with the local tester environment or with OSM's CI/CD in terms of versions, destinations, paths, credentials, etc. All the test conditions can be completely defined using environment variables if needed.
  54 - Its provisioner script (`provisioner.sh`) can be used as-is for provisioning other types of environments, such as a Docker containers.
  55 - Likewise, the provisioner script can serve as documentation/validation of different installation processes maintained by OSM (client, Robot, etc.).
  56
  57 Here is the sandbox what Vagrant creates for you:
  58
  59 ![Diagram of the functionality of the Sandbox](assets/image-20200406234414818.png)
  60
  61 As it can be seen, the provisioning of the sandbox installs several pieces of software:
  62
  63 - OSM Client.
  64 - Robot Framework and all library dependencies required to run the full test suite.
  65 - Other complementary utilities to perform the tests or ease troubleshooting.
  66
  67 In addition, the provision of the sandbox requires a number of inputs:
  68
  69 - The collection of E2E Robot tests for OSM.
  70 - Details of OSM instance(s) available for testing, part of the DUT.
  71 - Details of VIM(s) available for testing, part of the DUT.
  72 - Location of VNF and NS packages required to run the tests.
  73 - Location of VM images required to run the tests (future use).
  74
  75 ## PRE-REQUIREMENTS
  76
  77 ### Available infrastructure (DUT)
  78
  79 - There is at least one VIM available and reachable.
  80 - There is at least one OSM instance available and reachable.
  81 - The OSM instance(s) has (have) at least one target added per VIM.
  82
  83 ### Software pre-requirements already covered by Vagrant
  84
  85 - `authorized_keys` at `~/.ssh` with proper permissions.
  86 - `id_rsa`, `id_rsa.pub` at `~/.ssh` with proper permissions.
  87 - A functional `.gitconfig` file at `~` with proper permissions.
  88 - Base configuration files at `${BASE_CONFIG_FOLDER}` (for Vagrant, `~/baseconfig`):
  89   - `seedconfig.rc`, where most basic configuration is made.
  90   - `patchconfig.rc`, where a Gerrit patch-set for Devops is selected. This file is optional.
  91 - Local environment configuration files at `${LOCAL_CONFIG_FOLDER}` (for Vagrant, `~/localconfig`)
  92   - `envprovisioning.sh`, where local provisioning tasks are scripted. This file is optional.
  93   - `envconfig.rc`, where the DUT (VIM and OSM) are defined with environment variables.
  94 - All packages required for the tests are already placed at `${PACKAGES_FOLDER}`.
  95   - In Vagrant, they are cloned into `/home/vagrant/packages/osm-packages` in the VM.
  96 - All images required for the tests are already placed at `${IMAGES_FOLDER}`.
  97   - In Vagrant, `/vagrant/images`.
  98   - This folder is intended for future use, but not relevant for the current test suite.
  99
 100 ### Software pre-requirements to be fulfilled by the user
 101
 102 Users **should edit** the information about the DUT (local VIM and available OSM) before provisioning the sandbox.
 103
 104 In the case of Vagrant, the `localconfig` sub-folder of the Vagrant sandbox definition (i.e. at the host) contains the relevant files to be edited:
 105
 106 1. `envprovisioning.sh` is used as "provisioner" to retrieve some the local environment data, i.e. it is a script intended to retrieve information from some well-known locations, such as local Git repos, that will be referred lated by `envconfig.rc`.
 107 2. `envconfig.rc` contains the minimal set of environment variables required to run successfully the suite of Robot tests.
 108
 109 Once the vagrant sandbox is created, these files will be automatically copied into the VM to `${LOCAL_CONFIG_FOLDER}`) so that they can complete the configuration of the test environment.
 110
 111 ## Configuration setup
 112
 113 ### Tester setup and test suite configuration
 114
 115 Setup of testing conditions, independent from the local environment. This configuration is defined in two configuration files, stored at `${BASE_CONFIG_FOLDER}` (for Vagrant, `~/baseconfig`).
 116
 117 #### Base configuration: `seedconfig.rc`
 118
 119 This file contains common base configuration for the test suite, independent of the environment.
 120
 121 This repo provides a configuration customized for Vagrant sandboxes. If that is your case, please do not edit. However, the existing file can be used as template for creating a `seedconfig.rc` for other types of environments (e.g. Docker).
 122
 123 Hare is the sample of `seedconfig.rc` for Vagrant with the environment variables commented:
 124
 125 ```bash
 126 # Base folder for all operations
 127 export BASE_FOLDER=/home/vagrant
 128 # EOL account for SSH operations. Required for password-less operations with Git.
 129 # Comment to undefine and it will use HTTP instead
 130 export ETSIUSERNAME=$(git config user.name)
 131 # Folder where Robot tests are stored
 132 export ROBOT_DEVOPS_FOLDER="${HOME}/devops/robot-systest"
 133 # Folder to save alternative DUT environments (optional)
 134 export ENVIRONMENTS_FOLDER=environments
 135 # Folder where all required packages are stored
 136 export BASE_PACKAGES_FOLDER="${BASE_FOLDER}/packages"
 137 export PACKAGES_FOLDER="${BASE_PACKAGES_FOLDER}/osm-packages"
 138 # Folder where all required images are stored (intended for future use)
 139 #export IMAGES_FOLDER="/vagrant/images"
 140 # Folder where test results should be exported
 141 export ROBOT_REPORT_FOLDER="/vagrant/results"
 142 ```
 143
 144 #### Devops patch configuration (optional): `patchconfig.rc`
 145
 146 This file, when exists, defines an optional Gerrit patch-set to be applied over the current Devops master.
 147
 148 This configuration is optional and mostly intended for OSM developers. Do not use if you plan to run community-approved test suites.
 149
 150 Here is the sample of `patchconfig.rc` with the environment variable commented:
 151
 152 ```bash
 153 # URL to be used in a subsequent `pull` command to apply the patchset
 154 export DEVOPS_PATCH=refs/changes/51/8751/1
 155 ```
 156
 157 ### DUT configuration (local environment)
 158
 159 Setup of the local environment for the tests. This configuration is defined in configuration files stored at `${LOCAL_CONFIG_FOLDER}` (for Vagrant, `~/localconfig`).
 160
 161 #### Local environment provisioning (optional): `envprovisioning.sh`
 162
 163 This file, which is optional, is intended to be used as a script to retrieve information about the local environment, which might include cloning repositories, downloading credential files, etc. Typically, this is used to fetch sensitive information. There are two typical cases:
 164
 165 - `openstack.rc`
 166   - The provisioner, besides fetching it, would append the info to `${LOCAL_CONFIG_FOLDER}/envconfig.rc`.
 167 - `clouds.yaml`
 168   - The provisioner, besides fetching it, should copy the file to `${BASE_FOLDER}`.
 169
 170 Here is an example of `envprovisioning.sh` with relevant operations commented:
 171
 172 ```bash
 173 ssh-keyscan mygit.com >> ~/.ssh/known_hosts  # Often needed for non public repos
 174 git clone git@mygit.com:local-environment-data/vim-and-infra.git
 175 cp vim-and-infra/openstack/clouds.yaml "${BASE_FOLDER}"/ # Copy of credentials to base folder
 176 ```
 177
 178 #### Local environment configuration: `envconfig.rc`
 179
 180 This file, which is **mandatory**, is where the local DUT is completely defined with environment variables.
 181
 182 ```bash
 183 # VIM setup
 184 export OS_USERNAME=username
 185 export OS_PASSWORD=password
 186 export OS_TENANT_NAME=projectName
 187 export OS_AUTH_URL=https://identityHost:portNumber/v2.0
 188 export OS_TENANT_ID=tenantIDString
 189 export OS_REGION_NAME=regionName
 190 export OS_CACERT=/path/to/cacertFile
 191 # OSM location
 192 export OSM_HOSTNAME="192.168.1.22"
 193 # Details of the VIM target for OSM
 194 export VIM_TARGET="vim002-fortville-physnet"
 195 export VIM_MGMT_NET="management"
 196 # Optional: location of alternative `envconfig.rc`-like files
 197 export ENVIRONMENTS_FOLDER=environments
 198 ```
 199
 200 Alternatively, here is another example `envconfig.rc` where the VIM is defined with a credentials file, `clouds.yaml`:
 201
 202 ```bash
 203 # VIM setup
 204 export CLOUDS_PATH=${BASE_FOLDER} # Location of `clouds.yaml`
 205 export OS_CLOUD=vim-002
 206 # OSM location
 207 export OSM_HOSTNAME="192.168.1.22"
 208 # Details of the VIM target for OSM
 209 export VIM_TARGET="vim002-fortville-physnet"
 210 export VIM_MGMT_NET="management"
 211 # Optional: location of alternative `envconfig.rc`-like files
 212 export ENVIRONMENTS_FOLDER=environments
 213 ```