docs/how-to-use/LibraryUsage.rst

   1 **********************
   2 SNAPS-OO Library Usage
   3 **********************
   4
   5 The pattern used within the SNAPS-OO library for creating OpenStack
   6 instances have been made as consistent as possible amongst the different
   7 instance types. Each consists of a constructor that takes in a
   8 credentials object and generally takes in a single "settings"
   9 (configuration) object. The only exception to this rule is with the
  10 OpenStackVMInstance (creates an OpenStack Server) where it takes in the
  11 additional settings used for the associated image and SSH key-pairs
  12 credentials as those objects contain additional attributes required of
  13 SNAPS, primarily when one needs to obtain remote access. After
  14 instantiation, the create() method must be called to initiate all of the
  15 necessary remote API calls to OpenStack required for proper instance
  16 creation.
  17
  18 SNAPS Credentials
  19 =================
  20
  21 As communicating with OpenStack is performed via secure remote RESTful
  22 API calls, any function or method performing any type of query or CRUD
  23 operation must know how to connect to the NFVI. The class ***OSCreds***
  24 defined in *snaps.openstack.os\_credentials.py* contains everything
  25 required to connect to any Keystone v2.0 or v3 authorization server. The
  26 attributes are listed below:
  27
  28 -  username
  29 -  password
  30 -  auth\_url
  31 -  project\_name (aka. tenant\_name)
  32 -  identity\_api\_version (for obtaining Keystone authorization token.
  33    Versions 2.0 & v3 only validated.)
  34 -  image\_api\_version (Glance version 1 & 2 only validated)
  35 -  network\_api\_version (Neutron version 2 currently only validated)
  36 -  compute\_api\_version (Nova version 2 currently only validated)
  37 -  heat\_api\_version (Heat version 1 currently only validated)
  38 -  user\_domain\_id (default='default')
  39 -  user\_domain\_name (default='default')
  40 -  project\_domain\_id (default='default')
  41 -  project\_domain\_name (default='default')
  42 -  interface (default='admin', used to specify the endpoint type for keystone: public, admin, internal)
  43 -  cacert (default=False, expected values T|F to denote server certificate verification, else value contains the path to an HTTPS certificate)
  44 -  region_name (The region name default=None)
  45 -  proxy\_settings
  46
  47    -  host (the HTTP proxy host)
  48    -  port (the HTTP proxy port)
  49    -  https\_host (the HTTPS proxy host, default value of host)
  50    -  https\_port (the HTTPS proxy port, default value of port)
  51    -  ssh\_proxy\_cmd (same as the value placed into ssh -o
  52       ProxyCommand='<this config value>')
  53
  54 Create OS Credentials Object
  55 ----------------------------
  56
  57 .. code:: python
  58
  59     from snaps.openstack.os_credentials import OSCreds
  60     os_creds=OSCreds(username='admin', password='admin',
  61                      auth_url='http://localhost:5000/v3', project_name='admin',
  62                      identity_api_version=3)
  63
  64 SNAPS Object Creators
  65 =====================
  66
  67 Each creator minimally requires an OSCreds object for connecting to the
  68 NFVI, associated \*Settings object for instance configuration, create()
  69 method to make the necessary remote API calls and create all of the
  70 necessary OpenStack instances required, and clean() method that is
  71 responsible for deleting all associated OpenStack instances. Please see
  72 the class diagram `here </display/SNAP/SNAPS-OO+Classes>`__. Below is a
  73 textual representation of the requirements of each creator classes with
  74 their associated setting classes and a sample code snippet on how to use
  75 the code.
  76
  77 Create User
  78 -----------
  79 -  User - snaps.openstack.create\_user.OpenStackUser
  80
  81    -  snaps.openstack.create\_user.UserSettings
  82
  83       -  name - the username (required)
  84       -  password - the user's password (required)
  85       -  project\_name - the name of the project to associated to this
  86          user (optional)
  87       -  domain\_name - the user's domain (default='default')
  88       -  email - the user's email address (optional)
  89       -  enabled - flag to determine whether or not the user should be
  90          enabled (default=True)
  91
  92 .. code:: python
  93
  94     from snaps.openstack.create_user import UserSettings, OpenStackUser
  95     user_settings = UserSettings(name='username', password='password')
  96     user_creator = OpenStackUser(os_creds, user_settings)
  97     user_creator.create()
  98
  99     # Retrieve OS creds for new user for creating other OpenStack instance
 100     user_creds = user_creator.get_os_creds(os_creds.project_name)
 101
 102     # Perform logic
 103     ...
 104
 105     # Cleanup
 106     user_creator.clean()
 107
 108 Create Project
 109 --------------
 110 -  Project - snaps.openstack.create\_project.OpenStackProject
 111
 112    -  snaps.openstack.create\_project.ProjectSettings
 113
 114       -  name - the project name (required)
 115       -  domain - the project's domain (default='default')
 116       -  description - the project's description (optional)
 117       -  enables - flag to determine whether or not the project should
 118          be enabled (default=True)
 119
 120
 121 .. code:: python
 122
 123     from snaps.openstack.create_project import ProjectSettings, OpenStackProject
 124     project_settings = ProjectSettings(name='username', password='password')
 125     project_creator = OpenStackProject(os_creds, project_settings)
 126     project_creator.create()
 127
 128     # Perform logic
 129     ...
 130
 131     # Cleanup
 132     project_creator.clean()
 133
 134 Create Flavor
 135 -------------
 136 -  Flavor - snaps.openstack.create\_flavor.OpenStackFlavor
 137
 138    -  snaps.openstack.create\_flavor.FlavorSettings
 139
 140       -  name - the flavor name (required)
 141       -  flavor\_id - the flavor's string ID (default='auto')
 142       -  ram - memory in MB to allocate to VM (required)
 143       -  disk - disk storage in GB (required)
 144       -  vcpus - the number of CPUs to allocate to VM (required)
 145       -  ephemeral - the size of the ephemeral disk in GB (default=0)
 146       -  swap - the size of the swap disk in GB (default=0)
 147       -  rxtx\_factor - the receive/transmit factor to be set on ports
 148          if backend supports QoS extension (default=1.0)
 149       -  is\_public - flag that denotes whether or not other projects
 150          can access image (default=True)
 151
 152 .. code:: python
 153
 154     from snaps.openstack.create_flavor import FlavorSettings, OpenStackFlavor
 155     flavor_settings = FlavorSettings(name='flavor-name', ram=4, disk=10, vcpus=2)
 156     flavor_creator = OpenStackFlavor(os_creds, flavor_settings)
 157     flavor_creator.create()
 158
 159     # Perform logic
 160     ...
 161
 162     # Cleanup
 163     flavor_creator.clean()
 164
 165 Create Image
 166 ------------
 167 -  Image - snaps.openstack.create\_image.OpenStackImage
 168
 169    -  snaps.openstack.create\_image.ImageSettings
 170
 171       -  name - the image name (required)
 172       -  image\_user - the default image user generally used by
 173          OpenStackVMInstance class for obtaining an SSH connection
 174          (required)
 175       -  img\_format - the image's format (i.e. qcow2) (required)
 176       -  url - the download URL to obtain the image file (this or
 177          image\_file must be configured, not both)
 178       -  image\_file - the location of the file to be sourced from the
 179          local filesystem (this or url must be configured, not both)
 180       -  nic\_config\_pb\_loc - the location of the ansible playbook
 181          that can configure additional NICs. Floating IPs are required
 182          to perform this operation. (optional)
 183
 184
 185 .. code:: python
 186
 187     from snaps.openstack.create_image import ImageSettings, OpenStackImage
 188     image_settings = ImageSettings(name='image-name', image_user='ubuntu', img_format='qcow2',
 189                                    url='http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img')
 190     image_creator = OpenStackImage(os_creds, image_settings)
 191     image_creator.create()
 192
 193     # Perform logic
 194     ...
 195
 196     # Cleanup
 197     image_creator.clean()
 198
 199 Create Keypair
 200 --------------
 201 -  Keypair - snaps.openstack.create\_keypair.OpenStackKeypair
 202
 203    -  snaps.openstack.create\_keypair.KeypairSettings
 204
 205       -  name - the keypair name (required)
 206       -  public\_filepath - the file location to where the public key is
 207          to be written or currently resides (optional)
 208       -  private\_filepath - the file location to where the private key
 209          file is to be written or currently resides (optional but highly
 210          recommended to leverage or the private key will be lost
 211          forever)
 212
 213 .. code:: python
 214
 215     from snaps.openstack.create_keypairs import KeypairSettings, OpenStackKeypair
 216     keypair_settings = KeypairSettings(name='kepair-name', private_filepath='/tmp/priv-kp')
 217     keypair_creator = OpenStackKeypair(os_creds, keypair_settings)
 218     keypair_creator.create()
 219
 220     # Perform logic
 221     ...
 222
 223     # Cleanup
 224     keypair_creator.clean()
 225
 226 Create Network
 227 --------------
 228
 229 -  Network - snaps.openstack.create\_network.OpenStackNetwork
 230
 231    -  snaps.openstack.create\_network.NetworkSettings
 232
 233       -  name - the name of the network (required)
 234       -  admin\_state\_up - flag denoting the administrative status of
 235          the network (True = up, False = down)
 236       -  shared - flag indicating whether the network can be shared
 237          across projects/tenants (default=True)
 238       -  project\_name - the name of the project (optional - can only be
 239          set by admin users)
 240       -  external - flag determining if network has external access
 241          (default=False)
 242       -  network\_type - the type of network (i.e. vlan\|vxlan\|flat)
 243       -  physical\_network - the name of the physical network (required
 244          when network\_type is 'flat')
 245       -  subnet\_settings (list of optional
 246          snaps.openstack.create\_network.SubnetSettings objects)
 247
 248          -  cidr - the subnet's CIDR (required)
 249          -  ip\_version - 4 or 6 (default=4)
 250          -  name - the subnet name (required)
 251          -  project\_name - the name of the project (optional - can only
 252             be set by admin users)
 253          -  start - the start address for the allocation pools
 254          -  end - the end address for the allocation pools
 255          -  gateway\_ip - the gateway IP
 256          -  enable\_dhcp - flag to determine whether or not to enable
 257             DHCP (optional)
 258          -  dns\_nameservers - a list of DNS nameservers
 259          -  host\_routes - list of host route dictionaries for subnet
 260             (optional, see pydoc and Neutron API for more details)
 261          -  destination - the destination for static route (optional)
 262          -  nexthop - the next hop for the destination (optional)
 263          -  ipv6\_ra\_mode - valid values include: 'dhcpv6-stateful',
 264             'dhcp6v-stateless', 'slaac' (optional)
 265          -  ipvc\_address\_mode - valid values include:
 266             'dhcpv6-stateful', 'dhcp6v-stateless', 'slaac' (optional)
 267
 268 .. code:: python
 269
 270     from snaps.openstack.create_network import NetworkSettings, SubnetSettings, OpenStackNetwork
 271
 272     subnet_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
 273     network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
 274
 275     network_creator = OpenStackNetwork(os_creds, network_settings)
 276     network_creator.create()
 277
 278     # Perform logic
 279     ...
 280
 281     # Cleanup
 282     network_creator.clean()
 283
 284 Create Security Group
 285 ---------------------
 286
 287 -  Security Group -
 288    snaps.openstack.create\_security\_group.OpenStackSecurityGroup
 289
 290    -  snaps.openstack.create\_security\_group.SecurityGroupSettings
 291
 292       -  name - the security group's name (required)
 293       -  description - the description (optional)
 294       -  project\_name - the name of the project (optional - can only be
 295          set by admin users)
 296       -  rule\_settings (list of
 297          optional snaps.openstack.create\_security\_group.SecurityGroupRuleSettings
 298          objects)
 299
 300          -  sec\_grp\_name - the name of the associated security group
 301             (required)
 302          -  description - the description (optional)
 303          -  direction - enum
 304             snaps.openstack.create\_security\_group.Direction (required)
 305          -  remote\_group\_id - the group ID to associate with this rule
 306          -  protocol -
 307             enum snaps.openstack.create\_security\_group.Protocol
 308             (optional)
 309          -  ethertype -
 310             enum snaps.openstack.create\_security\_group.Ethertype
 311             (optional)
 312          -  port\_range\_min - the max port number in the range that is
 313             matched by the security group rule (optional)
 314          -  port\_range\_max - the min port number in the range that is
 315             matched by the security group rule (optional)
 316          -  sec\_grp\_rule - the rule object to a security group rule
 317             object to associate (note: does not work currently)
 318          -  remote\_ip\_prefix - the remote IP prefix to associate with
 319             this metering rule packet (optional)
 320
 321 .. code:: python
 322
 323     from snaps.openstack.create_security_group import SecurityGroupSettings, SecurityGroupRuleSettings, Direction, OpenStackSecurityGroup
 324
 325     rule_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
 326     network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
 327
 328     sec_grp_name = 'sec-grp-name'
 329     rule_settings = SecurityGroupRuleSettings(name=sec_grp_name, direction=Direction.ingress)
 330     security_group_settings = SecurityGroupSettings(name=sec_grp_name, rule_settings=[rule_settings])
 331
 332     security_group_creator = OpenStackSecurityGroup(os_creds, security_group_settings)
 333     security_group_creator.create()
 334
 335     # Perform logic
 336     ...
 337
 338     # Cleanup
 339     security_group_creator.clean()
 340
 341 Create Router
 342 -------------
 343
 344 -  Router - snaps.openstack.create\_router.OpenStackRouter
 345
 346    -  snaps.openstack.create\_router.RouterSettings
 347
 348       -  name - the router name (required)
 349       -  project\_name - the name of the project (optional - can only be
 350          set by admin users)
 351       -  external\_gateway - the name of the external network (optional)
 352       -  admin\_state\_up - flag to denote the administrative status of
 353          the router (default=True)
 354       -  external\_fixed\_ips - dictionary containing the IP address
 355          parameters (parameter not tested)
 356       -  internal\_subnets - list of subnet names to which this router
 357          will connect (optional)
 358       -  port\_settings (list of optional
 359          snaps.openstack.create\_router.PortSettings objects) - creates
 360          custom ports to internal subnets (similar to internal\_subnets
 361          with more control)
 362
 363          -  name
 364          -  network\_name
 365          -  admin\_state\_up
 366          -  project\_name - the name of the project (optional - can only
 367             be set by admin users)
 368          -  mac\_address
 369          -  ip\_addrs
 370          -  fixed\_ips
 371          -  security\_groups
 372          -  allowed\_address\_pairs
 373          -  opt\_value
 374          -  opt\_name
 375          -  device\_owner
 376          -  device\_id
 377
 378 .. code:: python
 379
 380     from snaps.openstack.create_router import RouterSettings, OpenStackRouter
 381
 382     router_settings = RouterSettings(name='router-name', external_gateway='external')
 383     router_creator = OpenStackRouter(os_creds, router_settings)
 384     router_creator.create()
 385
 386     # Perform logic
 387     ...
 388
 389     # Cleanup
 390     router_creator.clean()
 391
 392 Create VM Instance
 393 ------------------
 394
 395 -  VM Instances - snaps.openstack.create\_instance.OpenStackVmInstance
 396
 397    -  snaps.openstack.create\_instance.VmInstanceSettings
 398
 399       -  name - the name of the VM (required)
 400       -  flavor - the name of the flavor (required)
 401       -  port\_settings - list of
 402          snaps.openstack.create\_network.PortSettings objects where each
 403          denote a NIC (see above in create router section for details)
 404          API does not require, but newer NFVIs now require VMs have at
 405          least one network
 406       -  security\_group\_names - a list of security group names to
 407          apply to VM
 408       -  floating\_ip\_settings (list of
 409          snaps.openstack\_create\_instance.FloatingIpSettings objects)
 410
 411          -  name - a name to a floating IP for easy lookup
 412          -  port\_name - the name of the VM port on which the floating
 413             IP should be applied (required)
 414          -  router\_name - the name of the router to the external
 415             network (required)
 416          -  subnet\_name - the name of the subnet on which to attach the
 417             floating IP (optional)
 418          -  provisioning - when true, this floating IP will be used for
 419             provisioning which will come into play once we are able to
 420             get multiple floating IPs working.
 421
 422       -  sudo\_user - overrides the image\_settings.image\_user value
 423          when attempting to connect via SSH
 424       -  vm\_boot\_timeout - the number of seconds that the thread will
 425          block when querying the VM's status when building (default=900)
 426       -  vm\_delete\_timeout - the number of seconds that the thread
 427          will block when querying the VM's status when deleting
 428          (default=300)
 429       -  ssh\_connect\_timeout - the number of seconds that the thread
 430          will block when attempting to obtain an SSH connection
 431          (default=180)
 432       -  availability\_zone - the name of the compute server on which to
 433          deploy the VM (optional must be admin)
 434       -  userdata - the cloud-init script to execute after VM has been
 435          started
 436
 437    -  image\_settings - see snaps.openstack.create\_image.ImageSettings
 438       above (required)
 439    -  keypair\_settings - see
 440       snaps.openstack.create\_keypairs.KeypairSettings above (optional)
 441
 442 .. code:: python
 443
 444     from snaps.openstack.create_instance import VmInstanceSettings, FloatingIpSettings, OpenStackVmInstance
 445     from snaps.openstack.create_network import PortSettings
 446
 447     port_settings = PortSettings(name='port-name', network_name=network_settings.name)
 448     floating_ip_settings = FloatingIpSettings(name='fip1', port_name=port_settings.name, router_name=router_settings.name)
 449     instance_settings = VmInstanceSettings(name='vm-name', flavor='flavor_settings.name', port_settings=[port_settings],
 450                                            floating_ip_settings=[floating_ip_settings])
 451
 452     instance_creator = OpenStackVmInstance(os_creds, instance_settings, image_settings, kepair_settings)
 453     instance_creator.create()
 454
 455     # Perform logic
 456     ...
 457     ssh_client = instance_creator.ssh_client()
 458     ...
 459
 460     # Cleanup
 461     instance_creator.clean()
 462
 463 Ansible Provisioning
 464 ====================
 465
 466 Being able to easily create OpenStack instances such as virtual networks
 467 and VMs is a good start to the problem of NFV; however, an NFVI is
 468 useless unless there is some software performing some function. This is
 469 why we added Ansible playbook support to SNAPS-OO which can be located
 470 in snaps.provisioning.ansible\_utils#apply\_playbook. See below for a
 471 description of that function's parameters:
 472
 473 -  playbook\_path - the file location of the ansible playbook
 474 -  hosts\_inv - a list of hosts/IP addresses to which the playbook will
 475    be applied
 476 -  host\_user - the user (preferably sudo) to use for applying the
 477    playbook
 478 -  ssh\_priv\_key\_file\_path - the location to the private key file
 479    used for SSH
 480 -  variables - a dict() of substitution values for Jinga2 templates
 481    leveraged by Ansible
 482 -  proxy\_setting - used to extract the SSH proxy command (optional)
 483
 484 Apply Ansible Playbook Utility
 485 ------------------------------
 486
 487 .. code:: python
 488
 489     from snaps.provisioning import ansible_utils
 490
 491     ansible_utils.apply_playbook(playbook_path='provisioning/tests/playbooks/simple_playbook.yml',
 492                                  hosts_inv=[ip], host_user=user, ssh_priv_key_file_path=priv_key,
 493                                  proxy_setting=self.os_creds.proxy_settings)
 494
 495 OpenStack Utilities
 496 ===================
 497
 498 For those who do like working procedurally, SNAPS-OO also leverages
 499 utilitarian functions for nearly every query or request made to
 500 OpenStack. This pattern will make it easier to deal with API version
 501 changes as they would all be made in one place. (see keystone\_utils for
 502 an example of this pattern as this is the only API where SNAPS is
 503 supporting more than one version)
 504
 505 -  snaps.openstack.utils.keystone\_utils - for calls to the Keystone
 506    APIs
 507 -  snaps.openstack.utils.glance\_utils - for calls to the Glance APIs
 508 -  snaps.openstack.utils.neutron\_utils - for calls to the Neutron APIs
 509 -  snaps.openstack.utils.nova\_utils - for calls to the Nova APIs