Shared Filesystems¶

The `manila.share.manager` Module¶

NAS share manager managers creating shares and access rights.

Related Flags

share_driver:: Used by ShareManager.

class ShareManager(share_driver=None, service_name=None, *args, **kwargs)

Bases: SchedulerDependentManager

Manages NAS storages.

RPC_API_VERSION = '1.29'

check_update_share_network_security_service(context, share_network_id, new_security_service_id, current_security_service_id=None)

check_update_share_server_network_allocations(context, share_network_id, new_share_network_subnet)

connection_get_info(context, share_instance_id)

create_backup(context, backup)

create_backup_continue(context): Invokes driver to continue backup of share.

create_replicated_snapshot(**kwargs)

create_share_group(context, share_group_id)

create_share_group_snapshot(context, share_group_snapshot_id)

create_share_instance(context, share_instance_id, request_spec=None, filter_properties=None, snapshot_id=None): Creates a share instance.

create_share_replica(**kwargs)

create_share_server(context, share_server_id, share_instance_id)

Invoked to create a share server in this backend.

This method is invoked to create the share server defined in the model obtained by the supplied id.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_server_id – The id of the server to be created.
share_instance_id – The id of the share instance

create_snapshot(context, share_id, snapshot_id): Create snapshot for share.

delete_backup(context, backup)

delete_expired_share(ctxt)

delete_expired_transfers(ctxt)

delete_free_share_servers(ctxt)

delete_replicated_snapshot(**kwargs)

delete_share_group(context, share_group_id)

delete_share_group_snapshot(context, share_group_snapshot_id)

delete_share_instance(context, share_instance_id, force=False, deferred_delete=False): Delete a share instance.

delete_share_replica(**kwargs)

delete_share_server(context, share_server)

delete_snapshot(context, snapshot_id, force=False, deferred_delete=False): Delete share snapshot.

do_deferred_share_deletion(ctxt)

do_deferred_snapshot_deletion(ctxt)

ensure_driver_resources(ctxt, skip_backend_info_check=False)

extend_share(context, share_id, new_size, reservations)

init_host(service_id=None): Initialization for a standalone service.

is_service_ready()

Return if Manager is ready to accept requests.

This is to inform Service class that in case of manila driver initialization failure the manager is actually down and not ready to accept any requests.

manage_share(context, share_id, driver_options)

manage_share_server(context, share_server_id, identifier, driver_opts)

manage_snapshot(context, snapshot_id, driver_options)

migration_cancel(context, src_instance_id, dest_instance_id)

migration_complete(context, src_instance_id, dest_instance_id)

migration_driver_continue(context): Invokes driver to continue migration of shares.

migration_get_progress(context, src_instance_id, dest_instance_id)

migration_start(context, share_id, dest_host, force_host_assisted_migration, preserve_metadata, writable, nondisruptive, preserve_snapshots, new_share_network_id=None, new_share_type_id=None): Migrates a share from current host to another host.

periodic_share_replica_snapshot_update(context)

periodic_share_replica_update(context)

periodic_share_status_update(context): Invokes share driver to update shares status.

promote_share_replica(**kwargs)

provide_share_server(context, share_instance_id, share_network_id, snapshot_id=None)

Invoked to provide a compatible share server.

This method is invoked to find a compatible share server among the existing ones or create a share server database instance with the share server properties that will be used to create the share server later.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_instance_id – The id of the share instance whose model attributes will be used to provide the share server.
share_network_id – The id of the share network the share server to be provided has to be related to.
snapshot_id – The id of the snapshot to be used to obtain the share server if applicable.

Returns:

The id of the share server that is being provided.

publish_service_capabilities(context): Collect driver status and then publish it.

restore_backup(context, backup, share_id)

restore_backup_continue(context)

revert_to_snapshot(context, snapshot_id, reservations)

share_server_migration_cancel(context, src_share_server_id, dest_share_server_id)

share_server_migration_check(context, share_server_id, dest_host, writable, nondisruptive, preserve_snapshots, new_share_network_id)

share_server_migration_complete(context, src_share_server_id, dest_share_server_id): Invokes driver to complete the migration of share server.

share_server_migration_driver_continue(context): Invokes driver to continue migration of share server.

share_server_migration_get_progress(context, src_share_server_id, dest_share_server_id)

share_server_migration_start(context, share_server_id, dest_host, writable, nondisruptive, preserve_snapshots, new_share_network_id=None): Migrates a share server from current host to another host.

shrink_share(context, share_id, new_size)

snapshot_update_access(context, snapshot_instance_id)

transfer_accept(context, share_id, new_user, new_project, clear_rules)

unmanage_share(context, share_id)

unmanage_share_server(context, share_server_id, force=False)

unmanage_snapshot(context, snapshot_id)

update_access(context, share_instance_id): Allow/Deny access to some share.

update_access_for_instances(context, share_instance_ids, share_server_id=None): Allow/Deny access to shares that belong to the same share server.

update_share_from_metadata(context, share_id, metadata)

update_share_network_security_service(context, share_network_id, new_security_service_id, current_security_service_id=None)

update_share_replica(context, share_replica_id, share_id=None): Initiated by the force_update API.

update_share_server_network_allocations(context, share_network_id, new_share_network_subnet_id)

update_share_usage_size(context): Invokes driver to gather usage size of shares.

add_hooks(f)

Hook decorator to perform action before and after a share method call

The hook decorator can perform actions before some share driver methods calls and after a call with results of driver call and preceding hook call.

locked_share_network_operation(operation)

Lock decorator for share network operations.

Takes a named lock prior to executing the operation. The lock is named with the id of the share network.

locked_share_replica_operation(operation)

Lock decorator for share replica operations.

Takes a named lock prior to executing the operation. The lock is named with the id of the share to which the replica belongs.

Intended use: If a replica operation uses this decorator, it will block actions on all share replicas of the share until the named lock is free. This is used to protect concurrent operations on replicas of the same share e.g. promote ReplicaA while deleting ReplicaB, both belonging to the same share.

The `manila.share.driver` Module¶

Drivers for shares.

class ExecuteMixin

Bases: object

Provides an executable functionality to a driver class.

init_execute_mixin(*args, **kwargs)

set_execute(execute)

class GaneshaMixin

Bases: object

Augment derived classes with Ganesha configuration.

init_ganesha_mixin(*args, **kwargs)

class ShareDriver(driver_handles_share_servers, *args, **kwargs)

Bases: object

Class defines interface of NAS driver.

add_ip_version_capability(data)

Add IP version support capabilities.

When DHSS is true, the capabilities are determined by driver and configured network plugin. When DHSS is false, the capabilities are determined by driver only. :param data: the capability dictionary :returns: capability data

property admin_network_api

allocate_admin_network(context, share_server, count=None, **kwargs): Allocate admin network resources using given network information.

allocate_network(context, share_server, share_network, share_network_subnet, count=None, **kwargs): Allocate network resources using given network information.

allow_access(context, share, access, share_server=None): Allow access to the share.

check_for_setup_error(): Check for setup error.

check_update_share_server_network_allocations(context, share_server, current_network_allocations, new_share_network_subnet, security_services, share_instances, share_instances_rules)

“Check if the share server network allocation update is supported.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_server – Reference to the share server object that will be updated.
current_network_allocations – All network allocations associated with the share server that will be updated:

Example:

{
    'admin_network_allocations':
        [
            {
                'ip_address': '10.193.154.11',
                'ip_version': 4,
                'cidr': '10.193.154.0/28',
                'gateway': '10.193.154.1',
                'mtu': 1500,
                'network_type': 'vlan',
                'segmentation_id': 3000,
                'mac_address': ' AA:AA:AA:AA:AA:AA',
                ...
            },
        ],
    'subnets':
        [
           {
            'share_network_subnet_id': '0bdeaa8c6db3-3bc10d67',
            'neutron_net_id': '2598-4122-bb62-0bdeaa8c6db3',
            'neutron_subnet_id': '3bc10d67-2598-4122-bb62',
            'network_allocations':
                [
                    {
                        'ip_address': '10.193.154.10',
                        'ip_version': 4,
                        'cidr': '10.193.154.0/28',
                        'gateway': '10.193.154.1',
                        'mtu': 1500,
                        'network_type': 'vlan',
                        'segmentation_id': 3000,
                        'mac_address': ' AA:AA:AA:AA:AA:AA',
                        ...
                    },
                ],
            },
        ],
}

Parameters:: new_share_network_subnet – dict containing the subnet data that has to be checked if it can be added to the share server:

Example:

{
    'availability_zone_id': '0bdeaa8c6db3-3bc10d67',
    'neutron_net_id': '2598-4122-bb62-0bdeaa8c6db3',
    'neutron_subnet_id': '3bc10d67-2598-4122-bb62',
    'ip_version': 4,
    'cidr': '10.193.154.0/28',
    'gateway': '10.193.154.1',
    'mtu': 1500,
    'network_type': 'vlan',
    'segmentation_id': 3000,
}

Parameters:

security_services – list of security services configured with this share server.
share_instances – A list of share instances that belong to the share server that is affected by the update.
share_instances_rules – A list of access rules, grouped by share instance, in the following format.

Example:

[
   {
    'share_instance_id': '3bc10d67-2598-4122-bb62-0bdeaa8c6db3',
    'access_rules':
    [
        {
        'access_id':'906d0094-3e34-4d6c-a184-d08a908033e3',
        'access_type':'ip',
        'access_key':None,
        'access_to':'10.0.0.1',
        'access_level':'rw'
         ...
        },
    ],
    },
]

:return Boolean indicating whether the update is possible or not. It is: the driver responsibility to log the reason why not accepting the update.

check_update_share_server_security_service(context, share_server, network_info, share_instances, share_instance_rules, new_security_service, current_security_service=None)

Check if the current share server security service is supported.

If the driver supports different security services, the user can request the addition of a new security service, with a different type. If the user wants to update the current security service configuration, the driver will receive both current and new security services, which will always be of the same type.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_server – Reference to the share server object that will be updated.
network_info – All network allocation associated with the share server that will be updated.
share_instances – A list of share instances that belong to the share server that is affected by the update.
share_instance_rules – A list of access rules, grouped by share instance, in the following format.

Example:

[
   {
    'share_instance_id': '3bc10d67-2598-4122-bb62-0bdeaa8c6db3',
    'access_rules':
    [
        {
        'access_id':'906d0094-3e34-4d6c-a184-d08a908033e3',
        'access_type':'ip',
        'access_key':None,
        'access_to':'10.0.0.1',
        'access_level':'rw'
         ...
        },
    ],
    },
]

Parameters:

new_security_service – New security service object to be configured in the share server.
current_security_service – When provided, represents the current security service that will be replaced by the ‘new_security_service’.

Returns:

‘True’ if the driver support the requested update, ‘False’ otherwise.

choose_share_server_compatible_with_share(context, share_servers, share, snapshot=None, share_group=None)

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

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

Parameters:

context – Current context
share_servers – list with share-server models
share – share model
snapshot – snapshot model
share_group – ShareGroup model with shares

Returns:

share-server or None

choose_share_server_compatible_with_share_group(context, share_servers, share_group_ref, share_group_snapshot=None)

connection_get_info(context, share, share_server=None)

Is called to provide necessary generic migration logic.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share – Reference to the share being migrated.
share_server – Share server model or None.

Returns:

A dictionary with migration information.

create_backup(context, share_instance, backup, share_server=None)

Starts backup of a given share_instance into backup.

Driver should implement this method if willing to perform backup of share_instance. This method should start the backup procedure in the backend and end. Following steps should be done in ‘create_backup_continue’.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_instance – Reference to the original share instance.
backup – Share backup model.
share_server – share server in case of dhss_true

create_backup_continue(context, share_instance, backup, share_server=None)

Continue backup of a given share_instance into backup.

Driver must implement this method if it supports ‘create_backup’ method. This method should continue the remaining backup procedure in the backend and report the progress of backup.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_instance – Reference to the original share instance.
backup – Share backup model.
share_server – share server in case of dhss_true

create_replica(context, replica_list, new_replica, access_rules, replica_snapshots, share_server=None)

Replicate the active replica to a new replica on this backend.

Note

This call is made on the host that the new replica is being created upon.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share. This list also contains the replica to be created. The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
    {
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'active',
        ...
    'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '07574742-67ea-4dfd-9844-9fbd8ada3d87',
    'share_server': <models.ShareServer> or None,
    },
    ...
]

Parameters:: new_replica – The share replica dictionary.

Example:

{
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'deleted': False,
    'host': 'openstack2@cmodeSSVMNFS2',
    'status': 'creating',
    'scheduled_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'launched_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'terminated_at': None,
    'replica_state': 'out_of_sync',
    'availability_zone_id': 'f6e146d0-65f0-11e5-9d70-feff819cdc9f',
    'export_locations': [
        models.ShareInstanceExportLocations,
    ],
    'access_rules_status': 'out_of_sync',
    'share_network_id': '4ccd5318-65f1-11e5-9d70-feff819cdc9f',
    'share_server_id': 'e6155221-ea00-49ef-abf9-9f89b7dd900a',
    'share_server': <models.ShareServer> or None,
}

Parameters:: access_rules – A list of access rules. These are rules that other instances of the share already obey. Drivers are expected to apply access rules to the new replica or disregard access rules that don’t apply.

Example:

[
 {
    'id': 'f0875f6f-766b-4865-8b41-cccb4cdf1676',
    'deleted' = False,
    'share_id' = 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'access_type' = 'ip',
    'access_to' = '172.16.20.1',
    'access_level' = 'rw',
 }
]

Parameters:: replica_snapshots – List of dictionaries of snapshot instances. This includes snapshot instances of every snapshot of the share whose ‘aggregate_status’ property was reported to be ‘available’ when the share manager initiated this request. Each list member will have two sub dictionaries: ‘active_replica_snapshot’ and ‘share_replica_snapshot’. The ‘active’ replica snapshot corresponds to the instance of the snapshot on any of the ‘active’ replicas of the share while share_replica_snapshot corresponds to the snapshot instance for the specific replica that will need to exist on the new share replica that is being created. The driver needs to ensure that this snapshot instance is truly available before transitioning the replica from ‘out_of_sync’ to ‘in_sync’. Snapshots instances for snapshots that have an ‘aggregate_status’ of ‘creating’ or ‘deleting’ will be polled for in the update_replicated_snapshot method.

Example:

[
 {
 'active_replica_snapshot': {
    'id': '8bda791c-7bb6-4e7b-9b64-fefff85ff13e',
    'share_instance_id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'status': 'available',
    'provider_location': '/newton/share-snapshot-10e49c3e-aca9',
    ...
    },
 'share_replica_snapshot': {
    'id': '',
    'share_instance_id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'status': 'available',
    'provider_location': None,
        ...
    },
 }
]

Parameters:: share_server – <models.ShareServer> or None Share server of the replica being created.
Returns:: None or a dictionary. The dictionary can contain export_locations replica_state and access_rules_status. export_locations is a list of paths and replica_state is one of ‘active’, ‘in_sync’, ‘out_of_sync’ or ‘error’.

Important

A backend supporting ‘writable’ type replication should return ‘active’ as the replica_state.

Export locations should be in the same format as returned during the create_share call.

Example:

{
    'export_locations': [
        {
            'path': '172.16.20.22/sample/export/path',
             'is_admin_only': False,
             'metadata': {'some_key': 'some_value'},
        },
    ],
     'replica_state': 'in_sync',
     'access_rules_status': 'in_sync',
}

create_replicated_snapshot(context, replica_list, replica_snapshots, share_server=None)

Create a snapshot on active instance and update across the replicas.

Note

This call is made on the ‘active’ replica’s host. Drivers are expected to transfer the snapshot created to the respective replicas.

The driver is expected to return model updates to the share manager. If it was able to confirm the creation of any number of the snapshot instances passed in this interface, it can set their status to ‘available’ as a cue for the share manager to set the progress attr to ‘100%’.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
    {
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'active',
        ...
    'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
    'share_server': <models.ShareServer> or None,
    },
    ...
]

Parameters:: replica_snapshots – List of dictionaries of snapshot instances. These snapshot instances track the snapshot across the replicas. All the instances will have their status attribute set to ‘creating’.

Example:

 [
    {
    'id': 'd3931a93-3984-421e-a9e7-d9f71895450a',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
    'status: 'creating',
    'progress': '0%',
        ...
    },
    {
    'id': '8bda791c-7bb6-4e7b-9b64-fefff85ff13e',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
    'status: 'creating',
    'progress': '0%',
        ...
    },
    ...
]

Parameters:: share_server – <models.ShareServer> or None
Returns:: List of dictionaries of snapshot instances. The dictionaries can contain values that need to be updated on the database for the snapshot instances being created.
Raises:: Exception. Any exception in this method will set all instances to ‘error’.

create_share(context, share, share_server=None): Is called to create share.

create_share_from_snapshot(context, share, snapshot, share_server=None, parent_share=None)

Is called to create share from snapshot.

Creating a share from snapshot can take longer than a simple clone operation if data copy is required from one host to another. For this reason driver will be able complete this creation asynchronously, by providing a ‘creating_from_snapshot’ status in the model update.

When answering asynchronously, drivers must implement the call ‘get_share_status’ in order to provide updates for shares with ‘creating_from_snapshot’ status.

It is expected that the driver returns a model update to the share manager that contains: share status and a list of export_locations. A list of ‘export_locations’ is mandatory only for share in ‘available’ status. The current supported status are ‘available’ and ‘creating_from_snapshot’.

Parameters:

context – Current context
share – Share instance model with share data.
snapshot – Snapshot instance model .
share_server – Share server model or None.
parent_share – Share model from parent snapshot with share data and share server model.

Returns:

a dictionary of updates containing current share status and its export_location (if available).

Example:

{
    'status': 'available',
    'export_locations': [{...}, {...}],
}

Raises:

ShareBackendException. A ShareBackendException in this method will set the instance to ‘error’ and the operation will end.

create_share_group(context, share_group_dict, share_server=None)

Create a share group.

Parameters:

context
share_group_dict – The share group details EXAMPLE: { ‘status’: ‘creating’, ‘project_id’: ‘13c0be6290934bd98596cfa004650049’, ‘user_id’: ‘a0314a441ca842019b0952224aa39192’, ‘description’: None, ‘deleted’: ‘False’, ‘created_at’: datetime.datetime(2015, 8, 10, 15, 14, 6), ‘updated_at’: None, ‘source_share_group_snapshot_id’: ‘some_fake_uuid’, ‘share_group_type_id’: ‘some_fake_uuid’, ‘host’: ‘hostname@backend_name’, ‘share_network_id’: None, ‘share_server_id’: None, ‘deleted_at’: None, ‘share_types’: [<models.ShareGroupShareTypeMapping>], ‘id’: ‘some_fake_uuid’, ‘name’: None }

Returns:

(share_group_model_update, share_update_list) share_group_model_update - a dict containing any values to be updated for the SG in the database. This value may be None.

create_share_group_from_share_group_snapshot(context, share_group_dict, share_group_snapshot_dict, share_server=None)

Create a share group from a share group snapshot.

When creating a share from snapshot operation takes longer than a simple clone operation, drivers will be able to complete this creation asynchronously, by providing a ‘creating_from_snapshot’ status in the returned model update. The current supported status are ‘available’ and ‘creating_from_snapshot’.

In order to provide updates for shares with ‘creating_from_snapshot’ status, drivers must implement the call ‘get_share_status’.

Parameters:

context

share_group_dict –

The share group details EXAMPLE: .. code:

{
'status': 'creating',
'project_id': '13c0be6290934bd98596cfa004650049',
'user_id': 'a0314a441ca842019b0952224aa39192',
'description': None,
'deleted': 'False',
'created_at': datetime.datetime(2015, 8, 10, 15, 14, 6),
'updated_at': None,
'source_share_group_snapshot_id':
    'f6aa3b59-57eb-421e-965c-4e182538e36a',
'host': 'hostname@backend_name',
'deleted_at': None,
'shares': [<models.Share>], # The new shares being created
'share_types': [<models.ShareGroupShareTypeMapping>],
'id': 'some_fake_uuid',
'name': None
}

share_group_snapshot_dict –

The share group snapshot details EXAMPLE: .. code:

{
'status': 'available',
'project_id': '13c0be6290934bd98596cfa004650049',
'user_id': 'a0314a441ca842019b0952224aa39192',
'description': None,
'deleted': '0',
'created_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
'updated_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
'share_group_id': 'some_fake_uuid',
'share_share_group_snapshot_members': [
    {
     'status': 'available',
     'user_id': 'a0314a441ca842019b0952224aa39192',
     'deleted': 'False',
     'created_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
     'share': <models.Share>,
     'updated_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
     'share_proto': 'NFS',
     'project_id': '13c0be6290934bd98596cfa004650049',
     'share_group_snapshot_id': 'some_fake_uuid',
     'deleted_at': None,
     'id': 'some_fake_uuid',
     'size': 1
    }
],
'deleted_at': None,
'id': 'f6aa3b59-57eb-421e-965c-4e182538e36a',
'name': None
}

Returns:

(share_group_model_update, share_update_list) share_group_model_update - a dict containing any values to be updated for the share group in the database. This value may be None

share_update_list - a list of dictionaries containing dicts for every share created in the share group. Any share dicts should at a minimum contain the ‘id’ key and, for synchronous creation, the ‘export_locations’. For asynchronous share creation this dict must also contain the key ‘status’ with the value set to ‘creating_from_snapshot’. The current supported status are ‘available’ and ‘creating_from_snapshot’. Export locations should be in the same format as returned by a share_create. This list may be empty or None. EXAMPLE: .. code:

[
    {
    'id': 'uuid',
    'export_locations': [{...}, {...}],
    },
    {
    'id': 'uuid',
    'export_locations': [],
    'status': 'creating_from_snapshot',
    },
]

create_share_group_snapshot(context, snap_dict, share_server=None)

Create a share group snapshot.

Parameters:

context

snap_dict –

The share group snapshot details EXAMPLE: .. code:

{
'status': 'available',
'project_id': '13c0be6290934bd98596cfa004650049',
'user_id': 'a0314a441ca842019b0952224aa39192',
'description': None,
'deleted': '0',
'created_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
'updated_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
'share_group_id': 'some_fake_uuid',
'share_group_snapshot_members': [
    {
     'status': 'available',
     'share_type_id': 'some_fake_uuid',
     'user_id': 'a0314a441ca842019b0952224aa39192',
     'deleted': 'False',
     'created_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
     'share': <models.Share>,
     'updated_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
     'share_proto': 'NFS',
     'share_name': 'share_some_fake_uuid',
     'name': 'share-snapshot-some_fake_uuid',
     'project_id': '13c0be6290934bd98596cfa004650049',
     'share_group_snapshot_id': 'some_fake_uuid',
     'deleted_at': None,
     'share_id': 'some_fake_uuid',
     'id': 'some_fake_uuid',
     'size': 1,
     'provider_location': None,
    }
],
'deleted_at': None,
'id': 'some_fake_uuid',
'name': None
}

Returns:

(share_group_snapshot_update, member_update_list) share_group_snapshot_update - a dict containing any values to be updated for the CGSnapshot in the database. This value may be None.

member_update_list - a list of dictionaries containing for every member of the share group snapshot. Each dict should contains values to be updated for the ShareGroupSnapshotMember in the database. This list may be empty or None.

create_snapshot(context, snapshot, share_server=None)

Is called to create snapshot.

Parameters:

context – Current context
snapshot – Snapshot model. Share model could be retrieved through snapshot[‘share’].
share_server – Share server model or None.

Returns:

None or a dictionary with key ‘export_locations’ containing a list of export locations, if snapshots can be mounted.

property creating_shares_from_snapshots_is_supported: Calculate default value for create_share_from_snapshot_support.

deallocate_network(context, share_server_id, share_network=None, share_network_subnet=None): Deallocate network resources for the given share server.

delete_backup(context, backup, share_instance, share_server=None): Is called to remove backup.

delete_replica(context, replica_list, replica_snapshots, replica, share_server=None)

Delete a replica.

Note

This call is made on the host that hosts the replica being deleted.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share This list also contains the replica to be deleted. The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
    {
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'active',
        ...
    'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '07574742-67ea-4dfd-9844-9fbd8ada3d87',
    'share_server': <models.ShareServer> or None,
    },
    ...
]

Parameters:: replica – Dictionary of the share replica being deleted.

Example:

{
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'deleted': False,
    'host': 'openstack2@cmodeSSVMNFS2',
    'status': 'available',
    'scheduled_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'launched_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'terminated_at': None,
    'replica_state': 'in_sync',
    'availability_zone_id': 'f6e146d0-65f0-11e5-9d70-feff819cdc9f',
    'export_locations': [
        models.ShareInstanceExportLocations
    ],
    'access_rules_status': 'out_of_sync',
    'share_network_id': '4ccd5318-65f1-11e5-9d70-feff819cdc9f',
    'share_server_id': '53099868-65f1-11e5-9d70-feff819cdc9f',
    'share_server': <models.ShareServer> or None,
}

Parameters:: replica_snapshots – List of dictionaries of snapshot instances. The dict contains snapshot instances that are associated with the share replica being deleted. No model updates to snapshot instances are possible in this method. The driver should return when the cleanup is completed on the backend for both, the snapshots and the replica itself. Drivers must handle situations where the snapshot may not yet have finished ‘creating’ on this replica.

Example:

[
    {
    'id': '89dafd00-0999-4d23-8614-13eaa6b02a3b',
    'snapshot_id': '3ce1caf7-0945-45fd-a320-714973e949d3',
    'status: 'available',
    'share_instance_id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f'
        ...
    },
    {
    'id': '8bda791c-7bb6-4e7b-9b64-fefff85ff13e',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
    'status: 'creating',
    'share_instance_id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f'
        ...
    },
    ...
]

Parameters:: share_server – <models.ShareServer> or None Share server of the replica to be deleted.
Returns:: None.
Raises:: Exception. Any exception raised will set the share replica’s ‘status’ and ‘replica_state’ attributes to ‘error_deleting’. It will not affect snapshots belonging to this replica.

delete_replicated_snapshot(context, replica_list, replica_snapshots, share_server=None)

Delete a snapshot by deleting its instances across the replicas.

Note

This call is made on the ‘active’ replica’s host, since drivers may not be able to delete the snapshot from an individual replica.

The driver is expected to return model updates to the share manager. If it was able to confirm the removal of any number of the snapshot instances passed in this interface, it can set their status to ‘deleted’ as a cue for the share manager to clean up that instance from the database.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
    {
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'active',
        ...
    'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
    'share_server': <models.ShareServer> or None,
    },
    ...
]

Parameters:: replica_snapshots – List of dictionaries of snapshot instances. These snapshot instances track the snapshot across the replicas. All the instances will have their status attribute set to ‘deleting’.

Example:

 [
    {
    'id': 'd3931a93-3984-421e-a9e7-d9f71895450a',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
    'status': 'deleting',
    'progress': '100%',
        ...
    },
    {
    'id': '8bda791c-7bb6-4e7b-9b64-fefff85ff13e',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
    'status: 'deleting',
    'progress': '100%',
        ...
    },
    ...
]

Parameters:: share_server – <models.ShareServer> or None
Returns:: List of dictionaries of snapshot instances. The dictionaries can contain values that need to be updated on the database for the snapshot instances being deleted. To confirm the deletion of the snapshot instance, set the ‘status’ attribute of the instance to ‘deleted’ (constants.STATUS_DELETED)
Raises:: Exception. Any exception in this method will set the status attribute of all snapshot instances to ‘error_deleting’.

delete_share(context, share, share_server=None): Is called to remove share.

delete_share_group(context, share_group_dict, share_server=None)

Delete a share group

Parameters:

context – The request context

share_group_dict –

The share group details EXAMPLE: .. code:

{
'status': 'creating',
'project_id': '13c0be6290934bd98596cfa004650049',
'user_id': 'a0314a441ca842019b0952224aa39192',
'description': None,
'deleted': 'False',
'created_at': datetime.datetime(2015, 8, 10, 15, 14, 6),
'updated_at': None,
'source_share_group_snapshot_id': 'some_fake_uuid',
'share_share_group_type_id': 'some_fake_uuid',
'host': 'hostname@backend_name',
'deleted_at': None,
'shares': [<models.Share>], # The new shares being created
'share_types': [<models.ShareGroupShareTypeMapping>],
'id': 'some_fake_uuid',
'name': None
}

Returns:

share_group_model_update share_group_model_update - a dict containing any values to be updated for the group in the database. This value may be None.

delete_share_group_snapshot(context, snap_dict, share_server=None)

Delete a share group snapshot

Parameters:

context

snap_dict –

The share group snapshot details EXAMPLE: .. code:

{
'status': 'available',
'project_id': '13c0be6290934bd98596cfa004650049',
'user_id': 'a0314a441ca842019b0952224aa39192',
'description': None,
'deleted': '0',
'created_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
'updated_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
'share_group_id': 'some_fake_uuid',
'share_group_snapshot_members': [
    {
     'status': 'available',
     'share_type_id': 'some_fake_uuid',
     'share_id': 'some_fake_uuid',
     'user_id': 'a0314a441ca842019b0952224aa39192',
     'deleted': 'False',
     'created_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
     'share': <models.Share>,
     'updated_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
     'share_proto': 'NFS',
     'share_name':'share_some_fake_uuid',
     'name': 'share-snapshot-some_fake_uuid',
     'project_id': '13c0be6290934bd98596cfa004650049',
     'share_group_snapshot_id': 'some_fake_uuid',
     'deleted_at': None,
     'id': 'some_fake_uuid',
     'size': 1,
     'provider_location': 'fake_provider_location_value',
    }
],
'deleted_at': None,
'id': 'f6aa3b59-57eb-421e-965c-4e182538e36a',
'name': None
}

Returns:

(share_group_snapshot_update, member_update_list) share_group_snapshot_update - a dict containing any values to be updated for the ShareGroupSnapshot in the database. This value may be None.

delete_snapshot(context, snapshot, share_server=None)

Is called to remove snapshot.

Parameters:

context – Current context
snapshot – Snapshot model. Share model could be retrieved through snapshot[‘share’].
share_server – Share server model or None.

deny_access(context, share, access, share_server=None): Deny access to the share.

do_setup(context): Any initialization the share driver does while starting.

property driver_handles_share_servers

ensure_share(context, share, share_server=None)

Invoked to ensure that share is exported.

Driver can use this method to update the list of export locations of the share if it changes. To do that, you should return list with export locations.

It is preferred if the driver implements “get_backend_info” and “ensure_shares” instead of this routine.

Returns:: None or list with export locations

ensure_shares(context, shares)

Invoked to ensure that shares are exported.

Driver can use this method to update the “status” and/or list of export locations of the shares if they change. To do that, a dictionary of shares should be returned. In addition, the driver can seek to “reapply_access_rules” (boolean) on a per-share basis. When this property exists and is set to True, the share manager service will invoke “update_access” with all the access rules from the service database. :shares: A list of all shares for updates. :returns: None or a dictionary of updates in the format.

Example:

{
    '09960614-8574-4e03-89cf-7cf267b0bd08': {
        'export_locations': [{...}, {...}],
        'status': 'error',
        'reapply_access_rules': False,
    },

    '28f6eabb-4342-486a-a7f4-45688f0c0295': {
        'export_locations': [{...}, {...}],
        'status': 'available',
        'reapply_access_rules': True,
    },

}

extend_share(share, new_size, share_server=None)

Extends size of existing share.

Parameters:

share – Share model
new_size – New size of share (new_size > share[‘size’])
share_server – Optional – Share server model

get_admin_network_allocations_number()

get_backend_info(context)

Get driver and array configuration parameters.

Driver can use this method to get the special configuration info and return for assessment. The share manager service uses this assessment to invoke “ensure_shares” during service startup.

Returns:

A dictionary containing driver-specific info.

Example:

{
     'version': '2.23'
     'port': '80',
     'logicalportip': '1.1.1.1',
      ...
}

get_configured_ip_versions()

“Get allowed IP versions.

The supported versions are returned with list, possible values are: [4], [6], or [4, 6]

Drivers that assert ipv6_implemented = True must override this method. If the returned list includes 4, then shares created by this driver must have an IPv4 export location. If the list includes 6, then shares created by the driver must have an IPv6 export location.

Drivers should check that their storage controller actually has IPv4/IPv6 enabled and configured properly.

get_default_filter_function(pool=None)

Get the default filter_function string.

Each driver could overwrite the method to return a well-known default string if it is available.

Parameters:: pool – pool name to get the filter or None
Returns:: None

get_default_goodness_function()

Get the default goodness_function string.

Each driver could overwrite the method to return a well-known default string if it is available.

Returns:: None

get_filter_function(pool=None)

Get filter_function string.

Returns either the string from the driver instance or global section in manila.conf. If nothing is specified in manila.conf, then try to find the default filter_function. When None is returned the scheduler will always pass the driver instance.

Parameters:: pool – pool name to get the filter or None
Returns:: a filter_function string or None

get_goodness_function()

Get good_function string.

Returns either the string from the driver instance or global section in manila.conf. If nothing is specified in manila.conf, then try to find the default goodness_function. When None is returned the scheduler will give the lowest score to the driver instance.

Returns:: a goodness_function string or None

get_network_allocations_number()

Returns number of network allocations for creating VIFs.

Drivers that use Nova for share servers should return zero (0) here same as Generic driver does. Because Nova will handle network resources allocation. Drivers that handle networking itself should calculate it according to their own requirements. It can have 1+ network interfaces.

get_optional_share_creation_data(share, share_server=None)

Get info to set in shares after their creation.

Driver can use this method to get the special info and return for assessment. The share manager service uses this assessment to set this info to shares after the creation.

Returns:

A dictionary containing driver-specific info.

Example:

{
     'metadata': {'__mount_options': 'fake_key=fake_val'}
      ...
}

get_periodic_hook_data(context, share_instances)

Dedicated for update/extend of data for existing share instances.

Redefine this method in share driver to be able to update/change/extend share instances data that will be used by periodic hook action. One of possible updates is add-on of “automount” CLI commands for each share instance for case of notification is enabled using ‘hook’ approach.

Parameters:

context – Current context
share_instances – share instances list provided by share manager

Returns:

list of share instances.

get_pool(share)

Return pool name where the share resides on.

Parameters:: share – The share hosted by the driver.

get_share_server_network_info(context, share_server, identifier, driver_options)

Obtain network allocations used by share server.

Parameters:

context – Current context.
share_server – Share server model.
identifier – A driver-specific share server identifier
driver_options – Dictionary of driver options to assist managing the share server

Returns:

A list containing IP addresses allocated in the backend.

Example:

['10.10.10.10', 'fd11::2000', '192.168.10.10']

get_share_server_pools(share_server)

Return list of pools related to a particular share server.

Parameters:: share_server – ShareServer class instance.

get_share_stats(refresh=False)

Get share status.

If ‘refresh’ is True, run update the stats first.

get_share_status(share, share_server=None)

Invoked periodically to get the current status of a given share.

Driver can use this method to update the status of a share that is still pending from other operations. This method is expected to be called in a periodic interval set by the ‘periodic_interval’ configuration in seconds.

Parameters:

share – share to get updated status from.
share_server – share server model or None.

Returns:

a dictionary of updates with the current share status, that must be ‘available’, ‘creating_from_snapshot’ or ‘error’, a list of export locations, if available, and a progress field which indicates the completion of the share creation operation. EXAMPLE:

{
    'status': 'available',
    'export_locations': [{...}, {...}],
    'progress': '50%'
}

Raises:

ShareBackendException. A ShareBackendException in this method will set the instance status to ‘error’.

manage_existing(share, driver_options)

Brings an existing share under Manila management.

If the provided share is not valid, then raise a ManageInvalidShare exception, specifying a reason for the failure.

If the provided share is not in a state that can be managed, such as being replicated on the backend, the driver MUST raise ManageInvalidShare exception with an appropriate message.

The share has a share_type, and the driver can inspect that and compare against the properties of the referenced backend share. If they are incompatible, raise a ManageExistingShareTypeMismatch, specifying a reason for the failure.

This method is invoked when the share is being managed with a share type that has driver_handles_share_servers extra-spec set to False.

Parameters:

share – Share model
driver_options – Driver-specific options provided by admin.

Returns:

share_update dictionary with required key ‘size’, which should contain size of the share.

manage_existing_snapshot(snapshot, driver_options)

Brings an existing snapshot under Manila management.

If provided snapshot is not valid, then raise a ManageInvalidShareSnapshot exception, specifying a reason for the failure.

This method is invoked when the snapshot that is being managed belongs to a share that has its share type with driver_handles_share_servers extra-spec set to False.

Parameters:: snapshot – ShareSnapshotInstance model with ShareSnapshot data.

Example::: { ‘id’: <instance id>, ‘snapshot_id’: < snapshot id>, ‘provider_location’: <location>, … }

Parameters:: driver_options – Optional driver-specific options provided by admin.

Example:

{
'key': 'value',
...
}

Returns:: model_update dictionary with required key ‘size’, which should contain size of the share snapshot, and key ‘export_locations’ containing a list of export locations, if snapshots can be mounted.

manage_existing_snapshot_with_server(snapshot, driver_options, share_server=None)

Brings an existing snapshot under Manila management.

If provided snapshot is not valid, then raise a ManageInvalidShareSnapshot exception, specifying a reason for the failure.

This method is invoked when the snapshot that is being managed belongs to a share that has its share type with driver_handles_share_servers extra-spec set to True.

Parameters:: snapshot – ShareSnapshotInstance model with ShareSnapshot data.

Example::: { ‘id’: <instance id>, ‘snapshot_id’: < snapshot id>, ‘provider_location’: <location>, … }

Parameters:: driver_options – Optional driver-specific options provided by admin.

Example:

{
'key': 'value',
...
}

Parameters:: share_server – Share server model or None.
Returns:: model_update dictionary with required key ‘size’, which should contain size of the share snapshot, and key ‘export_locations’ containing a list of export locations, if snapshots can be mounted.

manage_existing_with_server(share, driver_options, share_server=None)

Brings an existing share under Manila management.

If the provided share is not valid, then raise a ManageInvalidShare exception, specifying a reason for the failure.

If the provided share is not in a state that can be managed, such as being replicated on the backend, the driver MUST raise ManageInvalidShare exception with an appropriate message.

This method is invoked when the share is being managed with a share type that has driver_handles_share_servers extra-spec set to True.

Parameters:

share – Share model
driver_options – Driver-specific options provided by admin.
share_server – Share server model or None.

Returns:

share_update dictionary with required key ‘size’, which should contain size of the share.

manage_server(context, share_server, identifier, driver_options)

Manage the share server and return compiled back end details.

Parameters:

context – Current context.
share_server – Share server model.
identifier – A driver-specific share server identifier
driver_options – Dictionary of driver options to assist managing the share server

Returns:

Identifier and dictionary with back end details to be saved in the database.

Example:

'my_new_server_identifier',{'server_name': 'my_old_server'}

property max_share_server_size

property max_shares_per_share_server

migration_cancel(context, source_share, destination_share, source_snapshots, snapshot_mappings, share_server=None, destination_share_server=None)

Cancels migration of a given share to another host.

Note

Is called in source share’s backend to cancel migration.

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

Parameters:

context – The ‘context.RequestContext’ object for the request.
source_share – Reference to the original share model.
destination_share – Reference to the share model to be used by migrated share.
source_snapshots – List of snapshots owned by the source share.
snapshot_mappings – Mapping of source snapshot IDs to destination snapshot models.
share_server – Share server model or None.
destination_share_server – Destination Share server model or None.

migration_check_compatibility(context, source_share, destination_share, share_server=None, destination_share_server=None)

Checks destination compatibility for migration of a given share.

Note

Is called to test compatibility with destination backend.

Driver should check if it is compatible with destination backend so driver-assisted migration can proceed.

Parameters:

context – The ‘context.RequestContext’ object for the request.
source_share – Reference to the share to be migrated.
destination_share – Reference to the share model to be used by migrated share.
share_server – Share server model or None.
destination_share_server – Destination Share server model or None.

Returns:

A dictionary containing values indicating if destination backend is compatible, if share can remain writable during migration, if it can preserve all file metadata and if it can perform migration of given share non-disruptively.

Example:

{
    'compatible': True,
    'writable': True,
    'preserve_metadata': True,
    'nondisruptive': True,
    'preserve_snapshots': True,
}

migration_complete(context, source_share, destination_share, source_snapshots, snapshot_mappings, share_server=None, destination_share_server=None)

Completes migration of a given share to another host.

Note

Is called in source share’s backend to complete migration.

If driver is implementing 2-phase migration, this method should perform the disruptive tasks related to the 2nd phase of migration, thus completing it. Driver should also delete all original share data from source backend.

Parameters:

context – The ‘context.RequestContext’ object for the request.
source_share – Reference to the original share model.
destination_share – Reference to the share model to be used by migrated share.
source_snapshots – List of snapshots owned by the source share.
snapshot_mappings – Mapping of source snapshot IDs to destination snapshot models.
share_server – Share server model or None.
destination_share_server – Destination Share server model or None.

Returns:

If the migration changes the share export locations, snapshot provider locations or snapshot export locations, this method should return a dictionary with the relevant info. In such case, a dictionary containing a list of export locations and a list of model updates for each snapshot indexed by their IDs.

Example:

{
    'export_locations':
    [
        {
        'path': '1.2.3.4:/foo',
        'metadata': {},
        'is_admin_only': False
        },
        {
        'path': '5.6.7.8:/foo',
        'metadata': {},
        'is_admin_only': True
        },
    ],
    'snapshot_updates':
    {
        'bc4e3b28-0832-4168-b688-67fdc3e9d408':
        {
        'provider_location': '/snapshots/foo/bar_1',
        'export_locations':
        [
            {
            'path': '1.2.3.4:/snapshots/foo/bar_1',
            'is_admin_only': False,
            },
            {
            'path': '5.6.7.8:/snapshots/foo/bar_1',
            'is_admin_only': True,
            },
        ],
        },
        '2e62b7ea-4e30-445f-bc05-fd523ca62941':
        {
        'provider_location': '/snapshots/foo/bar_2',
        'export_locations':
        [
            {
            'path': '1.2.3.4:/snapshots/foo/bar_2',
            'is_admin_only': False,
            },
            {
            'path': '5.6.7.8:/snapshots/foo/bar_2',
            'is_admin_only': True,
            },
        ],
        },
    },
}

migration_continue(context, source_share, destination_share, source_snapshots, snapshot_mappings, share_server=None, destination_share_server=None)

Continues migration of a given share to another host.

Note

Is called in source share’s backend to continue migration.

Driver should implement this method to continue monitor the migration progress in storage and perform following steps until 1st phase is completed.

Parameters:

context – The ‘context.RequestContext’ object for the request.
source_share – Reference to the original share model.
destination_share – Reference to the share model to be used by migrated share.
source_snapshots – List of snapshots owned by the source share.
snapshot_mappings – Mapping of source snapshot IDs to destination snapshot models.
share_server – Share server model or None.
destination_share_server – Destination Share server model or None.

Returns:

Boolean value to indicate if 1st phase is finished.

migration_get_progress(context, source_share, destination_share, source_snapshots, snapshot_mappings, share_server=None, destination_share_server=None)

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

Note

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

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

Parameters:

context – The ‘context.RequestContext’ object for the request.
source_share – Reference to the original share model.
destination_share – Reference to the share model to be used by migrated share.
source_snapshots – List of snapshots owned by the source share.
snapshot_mappings – Mapping of source snapshot IDs to destination snapshot models.
share_server – Share server model or None.
destination_share_server – Destination Share server model or None.

Returns:

A dictionary with at least ‘total_progress’ field containing the percentage value.

migration_start(context, source_share, destination_share, source_snapshots, snapshot_mappings, share_server=None, destination_share_server=None)

Starts migration of a given share to another host.

Note

Is called in source share’s backend to start migration.

Driver should implement this method if willing to perform migration in a driver-assisted way, useful for when source share’s backend driver is compatible with destination backend driver. This method should start the migration procedure in the backend and end. Following steps should be done in ‘migration_continue’.

Parameters:

context – The ‘context.RequestContext’ object for the request.
source_share – Reference to the original share model.
destination_share – Reference to the share model to be used by migrated share.
source_snapshots – List of snapshots owned by the source share.
snapshot_mappings – Mapping of source snapshot IDs to destination snapshot models.
share_server – Share server model or None.
destination_share_server – Destination Share server model or None.

promote_replica(context, replica_list, replica, access_rules, share_server=None, quiesce_wait_time=None)

Promote a replica to ‘active’ replica state.

Note

This call is made on the host that hosts the replica being promoted.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share This list also contains the replica to be promoted. The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
    {
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'active',
        ...
    'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '07574742-67ea-4dfd-9844-9fbd8ada3d87',
    'share_server': <models.ShareServer> or None,
    },
    ...
]

Parameters:: replica – Dictionary of the replica to be promoted.

Example:

{
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'deleted': False,
    'host': 'openstack2@cmodeSSVMNFS2',
    'status': 'available',
    'scheduled_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'launched_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'terminated_at': None,
    'replica_state': 'in_sync',
    'availability_zone_id': 'f6e146d0-65f0-11e5-9d70-feff819cdc9f',
    'export_locations': [
        models.ShareInstanceExportLocations
    ],
    'access_rules_status': 'in_sync',
    'share_network_id': '4ccd5318-65f1-11e5-9d70-feff819cdc9f',
    'share_server_id': '07574742-67ea-4dfd-9844-9fbd8ada3d87',
    'share_server': <models.ShareServer> or None,
}

Parameters:: access_rules – A list of access rules These access rules are obeyed by other instances of the share

Example:

[
 {
    'id': 'f0875f6f-766b-4865-8b41-cccb4cdf1676',
    'deleted' = False,
    'share_id' = 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'access_type' = 'ip',
    'access_to' = '172.16.20.1',
    'access_level' = 'rw',
 }
]

Parameters:

share_server – <models.ShareServer> or None Share server of the replica to be promoted.
quiesce_wait_time – time in seconds or None Share replica promote quiesce wait time.

Returns:

updated_replica_list or None. The driver can return the updated list as in the request parameter. Changes that will be updated to the Database are: ‘export_locations’, ‘access_rules_status’ and ‘replica_state’.

Raises:

Exception. This can be any exception derived from BaseException. This is re-raised by the manager after some necessary cleanup. If the driver raises an exception during promotion, it is assumed that all of the replicas of the share are in an inconsistent state. Recovery is only possible through the periodic update call and/or administrator intervention to correct the ‘status’ of the affected replicas if they become healthy again.

property replication_domain

restore_backup(context, backup, share_instance, share_server=None)

Starts restoring backup into a given share_instance.

Driver should implement this method if willing to perform restore of backup into a share_instance. This method should start the backup restore procedure in the backend and end. Following steps should be done in ‘restore_backup_continue’.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_instance – Reference to the original share instance.
backup – Share backup model.
share_server – share server in case of dhss_true

restore_backup_continue(context, backup, share_instance, share_server=None)

Continue restore of a given backup into share_instance.

Driver must implement this method if it supports ‘restore_backup’ method. This method should continue the remaining restore procedure in the backend and report the progress of backup restore.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_instance – Reference to the original share instance.
backup – Share backup model.
share_server – share server in case of dhss_true

revert_to_replicated_snapshot(context, active_replica, replica_list, active_replica_snapshot, replica_snapshots, share_access_rules, snapshot_access_rules, share_server=None)

Reverts a replicated share (in place) to the specified snapshot.

Note

This call is made on the ‘active’ replica’s host, since drivers may not be able to revert snapshots on individual replicas.

Does not delete the share snapshot. The share and snapshot must both be ‘available’ for the restore to be attempted. The snapshot must be the most recent one taken by Manila; the API layer performs this check so the driver doesn’t have to.

The share must be reverted in place to the contents of the snapshot. Application admins should quiesce or otherwise prepare the application for the shared file system contents to change suddenly.

Parameters:

context – Current context
active_replica – The current active replica
replica_list – List of all replicas for a particular share The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’ and its ‘status’ set to ‘reverting’.
active_replica_snapshot – snapshot to be restored
replica_snapshots – List of dictionaries of snapshot instances. These snapshot instances track the snapshot across the replicas. The snapshot of the active replica to be restored with have its status attribute set to ‘restoring’.
share_access_rules – List of access rules for the affected share.
snapshot_access_rules – List of access rules for the affected snapshot.
share_server – Optional – Share server model

revert_to_snapshot(context, snapshot, share_access_rules, snapshot_access_rules, share_server=None)

Reverts a share (in place) to the specified snapshot.

The share must be reverted in place to the contents of the snapshot. Application admins should quiesce or otherwise prepare the application for the shared file system contents to change suddenly.

Parameters:

context – Current context
snapshot – The snapshot to be restored
share_access_rules – List of all access rules for the affected share
snapshot_access_rules – List of all access rules for the affected snapshot
share_server – Optional – Share server model or None

setup_server(*args, **kwargs)

share_server_migration_cancel(context, src_share_server, dest_share_server, shares, snapshots)

Cancels migration of a given share server to another host.

Note

Is called in destination share server’s backend to continue migration.

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

Parameters:

context – The ‘context.RequestContext’ object for the request.
src_share_server – Reference to the original share server.
dest_share_server – Reference to the share server to be used as destination.
shares – All shares in the source share server that should be migrated.
snapshots – All snapshots in the source share server that should be migrated.

share_server_migration_check_compatibility(context, share_server, dest_host, old_share_network, new_share_network, shares_request_spec)

Checks destination compatibility for migration of a share server.

Note

Is called in destination share server’s backend to continue migration. Can be called by an admin to check if a given host is compatible or by the share manager to test compatibility with destination backend.

Driver should check if it is compatible with destination backend so driver-assisted migration can proceed.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_server – Share server model.
dest_host – Reference to the hos to be used by the migrated share server.
old_share_network – Share network model where the source share server is placed.
new_share_network – Share network model where the share server is going to be migrated to.
shares_request_spec – Dict. Contains information about all shares and share types that belong to the source share server. The drivers can use this information to check if the capabilities match with the destination backend and if there is available space to hold the new share server and all its resource.

Example:

{
'shares_size': 100,
'snapshots_size': 100,
'shares_req_spec':
[
    {
    'share_properties':
        {
        'size': 10
        'user_id': '2f5c1df4-5203-444e-b68e-1e60f3f26fc3'
        'project_id': '0b82b278-51d6-4357-b273-0d7263982c31'
        'snapshot_support': True
        'create_share_from_snapshot_support': True
        'revert_to_snapshot_support': False
        'mount_snapshot_support': False
        'share_proto': NFS
        'share_type_id': '360e01c1-a4f7-4782-9676-dc013f1a2f21'
        'is_public': False
        'share_group_id': None
        'source_share_group_snapshot_member_id': None
        'snapshot_id': None
        },
    'share_instance_properties':
        {
        'availability_zone_id':
            '02377ad7-381c-4b25-a04c-6fd218f22a91',
        'share_network_id': '691544aa-da83-4669-8522-22719f236e16',
        'share_server_id': 'cd658413-d02c-4d1b-ac8a-b6b972e76bac',
        'share_id': 'e42fec45-781e-4dcc-a4d2-44354ad5ae91',
        'host': 'hostA@backend1#pool0',
        'status': 'available',
        },
    'share_type':
        {
        'id': '360e01c1-a4f7-4782-9676-dc013f1a2f21',
        'name': 'dhss_false',
        'is_public': False,
        'extra_specs':
            {
            'driver_handles_share_servers': False,
            }
        },
    'share_id': e42fec45-781e-4dcc-a4d2-44354ad5ae91,
    },
],
}

Returns:

Example:

{
    'compatible': True,
    'writable': True,
    'nondisruptive': True,
    'preserve_snapshots': True,
    'migration_cancel': True,
    'migration_get_progress': False,
}

share_server_migration_complete(context, src_share_server, dest_share_server, shares, snapshots, new_network_info)

Completes migration of a given share server to another host.

Note

Is called in destination share server’s backend to complete migration.

It expected that all shares and snapshots will be available at the destination share server in the end of the migration complete and all updates provided in the returned model update.

Parameters:

context – The ‘context.RequestContext’ object for the request.
src_share_server – Reference to the original share server.
dest_share_server – Reference to the share server to be used as destination.
shares – All shares in the source share server that should be migrated.
snapshots – All snapshots in the source share server that should be migrated.
new_network_info – Network allocation associated to the destination share server.

Returns:

If the migration changes the shares export locations, snapshots provider locations or snapshots export locations, this method should return a dictionary containing a list of share instances and snapshot instances indexed by their id’s, where each instance should provide a dict with the relevant information that need to be updated.

Example:

{
    'share_updates':
    {
        '4363eb92-23ca-4888-9e24-502387816e2a':
        {
        'export_locations':
        [
            {
            'path': '1.2.3.4:/foo',
            'metadata': {},
            'is_admin_only': False
            },
            {
            'path': '5.6.7.8:/foo',
            'metadata': {},
            'is_admin_only': True
            },
        ],
        'pool_name': 'poolA',
        },
    },
    'snapshot_updates':
    {
        'bc4e3b28-0832-4168-b688-67fdc3e9d408':
        {
        'provider_location': '/snapshots/foo/bar_1',
        'export_locations':
        [
            {
            'path': '1.2.3.4:/snapshots/foo/bar_1',
            'is_admin_only': False,
            },
            {
            'path': '5.6.7.8:/snapshots/foo/bar_1',
            'is_admin_only': True,
            },
        ],
        },
        '2e62b7ea-4e30-445f-bc05-fd523ca62941':
        {
        'provider_location': '/snapshots/foo/bar_2',
        'export_locations':
        [
            {
            'path': '1.2.3.4:/snapshots/foo/bar_2',
            'is_admin_only': False,
            },
            {
            'path': '5.6.7.8:/snapshots/foo/bar_2',
            'is_admin_only': True,
            },
        ],
        },
    }
    'backend_details':
    {
        'new_share_server_info_key':
            'new_share_server_info_value',
    },
}

share_server_migration_continue(context, src_share_server, dest_share_server, shares, snapshots)

Continues migration of a given share server to another host.

Note

Is called in destination share server’s backend to continue migration.

Driver should implement this method to continue monitor the migration progress in storage and perform following steps until 1st phase is completed.

Parameters:

context – The ‘context.RequestContext’ object for the request.
src_share_server – Reference to the original share server.
dest_share_server – Reference to the share server to be used as destination.
shares – All shares in the source share server that should be migrated.
snapshots – All snapshots in the source share server that should be migrated.

Returns:

Boolean value to indicate if 1st phase is finished.

share_server_migration_get_progress(context, src_share_server, dest_share_server, shares, snapshots)

Obtains progress of migration of a share server to another host.

Note

Is called in destination share’s backend to obtain migration progress.

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

Parameters:

context – The ‘context.RequestContext’ object for the request.
src_share_server – Reference to the original share server.
dest_share_server – Reference to the share server to be used as destination.
shares – All shares in the source share server that should be migrated.
snapshots – All snapshots in the source share server that should be migrated.

Returns:

A dictionary with at least ‘total_progress’ field containing the percentage value.

share_server_migration_start(context, src_share_server, dest_share_server, shares, snapshots)

Starts migration of a given share server to another host.

Note

Is called in destination share server’s backend to start migration.

Driver should implement this method if willing to perform a server migration in driver-assisted way, useful when source share server’s backend driver is compatible with destination backend driver. This method should start the migration procedure in the backend and return immediately. Following steps should be done in ‘share_server_migration_continue’.

Parameters:

context – The ‘context.RequestContext’ object for the request.
src_share_server – Reference to the original share server.
dest_share_server – Reference to the share server to be used by as destination.
shares – All shares in the source share server that should be migrated.
snapshots – All snapshots in the source share server that should be migrated.

Returns:

Dict with migration information to be set in the destination share server.

Example:

{
    'backend_details': {
        'migration_info_key':  'migration_info_value',
    }
}

shrink_share(share, new_size, share_server=None)

Shrinks size of existing share.

If consumed space on share larger than new_size driver should raise ShareShrinkingPossibleDataLoss exception: raise ShareShrinkingPossibleDataLoss(share_id=share[‘id’])

Parameters:

share – Share model
new_size – New size of share (new_size < share[‘size’])
share_server – Optional – Share server model

:raises ShareShrinkingPossibleDataLoss, NotImplementedError

snapshot_update_access(context, snapshot, access_rules, add_rules, delete_rules, share_server=None)

Update access rules for given snapshot.

access_rules contains all access_rules that need to be on the share. If the driver can make bulk access rule updates, it can safely ignore the add_rules and delete_rules parameters.

If the driver cannot make bulk access rule changes, it can rely on new rules to be present in add_rules and rules that need to be removed to be present in delete_rules.

When a rule in add_rules already exists in the back end, drivers must not raise an exception. When a rule in delete_rules was never applied, drivers must not raise an exception, or attempt to set the rule to error state.

add_rules and delete_rules can be empty lists, in this situation, drivers should ensure that the rules present in access_rules are the same as those on the back end.

Parameters:

context – Current context
snapshot – Snapshot model with snapshot data.
access_rules – All access rules for given snapshot
add_rules – Empty List or List of access rules which should be added. access_rules already contains these rules.
delete_rules – Empty List or List of access rules which should be removed. access_rules doesn’t contain these rules.
share_server – None or Share server model

property snapshots_are_supported

teardown_server(*args, **kwargs)

transfer_accept(context, share, new_user, new_project, access_rules=None, share_server=None)

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

Parameters:

context – The ‘context.RequestContext’ object for the request.
share – Share instance model.
access_rules – A list of access rules for given share.
new_user – the share will be updated with the new user id .
new_project – the share will be updated with the new project id.
share_server – share server for given share.

unmanage(share)

Removes the specified share from Manila management.

Does not delete the underlying backend share.

For most drivers, this will not need to do anything. However, some drivers might use this call as an opportunity to clean up any Manila-specific configuration that they have associated with the backend share.

If provided share cannot be unmanaged, then raise an UnmanageInvalidShare exception, specifying a reason for the failure.

This method is invoked when the share is being unmanaged with a share type that has driver_handles_share_servers extra-spec set to False.

unmanage_server(server_details, security_services=None)

Unmanages the share server.

If a driver supports unmanaging of share servers, the driver must override this method and return successfully.

Parameters:

server_details – share server backend details.
security_services – list of security services configured with this share server.

unmanage_snapshot(snapshot)

Removes the specified snapshot from Manila management.

Does not delete the underlying backend share snapshot.

If provided share snapshot cannot be unmanaged, then raise an UnmanageInvalidShareSnapshot exception, specifying a reason for the failure.

This method is invoked when the snapshot that is being unmanaged belongs to a share that has its share type with driver_handles_share_servers extra-spec set to False.

unmanage_snapshot_with_server(snapshot, share_server=None)

Removes the specified snapshot from Manila management.

Does not delete the underlying backend share snapshot.

If provided share snapshot cannot be unmanaged, then raise an UnmanageInvalidShareSnapshot exception, specifying a reason for the failure.

This method is invoked when the snapshot that is being unmanaged belongs to a share that has its share type with driver_handles_share_servers extra-spec set to True.

unmanage_with_server(share, share_server=None)

Removes the specified share from Manila management.

Does not delete the underlying backend share.

If provided share cannot be unmanaged, then raise an UnmanageInvalidShare exception, specifying a reason for the failure.

This method is invoked when the share is being unmanaged with a share type that has driver_handles_share_servers extra-spec set to True.

update_access(context, share, access_rules, add_rules, delete_rules, share_server=None)

Update access rules for given share.

access_rules contains all access_rules that need to be on the share. If the driver can make bulk access rule updates, it can safely ignore the add_rules and delete_rules parameters.

If the driver cannot make bulk access rule changes, it can rely on new rules to be present in add_rules and rules that need to be removed to be present in delete_rules.

When a rule in delete_rules was never applied, drivers must not raise an exception, or attempt to set the rule to error state.

add_rules and delete_rules can be empty lists, in this situation, drivers should ensure that the rules present in access_rules are the same as those on the back end. One scenario where this situation is forced is when the access_level is changed for all existing rules (share migration and for readable replicas).

Drivers must be mindful of this call for share replicas. When ‘update_access’ is called on one of the replicas, the call is likely propagated to all replicas belonging to the share, especially when individual rules are added or removed. If a particular access rule does not make sense to the driver in the context of a given replica, the driver should be careful to report a correct behavior, and take meaningful action. For example, if R/W access is requested on a replica that is part of a “readable” type replication; R/O access may be added by the driver instead of R/W. Note that raising an exception will result in the access_rules_status on the replica, and the share itself being “out_of_sync”. Drivers can sync on the valid access rules that are provided on the create_replica and promote_replica calls.

Parameters:

context – Current context
share – Share model with share data.
access_rules – A list of access rules for given share
add_rules – Empty List or List of access rules which should be added. access_rules already contains these rules.
delete_rules – Empty List or List of access rules which should be removed. access_rules doesn’t contain these rules.
share_server – None or Share server model

Returns:

None, or a dictionary of updates in the format:

‘09960614-8574-4e03-89cf-7cf267b0bd08’: {

‘access_key’: ‘alice31493e5441b8171d2310d80e37e’, ‘state’: ‘error’,

},

’28f6eabb-4342-486a-a7f4-45688f0c0295’: {

‘access_key’: ‘bob0078aa042d5a7325480fd13228b’, ‘state’: ‘active’,

},

}

The top level keys are ‘access_id’ fields of the access rules that need to be updated. access_key``s are credentials (str) of the entities granted access. Any rule in the ``access_rules parameter can be updated.

Important

Raising an exception in this method will force all rules in ‘applying’ and ‘denying’ states to ‘error’.

An access rule can be set to ‘error’ state, either explicitly via this return parameter or because of an exception raised in this method. Such an access rule will no longer be sent to the driver on subsequent access rule updates. When users deny that rule however, the driver will be asked to deny access to the client/s represented by the rule. We expect that a rule that was error-ed at the driver should never exist on the back end. So, do not fail the deletion request.

Also, it is possible that the driver may receive a request to add a rule that is already present on the back end. This can happen if the share manager service goes down while the driver is committing access rule changes. Since we cannot determine if the rule was applied successfully by the driver before the disruption, we will treat all ‘applying’ transitional rules as new rules and repeat the request.

update_admin_network_allocation(context, share_server): Update admin network allocation after share server creation.

update_network_allocation(context, share_server): Update network allocation after share server creation.

update_replica_state(context, replica_list, replica, access_rules, replica_snapshots, share_server=None)

Update the replica_state of a replica.

Note

This call is made on the host which hosts the replica being updated.

Drivers should fix replication relationships that were broken if possible inside this method.

This method is called periodically by the share manager; and whenever requested by the administrator through the ‘resync’ API.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share This list also contains the replica to be updated. The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
    {
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'active',
        ...
    'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
    'share_server': <models.ShareServer> or None,
    },
    {
    'id': 'e82ff8b6-65f0-11e5-9d70-feff819cdc9f',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'replica_state': 'in_sync',
        ...
    'share_server_id': '07574742-67ea-4dfd-9844-9fbd8ada3d87',
    'share_server': <models.ShareServer> or None,
    },
    ...
]

Parameters:: replica – Dictionary of the replica being updated Replica state will always be ‘in_sync’, ‘out_of_sync’, or ‘error’. Replicas in ‘active’ state will not be passed via this parameter.

Example:

{
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'deleted': False,
    'host': 'openstack2@cmodeSSVMNFS1',
    'status': 'available',
    'scheduled_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'launched_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'terminated_at': None,
    'replica_state': 'in_sync',
    'availability_zone_id': 'e2c2db5c-cb2f-4697-9966-c06fb200cb80',
    'export_locations': [
        models.ShareInstanceExportLocations,
    ],
    'access_rules_status': 'in_sync',
    'share_network_id': '4ccd5318-65f1-11e5-9d70-feff819cdc9f',
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
}

Parameters:: access_rules – A list of access rules These access rules are obeyed by other instances of the share. The driver could attempt to sync on any un-applied access_rules.

Example:

[
 {
    'id': 'f0875f6f-766b-4865-8b41-cccb4cdf1676',
    'deleted' = False,
    'share_id' = 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'access_type' = 'ip',
    'access_to' = '172.16.20.1',
    'access_level' = 'rw',
 }
]

Parameters:: replica_snapshots – List of dictionaries of snapshot instances. This includes snapshot instances of every snapshot of the share whose ‘aggregate_status’ property was reported to be ‘available’ when the share manager initiated this request. Each list member will have two sub dictionaries: ‘active_replica_snapshot’ and ‘share_replica_snapshot’. The ‘active’ replica snapshot corresponds to the instance of the snapshot on any of the ‘active’ replicas of the share while share_replica_snapshot corresponds to the snapshot instance for the specific replica being updated. The driver needs to ensure that this snapshot instance is truly available before transitioning from ‘out_of_sync’ to ‘in_sync’. Snapshots instances for snapshots that have an ‘aggregate_status’ of ‘creating’ or ‘deleting’ will be polled for in the update_replicated_snapshot method.

Example:

 [
  {
'active_replica_snapshot': {
     'id': '8bda791c-7bb6-4e7b-9b64-fefff85ff13e',
     'share_instance_id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
     'status': 'available',
     'provider_location': '/newton/share-snapshot-10e49c3e-aca9',
     ...
    },
 'share_replica_snapshot': {
     'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
     'share_instance_id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
     'status': 'creating',
     'provider_location': None,
        ...
    },
  }
 ]

Parameters:: share_server – <models.ShareServer> or None
Returns:: replica_state: a str value denoting the replica_state. Valid values are ‘in_sync’ and ‘out_of_sync’ or None (to leave the current replica_state unchanged).

update_replicated_snapshot(context, replica_list, share_replica, replica_snapshots, replica_snapshot, share_server=None)

Update the status of a snapshot instance that lives on a replica.

Note

For DR and Readable styles of replication, this call is made on the replica’s host and not the ‘active’ replica’s host.

This method is called periodically by the share manager. It will query for snapshot instances that track the parent snapshot across non-‘active’ replicas. Drivers can expect the status of the instance to be ‘creating’ or ‘deleting’. If the driver sees that a snapshot instance has been removed from the replica’s backend and the instance status was set to ‘deleting’, it is expected to raise a SnapshotResourceNotFound exception. All other exceptions will set the snapshot instance status to ‘error’. If the instance was not in ‘deleting’ state, raising a SnapshotResourceNotFound will set the instance status to ‘error’.

Parameters:

context – Current context
replica_list – List of all replicas for a particular share The ‘active’ replica will have its ‘replica_state’ attr set to ‘active’.

Example:

[
     {
      'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
      'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
      'replica_state': 'in_sync',
      ...
      'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
      'share_server': <models.ShareServer> or None,
     },
     {
      'id': '10e49c3e-aca9-483b-8c2d-1c337b38d6af',
      'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
      'replica_state': 'active',
      ...
      'share_server_id': 'f63629b3-e126-4448-bec2-03f788f76094',
      'share_server': <models.ShareServer> or None,
     },
      ...
]

Parameters:: share_replica – Share replica dictionary. This replica is associated with the snapshot instance whose status is being updated. Replicas in ‘active’ replica_state will not be passed via this parameter.

Example:

{
    'id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_id': 'f0e4bb5e-65f0-11e5-9d70-feff819cdc9f',
    'deleted': False,
    'host': 'openstack2@cmodeSSVMNFS1',
    'status': 'available',
    'scheduled_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'launched_at': datetime.datetime(2015, 8, 10, 0, 5, 58),
    'terminated_at': None,
    'replica_state': 'in_sync',
    'availability_zone_id': 'e2c2db5c-cb2f-4697-9966-c06fb200cb80',
    'export_locations': [
        models.ShareInstanceExportLocations,
    ],
    'access_rules_status': 'in_sync',
    'share_network_id': '4ccd5318-65f1-11e5-9d70-feff819cdc9f',
    'share_server_id': '4ce78e7b-0ef6-4730-ac2a-fd2defefbd05',
}

Parameters:: replica_snapshots – List of dictionaries of snapshot instances. These snapshot instances track the snapshot across the replicas. This will include the snapshot instance being updated as well.

Example:

 [
    {
    'id': 'd3931a93-3984-421e-a9e7-d9f71895450a',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
        ...
    },
    {
    'id': '8bda791c-7bb6-4e7b-9b64-fefff85ff13e',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
        ...
    },
    ...
]

Parameters:: replica_snapshot – Dictionary of the snapshot instance. This is the instance to be updated. It will be in ‘creating’ or ‘deleting’ state when sent via this parameter.

Example:

{
    'name': 'share-snapshot-18825630-574f-4912-93bb-af4611ef35a2',
    'share_id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'share_name': 'share-d487b88d-e428-4230-a465-a800c2cce5f8',
    'status': 'creating',
    'id': '18825630-574f-4912-93bb-af4611ef35a2',
    'deleted': False,
    'created_at': datetime.datetime(2016, 8, 3, 0, 5, 58),
    'share': <models.ShareInstance>,
    'updated_at': datetime.datetime(2016, 8, 3, 0, 5, 58),
    'share_instance_id': 'd487b88d-e428-4230-a465-a800c2cce5f8',
    'snapshot_id': '13ee5cb5-fc53-4539-9431-d983b56c5c40',
    'progress': '0%',
    'deleted_at': None,
    'provider_location': None,
}

Parameters:: share_server – <models.ShareServer> or None
Returns:: replica_snapshot_model_update: a dictionary. The dictionary must contain values that need to be updated on the database for the snapshot instance that represents the snapshot on the replica.
Raises:: exception.SnapshotResourceNotFound Raise this exception for snapshots that are not found on the backend and their status was ‘deleting’.

update_share_from_metadata(context, share, metadata, share_server=None)

Update the share from metadata.

Driver must implement this method if needs to perform some action on given resource (i.e. share) based on provided metadata.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share – Share instance model with share data.
metadata – Dict contains key-value pair where driver will perform necessary action based on key.
share_server – Reference to the share server.

update_share_server_network_allocations(context, share_server, current_network_allocations, new_network_allocations, security_services, shares, snapshots)

Updates a share server’s network allocations.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_server – reference to the share server that have to update network allocations.
current_network_allocations – all network allocations associated with the share server that will be updated

Example:

{
    'admin_network_allocations':
        [
            {
                'ip_address': '10.193.154.11',
                'ip_version': 4,
                'cidr': '10.193.154.0/28',
                'gateway': '10.193.154.1',
                'mtu': 1500,
                'network_type': 'vlan',
                'segmentation_id': 3000,
                'mac_address': ' AA:AA:AA:AA:AA:AA',
            },
            ...
        ],
    'subnets':
        [
           {
            'share_network_subnet_id': '0bdeaa8c6db3-3bc10d67',
            'neutron_net_id': '2598-4122-bb62-0bdeaa8c6db3',
            'neutron_subnet_id': '3bc10d67-2598-4122-bb62',
            'network_allocations':
                [
                    {
                        'ip_address': '10.193.154.10',
                        'ip_version': 4,
                        'cidr': '10.193.154.0/28',
                        'gateway': '10.193.154.1',
                        'mtu': 1500,
                        'network_type': 'vlan',
                        'segmentation_id': 3000,
                        'mac_address': ' AA:AA:AA:AA:AA:AA',
                    },
                    ...
                ],
            },
        ],
}

Parameters:: new_network_allocations – allocations that must be configured in the share server.

Example:

{
    'share_network_subnet_id': '0bdeaa8c6db3-3bc10d67',
    'neutron_net_id': '2598-4122-bb62-0bdeaa8c6db3',
    'neutron_subnet_id': '3bc10d67-2598-4122-bb62',
    'network_allocations':
        [
            {
                'ip_address': '10.193.154.10',
                'ip_version': 4,
                'cidr': '10.193.154.0/28',
                'gateway': '10.193.154.1',
                'mtu': 1500,
                'network_type': 'vlan',
                'segmentation_id': 3000,
                'mac_address': 'AA:AA:AA:AA:AA:AA',
                ...
            },
        ],
},

Parameters:

security_services – list of security services configured with this share server.
shares – All shares in the share server.
snapshots – All snapshots in the share server.

Raises:

Exception. By raising an exception, the share server and all its shares and snapshots instances will be set to ‘error’. The error can contain the field ‘details_data’ as a dict with the key ‘server_details’ containing the backend details dict that will be saved to share server.

:return If the update changes the shares export locations or snapshots

export locations, this method should return a dictionary containing a list of share instances and snapshot instances indexed by their id’s, where each instance should provide a dict with the relevant information that need to be updated. Also, the returned dict can contain the updated back end details to be saved in the database.

Example:

{
    'share_updates':
    {
        '4363eb92-23ca-4888-9e24-502387816e2a':
        [
            {
            'path': '1.2.3.4:/foo',
            'metadata': {},
            'is_admin_only': False
            },
            {
            'path': '5.6.7.8:/foo',
            'metadata': {},
            'is_admin_only': True
            },
        ],
        ...
    },
    'snapshot_updates':
    {
        'bc4e3b28-0832-4168-b688-67fdc3e9d408':
        {
        'provider_location': '/snapshots/foo/bar_1',
        'export_locations':
        [
            {
            'path': '1.2.3.4:/snapshots/foo/bar_1',
            'is_admin_only': False,
            },
            {
            'path': '5.6.7.8:/snapshots/foo/bar_1',
            'is_admin_only': True,
            },
        ],
        },
        '2e62b7ea-4e30-445f-bc05-fd523ca62941':
        {
        'provider_location': '/snapshots/foo/bar_2',
        'export_locations':
        [
            {
            'path': '1.2.3.4:/snapshots/foo/bar_2',
            'is_admin_only': False,
            },
            {
            'path': '5.6.7.8:/snapshots/foo/bar_2',
            'is_admin_only': True,
            },
        ],
        },
    }
    'server_details':
    {
        'new_share_server_info_key':
            'new_share_server_info_value',
    },
}

update_share_server_security_service(context, share_server, network_info, share_instances, share_instance_rules, new_security_service, current_security_service=None)

Updates share server security service configuration.

Parameters:

context – The ‘context.RequestContext’ object for the request.
share_server – Reference to the share server object that will be updated.
network_info – All network allocation associated with the share server that will be updated.
share_instances – A list of share instances that belong to the share server that is being updated.
share_instance_rules – A list of access rules, grouped by share instance, in the following format.

Example:

[
   {
    'share_instance_id': '3bc10d67-2598-4122-bb62-0bdeaa8c6db3',
    'access_rules':
    [
        {
        'access_id':'906d0094-3e34-4d6c-a184-d08a908033e3',
        'access_type':'ip',
        'access_key':None,
        'access_to':'10.0.0.1',
        'access_level':'rw'
         ...
        },
    ],
    },
]

Parameters:

new_security_service – New security service object to be configured in the share server.
current_security_service – When provided, represents the current security service that will be replaced by the ‘new_security_service’.

Raises:

ShareBackendException. A ShareBackendException should only be raised if the share server failed to update the security service, compromising all its access rules. By raising an exception, the share server and all its share instances will be set to ‘error’.

Returns:

None, or a dictionary of updates in the following format.

Example:

{
    '3bc10d67-2598-4122-bb62-0bdeaa8c6db3':
    {
        '09960614-8574-4e03-89cf-7cf267b0bd08':
        {
            'access_key': 'alice31493e5441b8171d2310d80e37e',
            'state': 'error',
        },
        '28f6eabb-4342-486a-a7f4-45688f0c0295':
        {
            'access_key': 'bob0078aa042d5a7325480fd13228b',
            'state': 'active',
        },
    },
}

The top level keys are share_instance_id’s which should provide another dictionary of access rules to be updated, indexed by their ‘access_id’. The inner access rules dictionary should only contain the access rules that need to be updated.

update_share_usage_size(context, shares)

Invoked to get the usage size of given shares.

Driver can use this method to update the share usage size of the shares. To do that, a dictionary of shares should be returned. :param shares: None or a list of all shares for updates. :returns: An empty list or a list of dictionary of updates in the following format. The value of “used_size” can be specified in GiB units, as a floating point number:

[
    {
        'id': '09960614-8574-4e03-89cf-7cf267b0bd08',
        'used_size': '200',
        'gathered_at': datetime.datetime(2017, 8, 10, 15, 14, 6),
    },
]

Shared Filesystems

Shared Filesystems¶

manila 19.1.0.dev42

Page Contents

Shared Filesystems

Shared Filesystems¶

The manila.share.manager Module¶

The manila.share.driver Module¶

manila 19.1.0.dev42

Page Contents

The `manila.share.manager` Module¶

The `manila.share.driver` Module¶