docs/how-to-use/VirtEnvDeploy.rst

   1 Overview
   2 ========
   3
   4 The main purpose of this project is to enable one to describe a virtual environment in a YAML file and enable the
   5 user to deploy it to an OpenStack cloud in a repeatable manner. There are also options to un-deploy that same
   6 environment by leveraging the original YAML file.
   7
   8 To deploy/clean virtual environments
   9 ====================================
  10
  11 -  Clone Repository
  12
  13    -  git clone https://gerrit.cablelabs.com/snaps-provisioning
  14
  15 -  Install Library
  16
  17    -  pip install -e /
  18
  19 -  Deploy
  20
  21    -  cd
  22    -  python snaps/deploy\_venv.py -e -d
  23    -  Working example:
  24
  25 ::
  26
  27     python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -d
  28
  29 -  Clean
  30
  31    -  python deploy\_venv.py -e -c
  32    -  Working example (cleanup of a previously deployed virtual
  33       environment where the VM has Yardstick installed):
  34
  35 ::
  36
  37     python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -c
  38
  39 Environment Configuration YAML File
  40 ===================================
  41
  42 The configuration file used to deploy and provision a virtual environment has been designed to describe the required
  43 images, networks, SSH public and private keys, associated VMs, as well as any required post deployment provisioning
  44 tasks.
  45
  46 \*\*\* Please note that many of the more esoteric optional supported
  47 attributes still have not been fully tested. ***
  48 *** Some of the nested bullets are being hidden by GitLabs, please see
  49 doc/VirtEnvDeploy.md.\*\*\*
  50
  51 -  openstack: the top level tag that denotes configuration for the
  52    OpenStack components
  53
  54    -  connection: - contains the credentials and endpoints required to
  55       connect with OpenStack
  56    -  username: - the project's user (required)
  57    -  password: - the tentant's user password (required)
  58    -  auth\_url: - the URL to the OpenStack APIs (required)
  59    -  project\_name: - the name of the OpenStack project for the user
  60       (required)
  61    -  http\_proxy: - the {{ host }}:{{ port }} of the proxy server the
  62       HTTPPhotoman01(optional)
  63    -  images: - describes each image
  64    -  image:
  65
  66       -  name: The unique image name. If the name already exists for
  67          your project, a new one will not be created (required)
  68       -  format: The format type of the image i.e. qcow2 (required)
  69       -  download\_url: The HTTP download location of the image file
  70          (required)
  71       -  nic\_config\_pb\_loc: The file location relative to the CWD
  72          (python directory) to the Ansible Playbook used to configure
  73          VMs with more than one port. VMs get their first NIC configured
  74          for free while subsequent ones are not. This value/script will
  75          only be leveraged when necessary. Centos has been supported
  76          with
  77          "provisioning/ansible/centos-network-setup/configure\_host.yml".
  78
  79    -  networks:
  80    -  network:
  81
  82       -  name: The name of the network to be created. If one already
  83          exists, a new one will not be created (required)
  84       -  admin\_state\_up: T\|F (default True)
  85       -  shared: (optional)
  86       -  project\_name: Name of the project who owns the network. Note:
  87          only administrative users can specify projects other than their
  88          own (optional)
  89       -  external: T\|F whether or not network is external (default
  90          False)
  91       -  network\_type: The type of network to create. (optional)
  92       -  subnets:
  93       -  subnet:
  94
  95          -  name: The name of the network to be created. If one already
  96             exists, a new one will not be created. Note: although
  97             OpenStack allows for multiple subnets to be applied to any
  98             given network, we have not included support as our current
  99             use cases does not utilize this functionality (required)
 100          -  cidr: The subnet mask value (required)
 101          -  dns\_nameservers: A list of IP values used for DNS
 102             resolution (default: 8.8.8.8)
 103          -  ip\_version: 4\|6 (default: 4)
 104          -  project\_name: Name of the project who owns the network.
 105             Note: only administrative users can specify projects other
 106             than their own (optional)
 107          -  start: The start address for allocation\_pools (optional)
 108          -  end: The ending address for allocation\_pools (optional)
 109          -  gateway\_ip: The IP address to the gateway (optional)
 110          -  enable\_dhcp: T\|F (optional)
 111          -  dns\_nameservers: List of DNS server IPs
 112          -  host\_routes: A list of host route dictionaries (optional)
 113             i.e.:
 114             ``yaml    "host_routes":[    {    "destination":"0.0.0.0/0",    "nexthop":"123.456.78.9"    },    {    "destination":"192.168.0.0/24",    "nexthop":"192.168.0.1"    }    ]``
 115          -  destination: The destination for a static route (optional)
 116          -  nexthop: The next hop for the destination (optional)
 117          -  ipv6\_ra\_mode: Valid values: "dhcpv6-stateful",
 118             "dhcpv6-stateless", and "slaac" (optional)
 119          -  ipv6\_address\_mode: Valid values: "dhcpv6-stateful",
 120             "dhcpv6-stateless", and "slaac" (optional)
 121
 122    -  routers:
 123
 124       -  router:
 125       -  name: The name of the router to be created. If one already
 126          exists, a new one will not be created (required)
 127       -  project\_name: Name of the project who owns the network. Note:
 128          only administrative users can specify projects other than their
 129          own (optional)
 130       -  internal\_subnets: A list of subnet names on which the router
 131          will be placed (optional)
 132       -  external\_gateway: A dictionary containing the external gateway
 133          parameters: "network\_id", "enable\_snat",
 134          "external\_fixed\_ips" (optional)
 135       -  interfaces: A list of port interfaces to create to other
 136          subnets (optional)
 137
 138          -  port (Leverages the same class/structure as port objects on
 139             VM instances. See port definition below for a
 140             full accounting of the port attributes. The ones listed
 141             below are generally used for routers)
 142
 143             -  name: The name given to the new port (must be unique for
 144                project) (required)
 145             -  network\_name: The name of the new port's network
 146                (required)
 147             -  ip\_addrs: A list of k/v pairs (optional)
 148             -  subnet\_name: the name of a subnet that is on the port's
 149                network
 150             -  ip: An IP address of the associated subnet to assign to
 151                the new port (optional but generally required for router
 152                interfaces)
 153
 154    -  keypairs:
 155
 156       -  keypair:
 157       -  name: The name of the keypair to be created. If one already
 158          exists, a new one will not be created but simply loaded from
 159          its configured file location (required)
 160       -  public\_filepath: The path to where the generated public key
 161          will be stored if it does not exist (optional but really
 162          required for provisioning purposes)
 163       -  private\_filepath: The path to where the generated private key
 164          will be stored if it does not exist (optional but really
 165          required for provisioning purposes)
 166
 167    -  instances:
 168
 169       -  instance:
 170       -  name: The unique instance name for project. (required)
 171       -  flavor: Must be one of the preconfigured flavors (required)
 172       -  imageName: The name of the image to be used for deployment
 173          (required)
 174       -  keypair\_name: The name of the keypair to attach to instance
 175          (optional but required for NIC configuration and Ansible
 176          provisioning)
 177       -  sudo\_user: The name of a sudo\_user that is attached to the
 178          keypair (optional but required for NIC configuration and
 179          Ansible provisioning)
 180       -  vm\_boot\_timeout: The number of seconds to block waiting for
 181          an instance to deploy and boot (default 900)
 182       -  vm\_delete\_timeout: The number of seconds to block waiting for
 183          an instance to be deleted (default 300)
 184       -  ssh\_connect\_timeout: The number of seconds to block waiting
 185          for an instance to achieve an SSH connection (default 120)
 186       -  ports: A list of port configurations (should contain at least
 187          one)
 188       -  port: Denotes the configuration of a NIC
 189
 190          -  name: The unique port name for project (required)
 191          -  network\_name: The name of the network to which the port is
 192             attached (required)
 193          -  ip\_addrs: Static IP addresses to be added to the port by
 194             subnet (optional)
 195          -  subnet\_name: The name of the subnet
 196          -  ip: The assigned IP address (when null, OpenStack will
 197             assign an IP to the port)
 198          -  admin\_state\_up: T\|F (default True)
 199          -  project\_name: The name of the project who owns the network.
 200             Only administrative users can specify a the project ID other
 201             than their own (optional)
 202          -  mac\_address: The desired MAC for the port (optional)
 203          -  fixed\_ips: A dictionary that allows one to specify only a
 204             subnet ID, OpenStack Networking allocates an available IP
 205             from that subnet to the port. If you specify both a subnet
 206             ID and an IP address, OpenStack Networking tries to allocate
 207             the specified address to the port. (optional)
 208          -  seurity\_groups: A list of security group IDs (optional)
 209          -  allowed\_address\_pairs: A dictionary containing a set of
 210             zero or more allowed address pairs. An address pair contains
 211             an IP address and MAC address. (optional)
 212          -  opt\_value: The extra DHCP option value (optional)
 213          -  opt\_name: The extra DHCP option name (optional)
 214          -  device\_owner: The ID of the entity that uses this port. For
 215             example, a DHCP agent (optional)
 216          -  device\_id: The ID of the device that uses this port. For
 217             example, a virtual server (optional)
 218
 219    -  floating\_ips: list of floating\_ip configurations (optional)
 220
 221       -  floating\_ip:
 222       -  name: Must be unique for VM instance (required)
 223       -  port\_name: The name of the port requiring access to the
 224          external network (required)
 225       -  subnet\_name: The name of the subnet contains the IP address on
 226          the port on which to create the floating IP (optional)
 227       -  router\_name: The name of the router connected to an external
 228          network used to attach the floating IP (required)
 229       -  provisioning: (True\|False) Denotes whether or not this IP can
 230          be used for Ansible provisioning (default True)
 231
 232 -  ansible: Each set of attributes below are contained in a list
 233
 234    -  playbook\_location: Full path or relative to the directory in
 235       which the deployment file resides (required)
 236    -  hosts: A list of hosts to which the playbook will be executed
 237       (required)
 238    -  variables: Should your Ansible scripts require any substitution
 239       values to be applied with Jinga2templates, the values defined here
 240       will be used to for substitution
 241    -  tag name = substitution variable names. For instance, for any file
 242       being pushed to the host being provisioned containing a value such
 243       as {{ foo }}, you must specify a tag name of "foo"
 244
 245       -  vm\_name:
 246       -  type: string\|port\|os\_creds\|vm-attr (note: will need to make
 247          changes to deploy\_venv.py#\_\_get\_variable\_value() for
 248          additional support)
 249       -  when type == string, an tag name "value" must exist and its
 250          value will be used for template substituion
 251       -  when type == port, custom code has been written to extract
 252          certain assigned values to the port:
 253
 254          -  vm\_name: must correspond to a VM's name as configured in
 255             this file
 256          -  port\_name: The name of the port from which to extract the
 257             substitution values (required)
 258          -  port\_value: The port value. Currently only supporting
 259             "mac\_address" and "ip\_address" (only the first)
 260
 261       -  when type == os\_creds, custom code has been written to extract
 262          the file's connection values:
 263
 264          -  username: connection's user
 265          -  password: connection's password
 266          -  auth\_url: connection's URL
 267          -  project\_name: connection's project
 268
 269       -  when type == vm-attr, custom code has been written to extract
 270          the following attributes from the vm:
 271
 272          -  vm\_name: must correspond to a VM's name as configured in
 273             this file
 274          -  value -> floating\_ip: is currently the only vm-attr
 275             supported