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 - user\_domain\_id (default='default')
38 - project\_domain\_id (default='default')
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>')
46 Create OS Credentials Object
47 ----------------------------
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)
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
71 - User - snaps.openstack.create\_user.OpenStackUser
73 - snaps.openstack.create\_user.UserSettings
75 - name - the username (required)
76 - password - the user's password (required)
77 - project\_name - the name of the project to associated to this
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)
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)
91 # Retrieve OS creds for new user for creating other OpenStack instance
92 user_creds = user_creator.get_os_creds(os_creds.project_name)
102 - Project - snaps.openstack.create\_project.OpenStackProject
104 - snaps.openstack.create\_project.ProjectSettings
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)
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()
124 project_creator.clean()
128 - Flavor - snaps.openstack.create\_flavor.OpenStackFlavor
130 - snaps.openstack.create\_flavor.FlavorSettings
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)
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()
155 flavor_creator.clean()
159 - Image - snaps.openstack.create\_image.OpenStackImage
161 - snaps.openstack.create\_image.ImageSettings
163 - name - the image name (required)
164 - image\_user - the default image user generally used by
165 OpenStackVMInstance class for obtaining an SSH connection
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)
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()
189 image_creator.clean()
193 - Keypair - snaps.openstack.create\_keypair.OpenStackKeypair
195 - snaps.openstack.create\_keypair.KeypairSettings
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
207 from snaps.openstack.create_keypair 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()
216 keypair_creator.clean()
221 - Network - snaps.openstack.create\_network.OpenStackNetwork
223 - snaps.openstack.create\_network.NetworkSettings
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
232 - external - flag determining if network has external access
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)
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
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)
262 from snaps.openstack.create_network import NetworkSettings, SubnetSettings, OpenStackNetwork
264 subnet_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
265 network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
267 network_creator = OpenStackNetwork(os_creds, network_settings)
268 network_creator.create()
274 network_creator.clean()
276 Create Security Group
277 ---------------------
280 snaps.openstack.create\_security\_group.OpenStackSecurityGroup
282 - snaps.openstack.create\_security\_group.SecurityGroupSettings
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
288 - rule\_settings (list of
289 optional snaps.openstack.create\_security\_group.SecurityGroupRuleSettings
292 - sec\_grp\_name - the name of the associated security group
294 - description - the description (optional)
296 snaps.openstack.create\_security\_group.Direction (required)
297 - remote\_group\_id - the group ID to associate with this rule
299 enum snaps.openstack.create\_security\_group.Protocol
302 enum snaps.openstack.create\_security\_group.Ethertype
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)
315 from snaps.openstack.create_security_group import SecurityGroupSettings, SecurityGroupRuleSettings, Direction, OpenStackSecurityGroup
317 rule_settings = SubnetSettings(name='subnet-name', cidr='10.0.0.0/24')
318 network_settings = NetworkSettings(name='network-name', subnet_settings=[subnet_settings])
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])
324 security_group_creator = OpenStackSecurityGroup(os_creds, security_group_settings)
325 security_group_creator.create()
331 security_group_creator.clean()
336 - Router - snaps.openstack.create\_router.OpenStackRouter
338 - snaps.openstack.create\_router.RouterSettings
340 - name - the router name (required)
341 - project\_name - the name of the project (optional - can only be
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
358 - project\_name - the name of the project (optional - can only
359 be set by admin users)
364 - allowed\_address\_pairs
372 from snaps.openstack.create_router import RouterSettings, OpenStackRouter
374 router_settings = RouterSettings(name='router-name', external_gateway='external')
375 router_creator = OpenStackRouter(os_creds, router_settings)
376 router_creator.create()
382 router_creator.clean()
387 - VM Instances - snaps.openstack.create\_instance.OpenStackVmInstance
389 - snaps.openstack.create\_instance.VmInstanceSettings
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
398 - security\_group\_names - a list of security group names to
400 - floating\_ip\_settings (list of
401 snaps.openstack\_create\_instance.FloatingIpSettings objects)
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
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.
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
421 - ssh\_connect\_timeout - the number of seconds that the thread
422 will block when attempting to obtain an SSH connection
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
429 - image\_settings - see snaps.openstack.create\_image.ImageSettings
431 - keypair\_settings - see
432 snaps.openstack.create\_keypairs.KeypairSettings above (optional)
436 from snaps.openstack.create_instance import VmInstanceSettings, FloatingIpSettings, OpenStackVmInstance
437 from snaps.openstack.create_network import PortSettings
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])
444 instance_creator = OpenStackVmInstance(os_creds, instance_settings, image_settings, kepair_settings)
445 instance_creator.create()
449 ssh_client = instance_creator.ssh_client()
453 instance_creator.clean()
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:
465 - playbook\_path - the file location of the ansible playbook
466 - hosts\_inv - a list of hosts/IP addresses to which the playbook will
468 - host\_user - the user (preferably sudo) to use for applying the
470 - ssh\_priv\_key\_file\_path - the location to the private key file
472 - variables - a dict() of substitution values for Jinga2 templates
474 - proxy\_setting - used to extract the SSH proxy command (optional)
476 Apply Ansible Playbook Utility
477 ------------------------------
481 from snaps.provisioning import ansible_utils
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)
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)
497 - snaps.openstack.utils.keystone\_utils - for calls to the Keystone
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