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 'error_msg': (optional) text that explains the ERROR status
236 other VIM specific fields: (optional) whenever possible using the same naming of filter_dict param
237 List can be empty if no network map the filter_dict. Raise an exception only upon VIM connectivity,
238 authorization, or some other unspecific error
240 raise vimconnNotImplemented( "Should have implemented this" )
242 def get_network(self
, net_id
):
243 """Obtain network details from the 'net_id' VIM network
244 Return a dict that contains:
245 'id': (mandatory) VIM network id, that is, net_id
246 'name': (mandatory) VIM network name
247 'status': (mandatory) can be 'ACTIVE', 'INACTIVE', 'DOWN', 'BUILD', 'ERROR', 'VIM_ERROR', 'OTHER'
248 'error_msg': (optional) text that explains the ERROR status
249 other VIM specific fields: (optional) whenever possible using the same naming of filter_dict param
250 Raises an exception upon error or when network is not found
252 raise vimconnNotImplemented( "Should have implemented this" )
254 def delete_network(self
, net_id
):
255 """Deletes a tenant network from VIM
256 Returns the network identifier or raises an exception upon error or when network is not found
258 raise vimconnNotImplemented( "Should have implemented this" )
260 def refresh_nets_status(self
, net_list
):
261 """Get the status of the networks
263 'net_list': a list with the VIM network id to be get the status
264 Returns a dictionary with:
265 'net_id': #VIM id of this network
266 status: #Mandatory. Text with one of:
267 # DELETED (not found at vim)
268 # VIM_ERROR (Cannot connect to VIM, authentication problems, VIM response error, ...)
269 # OTHER (Vim reported other status not understood)
270 # ERROR (VIM indicates an ERROR status)
271 # ACTIVE, INACTIVE, DOWN (admin down),
272 # BUILD (on building process)
273 error_msg: #Text with VIM error message, if any. Or the VIM connection ERROR
274 vim_info: #Text with plain information obtained from vim (yaml.safe_dump)
277 raise vimconnNotImplemented( "Should have implemented this" )
279 def get_flavor(self
, flavor_id
):
280 """Obtain flavor details from the VIM
281 Returns the flavor dict details {'id':<>, 'name':<>, other vim specific }
282 Raises an exception upon error or if not found
284 raise vimconnNotImplemented( "Should have implemented this" )
286 def get_flavor_id_from_data(self
, flavor_dict
):
287 """Obtain flavor id that match the flavor description
289 'flavor_dict': dictionary that contains:
290 'disk': main hard disk in GB
292 'vcpus': number of virtual cpus
293 #TODO: complete parameters for EPA
294 Returns the flavor_id or raises a vimconnNotFoundException
296 raise vimconnNotImplemented( "Should have implemented this" )
298 def new_flavor(self
, flavor_data
):
299 """Adds a tenant flavor to VIM
300 flavor_data contains a dictionary with information, keys:
302 ram: memory (cloud type) in MBytes
303 vpcus: cpus (cloud type)
304 extended: EPA parameters
305 - numas: #items requested in same NUMA
306 memory: number of 1G huge pages memory
307 paired-threads|cores|threads: number of paired hyperthreads, complete cores OR individual threads
308 interfaces: # passthrough(PT) or SRIOV interfaces attached to this numa
309 - name: interface name
310 dedicated: yes|no|yes:sriov; for PT, SRIOV or only one SRIOV for the physical NIC
311 bandwidth: X Gbps; requested guarantee bandwidth
312 vpci: requested virtual PCI address
316 Returns the flavor identifier"""
317 raise vimconnNotImplemented( "Should have implemented this" )
319 def delete_flavor(self
, flavor_id
):
320 """Deletes a tenant flavor from VIM identify by its id
321 Returns the used id or raise an exception"""
322 raise vimconnNotImplemented( "Should have implemented this" )
324 def new_image(self
, image_dict
):
325 """ Adds a tenant image to VIM
326 Returns the image id or raises an exception if failed
328 raise vimconnNotImplemented( "Should have implemented this" )
330 def delete_image(self
, image_id
):
331 """Deletes a tenant image from VIM
332 Returns the image_id if image is deleted or raises an exception on error"""
333 raise vimconnNotImplemented( "Should have implemented this" )
335 def get_image_id_from_path(self
, path
):
336 """Get the image id from image path in the VIM database.
337 Returns the image_id or raises a vimconnNotFoundException
339 raise vimconnNotImplemented( "Should have implemented this" )
341 def get_image_list(self
, filter_dict
={}):
342 """Obtain tenant images from VIM
346 checksum: image checksum
348 Returns the image list of dictionaries:
349 [{<the fields at Filter_dict plus some VIM specific>}, ...]
352 raise vimconnNotImplemented( "Should have implemented this" )
354 def new_vminstance(self
, name
, description
, start
, image_id
, flavor_id
, net_list
, cloud_config
=None,
356 """Adds a VM instance to VIM
358 'start': (boolean) indicates if VM must start or created in pause mode.
359 'image_id','flavor_id': image and flavor VIM id to use for the VM
360 'net_list': list of interfaces, each one is a dictionary with:
361 'name': (optional) name for the interface.
362 'net_id': VIM network id where this interface must be connect to. Mandatory for type==virtual
363 'vpci': (optional) virtual vPCI address to assign at the VM. Can be ignored depending on VIM capabilities
364 'model': (optional and only have sense for type==virtual) interface model: virtio, e2000, ...
365 'mac_address': (optional) mac address to assign to this interface
366 #TODO: CHECK if an optional 'vlan' parameter is needed for VIMs when type if VF and net_id is not provided,
367 the VLAN tag to be used. In case net_id is provided, the internal network vlan is used for tagging VF
368 'type': (mandatory) can be one of:
369 'virtual', in this case always connected to a network of type 'net_type=bridge'
370 'PF' (passthrough): depending on VIM capabilities it can be connected to a data/ptp network ot it
371 can created unconnected
372 'VF' (SRIOV with VLAN tag): same as PF for network connectivity.
373 'VFnotShared'(SRIOV without VLAN tag) same as PF for network connectivity. VF where no other VFs
374 are allocated on the same physical NIC
375 'bw': (optional) only for PF/VF/VFnotShared. Minimal Bandwidth required for the interface in GBPS
376 'port_security': (optional) If False it must avoid any traffic filtering at this interface. If missing
377 or True, it must apply the default VIM behaviour
378 After execution the method will add the key:
379 'vim_id': must be filled/added by this method with the VIM identifier generated by the VIM for this
380 interface. 'net_list' is modified
381 'cloud_config': (optional) dictionary with:
382 'key-pairs': (optional) list of strings with the public key to be inserted to the default user
383 'users': (optional) list of users to be inserted, each item is a dict with:
384 'name': (mandatory) user name,
385 'key-pairs': (optional) list of strings with the public key to be inserted to the user
386 'user-data': (optional) string is a text script to be passed directly to cloud-init
387 'config-files': (optional). List of files to be transferred. Each item is a dict with:
388 'dest': (mandatory) string with the destination absolute path
389 'encoding': (optional, by default text). Can be one of:
390 'b64', 'base64', 'gz', 'gz+b64', 'gz+base64', 'gzip+b64', 'gzip+base64'
391 'content' (mandatory): string with the content of the file
392 'permissions': (optional) string with file permissions, typically octal notation '0644'
393 'owner': (optional) file owner, string with the format 'owner:group'
394 'boot-data-drive': boolean to indicate if user-data must be passed using a boot drive (hard disk)
395 'disk_list': (optional) list with additional disks to the VM. Each item is a dict with:
396 'image_id': (optional). VIM id of an existing image. If not provided an empty disk must be mounted
397 'size': (mandatory) string with the size of the disk in GB
398 Returns the instance identifier or raises an exception on error
400 raise vimconnNotImplemented( "Should have implemented this" )
402 def get_vminstance(self
,vm_id
):
403 """Returns the VM instance information from VIM"""
404 raise vimconnNotImplemented( "Should have implemented this" )
406 def delete_vminstance(self
, vm_id
):
407 """Removes a VM instance from VIM
408 Returns the instance identifier"""
409 raise vimconnNotImplemented( "Should have implemented this" )
411 def refresh_vms_status(self
, vm_list
):
412 """Get the status of the virtual machines and their interfaces/ports
413 Params: the list of VM identifiers
414 Returns a dictionary with:
415 vm_id: #VIM id of this Virtual Machine
416 status: #Mandatory. Text with one of:
417 # DELETED (not found at vim)
418 # VIM_ERROR (Cannot connect to VIM, VIM response error, ...)
419 # OTHER (Vim reported other status not understood)
420 # ERROR (VIM indicates an ERROR status)
421 # ACTIVE, PAUSED, SUSPENDED, INACTIVE (not running),
422 # BUILD (on building process), ERROR
423 # ACTIVE:NoMgmtIP (Active but any of its interface has an IP address
425 error_msg: #Text with VIM error message, if any. Or the VIM connection ERROR
426 vim_info: #Text with plain information obtained from vim (yaml.safe_dump)
427 interfaces: list with interface info. Each item a dictionary with:
428 vim_info: #Text with plain information obtained from vim (yaml.safe_dump)
429 mac_address: #Text format XX:XX:XX:XX:XX:XX
430 vim_net_id: #network id where this interface is connected, if provided at creation
431 vim_interface_id: #interface/port VIM id
432 ip_address: #null, or text with IPv4, IPv6 address
433 physical_compute: #identification of compute node where PF,VF interface is allocated
434 physical_pci: #PCI address of the NIC that hosts the PF,VF
435 physical_vlan: #physical VLAN used for VF
437 raise vimconnNotImplemented( "Should have implemented this" )
439 def action_vminstance(self
, vm_id
, action_dict
):
440 """Send and action over a VM instance from VIM
441 Returns the vm_id if the action was successfully sent to the VIM"""
442 raise vimconnNotImplemented( "Should have implemented this" )
444 def get_vminstance_console(self
, vm_id
, console_type
="vnc"):
446 Get a console for the virtual machine
448 vm_id: uuid of the VM
449 console_type, can be:
450 "novnc" (by default), "xvpvnc" for VNC types,
451 "rdp-html5" for RDP types, "spice-html5" for SPICE types
452 Returns dict with the console parameters:
453 protocol: ssh, ftp, http, https, ...
454 server: usually ip address
455 port: the http, ssh, ... port
456 suffix: extra text, e.g. the http path and query string
458 raise vimconnNotImplemented( "Should have implemented this" )
460 #NOT USED METHODS in current version
462 def host_vim2gui(self
, host
, server_dict
):
463 """Transform host dictionary from VIM format to GUI format,
464 and append to the server_dict
466 raise vimconnNotImplemented( "Should have implemented this" )
468 def get_hosts_info(self
):
469 """Get the information of deployed hosts
470 Returns the hosts content"""
471 raise vimconnNotImplemented( "Should have implemented this" )
473 def get_hosts(self
, vim_tenant
):
474 """Get the hosts and deployed instances
475 Returns the hosts content"""
476 raise vimconnNotImplemented( "Should have implemented this" )
478 def get_processor_rankings(self
):
479 """Get the processor rankings in the VIM database"""
480 raise vimconnNotImplemented( "Should have implemented this" )
482 def new_host(self
, host_data
):
483 """Adds a new host to VIM"""
484 """Returns status code of the VIM response"""
485 raise vimconnNotImplemented( "Should have implemented this" )
487 def new_external_port(self
, port_data
):
488 """Adds a external port to VIM"""
489 """Returns the port identifier"""
490 raise vimconnNotImplemented( "Should have implemented this" )
492 def new_external_network(self
,net_name
,net_type
):
493 """Adds a external network to VIM (shared)"""
494 """Returns the network identifier"""
495 raise vimconnNotImplemented( "Should have implemented this" )
497 def connect_port_network(self
, port_id
, network_id
, admin
=False):
498 """Connects a external port to a network"""
499 """Returns status code of the VIM response"""
500 raise vimconnNotImplemented( "Should have implemented this" )
502 def new_vminstancefromJSON(self
, vm_data
):
503 """Adds a VM instance to VIM"""
504 """Returns the instance identifier"""
505 raise vimconnNotImplemented( "Should have implemented this" )