1 # -*- coding: utf-8 -*-
4 # Copyright 2015 Telefónica Investigación y Desarrollo, S.A.U.
5 # This file is part of openmano
8 # Licensed under the Apache License, Version 2.0 (the "License"); you may
9 # not use this file except in compliance with the License. You may obtain
10 # a copy of the License at
12 # http://www.apache.org/licenses/LICENSE-2.0
14 # Unless required by applicable law or agreed to in writing, software
15 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 # License for the specific language governing permissions and limitations
20 # For those usages not covered by the Apache License, Version 2.0 please
21 # contact with: nfvlabs@tid.es
25 vimconn implement an Abstract class for the vim connector plugins
26 with the definition of the method to be implemented.
28 __author__
="Alfonso Tierno"
29 __date__
="$16-oct-2015 11:09:29$"
34 HTTP_Bad_Request
= 400
35 HTTP_Unauthorized
= 401
37 HTTP_Method_Not_Allowed
= 405
38 HTTP_Request_Timeout
= 408
40 HTTP_Not_Implemented
= 501
41 HTTP_Service_Unavailable
= 503
42 HTTP_Internal_Server_Error
= 500
44 class vimconnException(Exception):
45 """Common and base class Exception for all vimconnector exceptions"""
46 def __init__(self
, message
, http_code
=HTTP_Bad_Request
):
47 Exception.__init
__(self
, message
)
48 self
.http_code
= http_code
50 class vimconnConnectionException(vimconnException
):
51 """Connectivity error with the VIM"""
52 def __init__(self
, message
, http_code
=HTTP_Service_Unavailable
):
53 vimconnException
.__init
__(self
, message
, http_code
)
55 class vimconnUnexpectedResponse(vimconnException
):
56 """Get an wrong response from VIM"""
57 def __init__(self
, message
, http_code
=HTTP_Service_Unavailable
):
58 vimconnException
.__init
__(self
, message
, http_code
)
60 class vimconnAuthException(vimconnException
):
61 """Invalid credentials or authorization to perform this action over the VIM"""
62 def __init__(self
, message
, http_code
=HTTP_Unauthorized
):
63 vimconnException
.__init
__(self
, message
, http_code
)
65 class vimconnNotFoundException(vimconnException
):
66 """The item is not found at VIM"""
67 def __init__(self
, message
, http_code
=HTTP_Not_Found
):
68 vimconnException
.__init
__(self
, message
, http_code
)
70 class vimconnConflictException(vimconnException
):
71 """There is a conflict, e.g. more item found than one"""
72 def __init__(self
, message
, http_code
=HTTP_Conflict
):
73 vimconnException
.__init
__(self
, message
, http_code
)
75 class vimconnNotSupportedException(vimconnException
):
76 """The request is not supported by connector"""
77 def __init__(self
, message
, http_code
=HTTP_Service_Unavailable
):
78 vimconnException
.__init
__(self
, message
, http_code
)
80 class vimconnNotImplemented(vimconnException
):
81 """The method is not implemented by the connected"""
82 def __init__(self
, message
, http_code
=HTTP_Not_Implemented
):
83 vimconnException
.__init
__(self
, message
, http_code
)
86 """Abstract base class for all the VIM connector plugins
87 These plugins must implement a vimconnector class derived from this
88 and all these privated methods
90 def __init__(self
, uuid
, name
, tenant_id
, tenant_name
, url
, url_admin
=None, user
=None, passwd
=None, log_level
=None,
91 config
={}, persitent_info
={}):
94 'uuid': id asigned to this VIM
95 'name': name assigned to this VIM, can be used for logging
96 'tenant_id', 'tenant_name': (only one of them is mandatory) VIM tenant to be used
97 'url_admin': (optional), url used for administrative tasks
98 'user', 'passwd': credentials of the VIM user
99 'log_level': provider if it should use a different log_level than the general one
100 'config': dictionary with extra VIM information. This contains a consolidate version of general VIM config
101 at creation and particular VIM config at teh attachment
102 'persistent_info': dict where the class can store information that will be available among class
103 destroy/creation cycles. This info is unique per VIM/credential. At first call it will contain an
104 empty dict. Useful to store login/tokens information for speed up communication
106 Returns: Raise an exception is some needed parameter is missing, but it must not do any connectivity
107 check against the VIM
112 self
.url_admin
= url_admin
113 self
.tenant_id
= tenant_id
114 self
.tenant_name
= tenant_name
118 self
.logger
= logging
.getLogger('openmano.vim')
120 self
.logger
.setLevel( getattr(logging
, log_level
) )
121 if not self
.url_admin
: #try to use normal url
122 self
.url_admin
= self
.url
124 def __getitem__(self
,index
):
125 if index
=='tenant_id':
126 return self
.tenant_id
127 if index
=='tenant_name':
128 return self
.tenant_name
135 elif index
=='passwd':
139 elif index
=='url_admin':
140 return self
.url_admin
141 elif index
=="config":
144 raise KeyError("Invalid key '%s'" %str
(index
))
146 def __setitem__(self
,index
, value
):
147 if index
=='tenant_id':
148 self
.tenant_id
= value
149 if index
=='tenant_name':
150 self
.tenant_name
= value
157 elif index
=='passwd':
161 elif index
=='url_admin':
162 self
.url_admin
= value
164 raise KeyError("Invalid key '%s'" %str
(index
))
166 def check_vim_connectivity(self
):
167 """Checks VIM can be reached and user credentials are ok.
168 Returns None if success or raised vimconnConnectionException, vimconnAuthException, ...
170 raise vimconnNotImplemented( "Should have implemented this" )
172 def new_tenant(self
,tenant_name
,tenant_description
):
173 """Adds a new tenant to VIM with this name and description, this is done using admin_url if provided
174 "tenant_name": string max lenght 64
175 "tenant_description": string max length 256
176 returns the tenant identifier or raise exception
178 raise vimconnNotImplemented( "Should have implemented this" )
180 def delete_tenant(self
,tenant_id
,):
181 """Delete a tenant from VIM
182 tenant_id: returned VIM tenant_id on "new_tenant"
183 Returns None on success. Raises and exception of failure. If tenant is not found raises vimconnNotFoundException
185 raise vimconnNotImplemented( "Should have implemented this" )
187 def get_tenant_list(self
, filter_dict
={}):
188 """Obtain tenants of VIM
189 filter_dict dictionary that can contain the following keys:
190 name: filter by tenant name
191 id: filter by tenant uuid/id
193 Returns the tenant list of dictionaries, and empty list if no tenant match all the filers:
194 [{'name':'<name>, 'id':'<id>, ...}, ...]
196 raise vimconnNotImplemented( "Should have implemented this" )
198 def new_network(self
, net_name
, net_type
, ip_profile
=None, shared
=False, vlan
=None):
199 """Adds a tenant network to VIM
201 'net_name': name of the network
203 'bridge': overlay isolated network
204 'data': underlay E-LAN network for Passthrough and SRIOV interfaces
205 'ptp': underlay E-LINE network for Passthrough and SRIOV interfaces.
206 'ip_profile': is a dict containing the IP parameters of the network (Currently only IPv4 is implemented)
207 'ip-version': can be one of ["IPv4","IPv6"]
208 'subnet-address': ip_prefix_schema, that is X.X.X.X/Y
209 'gateway-address': (Optional) ip_schema, that is X.X.X.X
210 'dns-address': (Optional) ip_schema,
211 'dhcp': (Optional) dict containing
212 'enabled': {"type": "boolean"},
213 'start-address': ip_schema, first IP to grant
214 'count': number of IPs to grant.
215 'shared': if this network can be seen/use by other tenants/organization
216 'vlan': in case of a data or ptp net_type, the intended vlan tag to be used for the network
217 Returns the network identifier on success or raises and exception on failure
219 raise vimconnNotImplemented( "Should have implemented this" )
221 def get_network_list(self
, filter_dict
={}):
222 """Obtain tenant networks of VIM
224 'filter_dict' (optional) contains entries to return only networks that matches ALL entries:
225 name: string => returns only networks with this name
226 id: string => returns networks with this VIM id, this imply returns one network at most
227 shared: boolean >= returns only networks that are (or are not) shared
228 tenant_id: sting => returns only networks that belong to this tenant/project
229 ,#(not used yet) admin_state_up: boolean => returns only networks that are (or are not) in admin state active
230 #(not used yet) status: 'ACTIVE','ERROR',... => filter networks that are on this status
231 Returns the network list of dictionaries. each dictionary contains:
232 'id': (mandatory) VIM network id
233 'name': (mandatory) VIM network name
234 'status': (mandatory) can be 'ACTIVE', 'INACTIVE', 'DOWN', 'BUILD', 'ERROR', 'VIM_ERROR', 'OTHER'
235 'network_type': (optional) can be 'vxlan', 'vlan' or 'flat'
236 'segmentation_id': (optional) in case network_type is vlan or vxlan this field contains the segmentation id
237 'error_msg': (optional) text that explains the ERROR status
238 other VIM specific fields: (optional) whenever possible using the same naming of filter_dict param
239 List can be empty if no network map the filter_dict. Raise an exception only upon VIM connectivity,
240 authorization, or some other unspecific error
242 raise vimconnNotImplemented( "Should have implemented this" )
244 def get_network(self
, net_id
):
245 """Obtain network details from the 'net_id' VIM network
246 Return a dict that contains:
247 'id': (mandatory) VIM network id, that is, net_id
248 'name': (mandatory) VIM network name
249 'status': (mandatory) can be 'ACTIVE', 'INACTIVE', 'DOWN', 'BUILD', 'ERROR', 'VIM_ERROR', 'OTHER'
250 'error_msg': (optional) text that explains the ERROR status
251 other VIM specific fields: (optional) whenever possible using the same naming of filter_dict param
252 Raises an exception upon error or when network is not found
254 raise vimconnNotImplemented( "Should have implemented this" )
256 def delete_network(self
, net_id
):
257 """Deletes a tenant network from VIM
258 Returns the network identifier or raises an exception upon error or when network is not found
260 raise vimconnNotImplemented( "Should have implemented this" )
262 def refresh_nets_status(self
, net_list
):
263 """Get the status of the networks
265 'net_list': a list with the VIM network id to be get the status
266 Returns a dictionary with:
267 'net_id': #VIM id of this network
268 status: #Mandatory. Text with one of:
269 # DELETED (not found at vim)
270 # VIM_ERROR (Cannot connect to VIM, authentication problems, VIM response error, ...)
271 # OTHER (Vim reported other status not understood)
272 # ERROR (VIM indicates an ERROR status)
273 # ACTIVE, INACTIVE, DOWN (admin down),
274 # BUILD (on building process)
275 error_msg: #Text with VIM error message, if any. Or the VIM connection ERROR
276 vim_info: #Text with plain information obtained from vim (yaml.safe_dump)
279 raise vimconnNotImplemented( "Should have implemented this" )
281 def get_flavor(self
, flavor_id
):
282 """Obtain flavor details from the VIM
283 Returns the flavor dict details {'id':<>, 'name':<>, other vim specific }
284 Raises an exception upon error or if not found
286 raise vimconnNotImplemented( "Should have implemented this" )
288 def get_flavor_id_from_data(self
, flavor_dict
):
289 """Obtain flavor id that match the flavor description
291 'flavor_dict': dictionary that contains:
292 'disk': main hard disk in GB
294 'vcpus': number of virtual cpus
295 #TODO: complete parameters for EPA
296 Returns the flavor_id or raises a vimconnNotFoundException
298 raise vimconnNotImplemented( "Should have implemented this" )
300 def new_flavor(self
, flavor_data
):
301 """Adds a tenant flavor to VIM
302 flavor_data contains a dictionary with information, keys:
304 ram: memory (cloud type) in MBytes
305 vpcus: cpus (cloud type)
306 extended: EPA parameters
307 - numas: #items requested in same NUMA
308 memory: number of 1G huge pages memory
309 paired-threads|cores|threads: number of paired hyperthreads, complete cores OR individual threads
310 interfaces: # passthrough(PT) or SRIOV interfaces attached to this numa
311 - name: interface name
312 dedicated: yes|no|yes:sriov; for PT, SRIOV or only one SRIOV for the physical NIC
313 bandwidth: X Gbps; requested guarantee bandwidth
314 vpci: requested virtual PCI address
318 Returns the flavor identifier"""
319 raise vimconnNotImplemented( "Should have implemented this" )
321 def delete_flavor(self
, flavor_id
):
322 """Deletes a tenant flavor from VIM identify by its id
323 Returns the used id or raise an exception"""
324 raise vimconnNotImplemented( "Should have implemented this" )
326 def new_image(self
, image_dict
):
327 """ Adds a tenant image to VIM
328 Returns the image id or raises an exception if failed
330 raise vimconnNotImplemented( "Should have implemented this" )
332 def delete_image(self
, image_id
):
333 """Deletes a tenant image from VIM
334 Returns the image_id if image is deleted or raises an exception on error"""
335 raise vimconnNotImplemented( "Should have implemented this" )
337 def get_image_id_from_path(self
, path
):
338 """Get the image id from image path in the VIM database.
339 Returns the image_id or raises a vimconnNotFoundException
341 raise vimconnNotImplemented( "Should have implemented this" )
343 def get_image_list(self
, filter_dict
={}):
344 """Obtain tenant images from VIM
348 checksum: image checksum
350 Returns the image list of dictionaries:
351 [{<the fields at Filter_dict plus some VIM specific>}, ...]
354 raise vimconnNotImplemented( "Should have implemented this" )
356 def new_vminstance(self
, name
, description
, start
, image_id
, flavor_id
, net_list
, cloud_config
=None,
358 """Adds a VM instance to VIM
360 'start': (boolean) indicates if VM must start or created in pause mode.
361 'image_id','flavor_id': image and flavor VIM id to use for the VM
362 'net_list': list of interfaces, each one is a dictionary with:
363 'name': (optional) name for the interface.
364 'net_id': VIM network id where this interface must be connect to. Mandatory for type==virtual
365 'vpci': (optional) virtual vPCI address to assign at the VM. Can be ignored depending on VIM capabilities
366 'model': (optional and only have sense for type==virtual) interface model: virtio, e2000, ...
367 'mac_address': (optional) mac address to assign to this interface
368 #TODO: CHECK if an optional 'vlan' parameter is needed for VIMs when type if VF and net_id is not provided,
369 the VLAN tag to be used. In case net_id is provided, the internal network vlan is used for tagging VF
370 'type': (mandatory) can be one of:
371 'virtual', in this case always connected to a network of type 'net_type=bridge'
372 'PF' (passthrough): depending on VIM capabilities it can be connected to a data/ptp network ot it
373 can created unconnected
374 'VF' (SRIOV with VLAN tag): same as PF for network connectivity.
375 'VFnotShared'(SRIOV without VLAN tag) same as PF for network connectivity. VF where no other VFs
376 are allocated on the same physical NIC
377 'bw': (optional) only for PF/VF/VFnotShared. Minimal Bandwidth required for the interface in GBPS
378 'port_security': (optional) If False it must avoid any traffic filtering at this interface. If missing
379 or True, it must apply the default VIM behaviour
380 After execution the method will add the key:
381 'vim_id': must be filled/added by this method with the VIM identifier generated by the VIM for this
382 interface. 'net_list' is modified
383 'cloud_config': (optional) dictionary with:
384 'key-pairs': (optional) list of strings with the public key to be inserted to the default user
385 'users': (optional) list of users to be inserted, each item is a dict with:
386 'name': (mandatory) user name,
387 'key-pairs': (optional) list of strings with the public key to be inserted to the user
388 'user-data': (optional) string is a text script to be passed directly to cloud-init
389 'config-files': (optional). List of files to be transferred. Each item is a dict with:
390 'dest': (mandatory) string with the destination absolute path
391 'encoding': (optional, by default text). Can be one of:
392 'b64', 'base64', 'gz', 'gz+b64', 'gz+base64', 'gzip+b64', 'gzip+base64'
393 'content' (mandatory): string with the content of the file
394 'permissions': (optional) string with file permissions, typically octal notation '0644'
395 'owner': (optional) file owner, string with the format 'owner:group'
396 'boot-data-drive': boolean to indicate if user-data must be passed using a boot drive (hard disk)
397 'disk_list': (optional) list with additional disks to the VM. Each item is a dict with:
398 'image_id': (optional). VIM id of an existing image. If not provided an empty disk must be mounted
399 'size': (mandatory) string with the size of the disk in GB
400 Returns the instance identifier or raises an exception on error
402 raise vimconnNotImplemented( "Should have implemented this" )
404 def get_vminstance(self
,vm_id
):
405 """Returns the VM instance information from VIM"""
406 raise vimconnNotImplemented( "Should have implemented this" )
408 def delete_vminstance(self
, vm_id
):
409 """Removes a VM instance from VIM
410 Returns the instance identifier"""
411 raise vimconnNotImplemented( "Should have implemented this" )
413 def refresh_vms_status(self
, vm_list
):
414 """Get the status of the virtual machines and their interfaces/ports
415 Params: the list of VM identifiers
416 Returns a dictionary with:
417 vm_id: #VIM id of this Virtual Machine
418 status: #Mandatory. Text with one of:
419 # DELETED (not found at vim)
420 # VIM_ERROR (Cannot connect to VIM, VIM response error, ...)
421 # OTHER (Vim reported other status not understood)
422 # ERROR (VIM indicates an ERROR status)
423 # ACTIVE, PAUSED, SUSPENDED, INACTIVE (not running),
424 # BUILD (on building process), ERROR
425 # ACTIVE:NoMgmtIP (Active but any of its interface has an IP address
427 error_msg: #Text with VIM error message, if any. Or the VIM connection ERROR
428 vim_info: #Text with plain information obtained from vim (yaml.safe_dump)
429 interfaces: list with interface info. Each item a dictionary with:
430 vim_info: #Text with plain information obtained from vim (yaml.safe_dump)
431 mac_address: #Text format XX:XX:XX:XX:XX:XX
432 vim_net_id: #network id where this interface is connected, if provided at creation
433 vim_interface_id: #interface/port VIM id
434 ip_address: #null, or text with IPv4, IPv6 address
435 compute_node: #identification of compute node where PF,VF interface is allocated
436 pci: #PCI address of the NIC that hosts the PF,VF
437 vlan: #physical VLAN used for VF
439 raise vimconnNotImplemented( "Should have implemented this" )
441 def action_vminstance(self
, vm_id
, action_dict
):
442 """Send and action over a VM instance from VIM
443 Returns the vm_id if the action was successfully sent to the VIM"""
444 raise vimconnNotImplemented( "Should have implemented this" )
446 def get_vminstance_console(self
, vm_id
, console_type
="vnc"):
448 Get a console for the virtual machine
450 vm_id: uuid of the VM
451 console_type, can be:
452 "novnc" (by default), "xvpvnc" for VNC types,
453 "rdp-html5" for RDP types, "spice-html5" for SPICE types
454 Returns dict with the console parameters:
455 protocol: ssh, ftp, http, https, ...
456 server: usually ip address
457 port: the http, ssh, ... port
458 suffix: extra text, e.g. the http path and query string
460 raise vimconnNotImplemented( "Should have implemented this" )
462 #NOT USED METHODS in current version
464 def host_vim2gui(self
, host
, server_dict
):
465 """Transform host dictionary from VIM format to GUI format,
466 and append to the server_dict
468 raise vimconnNotImplemented( "Should have implemented this" )
470 def get_hosts_info(self
):
471 """Get the information of deployed hosts
472 Returns the hosts content"""
473 raise vimconnNotImplemented( "Should have implemented this" )
475 def get_hosts(self
, vim_tenant
):
476 """Get the hosts and deployed instances
477 Returns the hosts content"""
478 raise vimconnNotImplemented( "Should have implemented this" )
480 def get_processor_rankings(self
):
481 """Get the processor rankings in the VIM database"""
482 raise vimconnNotImplemented( "Should have implemented this" )
484 def new_host(self
, host_data
):
485 """Adds a new host to VIM"""
486 """Returns status code of the VIM response"""
487 raise vimconnNotImplemented( "Should have implemented this" )
489 def new_external_port(self
, port_data
):
490 """Adds a external port to VIM"""
491 """Returns the port identifier"""
492 raise vimconnNotImplemented( "Should have implemented this" )
494 def new_external_network(self
,net_name
,net_type
):
495 """Adds a external network to VIM (shared)"""
496 """Returns the network identifier"""
497 raise vimconnNotImplemented( "Should have implemented this" )
499 def connect_port_network(self
, port_id
, network_id
, admin
=False):
500 """Connects a external port to a network"""
501 """Returns status code of the VIM response"""
502 raise vimconnNotImplemented( "Should have implemented this" )
504 def new_vminstancefromJSON(self
, vm_data
):
505 """Adds a VM instance to VIM"""
506 """Returns the instance identifier"""
507 raise vimconnNotImplemented( "Should have implemented this" )