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 currently 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 - project\_domain\_id (default='default')
40 - interface (default='admin', used to specify the endpoint type for keystone: public, admin, internal)
41 - cacert (default=False, expected values T|F to denote server certificate verification, else value contains the path to an HTTPS certificate)
44 - host (the HTTP proxy host)
45 - port (the HTTP proxy port)
46 - https\_host (the HTTPS proxy host, default value of host)
47 - https\_port (the HTTPS proxy port, default value of port)
48 - ssh\_proxy\_cmd (same as the value placed into ssh -o
49 ProxyCommand='<this config value>')
51 Create OS Credentials Object
52 ----------------------------
56 from snaps.openstack.os_credentials import OSCreds
57 os_creds=OSCreds(username='admin', password='admin',
58 auth_url='http://localhost:5000/v3', project_name='admin',
59 identity_api_version=3)
64 Each creator minimally requires an OSCreds object for connecting to the
65 NFVI, associated \*Settings object for instance configuration, create()
66 method to make the necessary remote API calls and create all of the
67 necessary OpenStack instances required, and clean() method that is
68 responsible for deleting all associated OpenStack instances. Please see
69 the class diagram `here </display/SNAP/SNAPS-OO+Classes>`__. Below is a
70 textual representation of the requirements of each creator classes with
71 their associated setting classes and a sample code snippet on how to use
76 - User - snaps.openstack.create\_user.OpenStackUser
78 - snaps.openstack.create\_user.UserSettings
80 - name - the username (required)
81 - password - the user's password (required)
82 - project\_name - the name of the project to associated to this
84 - domain\_name - the user's domain (default='default')
85 - email - the user's email address (optional)
86 - enabled - flag to determine whether or not the user should be
87 enabled (default=True)
91 from snaps.openstack.create_user import UserSettings, OpenStackUser
92 user_settings = UserSettings(name='username', password='password')
93 user_creator = OpenStackUser(os_creds, user_settings)
96 # Retrieve OS creds for new user for creating other OpenStack instance
97 user_creds = user_creator.get_os_creds(os_creds.project_name)
107 - Project - snaps.openstack.create\_project.OpenStackProject
109 - snaps.openstack.create\_project.ProjectSettings
111 - name - the project name (required)
112 - domain - the project's domain (default='default')
113 - description - the project's description (optional)
114 - enables - flag to determine whether or not the project should
115 be enabled (default=True)
120 from snaps.openstack.create_project import ProjectSettings, OpenStackProject
121 project_settings = ProjectSettings(name='username', password='password')
122 project_creator = OpenStackProject(os_creds, project_settings)
123 project_creator.create()
129 project_creator.clean()
133 - Flavor - snaps.openstack.create\_flavor.OpenStackFlavor
135 - snaps.openstack.create\_flavor.FlavorSettings
137 - name - the flavor name (required)
138 - flavor\_id - the flavor's string ID (default='auto')
139 - ram - memory in MB to allocate to VM (required)
140 - disk - disk storage in GB (required)
141 - vcpus - the number of CPUs to allocate to VM (required)
142 - ephemeral - the size of the ephemeral disk in GB (default=0)
143 - swap - the size of the swap disk in GB (default=0)
144 - rxtx\_factor - the receive/transmit factor to be set on ports
145 if backend supports QoS extension (default=1.0)
146 - is\_public - flag that denotes whether or not other projects
147 can access image (default=True)
151 from snaps.openstack.create_flavor import FlavorSettings, OpenStackFlavor
152 flavor_settings = FlavorSettings(name='flavor-name', ram=4, disk=10, vcpus=2)
153 flavor_creator = OpenStackFlavor(os_creds, flavor_settings)
154 flavor_creator.create()
160 flavor_creator.clean()
164 - Image - snaps.openstack.create\_image.OpenStackImage
166 - snaps.openstack.create\_image.ImageSettings
168 - name - the image name (required)
169 - image\_user - the default image user generally used by
170 OpenStackVMInstance class for obtaining an SSH connection
172 - img\_format - the image's format (i.e. qcow2) (required)
173 - url - the download URL to obtain the image file (this or
174 image\_file must be configured, not both)
175 - image\_file - the location of the file to be sourced from the
176 local filesystem (this or url must be configured, not both)
177 - nic\_config\_pb\_loc - the location of the ansible playbook
178 that can configure additional NICs. Floating IPs are required
179 to perform this operation. (optional)
184 from snaps.openstack.create_image import ImageSettings, OpenStackImage
185 image_settings = ImageSettings(name='image-name', image_user='ubuntu', img_format='qcow2',
186 url='http://uec-images.ubuntu.com/releases/trusty/14.04/ubuntu-14.04-server-cloudimg-amd64-disk1.img')
187 image_creator = OpenStackImage(os_creds, image_settings)
188 image_creator.create()
194 image_creator.clean()
198 - Keypair - snaps.openstack.create\_keypair.OpenStackKeypair
200 - snaps.openstack.create\_keypair.KeypairSettings
202 - name - the keypair name (required)
203 - public\_filepath - the file location to where the public key is
204 to be written or currently resides (optional)
205 - private\_filepath - the file location to where the private key
206 file is to be written or currently resides (optional but highly
207 recommended to leverage or the private key will be lost
212 from snaps.openstack.create_keypairs import KeypairSettings, OpenStackKeypair
213 keypair_settings = KeypairSettings(name='kepair-name', private_filepath='/tmp/priv-kp')
214 keypair_creator = OpenStackKeypair(os_creds, keypair_settings)
215 keypair_creator.create()
221 keypair_creator.clean()
226 - Network - snaps.openstack.create\_network.OpenStackNetwork
228 - snaps.openstack.create\_network.NetworkSettings
230 - name - the name of the network (required)
231 - admin\_state\_up - flag denoting the administrative status of
232 the network (True = up, False = down)
233 - shared - flag indicating whether the network can be shared
234 across projects/tenants (default=True)
235 - project\_name - the name of the project (optional - can only be
237 - external - flag determining if network has external access
239 - network\_type - the type of network (i.e. vlan\|vxlan\|flat)
240 - physical\_network - the name of the physical network (required
241 when network\_type is 'flat')
242 - subnet\_settings (list of optional
243 snaps.openstack.create\_network.SubnetSettings objects)
245 - cidr - the subnet's CIDR (required)
246 - ip\_version - 4 or 6 (default=4)
247 - name - the subnet name (required)
248 - project\_name - the name of the project (optional - can only
249 be set by admin users)
250 - start - the start address for the allocation pools
251 - end - the end address for the allocation pools
252 - gateway\_ip - the gateway IP
253 - enable\_dhcp - flag to determine whether or not to enable
255 - dns\_nameservers - a list of DNS nameservers
256 - host\_routes - list of host route dictionaries for subnet
257 (optional, see pydoc and Neutron API for more details)
258 - destination - the destination for static route (optional)
259 - nexthop - the next hop for the destination (optional)
260 - ipv6\_ra\_mode - valid values include: 'dhcpv6-stateful',
261 'dhcp6v-stateless', 'slaac' (optional)
262 - ipvc\_address\_mode - valid values include:
263 'dhcpv6-stateful', 'dhcp6v-stateless', 'slaac' (optional)
267 from snaps.openstack.create_network import NetworkSettings, SubnetSettings, OpenStackNetwork
269 subnet_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
270 network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
272 network_creator = OpenStackNetwork(os_creds, network_settings)
273 network_creator.create()
279 network_creator.clean()
281 Create Security Group
282 ---------------------
285 snaps.openstack.create\_security\_group.OpenStackSecurityGroup
287 - snaps.openstack.create\_security\_group.SecurityGroupSettings
289 - name - the security group's name (required)
290 - description - the description (optional)
291 - project\_name - the name of the project (optional - can only be
293 - rule\_settings (list of
294 optional snaps.openstack.create\_security\_group.SecurityGroupRuleSettings
297 - sec\_grp\_name - the name of the associated security group
299 - description - the description (optional)
301 snaps.openstack.create\_security\_group.Direction (required)
302 - remote\_group\_id - the group ID to associate with this rule
304 enum snaps.openstack.create\_security\_group.Protocol
307 enum snaps.openstack.create\_security\_group.Ethertype
309 - port\_range\_min - the max port number in the range that is
310 matched by the security group rule (optional)
311 - port\_range\_max - the min port number in the range that is
312 matched by the security group rule (optional)
313 - sec\_grp\_rule - the rule object to a security group rule
314 object to associate (note: does not work currently)
315 - remote\_ip\_prefix - the remote IP prefix to associate with
316 this metering rule packet (optional)
320 from snaps.openstack.create_security_group import SecurityGroupSettings, SecurityGroupRuleSettings, Direction, OpenStackSecurityGroup
322 rule_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
323 network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
325 sec_grp_name = 'sec-grp-name'
326 rule_settings = SecurityGroupRuleSettings(name=sec_grp_name, direction=Direction.ingress)
327 security_group_settings = SecurityGroupSettings(name=sec_grp_name, rule_settings=[rule_settings])
329 security_group_creator = OpenStackSecurityGroup(os_creds, security_group_settings)
330 security_group_creator.create()
336 security_group_creator.clean()
341 - Router - snaps.openstack.create\_router.OpenStackRouter
343 - snaps.openstack.create\_router.RouterSettings
345 - name - the router name (required)
346 - project\_name - the name of the project (optional - can only be
348 - external\_gateway - the name of the external network (optional)
349 - admin\_state\_up - flag to denote the administrative status of
350 the router (default=True)
351 - external\_fixed\_ips - dictionary containing the IP address
352 parameters (parameter not tested)
353 - internal\_subnets - list of subnet names to which this router
354 will connect (optional)
355 - port\_settings (list of optional
356 snaps.openstack.create\_router.PortSettings objects) - creates
357 custom ports to internal subnets (similar to internal\_subnets
363 - project\_name - the name of the project (optional - can only
364 be set by admin users)
369 - allowed\_address\_pairs
377 from snaps.openstack.create_router import RouterSettings, OpenStackRouter
379 router_settings = RouterSettings(name='router-name', external_gateway='external')
380 router_creator = OpenStackRouter(os_creds, router_settings)
381 router_creator.create()
387 router_creator.clean()
392 - VM Instances - snaps.openstack.create\_instance.OpenStackVmInstance
394 - snaps.openstack.create\_instance.VmInstanceSettings
396 - name - the name of the VM (required)
397 - flavor - the name of the flavor (required)
398 - port\_settings - list of
399 snaps.openstack.create\_network.PortSettings objects where each
400 denote a NIC (see above in create router section for details)
401 API does not require, but newer NFVIs now require VMs have at
403 - security\_group\_names - a list of security group names to
405 - floating\_ip\_settings (list of
406 snaps.openstack\_create\_instance.FloatingIpSettings objects)
408 - name - a name to a floating IP for easy lookup
409 - port\_name - the name of the VM port on which the floating
410 IP should be applied (required)
411 - router\_name - the name of the router to the external
413 - subnet\_name - the name of the subnet on which to attach the
414 floating IP (optional)
415 - provisioning - when true, this floating IP will be used for
416 provisioning which will come into play once we are able to
417 get multiple floating IPs working.
419 - sudo\_user - overrides the image\_settings.image\_user value
420 when attempting to connect via SSH
421 - vm\_boot\_timeout - the number of seconds that the thread will
422 block when querying the VM's status when building (default=900)
423 - vm\_delete\_timeout - the number of seconds that the thread
424 will block when querying the VM's status when deleting
426 - ssh\_connect\_timeout - the number of seconds that the thread
427 will block when attempting to obtain an SSH connection
429 - availability\_zone - the name of the compute server on which to
430 deploy the VM (optional must be admin)
431 - userdata - the cloud-init script to execute after VM has been
434 - image\_settings - see snaps.openstack.create\_image.ImageSettings
436 - keypair\_settings - see
437 snaps.openstack.create\_keypairs.KeypairSettings above (optional)
441 from snaps.openstack.create_instance import VmInstanceSettings, FloatingIpSettings, OpenStackVmInstance
442 from snaps.openstack.create_network import PortSettings
444 port_settings = PortSettings(name='port-name', network_name=network_settings.name)
445 floating_ip_settings = FloatingIpSettings(name='fip1', port_name=port_settings.name, router_name=router_settings.name)
446 instance_settings = VmInstanceSettings(name='vm-name', flavor='flavor_settings.name', port_settings=[port_settings],
447 floating_ip_settings=[floating_ip_settings])
449 instance_creator = OpenStackVmInstance(os_creds, instance_settings, image_settings, kepair_settings)
450 instance_creator.create()
454 ssh_client = instance_creator.ssh_client()
458 instance_creator.clean()
463 Being able to easily create OpenStack instances such as virtual networks
464 and VMs is a good start to the problem of NFV; however, an NFVI is
465 useless unless there is some software performing some function. This is
466 why we added Ansible playbook support to SNAPS-OO which can be located
467 in snaps.provisioning.ansible\_utils#apply\_playbook. See below for a
468 description of that function's parameters:
470 - playbook\_path - the file location of the ansible playbook
471 - hosts\_inv - a list of hosts/IP addresses to which the playbook will
473 - host\_user - the user (preferably sudo) to use for applying the
475 - ssh\_priv\_key\_file\_path - the location to the private key file
477 - variables - a dict() of substitution values for Jinga2 templates
479 - proxy\_setting - used to extract the SSH proxy command (optional)
481 Apply Ansible Playbook Utility
482 ------------------------------
486 from snaps.provisioning import ansible_utils
488 ansible_utils.apply_playbook(playbook_path='provisioning/tests/playbooks/simple_playbook.yml',
489 hosts_inv=[ip], host_user=user, ssh_priv_key_file_path=priv_key,
490 proxy_setting=self.os_creds.proxy_settings)
495 For those who do like working procedurally, SNAPS-OO also leverages
496 utilitarian functions for nearly every query or request made to
497 OpenStack. This pattern will make it easier to deal with API version
498 changes as they would all be made in one place. (see keystone\_utils for
499 an example of this pattern as this is the only API where SNAPS is
500 supporting more than one version)
502 - snaps.openstack.utils.keystone\_utils - for calls to the Keystone
504 - snaps.openstack.utils.glance\_utils - for calls to the Glance APIs
505 - snaps.openstack.utils.neutron\_utils - for calls to the Neutron APIs
506 - snaps.openstack.utils.nova\_utils - for calls to the Nova APIs