laas-fog/README

   1 This Lab as a Serice project aims to create on demand OPNFV resources to developers.
   2 This project will automate the process, to the requested extent, of running an OPNFV
   3 installer and creating an Openstack environment within OPNFV automatically and on demand.
   4
   5 To run, execute (from the project root):
   6     source/deploy.py
   7
   8 To run the Pharos dahsboard listener, which will continualy poll the dashboard and run deployments in the background:
   9     source/listen.py --config <conf/pharos.conf>
  10
  11
  12 For convenience, there is a bash script source/stop.sh which will stop the dashboard listener and all related scripts.
  13
  14 BEFORE YOU CAN RUN:
  15 you must first:
  16 - Integrate FOG into your infrastructure
  17 - Fill out the needed configuration files
  18 - Populate the database with your available hosts
  19
  20
  21 FOG:
  22 Our OPNFV infrastructure uses a FOG server to pxe boot, read and write disk images, and otherwise control the hosts we have available for developers.
  23 FOG is an open source project, and you can view it here: https://fogproject.org/
  24 FOG provides an easy and scriptable way to completely wipe and write the disks of our hosts.
  25     This makes it quick and simple for us to restore our hosts to a known, clean state after a developer has released control of it.
  26
  27 To run the deploy script, you need to:
  28     Have a FOG master running
  29     Have your hosts registered to the FOG master
  30     Have a 'clean' disk image of for each installer / configuration you wish to support.
  31         - Fuel, Compass, and JOID all need different distros / versions to run properly
  32         - There is a mapping between images and their installers in the installer's config file
  33 The FOG server must be reachable by whatever machine is running this LaaS software,
  34 and have network access to PXE boot all of your hosted dev pods.
  35
  36
  37 CONFIGURATION:
  38 INSTALLERS#############################################################################################
  39 -database               Path to the SQLite database for storing host information.
  40                             Should be the same for all installers in most cases.
  41 -dhcp_log               Path to log file containing DHCP information for dev pods.
  42 -dhcp_server            IP address or hostname of the DHCP server which contains the above log file
  43                             set to `null` if the same machine will be running dhcp and this project
  44 -fog
  45 --api_key               The FOG api key. You may instead give the path to a file containing the api key.
  46 --server                The URL of the fog server.
  47                             ex: http://myServer.com/fog/
  48 --user_key              The FOG api key specific to your user.
  49                             You may instead give the path to a secrets file containing the key.
  50 --image_id              The id of the image FOG will use when this installer is requested.
  51 -installer              The name of the installer, as seen from the dashboard.
  52                             `null` will match when no installer is selected, or the `None` installer is..
  53 -logging_dir            The directory to create log files in.
  54                             Will create the dir if it does not already exist.
  55 -scenario               The default scenario if one is not specified by the user.
  56                             NOTE:   automation of different scenarios are not currently supported.
  57                                     These values are silently ignored.
  58 -hypervisor_config
  59 --networks              Path to the config file used to define the virtual networks for this installer.
  60 --vms                   Path to the config file used to define the virtual machines for this installer.
  61 -inventory              Path to inventory file mapping dashboard host id's to FOG hostnames.
  62 -vpn_config             Path to the vpn config file
  63
  64
  65 #########################################################################################################
  66
  67 DOMAINS##################################################################################################
  68 -jinja-template         Path to the jinja xml template used to create libvirt domain xml documents.
  69 -domains                A list of domains. List as many as you want, but be cognizant of hardware limitations
  70 --disk                  Path to the qcow2 disk image for this VM
  71 --interfaces            List of interfaces for the vm
  72 ---name                 The name of the network or bridge that provides this interface
  73 ---type                 The source of the interface. Either 'bridge' or 'network' is valid, but the bridge
  74                             must already exist on the host.
  75 --iso
  76 ---URL                  Where to fetch the ISO from
  77 ---location             Where to save the ISO to
  78 ---used                 Whether this host will use an iso as a boot drive
  79                             if `false`, the ISO will not be downloaded
  80 --memory                Memory to allocate to the VM in KiB
  81 --name                  libvirt name of VM
  82 --vcpus                 How many vcpus to allocate to this host.
  83 #########################################################################################################
  84
  85 NETWORKS#################################################################################################
  86 -jinja-template         Path to jinja template used to create libvirt XML network documents
  87 -networks               List of networks that will be created
  88 --brAddr                ip address of the bridge on the host
  89 --brName                name of the bridge on the host
  90 --cidr                  cidr of the virtual network
  91 --dhcp                  dhcp settingg
  92 ---rangeEnd             end of DHCP address range
  93 ---rangeStart           start of DHCP address range
  94 ---used                 Whether to enable dhcp for this network. Should probably be false.
  95 --forward               Libvirt network forwarding settings
  96 ---type                 forwarding type. See libvirt documentation for possible types.
  97 ---used                 if `false`, the network is isolated.
  98 --name                  Name of this network in Libvirt
  99 --netmask               Netmask for this network.
 100 ########################################################################################################
 101
 102 PHAROS##################################################################################################
 103 -dashboard              url of the dashboard. https://labs.opnfv.org is the public OPNFV dashboard
 104 -database               path to database to store booking information.
 105                             Should be the same db as the host database in most cases
 106 -default_configs        a mappping of installers and their configuration files.
 107 -inventory              path to the inventory file
 108 -logging_dir            Where the pharos dashboard listener should put log files.
 109 -poling                 How many times a second the listener will poll the dashboard
 110 -token                  Your paros api token. May also be a path to a file containing the token
 111 #######################################################################################################
 112
 113 VPN####################################################################################################
 114 NOTE: this all assumes you use LDAP authentication
 115 -server                 Domain name of your vpn server
 116 -authenticaion
 117 --pass                  password for your 'admin' user. May also be a path to a secrets file
 118 --user                  full dn of your 'admin' user
 119 -directory
 120 --root                  The lowest directory that this program will need to access
 121 --user                  The directory where users are stored, relative to the given root dir
 122 -user
 123 --objects               A list of object classes that vpn users will belong to.
 124                             Most general class should be on top, and get more specific from there.
 125                             ex: -top, -inetOrgPerson because `top` is more general
 126 -database               The booking database
 127 -permanent_users        Users that you want to be persistent, even if they have no bookings active
 128                             ie: your admin users
 129                             All other users will be deleted when they have no mroe bookings
 130 #######################################################################################################
 131
 132 INVENTORY##############################################################################################
 133 This file is used to map the resource id's known by pharos to the hostnames known by FOG.
 134 for example,
 135 50: fog-machine-4
 136 51: fog-machine-5
 137 52: fog-virtualPod-5.1
 138 #######################################################################################################
 139
 140 HOW IT WORKS:
 141
 142 0) lab resources are prepared and information is stored in the database
 143 1) source/listen.py launches a background instance of pharos.py
 144     -pharos.py continually polls the dashboard for booking info, and stores it in the database
 145 2) A known booking begins and pharos.py launches pod_manager.py
 146     - pod_manager is launched in a new process, so that the listener continues to poll the dashboard
 147       and multiple hosts can be provisioned at once
 148 3) pod_manager uses FOG to image the host
 149 4) if requested, pod_manager hands control to deployment_manager to install and deploy OPNFV
 150     - deployment_manager instantiates and calls the go() function of the given source/installers/installer subclass
 151 5) a vpn user is created and random root password is given to the dev pod
 152 ##########The dashboard does not yet support the following actions#############
 153 6) public ssh key of the user is fetched from the dashboard
 154 7) user is automatically notified their pod is ready, and given all needed info
 155
 156
 157 GENERAL NOTES:
 158
 159 resetDatabase.py relies on FOG to retrieve a list of all hosts available to developers
 160
 161 running:
 162     source/resetDatabase.py --both --config <CONFIG_FILE>
 163 will create a database and populate it.
 164 WARNING: This will delete existing information if run on a previously initialized database
 165
 166 To aid in visualization and understanding of the resulting topolgy after fully deploying OPNFV and Openstack in
 167 a development pod, you may review the LaaS_Diagram in this directory.