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.
   7
   8     Edit <path to repo>/examples/inst-w-volume/deploy-env.yaml with your OpenStack
   9     credentials and authorization URL
  10
  11    -  openstack: the top level tag that denotes configuration for the OpenStack components
  12
  13    -  connection: - contains the credentials and endpoints required to
  14       connect with OpenStack
  15    -  username: - the project's user (required)
  16    -  password: - the tentant's user password (required)
  17    -  auth\_url: - the URL to the OpenStack APIs (required)
  18    -  project\_name: - the name of the OpenStack project for the user
  19       (required)
  20    -  http\_proxy: - the {{ host }}:{{ port }} of the proxy server (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 -t ./inst-w-volume/deploy-vm-with-volume.yaml -e ./inst-w-volume/deploy-env.yaml -d
  33
  34 #. Clean the deployment.
  35
  36     ::
  37
  38       python launch.py -t ./complex-network/deploy-complex-network.yaml -e ./inst-w-volume/deploy-env.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    -  connections: the different connections/credentials to be used by the
  50       launcher application
  51
  52        -  connection: the credentials and endpoints required to connect to an
  53           OpenStack project/tenant
  54
  55           -  name: the name of the credentials for use when creating objects (required)
  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           -  identity\_api\_version: the Keystone client version to use (default = 2)
  62           -  image\_api\_version: the Glance client version to use (default = 2)
  63           -  network\_api\_version: the Neutron client version to use (default = 2)
  64           -  compute\_api\_version: the Nova client version to use (default = 2)
  65           -  heat\_api\_version: the Heat client version to use (default = 1)
  66           -  volume\_api\_version: the Cinder client version to use (default = 2)
  67           -  user\_domain\_id: the user domain ID to use (default = 'default')
  68           -  user\_domain\_name: the user domain name to use (default = 'Default')
  69           -  project\_domain\_id: the project domain ID to use (default = 'default')
  70           -  project\_domain\_name: the project domain name to use (default = 'Default')
  71           -  interface: Used to specify the endpoint type for keystone (default = 'public')
  72           -  cacert: True for https or the certification file location (default = False)
  73           -  region\_name: the region (default = None)
  74           -  proxy\_settings: for accessing APIs hidden behind an HTTP proxy
  75
  76               - host: hostname or IP of HTTP proxy host (required)
  77               - port: port number of the HTTP proxy server (required)
  78               - http\_host: hostname or IP of HTTPS proxy host (default = host)
  79               - port: port number of the HTTPS proxy server (default = port)
  80               - ssh\_proxy\_cmd: the OpenSSH command used to access the SSH port
  81                 of a VM (optional)
  82
  83    -  projects: the projects/tenants to create
  84
  85        -  project: a project/tenant to create (admin user credentials required)
  86
  87           -  os\_creds\_name: the connection name (default = 'default'
  88              required or use "os\_user" below instead)
  89           -  name: the project's name (required)
  90           -  domain or domain_name: the project's domain name (default = 'Default')
  91           -  description: the description (optional)
  92           -  users: a list of users to associate to the project (optional)
  93           -  enabled: when True the project will be enabled on creation (default = True)
  94
  95    -  users: the users to create
  96
  97        -  user: a user to create (admin user credentials required)
  98
  99           -  os\_creds\_name: the connection name (required)
 100           -  name: the username (required)
 101           -  password: the user's password (required)
 102           -  project\_name: the user's primary project name (optional)
 103           -  domain\_name: the user's domain name (default = 'Default')
 104           -  email: the user's email address (optional)
 105           -  roles: dict where key is the role's name and value is the name
 106              of the project to associate with the role (optional)
 107
 108    -  flavors: the flavors to create
 109
 110        -  flavor: a flavor to create (admin user credentials required)
 111
 112           -  os\_creds\_name: the connection name (default = 'default'
 113              required or use "os\_user" below instead)
 114           -  name: the name (required)
 115           -  flavor\_id: the string ID (default 'auto')
 116           -  ram: the required RAM in MB (required)
 117           -  disk: the size of the root disk in GB (required)
 118           -  vcpus: the number of virtual CPUs (required)
 119           -  ephemeral: the size of the ephemeral disk in GB (default 0)
 120           -  swap: the size of the dedicated swap disk in GB (default 0)
 121           -  rxtx\_factor: the receive/transmit factor to be set on ports if
 122              backend supports QoS extension (default 1.0)
 123           -  is\_public: denotes whether or not the flavor is public (default = True)
 124           -  metadata: freeform dict() for special metadata (optional)
 125
 126    -  qos_specs: the QoS Specs to create
 127
 128        -  qos_spec: a QoS Spec to create (admin user credentials required)
 129
 130           -  os\_creds\_name: the connection name (default = 'default'
 131              required or use "os\_user" below instead)
 132           -  name: the name (required)
 133           -  consumer: enumerations: 'front-end', 'back-end', 'both' (required)
 134           -  specs: dict of custom values (optional)
 135
 136    -  volume_types: the Volume Type to create
 137
 138        -  volume_type: a Volume Type to create (admin user credentials required)
 139
 140           -  os\_creds\_name: the connection name (default = 'default'
 141              required or use "os\_user" below instead)
 142           -  name: the name (required)
 143           -  description: the description (optional)
 144           -  qos_spec_name: the name of the associate QoS Spec (optional)
 145           -  public: visibility (default - False)
 146           -  encryption: the encryption settings (optional)
 147
 148              -  name: the name (required)
 149              -  provider_class: the provider class (required i.e. LuksEncryptor)
 150              -  control_location: enumerations: 'front-end', 'back-end' (required)
 151              -  cipher: the encryption algorithm/mode to use (optional)
 152              -  key_size: the size of the encryption key, in bits (optional)
 153
 154    -  volumes: the Volume to create
 155
 156        -  volume: a Volume to create
 157
 158           -  os\_creds\_name: the connection name (default = 'default'
 159              required or use "os\_user" below instead)
 160           -  os\_user: the connection from a new user defined in template
 161              (required or use "os\_creds\_name" above
 162
 163               - name: the user's name (required)
 164               - project\_name: the project name to use
 165
 166           -  name: the name (required)
 167           -  description: the description (optional)
 168           -  size: the volume size in GB (default = 1)
 169           -  image_name: the image name to leverage (optional)
 170           -  type_name: the volume type name to associate (optional)
 171           -  availability_zone: the zone name on which to deploy (optional)
 172           -  multi_attach: when true, volume can be attached to more than one VM
 173              (default = False)
 174
 175    -  images: describes each image to create
 176
 177        -  image:
 178
 179           -  os\_creds\_name: the connection name (default = 'default'
 180              required or use "os\_user" below instead)
 181           -  os\_user: the connection from a new user defined in template
 182              (required or use "os\_creds\_name" above
 183
 184               - name: the user's name (required)
 185               - project\_name: the project name to use
 186
 187           -  name: The unique image name. If the name already exists for
 188              your project, a new one will not be created (required)
 189           -  image\_user: the image's default sudo user (required)
 190           -  format or img\_format: the image format type (required i.e. qcow2)
 191           -  url or download\_url: The HTTP download location of the image file
 192              (required when "image_file" below has not been configured)
 193           -  image\_file: the image file location (required when "url" has not
 194              been configured)
 195           -  kernel\_image\_settings: the settings for a kernel image (optional)
 196           -  ramdisk\_image\_settings: the settings for a kernel image (optional)
 197           -  public: publically visibile when True (default = True)
 198
 199    -  networks:
 200        -  network:
 201
 202           -  os\_creds\_name: the connection name (default = 'default'
 203              required or use "os\_user" below instead)
 204           -  os\_user: the connection from a new user defined in template
 205              (required or use "os\_creds\_name" above
 206
 207               - name: the user's name (required)
 208               - project\_name: the project name to use
 209
 210           -  name: The name of the network to be created. If one already
 211              exists, a new one will not be created (required)
 212           -  admin\_state\_up: T\|F (default True)
 213           -  shared: (optional)
 214           -  project\_name: Name of the project who owns the network. Note:
 215              only administrative users can specify projects other than their
 216              own (optional)
 217           -  external: T\|F whether or not network is external (default False)
 218           -  network\_type: The type of network to create (optional)
 219           -  physical\_network: the name of the physical network
 220              (required when network_type is 'flat')
 221           -  segmentation\_id: the id of the segmentation
 222              (required when network_type is 'vlan')
 223           -  subnets:
 224               -  subnet:
 225
 226                  -  name: The name of the network to be created. If one already
 227                     exists, a new one will not be created. Note: although
 228                     OpenStack allows for multiple subnets to be applied to any
 229                     given network, we have not included support as our current
 230                     use cases does not utilize this functionality (required)
 231                  -  cidr: The subnet mask value (required)
 232                  -  dns\_nameservers: A list of IP values used for DNS
 233                     resolution (default: 8.8.8.8)
 234                  -  ip\_version: 4\|6 (default: 4)
 235                  -  project\_name: Name of the project who owns the network.
 236                     Note: only administrative users can specify projects other
 237                     than their own (optional)
 238                  -  start: The start address for allocation\_pools (optional)
 239                  -  end: The ending address for allocation\_pools (optional)
 240                  -  gateway\_ip: The IP address to the gateway (optional)
 241                  -  enable\_dhcp: T\|F (optional)
 242                  -  dns\_nameservers: List of DNS server IPs (default = ['8.8.8.8']
 243                  -  host\_routes: A list of host route dictionaries (optional)
 244                     i.e.:
 245                     ``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"    }    ]``
 246                  -  destination: The destination for a static route (optional)
 247                  -  nexthop: The next hop for the destination (optional)
 248                  -  ipv6\_ra\_mode: Valid values: "dhcpv6-stateful",
 249                     "dhcpv6-stateless", and "slaac" (optional)
 250                  -  ipv6\_address\_mode: Valid values: "dhcpv6-stateful",
 251                     "dhcpv6-stateless", and "slaac" (optional)
 252
 253    -  security_groups:
 254
 255       -  security_group:
 256
 257           -  os\_creds\_name: the connection name (default = 'default'
 258              required or use "os\_user" below instead)
 259           -  os\_user: the connection from a new user defined in template
 260              (required or use "os\_creds\_name" above
 261
 262               - name: the user's name (required)
 263               - project\_name: the project name to use
 264
 265           -  name: The name of the security group to be created (required)
 266           -  description: The security group's description (optional)
 267           -  project\_name: Name of the project who owns the security group (optional)
 268           -  rule\_settings: List of rules to place onto security group (optional)
 269
 270               -  description: the rule's description (optional)
 271               -  protocol: rule's protcol ('icmp' or 'tcp' or 'udp' or 'null')
 272               -  ethertype: rule's ethertype ('4' or '6')
 273               -  port\_range\_min: The minimum port number in the range that is
 274                  matched by the security group rule. When the protocol is 'tcp'
 275                  or 'udp', this value must be <= 'port_range_max' (optional)
 276               -  port\_range\_max: The maximum port number in the range that is
 277                  matched by the security group rule. When the protocol is 'tcp'
 278                  or 'udp', this value must be <= 'port_range_max' (optional)
 279               -  remote\_ip\_prefix: The remote IP prefix to associate with this
 280                  metering rule packet (optional)
 281
 282    -  routers:
 283
 284       -  router:
 285
 286           -  os\_creds\_name: the connection name (default = 'default'
 287              required or use "os\_user" below instead)
 288           -  os\_user: the connection from a new user defined in template
 289              (required or use "os\_creds\_name" above
 290
 291               - name: the user's name (required)
 292               - project\_name: the project name to use
 293
 294           -  name: The name of the router to be created (required)
 295           -  project\_name: Name of the project who owns the network (optional)
 296           -  external\_gateway: Name of the external network to which to route
 297              (optional)
 298           -  admin\_state\_up: T\|F (default True)
 299           -  external\_fixed\_ids: Dictionary containing the IP address
 300              parameters (optional)
 301           -  internal\_subnets: List of subnet names to which to connect this
 302              router (optional)
 303
 304              -  port_settings (Leverages the same class/structure as port objects on
 305                 VM instances. See port definition below for a
 306                 full accounting of the port attributes. The ones listed
 307                 below are generally used for routers)
 308
 309                 -  name: The name given to the new port (required and must be
 310                    unique for project)
 311                 -  network\_name: The name of the network on which to create
 312                    the port (optional)
 313                 -  admin\_state\_up: T\|F (default True)
 314                 -  project\_name: Name of the project who owns the network (optional)
 315                 -  mac\_address: The port's MAC address (optional)
 316                 -  ip\_addrs: A list of k/v pairs (optional)
 317                 -  security\_groups: a list of names of the the security groups
 318                    to apply to the port
 319                 -  opt\_value: The extra DHCP option value (optional)
 320                 -  opt\_name: The extra DHCP option name (optional)
 321
 322    -  keypairs:
 323
 324       -  keypair:
 325
 326           -  os\_creds\_name: the connection name (default = 'default'
 327              required or use "os\_user" below instead)
 328           -  os\_user: the connection from a new user defined in template
 329              (required or use "os\_creds\_name" above
 330
 331               - name: the user's name (required)
 332               - project\_name: the project name to use
 333
 334           -  name: The name of the keypair to be created. If one already
 335              exists, a new one will not be created but simply loaded from
 336              its configured file location (required)
 337           -  public\_filepath: The path to where the generated public key
 338              will be stored if it does not exist (optional but really
 339              required for provisioning purposes)
 340           -  private\_filepath: The path to where the generated private key
 341              will be stored if it does not exist (optional but really
 342              required for provisioning purposes)
 343
 344    -  instances:
 345
 346       -  instance:
 347
 348           -  os\_creds\_name: the connection name (default = 'default'
 349              required or use "os\_user" below instead)
 350           -  os\_user: the connection from a new user defined in template
 351              (required or use "os\_creds\_name" above
 352
 353               - name: the user's name (required)
 354               - project\_name: the project name to use
 355
 356           -  name: The unique instance name for project. (required)
 357           -  flavor: Must be one of the preconfigured flavors (required)
 358           -  imageName: The name of the image to be used for deployment
 359              (required)
 360           -  keypair\_name: The name of the keypair to attach to instance
 361              (optional but required for NIC configuration and Ansible
 362              provisioning)
 363           -  sudo\_user: The name of a sudo\_user that is attached to the
 364              keypair (optional but required for NIC configuration and
 365              Ansible provisioning)
 366           -  vm\_boot\_timeout: The number of seconds to block waiting for
 367              an instance to deploy and boot (default 900)
 368           -  vm\_delete\_timeout: The number of seconds to block waiting for
 369              an instance to be deleted (default 300)
 370           -  ssh\_connect\_timeout: The number of seconds to block waiting
 371              for an instance to achieve an SSH connection (default 120)
 372           -  ports: A list of port configurations (should contain at least
 373              one)
 374           -  port: Denotes the configuration of a NIC
 375
 376              -  name: The unique port name for project (required)
 377              -  network\_name: The name of the network to which the port is
 378                 attached (required)
 379              -  ip\_addrs: Static IP addresses to be added to the port by
 380                 subnet (optional)
 381              -  subnet\_name: The name of the subnet
 382              -  ip: The assigned IP address (when null, OpenStack will
 383                 assign an IP to the port)
 384              -  admin\_state\_up: T\|F (default True)
 385              -  project\_name: The name of the project who owns the network.
 386                 Only administrative users can specify a the project ID other
 387                 than their own (optional)
 388              -  mac\_address: The desired MAC for the port (optional)
 389              -  fixed\_ips: A dictionary that allows one to specify only a
 390                 subnet ID, OpenStack Networking allocates an available IP
 391                 from that subnet to the port. If you specify both a subnet
 392                 ID and an IP address, OpenStack Networking tries to allocate
 393                 the specified address to the port. (optional)
 394              -  seurity\_groups: A list of security group IDs (optional)
 395              -  allowed\_address\_pairs: A dictionary containing a set of
 396                 zero or more allowed address pairs. An address pair contains
 397                 an IP address and MAC address. (optional)
 398              -  opt\_value: The extra DHCP option value (optional)
 399              -  opt\_name: The extra DHCP option name (optional)
 400              -  device\_owner: The ID of the entity that uses this port. For
 401                 example, a DHCP agent (optional)
 402              -  device\_id: The ID of the device that uses this port. For
 403                 example, a virtual server (optional)
 404
 405        -  floating\_ips: list of floating\_ip configurations (optional)
 406
 407           -  floating\_ip:
 408           -  name: Must be unique for VM instance (required)
 409           -  port\_name: The name of the port requiring access to the
 410              external network (required)
 411           -  subnet\_name: The name of the subnet contains the IP address on
 412              the port on which to create the floating IP (optional)
 413           -  router\_name: The name of the router connected to an external
 414              network used to attach the floating IP (required)
 415           -  provisioning: (True\|False) Denotes whether or not this IP can
 416              be used for Ansible provisioning (default True)
 417
 418 -  ansible: Each set of attributes below are contained in a list
 419
 420    -  playbook\_location: Full path or relative to the directory in
 421       which the deployment file resides (required)
 422    -  hosts: A list of hosts to which the playbook will be executed
 423       (required)
 424    -  variables: Should your Ansible scripts require any substitution
 425       values to be applied with Jinga2templates, the values defined here
 426       will be used to for substitution
 427    -  tag name = substitution variable names. For instance, for any file
 428       being pushed to the host being provisioned containing a value such
 429       as {{ foo }}, you must specify a tag name of "foo"
 430
 431       -  vm\_name:
 432       -  type: string\|port\|os\_creds\|vm-attr (note: will need to make
 433          changes to deploy\_venv.py#\_\_get\_variable\_value() for
 434          additional support)
 435       -  when type == string, an tag name "value" must exist and its
 436          value will be used for template substituion
 437       -  when type == port, custom code has been written to extract
 438          certain assigned values to the port:
 439
 440          -  vm\_name: must correspond to a VM's name as configured in
 441             this file
 442          -  port\_name: The name of the port from which to extract the
 443             substitution values (required)
 444          -  port\_value: The port value. Currently only supporting
 445             "mac\_address" and "ip\_address" (only the first)
 446
 447       -  when type == os\_creds, custom code has been written to extract
 448          the file's connection values:
 449
 450          -  username: connection's user
 451          -  password: connection's password
 452          -  auth\_url: connection's URL
 453          -  project\_name: connection's project
 454
 455       -  when type == vm-attr, custom code has been written to extract
 456          the following attributes from the vm:
 457
 458          -  vm\_name: must correspond to a VM's name as configured in
 459             this file
 460          -  value -> floating\_ip: is currently the only vm-attr
 461             supported