Try an example
==============

Use launcher.py to deploy and clean up example environments.  These examples are described in YAML files.

#. Add your OpenStack connection information.

    Edit <path to repo>/examples/inst-w-volume/deploy-env.yaml with your OpenStack
    credentials and authorization URL

   -  openstack: the top level tag that denotes configuration for the OpenStack components

   -  connection: - contains the credentials and endpoints required to
      connect with OpenStack
   -  username: - the project's user (required)
   -  password: - the tentant's user password (required)
   -  auth\_url: - the URL to the OpenStack APIs (required)
   -  project\_name: - the name of the OpenStack project for the user
      (required)
   -  http\_proxy: - the {{ host }}:{{ port }} of the proxy server (optional)

#. Go to the examples directory.

    ::

      cd <snaps repo>/examples/

#. Deploy the launcher.

    ::

      python launch.py -t ./inst-w-volume/deploy-vm-with-volume.yaml -e ./inst-w-volume/deploy-env.yaml -d

#. Clean the deployment.

    ::

      python launch.py -t ./complex-network/deploy-complex-network.yaml -e ./inst-w-volume/deploy-env.yaml -c

#. Customize the deployment by changing the yaml file.

    The configuration file used to deploy and provision a virtual environment has been designed to describe the required
    images, networks, SSH public and private keys, associated VMs, as well as any required post deployment provisioning
    tasks.

-  openstack: the top level tag that denotes configuration for the
   OpenStack components

   -  connections: the different connections/credentials to be used by the
      launcher application

       -  connection: the credentials and endpoints required to connect to an
          OpenStack project/tenant

          -  name: the name of the credentials for use when creating objects (required)
          -  username: the project's user (required)
          -  password: the tentant's user password (required)
          -  auth\_url: the URL to the OpenStack APIs (required)
          -  project\_name: the name of the OpenStack project for the user
             (required)
          -  identity\_api\_version: the Keystone client version to use (default = 2)
          -  image\_api\_version: the Glance client version to use (default = 2)
          -  network\_api\_version: the Neutron client version to use (default = 2)
          -  compute\_api\_version: the Nova client version to use (default = 2)
          -  heat\_api\_version: the Heat client version to use (default = 1)
          -  volume\_api\_version: the Cinder client version to use (default = 2)
          -  user\_domain\_id: the user domain ID to use (default = 'default')
          -  user\_domain\_name: the user domain name to use (default = 'Default')
          -  project\_domain\_id: the project domain ID to use (default = 'default')
          -  project\_domain\_name: the project domain name to use (default = 'Default')
          -  interface: Used to specify the endpoint type for keystone (default = 'public')
          -  cacert: True for https or the certification file location (default = False)
          -  region\_name: the region (default = None)
          -  proxy\_settings: for accessing APIs hidden behind an HTTP proxy

              - host: hostname or IP of HTTP proxy host (required)
              - port: port number of the HTTP proxy server (required)
              - http\_host: hostname or IP of HTTPS proxy host (default = host)
              - port: port number of the HTTPS proxy server (default = port)
              - ssh\_proxy\_cmd: the OpenSSH command used to access the SSH port
                of a VM (optional)

   -  projects: the projects/tenants to create

       -  project: a project/tenant to create (admin user credentials required)

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  name: the project's name (required)
          -  domain or domain_name: the project's domain name (default = 'Default')
          -  description: the description (optional)
          -  users: a list of users to associate to the project (optional)
          -  enabled: when True the project will be enabled on creation (default = True)

   -  users: the users to create

       -  user: a user to create (admin user credentials required)

          -  os\_creds\_name: the connection name (required)
          -  name: the username (required)
          -  password: the user's password (required)
          -  project\_name: the user's primary project name (optional)
          -  domain\_name: the user's domain name (default = 'Default')
          -  email: the user's email address (optional)
          -  roles: dict where key is the role's name and value is the name
             of the project to associate with the role (optional)

   -  flavors: the flavors to create

       -  flavor: a flavor to create (admin user credentials required)

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  name: the name (required)
          -  flavor\_id: the string ID (default 'auto')
          -  ram: the required RAM in MB (required)
          -  disk: the size of the root disk in GB (required)
          -  vcpus: the number of virtual CPUs (required)
          -  ephemeral: the size of the ephemeral disk in GB (default 0)
          -  swap: the size of the dedicated swap disk in GB (default 0)
          -  rxtx\_factor: the receive/transmit factor to be set on ports if
             backend supports QoS extension (default 1.0)
          -  is\_public: denotes whether or not the flavor is public (default = True)
          -  metadata: freeform dict() for special metadata (optional)

   -  qos_specs: the QoS Specs to create

       -  qos_spec: a QoS Spec to create (admin user credentials required)

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  name: the name (required)
          -  consumer: enumerations: 'front-end', 'back-end', 'both' (required)
          -  specs: dict of custom values (optional)

   -  volume_types: the Volume Type to create

       -  volume_type: a Volume Type to create (admin user credentials required)

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  name: the name (required)
          -  description: the description (optional)
          -  qos_spec_name: the name of the associate QoS Spec (optional)
          -  public: visibility (default - False)
          -  encryption: the encryption settings (optional)

             -  name: the name (required)
             -  provider_class: the provider class (required i.e. LuksEncryptor)
             -  control_location: enumerations: 'front-end', 'back-end' (required)
             -  cipher: the encryption algorithm/mode to use (optional)
             -  key_size: the size of the encryption key, in bits (optional)

   -  volumes: the Volume to create

       -  volume: a Volume to create

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: the name (required)
          -  description: the description (optional)
          -  size: the volume size in GB (default = 1)
          -  image_name: the image name to leverage (optional)
          -  type_name: the volume type name to associate (optional)
          -  availability_zone: the zone name on which to deploy (optional)
          -  multi_attach: when true, volume can be attached to more than one VM
             (default = False)

   -  images: describes each image to create

       -  image:

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: The unique image name. If the name already exists for
             your project, a new one will not be created (required)
          -  image\_user: the image's default sudo user (required)
          -  format or img\_format: the image format type (required i.e. qcow2)
          -  url or download\_url: The HTTP download location of the image file
             (required when "image_file" below has not been configured)
          -  image\_file: the image file location (required when "url" has not
             been configured)
          -  kernel\_image\_settings: the settings for a kernel image (optional)
          -  ramdisk\_image\_settings: the settings for a kernel image (optional)
          -  public: publically visibile when True (default = True)

   -  networks:
       -  network:

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: The name of the network to be created. If one already
             exists, a new one will not be created (required)
          -  admin\_state\_up: T\|F (default True)
          -  shared: (optional)
          -  project\_name: Name of the project who owns the network. Note:
             only administrative users can specify projects other than their
             own (optional)
          -  external: T\|F whether or not network is external (default False)
          -  network\_type: The type of network to create (optional)
          -  physical\_network: the name of the physical network
             (required when network_type is 'flat')
          -  segmentation\_id: the id of the segmentation
             (required when network_type is 'vlan')
          -  subnets:
              -  subnet:

                 -  name: The name of the network to be created. If one already
                    exists, a new one will not be created. Note: although
                    OpenStack allows for multiple subnets to be applied to any
                    given network, we have not included support as our current
                    use cases does not utilize this functionality (required)
                 -  cidr: The subnet mask value (required)
                 -  dns\_nameservers: A list of IP values used for DNS
                    resolution (default: 8.8.8.8)
                 -  ip\_version: 4\|6 (default: 4)
                 -  project\_name: Name of the project who owns the network.
                    Note: only administrative users can specify projects other
                    than their own (optional)
                 -  start: The start address for allocation\_pools (optional)
                 -  end: The ending address for allocation\_pools (optional)
                 -  gateway\_ip: The IP address to the gateway (optional)
                 -  enable\_dhcp: T\|F (optional)
                 -  dns\_nameservers: List of DNS server IPs (default = ['8.8.8.8']
                 -  host\_routes: A list of host route dictionaries (optional)
                    i.e.:
                    ``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"    }    ]``
                 -  destination: The destination for a static route (optional)
                 -  nexthop: The next hop for the destination (optional)
                 -  ipv6\_ra\_mode: Valid values: "dhcpv6-stateful",
                    "dhcpv6-stateless", and "slaac" (optional)
                 -  ipv6\_address\_mode: Valid values: "dhcpv6-stateful",
                    "dhcpv6-stateless", and "slaac" (optional)

   -  security_groups:

      -  security_group:

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: The name of the security group to be created (required)
          -  description: The security group's description (optional)
          -  project\_name: Name of the project who owns the security group (optional)
          -  rule\_settings: List of rules to place onto security group (optional)

              -  description: the rule's description (optional)
              -  protocol: rule's protcol ('icmp' or 'tcp' or 'udp' or 'null')
              -  ethertype: rule's ethertype ('4' or '6')
              -  port\_range\_min: The minimum port number in the range that is
                 matched by the security group rule. When the protocol is 'tcp'
                 or 'udp', this value must be <= 'port_range_max' (optional)
              -  port\_range\_max: The maximum port number in the range that is
                 matched by the security group rule. When the protocol is 'tcp'
                 or 'udp', this value must be <= 'port_range_max' (optional)
              -  remote\_ip\_prefix: The remote IP prefix to associate with this
                 metering rule packet (optional)

   -  routers:

      -  router:

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: The name of the router to be created (required)
          -  project\_name: Name of the project who owns the network (optional)
          -  external\_gateway: Name of the external network to which to route
             (optional)
          -  admin\_state\_up: T\|F (default True)
          -  external\_fixed\_ids: Dictionary containing the IP address
             parameters (optional)
          -  internal\_subnets: List of subnet names to which to connect this
             router (optional)

             -  port_settings (Leverages the same class/structure as port objects on
                VM instances. See port definition below for a
                full accounting of the port attributes. The ones listed
                below are generally used for routers)

                -  name: The name given to the new port (required and must be
                   unique for project)
                -  network\_name: The name of the network on which to create
                   the port (optional)
                -  admin\_state\_up: T\|F (default True)
                -  project\_name: Name of the project who owns the network (optional)
                -  mac\_address: The port's MAC address (optional)
                -  ip\_addrs: A list of k/v pairs (optional)
                -  security\_groups: a list of names of the the security groups
                   to apply to the port
                -  opt\_value: The extra DHCP option value (optional)
                -  opt\_name: The extra DHCP option name (optional)

   -  keypairs:

      -  keypair:

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: The name of the keypair to be created. If one already
             exists, a new one will not be created but simply loaded from
             its configured file location (required)
          -  public\_filepath: The path to where the generated public key
             will be stored if it does not exist (optional but really
             required for provisioning purposes)
          -  private\_filepath: The path to where the generated private key
             will be stored if it does not exist (optional but really
             required for provisioning purposes)

   -  instances:

      -  instance:

          -  os\_creds\_name: the connection name (default = 'default'
             required or use "os\_user" below instead)
          -  os\_user: the connection from a new user defined in template
             (required or use "os\_creds\_name" above

              - name: the user's name (required)
              - project\_name: the project name to use

          -  name: The unique instance name for project. (required)
          -  flavor: Must be one of the preconfigured flavors (required)
          -  imageName: The name of the image to be used for deployment
             (required)
          -  keypair\_name: The name of the keypair to attach to instance
             (optional but required for NIC configuration and Ansible
             provisioning)
          -  sudo\_user: The name of a sudo\_user that is attached to the
             keypair (optional but required for NIC configuration and
             Ansible provisioning)
          -  vm\_boot\_timeout: The number of seconds to block waiting for
             an instance to deploy and boot (default 900)
          -  vm\_delete\_timeout: The number of seconds to block waiting for
             an instance to be deleted (default 300)
          -  ssh\_connect\_timeout: The number of seconds to block waiting
             for an instance to achieve an SSH connection (default 120)
          -  ports: A list of port configurations (should contain at least
             one)
          -  port: Denotes the configuration of a NIC

             -  name: The unique port name for project (required)
             -  network\_name: The name of the network to which the port is
                attached (required)
             -  ip\_addrs: Static IP addresses to be added to the port by
                subnet (optional)
             -  subnet\_name: The name of the subnet
             -  ip: The assigned IP address (when null, OpenStack will
                assign an IP to the port)
             -  admin\_state\_up: T\|F (default True)
             -  project\_name: The name of the project who owns the network.
                Only administrative users can specify a the project ID other
                than their own (optional)
             -  mac\_address: The desired MAC for the port (optional)
             -  fixed\_ips: A dictionary that allows one to specify only a
                subnet ID, OpenStack Networking allocates an available IP
                from that subnet to the port. If you specify both a subnet
                ID and an IP address, OpenStack Networking tries to allocate
                the specified address to the port. (optional)
             -  seurity\_groups: A list of security group IDs (optional)
             -  allowed\_address\_pairs: A dictionary containing a set of
                zero or more allowed address pairs. An address pair contains
                an IP address and MAC address. (optional)
             -  opt\_value: The extra DHCP option value (optional)
             -  opt\_name: The extra DHCP option name (optional)
             -  device\_owner: The ID of the entity that uses this port. For
                example, a DHCP agent (optional)
             -  device\_id: The ID of the device that uses this port. For
                example, a virtual server (optional)

       -  floating\_ips: list of floating\_ip configurations (optional)

          -  floating\_ip:
          -  name: Must be unique for VM instance (required)
          -  port\_name: The name of the port requiring access to the
             external network (required)
          -  subnet\_name: The name of the subnet contains the IP address on
             the port on which to create the floating IP (optional)
          -  router\_name: The name of the router connected to an external
             network used to attach the floating IP (required)
          -  provisioning: (True\|False) Denotes whether or not this IP can
             be used for Ansible provisioning (default True)

-  ansible: Each set of attributes below are contained in a list

   -  playbook\_location: Full path or relative to the directory in
      which the deployment file resides (required)
   -  hosts: A list of hosts to which the playbook will be executed
      (required)
   -  variables: Should your Ansible scripts require any substitution
      values to be applied with Jinga2templates, the values defined here
      will be used to for substitution
   -  tag name = substitution variable names. For instance, for any file
      being pushed to the host being provisioned containing a value such
      as {{ foo }}, you must specify a tag name of "foo"

      -  vm\_name:
      -  type: string\|port\|os\_creds\|vm-attr (note: will need to make
         changes to deploy\_venv.py#\_\_get\_variable\_value() for
         additional support)
      -  when type == string, an tag name "value" must exist and its
         value will be used for template substituion
      -  when type == port, custom code has been written to extract
         certain assigned values to the port:

         -  vm\_name: must correspond to a VM's name as configured in
            this file
         -  port\_name: The name of the port from which to extract the
            substitution values (required)
         -  port\_value: The port value. Currently only supporting
            "mac\_address" and "ip\_address" (only the first)

      -  when type == os\_creds, custom code has been written to extract
         the file's connection values:

         -  username: connection's user
         -  password: connection's password
         -  auth\_url: connection's URL
         -  project\_name: connection's project

      -  when type == vm-attr, custom code has been written to extract
         the following attributes from the vm:

         -  vm\_name: must correspond to a VM's name as configured in
            this file
         -  value -> floating\_ip: is currently the only vm-attr
            supported