Coverage for manila/share/driver.py: 86%

1# Copyright 2012 NetApp 

2# Copyright 2015 Mirantis inc. 

3# All Rights Reserved. 

4# 

5# Licensed under the Apache License, Version 2.0 (the "License"); you may 

6# not use this file except in compliance with the License. You may obtain 

7# a copy of the License at 

8# 

9# http://www.apache.org/licenses/LICENSE-2.0 

10# 

11# Unless required by applicable law or agreed to in writing, software 

12# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 

13# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 

14# License for the specific language governing permissions and limitations 

15# under the License. 

16""" 

17Drivers for shares. 

18 

19""" 

20 

21import time 

22 

23from oslo_config import cfg 

24from oslo_config import types 

25from oslo_log import log 

26 

27from manila.common import constants 

28from manila import exception 

29from manila.i18n import _ 

30from manila import network 

31from manila import utils 

32 

33LOG = log.getLogger(__name__) 

34 

35share_opts = [ 

36 # NOTE(rushiagr): Reasonable to define this option at only one place. 

37 cfg.IntOpt( 

38 'num_shell_tries', 

39 default=3, 

40 help='Number of times to attempt to run flakey shell commands.'), 

41 cfg.IntOpt( 

42 'reserved_share_percentage', 

43 default=0, 

44 help="The percentage of backend capacity reserved. Used for shares " 

45 "which are not created from the snapshot."), 

46 cfg.IntOpt( 

47 'reserved_share_from_snapshot_percentage', 

48 default=0, 

49 help="The percentage of backend capacity reserved. Used for shares " 

50 "created from the snapshot. On some platforms, shares can only " 

51 "be created from the snapshot on the host where snapshot was " 

52 "taken, so we can set a lower value in this option compared to " 

53 "reserved_share_percentage, and allow to create shares from the " 

54 "snapshot on the same host up to a higher threshold."), 

55 cfg.IntOpt( 

56 'reserved_share_extend_percentage', 

57 default=0, 

58 help="The percentage of backend capacity reserved for share extend " 

59 "operation. When existing limit of 'reserved_share_percentage' " 

60 "is hit, we do not want user to create a new share but existing " 

61 "shares can be extended based on value of this parameter."), 

62 cfg.StrOpt( 

63 'share_backend_name', 

64 help='The backend name for a given driver implementation.'), 

65 cfg.StrOpt( 

66 'network_config_group', 

67 help="Name of the configuration group in the Manila conf file " 

68 "to look for network config options." 

69 "If not set, the share backend's config group will be used." 

70 "If an option is not found within provided group, then " 

71 "'DEFAULT' group will be used for search of option."), 

72 cfg.BoolOpt( 

73 'driver_handles_share_servers', 

74 help="There are two possible approaches for share drivers in Manila. " 

75 "First is when share driver is able to handle share-servers and " 

76 "second when not. Drivers can support either both or only one " 

77 "of these approaches. So, set this opt to True if share driver " 

78 "is able to handle share servers and it is desired mode else set " 

79 "False. It is set to None by default to make this choice " 

80 "intentional."), 

81 cfg.FloatOpt( 

82 'max_over_subscription_ratio', 

83 default=20.0, 

84 min=1.0, 

85 help='Float representation of the over subscription ratio ' 

86 'when thin provisioning is involved. Default ratio is ' 

87 '20.0, meaning provisioned capacity can be 20 times ' 

88 'the total physical capacity. If the ratio is 10.5, it ' 

89 'means provisioned capacity can be 10.5 times the ' 

90 'total physical capacity. A ratio of 1.0 means ' 

91 'provisioned capacity cannot exceed the total physical ' 

92 'capacity. A ratio lower than 1.0 is invalid.'), 

93 cfg.ListOpt( 

94 'migration_ignore_files', 

95 default=['lost+found'], 

96 help="List of files and folders to be ignored when migrating shares. " 

97 "Items should be names (not including any path)."), 

98 cfg.StrOpt( 

99 'share_mount_template', 

100 default='mount -vt %(proto)s %(options)s %(export)s %(path)s', 

101 help="The template for mounting shares for this backend. Must specify " 

102 "the executable with all necessary parameters for the protocol " 

103 "supported. 'proto' template element may not be required if " 

104 "included in the command. 'export' and 'path' template elements " 

105 "are required. It is advisable to separate different commands " 

106 "per backend."), 

107 cfg.StrOpt( 

108 'share_unmount_template', 

109 default='umount -v %(path)s', 

110 help="The template for unmounting shares for this backend. Must " 

111 "specify the executable with all necessary parameters for the " 

112 "protocol supported. 'path' template element is required. It is " 

113 "advisable to separate different commands per backend."), 

114 cfg.Opt( 

115 'protocol_access_mapping', 

116 type=types.Dict(types.List(types.String(), bounds=True)), 

117 default={ 

118 'ip': ['nfs'], 

119 'user': ['cifs'], 

120 }, 

121 help="Protocol access mapping for this backend. Should be a " 

122 "dictionary comprised of " 

123 "{'access_type1': ['share_proto1', 'share_proto2']," 

124 " 'access_type2': ['share_proto2', 'share_proto3']}."), 

125 cfg.StrOpt( 

126 "admin_network_config_group", 

127 help="If share driver requires to setup admin network for share, then " 

128 "define network plugin config options in some separate config " 

129 "group and set its name here. Used only with another " 

130 "option 'driver_handles_share_servers' set to 'True'."), 

131 # Replication option/s 

132 cfg.StrOpt( 

133 "replication_domain", 

134 help="A string specifying the replication domain that the backend " 

135 "belongs to. This option needs to be specified the same in the " 

136 "configuration sections of all backends that support " 

137 "replication between each other. If this option is not " 

138 "specified in the group, it means that replication is not " 

139 "enabled on the backend."), 

140 cfg.StrOpt('backend_availability_zone', 

141 default=None, 

142 help='Availability zone for this share backend. If not set, ' 

143 'the ``storage_availability_zone`` option from the ' 

144 '``[DEFAULT]`` section is used.'), 

145 cfg.StrOpt('filter_function', 

146 help='String representation for an equation that will be ' 

147 'used to filter hosts.'), 

148 cfg.StrOpt('goodness_function', 

149 help='String representation for an equation that will be ' 

150 'used to determine the goodness of a host.'), 

151 cfg.IntOpt('max_shares_per_share_server', 

152 default=-1, 

153 help="Maximum number of share instances created in a share " 

154 "server."), 

155 cfg.IntOpt('max_share_server_size', 

156 default=-1, 

157 help="Maximum sum of gigabytes a share server can have " 

158 "considering all its share instances and snapshots.") 

159] 

160 

161ssh_opts = [ 

162 cfg.IntOpt( 

163 'ssh_conn_timeout', 

164 default=60, 

165 help='Backend server SSH connection timeout.'), 

166 cfg.IntOpt( 

167 'ssh_min_pool_conn', 

168 default=1, 

169 help='Minimum number of connections in the SSH pool.'), 

170 cfg.IntOpt( 

171 'ssh_max_pool_conn', 

172 default=10, 

173 help='Maximum number of connections in the SSH pool.'), 

174] 

175 

176ganesha_opts = [ 

177 cfg.StrOpt('ganesha_config_dir', 

178 default='/etc/ganesha', 

179 help='Directory where Ganesha config files are stored.'), 

180 cfg.StrOpt('ganesha_config_path', 

181 default='$ganesha_config_dir/ganesha.conf', 

182 help='Path to main Ganesha config file.'), 

183 cfg.StrOpt('ganesha_service_name', 

184 default='ganesha.nfsd', 

185 help='Name of the ganesha nfs service.'), 

186 cfg.StrOpt('ganesha_db_path', 

187 default='$state_path/manila-ganesha.db', 

188 help='Location of Ganesha database file. ' 

189 '(Ganesha module only.)'), 

190 cfg.StrOpt('ganesha_export_dir', 

191 default='$ganesha_config_dir/export.d', 

192 help='Path to directory containing Ganesha export ' 

193 'configuration. (Ganesha module only.)'), 

194 cfg.StrOpt('ganesha_export_template_dir', 

195 default='/etc/manila/ganesha-export-templ.d', 

196 help='Path to directory containing Ganesha export ' 

197 'block templates. (Ganesha module only.)'), 

198 cfg.BoolOpt('ganesha_rados_store_enable', 

199 default=False, 

200 help='Persist Ganesha exports and export counter ' 

201 'in Ceph RADOS objects, highly available storage.'), 

202 cfg.StrOpt('ganesha_rados_store_pool_name', 

203 help='Name of the Ceph RADOS pool to store Ganesha exports ' 

204 'and export counter.'), 

205 cfg.StrOpt('ganesha_rados_export_counter', 

206 default='ganesha-export-counter', 

207 help='Name of the Ceph RADOS object used as the Ganesha ' 

208 'export counter.'), 

209 cfg.StrOpt('ganesha_rados_export_index', 

210 default='ganesha-export-index', 

211 help='Name of the Ceph RADOS object used to store a list ' 

212 'of the export RADOS object URLS.'), 

213] 

214 

215CONF = cfg.CONF 

216CONF.register_opts(share_opts) 

217CONF.register_opts(ssh_opts) 

218CONF.register_opts(ganesha_opts) 

219 

220 

221class ExecuteMixin(object): 

222 """Provides an executable functionality to a driver class.""" 

223 

224 def init_execute_mixin(self, *args, **kwargs): 

225 if self.configuration: 225 ↛ 227line 225 didn't jump to line 227 because the condition on line 225 was always true

226 self.configuration.append_config_values(ssh_opts) 

227 self.set_execute(kwargs.pop('execute', utils.execute)) 

228 

229 def set_execute(self, execute): 

230 self._execute = execute 

231 

232 def _try_execute(self, *command, **kwargs): 

233 # NOTE(vish): Volume commands can partially fail due to timing, but 

234 # running them a second time on failure will usually 

235 # recover nicely. 

236 tries = 0 

237 while True: 

238 try: 

239 self._execute(*command, **kwargs) 

240 return True 

241 except exception.ProcessExecutionError: 

242 tries += 1 

243 if tries >= self.configuration.num_shell_tries: 

244 raise 

245 LOG.exception("Recovering from a failed execute. " 

246 "Try number %s", tries) 

247 time.sleep(tries ** 2) 

248 

249 

250class GaneshaMixin(object): 

251 """Augment derived classes with Ganesha configuration.""" 

252 

253 def init_ganesha_mixin(self, *args, **kwargs): 

254 if self.configuration: 254 ↛ exitline 254 didn't return from function 'init_ganesha_mixin' because the condition on line 254 was always true

255 self.configuration.append_config_values(ganesha_opts) 

256 

257 

258class ShareDriver(object): 

259 """Class defines interface of NAS driver.""" 

260 

261 def __init__(self, driver_handles_share_servers, *args, **kwargs): 

262 """Implements base functionality for share drivers. 

263 

264 :param driver_handles_share_servers: expected boolean value or 

265 tuple/list/set of boolean values. 

266 There are two possible approaches for share drivers in Manila. 

267 First is when share driver is able to handle share-servers and 

268 second when not. 

269 Drivers can support either both (indicated by a tuple/set/list with 

270 (True, False)) or only one of these approaches. So, it is allowed 

271 to be 'True' when share driver does support handling of share 

272 servers and allowed to be 'False' when it does support usage of 

273 unhandled share-servers that are not tracked by Manila. 

274 Share drivers are allowed to work only in one of two possible 

275 driver modes, that is why only one should be chosen. 

276 :param config_opts: tuple, list or set of config option lists 

277 that should be registered in driver's configuration right after 

278 this attribute is created. Useful for usage with mixin classes. 

279 """ 

280 super(ShareDriver, self).__init__() 

281 self.configuration = kwargs.get('configuration', None) 

282 self.initialized = False 

283 self._stats = {} 

284 self.ip_versions = None 

285 self.ipv6_implemented = False 

286 # Indicates whether a driver supports update of security services for 

287 # in-use share networks. This property will be saved in every new share 

288 # server. 

289 self.security_service_update_support = False 

290 # Indicates whether a driver supports adding subnet with its 

291 # allocations to an in-use share network availability zone. This 

292 # property will be saved in every new share server. 

293 self.restore_to_target_support = False 

294 # Indicates whether a driver supports out of place restores 

295 # to a share other then the source of a given backup. 

296 self.network_allocation_update_support = False 

297 self.dhss_mandatory_security_service_association = {} 

298 self.share_replicas_migration_support = False 

299 self.encryption_support = None 

300 

301 self.pools = [] 

302 if self.configuration: 

303 self.configuration.append_config_values(share_opts) 

304 network_config_group = (self.configuration.network_config_group or 

305 self.configuration.config_group) 

306 admin_network_config_group = ( 

307 self.configuration.admin_network_config_group) 

308 else: 

309 network_config_group = None 

310 admin_network_config_group = ( 

311 CONF.admin_network_config_group) 

312 

313 self._verify_share_server_handling(driver_handles_share_servers) 

314 if self.driver_handles_share_servers: 

315 # Enable common network 

316 self.network_api = network.API( 

317 config_group_name=network_config_group) 

318 

319 # Enable admin network 

320 if admin_network_config_group: 

321 self._admin_network_api = network.API( 

322 config_group_name=admin_network_config_group, 

323 label='admin') 

324 

325 for config_opt_set in kwargs.get('config_opts', []): 

326 self.configuration.append_config_values(config_opt_set) 

327 

328 if hasattr(self, 'init_execute_mixin'): 

329 # Instance with 'ExecuteMixin' 

330 # pylint: disable=no-member 

331 self.init_execute_mixin(*args, **kwargs) 

332 if hasattr(self, 'init_ganesha_mixin'): 

333 # Instance with 'GaneshaMixin' 

334 # pylint: disable=no-member 

335 self.init_ganesha_mixin(*args, **kwargs) 

336 

337 @property 

338 def admin_network_api(self): 

339 if hasattr(self, '_admin_network_api'): 

340 return self._admin_network_api 

341 

342 @property 

343 def driver_handles_share_servers(self): 

344 if self.configuration: 

345 return self.configuration.safe_get('driver_handles_share_servers') 

346 return CONF.driver_handles_share_servers 

347 

348 @property 

349 def replication_domain(self): 

350 if self.configuration: 350 ↛ 352line 350 didn't jump to line 352 because the condition on line 350 was always true

351 return self.configuration.safe_get('replication_domain') 

352 return CONF.replication_domain 

353 

354 @property 

355 def max_shares_per_share_server(self): 

356 if self.configuration: 356 ↛ 359line 356 didn't jump to line 359 because the condition on line 356 was always true

357 return self.configuration.safe_get( 

358 'max_shares_per_share_server') or -1 

359 return CONF.max_shares_per_share_server 

360 

361 @property 

362 def max_share_server_size(self): 

363 if self.configuration: 363 ↛ 365line 363 didn't jump to line 365 because the condition on line 363 was always true

364 return self.configuration.safe_get('max_share_server_size') or -1 

365 return CONF.max_share_server_size 

366 

367 def _verify_share_server_handling(self, driver_handles_share_servers): 

368 """Verifies driver_handles_share_servers and given configuration.""" 

369 if not isinstance(self.driver_handles_share_servers, bool): 

370 raise exception.ManilaException( 

371 "Config opt 'driver_handles_share_servers' has improper " 

372 "value - '%s'. Please define it as boolean." % 

373 self.driver_handles_share_servers) 

374 elif isinstance(driver_handles_share_servers, bool): 

375 driver_handles_share_servers = [driver_handles_share_servers] 

376 elif not isinstance(driver_handles_share_servers, (tuple, list, set)): 376 ↛ 377line 376 didn't jump to line 377 because the condition on line 376 was never true

377 raise exception.ManilaException( 

378 "Improper data provided for 'driver_handles_share_servers' - " 

379 "%s" % driver_handles_share_servers) 

380 

381 if any(not isinstance(v, bool) for v in driver_handles_share_servers): 

382 raise exception.ManilaException( 

383 "Provided wrong data: %s" % driver_handles_share_servers) 

384 

385 if (self.driver_handles_share_servers not in 

386 driver_handles_share_servers): 

387 raise exception.ManilaException( 

388 "Driver does not support mode 'driver_handles_share_servers=" 

389 "%(actual)s'. It can be used only with value '%(allowed)s'." % 

390 {'actual': self.driver_handles_share_servers, 

391 'allowed': driver_handles_share_servers}) 

392 

393 def migration_check_compatibility( 

394 self, context, source_share, destination_share, 

395 share_server=None, destination_share_server=None): 

396 """Checks destination compatibility for migration of a given share. 

397 

398 .. note:: 

399 Is called to test compatibility with destination backend. 

400 

401 Driver should check if it is compatible with destination backend so 

402 driver-assisted migration can proceed. 

403 

404 :param context: The 'context.RequestContext' object for the request. 

405 :param source_share: Reference to the share to be migrated. 

406 :param destination_share: Reference to the share model to be used by 

407 migrated share. 

408 :param share_server: Share server model or None. 

409 :param destination_share_server: Destination Share server model or 

410 None. 

411 :return: A dictionary containing values indicating if destination 

412 backend is compatible, if share can remain writable during 

413 migration, if it can preserve all file metadata and if it can 

414 perform migration of given share non-disruptively. 

415 

416 Example:: 

417 

418 { 

419 'compatible': True, 

420 'writable': True, 

421 'preserve_metadata': True, 

422 'nondisruptive': True, 

423 'preserve_snapshots': True, 

424 } 

425 

426 """ 

427 return { 

428 'compatible': False, 

429 'writable': False, 

430 'preserve_metadata': False, 

431 'nondisruptive': False, 

432 'preserve_snapshots': False, 

433 } 

434 

435 def migration_start( 

436 self, context, source_share, destination_share, 

437 source_snapshots, snapshot_mappings, share_server=None, 

438 destination_share_server=None): 

439 """Starts migration of a given share to another host. 

440 

441 .. note:: 

442 Is called in source share's backend to start migration. 

443 

444 Driver should implement this method if willing to perform migration 

445 in a driver-assisted way, useful for when source share's backend driver 

446 is compatible with destination backend driver. This method should 

447 start the migration procedure in the backend and end. Following steps 

448 should be done in 'migration_continue'. 

449 

450 :param context: The 'context.RequestContext' object for the request. 

451 :param source_share: Reference to the original share model. 

452 :param destination_share: Reference to the share model to be used by 

453 migrated share. 

454 :param source_snapshots: List of snapshots owned by the source share. 

455 :param snapshot_mappings: Mapping of source snapshot IDs to 

456 destination snapshot models. 

457 :param share_server: Share server model or None. 

458 :param destination_share_server: Destination Share server model or 

459 None. 

460 """ 

461 raise NotImplementedError() 

462 

463 def migration_continue( 

464 self, context, source_share, destination_share, source_snapshots, 

465 snapshot_mappings, share_server=None, 

466 destination_share_server=None): 

467 """Continues migration of a given share to another host. 

468 

469 .. note:: 

470 Is called in source share's backend to continue migration. 

471 

472 Driver should implement this method to continue monitor the migration 

473 progress in storage and perform following steps until 1st phase is 

474 completed. 

475 

476 :param context: The 'context.RequestContext' object for the request. 

477 :param source_share: Reference to the original share model. 

478 :param destination_share: Reference to the share model to be used by 

479 migrated share. 

480 :param source_snapshots: List of snapshots owned by the source share. 

481 :param snapshot_mappings: Mapping of source snapshot IDs to 

482 destination snapshot models. 

483 :param share_server: Share server model or None. 

484 :param destination_share_server: Destination Share server model or 

485 None. 

486 :return: Boolean value to indicate if 1st phase is finished. 

487 """ 

488 raise NotImplementedError() 

489 

490 def migration_complete( 

491 self, context, source_share, destination_share, source_snapshots, 

492 snapshot_mappings, share_server=None, 

493 destination_share_server=None): 

494 """Completes migration of a given share to another host. 

495 

496 .. note:: 

497 Is called in source share's backend to complete migration. 

498 

499 If driver is implementing 2-phase migration, this method should 

500 perform the disruptive tasks related to the 2nd phase of migration, 

501 thus completing it. Driver should also delete all original share data 

502 from source backend. 

503 

504 :param context: The 'context.RequestContext' object for the request. 

505 :param source_share: Reference to the original share model. 

506 :param destination_share: Reference to the share model to be used by 

507 migrated share. 

508 :param source_snapshots: List of snapshots owned by the source share. 

509 :param snapshot_mappings: Mapping of source snapshot IDs to 

510 destination snapshot models. 

511 :param share_server: Share server model or None. 

512 :param destination_share_server: Destination Share server model or 

513 None. 

514 :return: If the migration changes the share export locations, snapshot 

515 provider locations or snapshot export locations, this method should 

516 return a dictionary with the relevant info. In such case, a 

517 dictionary containing a list of export locations and a list of 

518 model updates for each snapshot indexed by their IDs. 

519 

520 Example:: 

521 

522 { 

523 'export_locations': 

524 [ 

525 { 

526 'path': '1.2.3.4:/foo', 

527 'metadata': {}, 

528 'is_admin_only': False 

529 }, 

530 { 

531 'path': '5.6.7.8:/foo', 

532 'metadata': {}, 

533 'is_admin_only': True 

534 }, 

535 ], 

536 'snapshot_updates': 

537 { 

538 'bc4e3b28-0832-4168-b688-67fdc3e9d408': 

539 { 

540 'provider_location': '/snapshots/foo/bar_1', 

541 'export_locations': 

542 [ 

543 { 

544 'path': '1.2.3.4:/snapshots/foo/bar_1', 

545 'is_admin_only': False, 

546 }, 

547 { 

548 'path': '5.6.7.8:/snapshots/foo/bar_1', 

549 'is_admin_only': True, 

550 }, 

551 ], 

552 }, 

553 '2e62b7ea-4e30-445f-bc05-fd523ca62941': 

554 { 

555 'provider_location': '/snapshots/foo/bar_2', 

556 'export_locations': 

557 [ 

558 { 

559 'path': '1.2.3.4:/snapshots/foo/bar_2', 

560 'is_admin_only': False, 

561 }, 

562 { 

563 'path': '5.6.7.8:/snapshots/foo/bar_2', 

564 'is_admin_only': True, 

565 }, 

566 ], 

567 }, 

568 }, 

569 } 

570 

571 """ 

572 raise NotImplementedError() 

573 

574 def migration_cancel( 

575 self, context, source_share, destination_share, source_snapshots, 

576 snapshot_mappings, share_server=None, 

577 destination_share_server=None): 

578 """Cancels migration of a given share to another host. 

579 

580 .. note:: 

581 Is called in source share's backend to cancel migration. 

582 

583 If possible, driver can implement a way to cancel an in-progress 

584 migration. 

585 

586 :param context: The 'context.RequestContext' object for the request. 

587 :param source_share: Reference to the original share model. 

588 :param destination_share: Reference to the share model to be used by 

589 migrated share. 

590 :param source_snapshots: List of snapshots owned by the source share. 

591 :param snapshot_mappings: Mapping of source snapshot IDs to 

592 destination snapshot models. 

593 :param share_server: Share server model or None. 

594 :param destination_share_server: Destination Share server model or 

595 None. 

596 """ 

597 raise NotImplementedError() 

598 

599 def transfer_accept(self, context, share, new_user, new_project, 

600 access_rules=None, share_server=None): 

601 """Backend update project and user info if stored on the backend. 

602 

603 :param context: The 'context.RequestContext' object for the request. 

604 :param share: Share instance model. 

605 :param access_rules: A list of access rules for given share. 

606 :param new_user: the share will be updated with the new user id . 

607 :param new_project: the share will be updated with the new project id. 

608 :param share_server: share server for given share. 

609 """ 

610 pass 

611 

612 def migration_get_progress( 

613 self, context, source_share, destination_share, source_snapshots, 

614 snapshot_mappings, share_server=None, 

615 destination_share_server=None): 

616 """Obtains progress of migration of a given share to another host. 

617 

618 .. note:: 

619 Is called in source share's backend to obtain migration progress. 

620 

621 If possible, driver can implement a way to return migration progress 

622 information. 

623 

624 :param context: The 'context.RequestContext' object for the request. 

625 :param source_share: Reference to the original share model. 

626 :param destination_share: Reference to the share model to be used by 

627 migrated share. 

628 :param source_snapshots: List of snapshots owned by the source share. 

629 :param snapshot_mappings: Mapping of source snapshot IDs to 

630 destination snapshot models. 

631 :param share_server: Share server model or None. 

632 :param destination_share_server: Destination Share server model or 

633 None. 

634 :return: A dictionary with at least 'total_progress' field containing 

635 the percentage value. 

636 """ 

637 raise NotImplementedError() 

638 

639 def connection_get_info(self, context, share, share_server=None): 

640 """Is called to provide necessary generic migration logic. 

641 

642 :param context: The 'context.RequestContext' object for the request. 

643 :param share: Reference to the share being migrated. 

644 :param share_server: Share server model or None. 

645 :return: A dictionary with migration information. 

646 """ 

647 mount_template = self._get_mount_command(context, share, share_server) 

648 

649 unmount_template = self._get_unmount_command(context, share, 

650 share_server) 

651 

652 access_mapping = self._get_access_mapping(context, share, share_server) 

653 

654 info = { 

655 'mount': mount_template, 

656 'unmount': unmount_template, 

657 'access_mapping': access_mapping, 

658 } 

659 

660 LOG.debug("Migration info obtained for share %(share_id)s: %(info)s.", 

661 {'share_id': share['id'], 'info': str(info)}) 

662 

663 return info 

664 

665 def _get_access_mapping(self, context, share, share_server): 

666 

667 mapping = self.configuration.safe_get('protocol_access_mapping') or {} 

668 result = {} 

669 share_proto = share['share_proto'].lower() 

670 for access_type, protocols in mapping.items(): 

671 if share_proto in [y.lower() for y in protocols]: 

672 result[access_type] = result.get(access_type, []) 

673 result[access_type].append(share_proto) 

674 return result 

675 

676 def _get_mount_command(self, context, share_instance, share_server=None): 

677 """Is called to delegate mounting share logic.""" 

678 

679 mount_template = self.configuration.safe_get('share_mount_template') 

680 

681 mount_export = self._get_mount_export(share_instance, share_server) 

682 

683 format_template = { 

684 'proto': share_instance['share_proto'].lower(), 

685 'export': mount_export, 

686 'path': '%(path)s', 

687 'options': '%(options)s', 

688 } 

689 

690 return mount_template % format_template 

691 

692 def _get_mount_export(self, share_instance, share_server=None): 

693 # NOTE(ganso): If drivers want to override the export_location IP, 

694 # they can do so using this configuration. This method can also be 

695 # overridden if necessary. 

696 path = next((x['path'] for x in share_instance['export_locations'] 

697 if x['is_admin_only']), None) 

698 if not path: 

699 path = share_instance['export_locations'][0]['path'] 

700 return path 

701 

702 def _get_unmount_command(self, context, share_instance, 

703 share_server=None): 

704 return self.configuration.safe_get('share_unmount_template') 

705 

706 def create_share(self, context, share, share_server=None): 

707 """Is called to create share.""" 

708 raise NotImplementedError() 

709 

710 def create_share_from_snapshot(self, context, share, snapshot, 

711 share_server=None, parent_share=None): 

712 """Is called to create share from snapshot. 

713 

714 Creating a share from snapshot can take longer than a simple clone 

715 operation if data copy is required from one host to another. For this 

716 reason driver will be able complete this creation asynchronously, by 

717 providing a 'creating_from_snapshot' status in the model update. 

718 

719 When answering asynchronously, drivers must implement the call 

720 'get_share_status' in order to provide updates for shares with 

721 'creating_from_snapshot' status. 

722 

723 It is expected that the driver returns a model update to the share 

724 manager that contains: share status and a list of export_locations. 

725 A list of 'export_locations' is mandatory only for share in 'available' 

726 status. 

727 The current supported status are 'available' and 

728 'creating_from_snapshot'. 

729 

730 :param context: Current context 

731 :param share: Share instance model with share data. 

732 :param snapshot: Snapshot instance model . 

733 :param share_server: Share server model or None. 

734 :param parent_share: Share model from parent snapshot with share data 

735 and share server model. 

736 

737 :returns: a dictionary of updates containing current share status and 

738 its export_location (if available). 

739 

740 Example:: 

741 

742 { 

743 'status': 'available', 

744 'export_locations': [{...}, {...}], 

745 } 

746 

747 :raises: ShareBackendException. 

748 A ShareBackendException in this method will set the instance to 

749 'error' and the operation will end. 

750 """ 

751 raise NotImplementedError() 

752 

753 def create_snapshot(self, context, snapshot, share_server=None): 

754 """Is called to create snapshot. 

755 

756 :param context: Current context 

757 :param snapshot: Snapshot model. Share model could be 

758 retrieved through snapshot['share']. 

759 :param share_server: Share server model or None. 

760 :return: None or a dictionary with key 'export_locations' containing 

761 a list of export locations, if snapshots can be mounted. 

762 """ 

763 raise NotImplementedError() 

764 

765 def delete_share(self, context, share, share_server=None): 

766 """Is called to remove share.""" 

767 raise NotImplementedError() 

768 

769 def delete_snapshot(self, context, snapshot, share_server=None): 

770 """Is called to remove snapshot. 

771 

772 :param context: Current context 

773 :param snapshot: Snapshot model. Share model could be 

774 retrieved through snapshot['share']. 

775 :param share_server: Share server model or None. 

776 """ 

777 raise NotImplementedError() 

778 

779 def get_pool(self, share): 

780 """Return pool name where the share resides on. 

781 

782 :param share: The share hosted by the driver. 

783 """ 

784 

785 def ensure_share(self, context, share, share_server=None): 

786 """Invoked to ensure that share is exported. 

787 

788 Driver can use this method to update the list of export locations of 

789 the share if it changes. To do that, you should return list with 

790 export locations. 

791 

792 It is preferred if the driver implements "get_backend_info" and 

793 "ensure_shares" instead of this routine. 

794 

795 :return: None or list with export locations 

796 """ 

797 raise NotImplementedError() 

798 

799 def allow_access(self, context, share, access, share_server=None): 

800 """Allow access to the share.""" 

801 raise NotImplementedError() 

802 

803 def deny_access(self, context, share, access, share_server=None): 

804 """Deny access to the share.""" 

805 raise NotImplementedError() 

806 

807 def update_access(self, context, share, access_rules, add_rules, 

808 delete_rules, update_rules, share_server=None): 

809 """Update access rules for given share. 

810 

811 ``access_rules`` contains all access_rules that need to be on the 

812 share. If the driver can make bulk access rule updates, it can 

813 safely ignore the ``add_rules`` and ``delete_rules`` parameters. 

814 

815 If the driver cannot make bulk access rule changes, it can rely on 

816 new rules to be present in ``add_rules`` and rules that need to be 

817 removed to be present in ``delete_rules``. 

818 

819 When a rule in ``delete_rules`` was never applied, drivers must not 

820 raise an exception, or attempt to set the rule to ``error`` state. 

821 

822 ``add_rules`` and ``delete_rules`` can be empty lists, in this 

823 situation, drivers should ensure that the rules present in 

824 ``access_rules`` are the same as those on the back end. One scenario 

825 where this situation is forced is when the access_level is changed for 

826 all existing rules (share migration and for readable replicas). 

827 

828 Drivers must be mindful of this call for share replicas. When 

829 'update_access' is called on one of the replicas, the call is likely 

830 propagated to all replicas belonging to the share, especially when 

831 individual rules are added or removed. If a particular access rule 

832 does not make sense to the driver in the context of a given replica, 

833 the driver should be careful to report a correct behavior, and take 

834 meaningful action. For example, if R/W access is requested on a 

835 replica that is part of a "readable" type replication; R/O access 

836 may be added by the driver instead of R/W. Note that raising an 

837 exception *will* result in the access_rules_status on the replica, 

838 and the share itself being "out_of_sync". Drivers can sync on the 

839 valid access rules that are provided on the ``create_replica`` and 

840 ``promote_replica`` calls. 

841 

842 :param context: Current context 

843 :param share: Share model with share data. 

844 :param access_rules: A list of access rules for given share 

845 :param add_rules: Empty List or List of access rules which should be 

846 added. access_rules already contains these rules. 

847 :param delete_rules: Empty List or List of access rules which should be 

848 removed. access_rules doesn't contain these rules. 

849 :param update_rules: Empty List or List of access rules which should be 

850 updated. access_rules already contains these rules. 

851 :param share_server: None or Share server model 

852 :returns: None, or a dictionary of updates in the format:: 

853 

854 { 

855 

856 '09960614-8574-4e03-89cf-7cf267b0bd08': { 

857 

858 'access_key': 'alice31493e5441b8171d2310d80e37e', 

859 'state': 'error', 

860 

861 }, 

862 

863 '28f6eabb-4342-486a-a7f4-45688f0c0295': { 

864 

865 'access_key': 'bob0078aa042d5a7325480fd13228b', 

866 'state': 'active', 

867 

868 }, 

869 

870 } 

871 

872 The top level keys are 'access_id' fields of the access rules that 

873 need to be updated. ``access_key``s are credentials (str) of the 

874 entities granted access. Any rule in the ``access_rules`` parameter 

875 can be updated. 

876 

877 .. important:: 

878 

879 Raising an exception in this method will force *all* rules in 

880 'applying' and 'denying' states to 'error'. 

881 

882 An access rule can be set to 'error' state, either explicitly 

883 via this return parameter or because of an exception raised in 

884 this method. Such an access rule will no longer be sent to the 

885 driver on subsequent access rule updates. When users deny that 

886 rule however, the driver will be asked to deny access to the 

887 client/s represented by the rule. We expect that a 

888 rule that was error-ed at the driver should never exist on the 

889 back end. So, do not fail the deletion request. 

890 

891 Also, it is possible that the driver may receive a request to 

892 add a rule that is already present on the back end. 

893 This can happen if the share manager service goes down 

894 while the driver is committing access rule changes. Since we 

895 cannot determine if the rule was applied successfully by the driver 

896 before the disruption, we will treat all 'applying' transitional 

897 rules as new rules and repeat the request. 

898 """ 

899 raise NotImplementedError() 

900 

901 def check_for_setup_error(self): 

902 """Check for setup error.""" 

903 pass 

904 

905 def do_setup(self, context): 

906 """Any initialization the share driver does while starting.""" 

907 

908 def get_share_stats(self, refresh=False): 

909 """Get share status. 

910 

911 If 'refresh' is True, run update the stats first. 

912 """ 

913 if refresh: 

914 self._update_share_stats() 

915 

916 return self._stats 

917 

918 def get_network_allocations_number(self): 

919 """Returns number of network allocations for creating VIFs. 

920 

921 Drivers that use Nova for share servers should return zero (0) here 

922 same as Generic driver does. 

923 Because Nova will handle network resources allocation. 

924 Drivers that handle networking itself should calculate it according 

925 to their own requirements. It can have 1+ network interfaces. 

926 """ 

927 raise NotImplementedError() 

928 

929 def get_admin_network_allocations_number(self): 

930 return 0 

931 

932 def update_network_allocation(self, context, share_server): 

933 """Update network allocation after share server creation.""" 

934 self.network_api.update_network_allocation(context, share_server) 

935 

936 def update_admin_network_allocation(self, context, share_server): 

937 """Update admin network allocation after share server creation.""" 

938 if (self.get_admin_network_allocations_number() and 938 ↛ 940line 938 didn't jump to line 940 because the condition on line 938 was never true

939 self.admin_network_api): 

940 self.admin_network_api.update_network_allocation(context, 

941 share_server) 

942 

943 def allocate_network(self, context, share_server, share_network, 

944 share_network_subnet, count=None, **kwargs): 

945 """Allocate network resources using given network information.""" 

946 if count is None: 

947 count = self.get_network_allocations_number() 

948 if count: 

949 kwargs.update(count=count) 

950 self.network_api.allocate_network( 

951 context, share_server, share_network=share_network, 

952 share_network_subnet=share_network_subnet, **kwargs) 

953 

954 def allocate_admin_network(self, context, share_server, count=None, 

955 **kwargs): 

956 """Allocate admin network resources using given network information.""" 

957 if count is None: 

958 count = self.get_admin_network_allocations_number() 

959 if count and not self.admin_network_api: 

960 msg = _("Admin network plugin is not set up.") 

961 raise exception.NetworkBadConfigurationException(reason=msg) 

962 elif count: 

963 kwargs.update(count=count) 

964 self.admin_network_api.allocate_network( 

965 context, share_server, **kwargs) 

966 

967 def deallocate_network(self, context, share_server_id, share_network=None, 

968 share_network_subnet=None): 

969 """Deallocate network resources for the given share server.""" 

970 if self.get_network_allocations_number(): 970 ↛ exitline 970 didn't return from function 'deallocate_network' because the condition on line 970 was always true

971 self.network_api.deallocate_network( 

972 context, share_server_id, share_network=share_network, 

973 share_network_subnet=share_network_subnet) 

974 

975 def choose_share_server_compatible_with_share(self, context, share_servers, 

976 share, snapshot=None, 

977 share_group=None, 

978 encryption_key_ref=None): 

979 """Method that allows driver to choose share server for provided share. 

980 

981 If compatible share-server is not found, method should return None. 

982 

983 :param context: Current context 

984 :param share_servers: list with share-server models 

985 :param share: share model 

986 :param snapshot: snapshot model 

987 :param share_group: ShareGroup model with shares 

988 :param encryption_key_ref: Encryption key reference 

989 :returns: share-server or None 

990 """ 

991 # If creating in a share group, use its share server 

992 if share_group: 992 ↛ 993line 992 didn't jump to line 993 because the condition on line 992 was never true

993 for share_server in share_servers: 

994 if (share_group.get('share_server_id') == 

995 share_server['id']): 

996 return share_server 

997 return None 

998 

999 return share_servers[0] if share_servers else None 

1000 

1001 def choose_share_server_compatible_with_share_group( 

1002 self, context, share_servers, share_group_ref, 

1003 share_group_snapshot=None): 

1004 

1005 return share_servers[0] if share_servers else None 

1006 

1007 def setup_server(self, *args, **kwargs): 

1008 if self.driver_handles_share_servers: 

1009 return self._setup_server(*args, **kwargs) 

1010 else: 

1011 LOG.debug( 

1012 "Skipping step 'setup share server', because driver is " 

1013 "enabled with mode when Manila does not handle share servers.") 

1014 

1015 def _setup_server(self, network_info, metadata=None): 

1016 """Sets up and configures share server with given network parameters. 

1017 

1018 Redefine it within share driver when it is going to handle share 

1019 servers. 

1020 

1021 :param metadata: a dictionary, for now containing a key 'request_host' 

1022 """ 

1023 raise NotImplementedError() 

1024 

1025 def manage_existing(self, share, driver_options): 

1026 """Brings an existing share under Manila management.