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
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:
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)
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>')
54 Create OS Credentials Object
55 ----------------------------
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)
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
79 - User - snaps.openstack.create\_user.OpenStackUser
81 - snaps.openstack.create\_user.UserSettings
83 - name - the username (required)
84 - password - the user's password (required)
85 - project\_name - the name of the project to associated to this
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)
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)
99 # Retrieve OS creds for new user for creating other OpenStack instance
100 user_creds = user_creator.get_os_creds(os_creds.project_name)
110 - Project - snaps.openstack.create\_project.OpenStackProject
112 - snaps.openstack.create\_project.ProjectSettings
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)
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()
132 project_creator.clean()
136 - Flavor - snaps.openstack.create\_flavor.OpenStackFlavor
138 - snaps.openstack.create\_flavor.FlavorSettings
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)
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()
163 flavor_creator.clean()
167 - Image - snaps.openstack.create\_image.OpenStackImage
169 - snaps.openstack.create\_image.ImageSettings
171 - name - the image name (required)
172 - image\_user - the default image user generally used by
173 OpenStackVMInstance class for obtaining an SSH connection
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)
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()
197 image_creator.clean()
201 - Keypair - snaps.openstack.create\_keypair.OpenStackKeypair
203 - snaps.openstack.create\_keypair.KeypairSettings
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
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()
224 keypair_creator.clean()
229 - Network - snaps.openstack.create\_network.OpenStackNetwork
231 - snaps.openstack.create\_network.NetworkSettings
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
240 - external - flag determining if network has external access
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)
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
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)
270 from snaps.openstack.create_network import NetworkSettings, SubnetSettings, OpenStackNetwork
272 subnet_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
273 network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
275 network_creator = OpenStackNetwork(os_creds, network_settings)
276 network_creator.create()
282 network_creator.clean()
284 Create Security Group
285 ---------------------
288 snaps.openstack.create\_security\_group.OpenStackSecurityGroup
290 - snaps.openstack.create\_security\_group.SecurityGroupSettings
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
296 - rule\_settings (list of
297 optional snaps.openstack.create\_security\_group.SecurityGroupRuleSettings
300 - sec\_grp\_name - the name of the associated security group
302 - description - the description (optional)
304 snaps.openstack.create\_security\_group.Direction (required)
305 - remote\_group\_id - the group ID to associate with this rule
307 enum snaps.openstack.create\_security\_group.Protocol
310 enum snaps.openstack.create\_security\_group.Ethertype
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)
323 from snaps.openstack.create_security_group import SecurityGroupSettings, SecurityGroupRuleSettings, Direction, OpenStackSecurityGroup
325 rule_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
326 network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
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])
332 security_group_creator = OpenStackSecurityGroup(os_creds, security_group_settings)
333 security_group_creator.create()
339 security_group_creator.clean()
344 - Router - snaps.openstack.create\_router.OpenStackRouter
346 - snaps.openstack.create\_router.RouterSettings
348 - name - the router name (required)
349 - project\_name - the name of the project (optional - can only be
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
366 - project\_name - the name of the project (optional - can only
367 be set by admin users)
372 - allowed\_address\_pairs
380 from snaps.openstack.create_router import RouterSettings, OpenStackRouter
382 router_settings = RouterSettings(name='router-name', external_gateway='external')
383 router_creator = OpenStackRouter(os_creds, router_settings)
384 router_creator.create()
390 router_creator.clean()
395 - VM Instances - snaps.openstack.create\_instance.OpenStackVmInstance
397 - snaps.openstack.create\_instance.VmInstanceSettings
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
406 - security\_group\_names - a list of security group names to
408 - floating\_ip\_settings (list of
409 snaps.openstack\_create\_instance.FloatingIpSettings objects)
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
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.
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
429 - ssh\_connect\_timeout - the number of seconds that the thread
430 will block when attempting to obtain an SSH connection
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
437 - image\_settings - see snaps.openstack.create\_image.ImageSettings
439 - keypair\_settings - see
440 snaps.openstack.create\_keypairs.KeypairSettings above (optional)
444 from snaps.openstack.create_instance import VmInstanceSettings, FloatingIpSettings, OpenStackVmInstance
445 from snaps.openstack.create_network import PortSettings
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])
452 instance_creator = OpenStackVmInstance(os_creds, instance_settings, image_settings, kepair_settings)
453 instance_creator.create()
457 ssh_client = instance_creator.ssh_client()
461 instance_creator.clean()
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:
473 - playbook\_path - the file location of the ansible playbook
474 - hosts\_inv - a list of hosts/IP addresses to which the playbook will
476 - host\_user - the user (preferably sudo) to use for applying the
478 - ssh\_priv\_key\_file\_path - the location to the private key file
480 - variables - a dict() of substitution values for Jinga2 templates
482 - proxy\_setting - used to extract the SSH proxy command (optional)
484 Apply Ansible Playbook Utility
485 ------------------------------
489 from snaps.provisioning import ansible_utils
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)
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)
505 - snaps.openstack.utils.keystone\_utils - for calls to the Keystone
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