docs/how-to-use/VirtEnvDeploy.rst

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