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