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