ZFS (on Linux) Driver

Manila ZFSonLinux share driver uses ZFS filesystem for exporting NFS shares. Written and tested using Linux version of ZFS.

Requirements

  • ‘NFS’ daemon that can be handled via “exportfs” app.

  • ‘ZFS’ filesystem packages, either Kernel or FUSE versions.

  • ZFS zpools that are going to be used by Manila should exist and be configured as desired. Manila will not change zpool configuration.

  • For remote ZFS hosts according to manila-share service host SSH should be installed.

  • For ZFS hosts that support replication:

    • SSH access for each other should be passwordless.

    • Service IP addresses should be available by ZFS hosts for each other.

Supported Operations

The following operations are supported:

  • Create NFS Share

  • Delete NFS Share

  • Manage NFS Share

  • Unmanage NFS Share

  • Allow NFS Share access

    • Only IP access type is supported for NFS

    • Both access levels are supported - ‘RW’ and ‘RO’

  • Deny NFS Share access

  • Create snapshot

  • Delete snapshot

  • Manage snapshot

  • Unmanage snapshot

  • Create share from snapshot

  • Extend share

  • Shrink share

  • Replication (experimental):

    • Create/update/delete/promote replica operations are supported

  • Share migration (experimental)

Possibilities

  • Any amount of ZFS zpools can be used by share driver.

  • Allowed to configure default options for ZFS datasets that are used for share creation.

  • Any amount of nested datasets is allowed to be used.

  • All share replicas are read-only, only active one is RW.

  • All share replicas are synchronized periodically, not continuously. So, status ‘in_sync’ means latest sync was successful. Time range between syncs equals to value of config global opt ‘replica_state_update_interval’.

  • Driver is able to use qualified extra spec ‘zfsonlinux:compression’. It can contain any value that is supported by used ZFS app. But if it is disabled via config option with value ‘compression=off’, then it will not be used.

Restrictions

The ZFSonLinux share driver has the following restrictions:

  • Only IP access type is supported for NFS.

  • Only FLAT network is supported.

  • ‘Promote share replica’ operation will switch roles of current ‘secondary’ replica and ‘active’. It does not make more than one active replica available.

  • ‘SaMBa’ based sharing is not yet implemented.

  • ‘Thick provisioning’ is not yet implemented.

Known problems

  • ‘Promote share replica’ operation will make ZFS filesystem that became secondary as RO only on NFS level. On ZFS level system will stay mounted as was - RW.

Backend Configuration

The following parameters need to be configured in the manila configuration file for the ZFSonLinux driver:

  • share_driver = manila.share.drivers.zfsonlinux.driver.ZFSonLinuxShareDriver

  • driver_handles_share_servers = False

  • replication_domain = custom_str_value_as_domain_name

    • if empty, then replication will be disabled

    • if set then will be able to be used as replication peer for other backend with same value.

  • zfs_share_export_ip = <user_facing IP address of ZFS host>

  • zfs_service_ip = <IP address of service network interface of ZFS host>

  • zfs_zpool_list = zpoolname1,zpoolname2/nested_dataset_for_zpool2

    • can be one or more zpools

    • can contain nested datasets

  • zfs_dataset_creation_options = <list of ZFS dataset options>

    • readonly,quota,sharenfs and sharesmb options will be ignored

  • zfs_dataset_name_prefix = <prefix>

    • Prefix to be used in each dataset name.

  • zfs_dataset_snapshot_name_prefix = <prefix>

    • Prefix to be used in each dataset snapshot name.

  • zfs_use_ssh = <boolean_value>

    • set ‘False’ if ZFS located on the same host as ‘manila-share’ service

    • set ‘True’ if ‘manila-share’ service should use SSH for ZFS configuration

  • zfs_ssh_username = <ssh_username>

    • required for replication operations

    • required for SSH’ing to ZFS host if ‘zfs_use_ssh’ is set to ‘True’

  • zfs_ssh_user_password = <ssh_user_password>

    • password for ‘zfs_ssh_username’ of ZFS host.

    • used only if ‘zfs_use_ssh’ is set to ‘True’

  • zfs_ssh_private_key_path = <path_to_private_ssh_key>

    • used only if ‘zfs_use_ssh’ is set to ‘True’

  • zfs_share_helpers = NFS=manila.share.drivers.zfsonlinux.utils.NFSviaZFSHelper

    • Approach for setting up helpers is similar to various other share driver

    • At least one helper should be used.

  • zfs_replica_snapshot_prefix = <prefix>

    • Prefix to be used in dataset snapshot names that are created by ‘update replica’ operation.

  • zfs_migration_snapshot_prefix = <prefix>

    • Prefix to be used in dataset snapshot names that are created for ‘migration’ operation.

Restart of manila-share service is needed for the configuration changes to take effect.

The manila.share.drivers.zfsonlinux.driver Module

Module with ZFSonLinux share driver that utilizes ZFS filesystem resources and exports them as shares.

class ZFSonLinuxShareDriver(*args, **kwargs)

Bases: manila.share.drivers.zfsonlinux.utils.ExecuteMixin, manila.share.driver.ShareDriver

create_replica(context, *args, **kwargs)

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, *args, **kwargs)

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, *args, **kwargs)

Is called to create share.

create_share_from_snapshot(context, *args, **kwargs)

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_snapshot(context, *args, **kwargs)

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.

delete_replica(context, *args, **kwargs)

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, *args, **kwargs)

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, *args, **kwargs)

Is called to remove share.

delete_snapshot(context, *args, **kwargs)

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.

do_setup(context)

Perform basic setup and checks.

ensure_share(context, *args, **kwargs)

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.

Returns

None or list with export locations

extend_share(context, *args, **kwargs)

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_network_allocations_number()

ZFS does not handle networking. Return 0.

get_pool(share)

Return pool name where the share resides on.

Parameters

share – The share hosted by the driver.

manage_existing(share, driver_options)

Manage existing ZFS dataset as manila share.

ZFSonLinux driver accepts only one driver_option ‘size’. If an administrator provides this option, then such quota will be set to dataset and used as share size. Otherwise, driver will set quota equal to nearest bigger rounded integer of usage size. Driver does not expect mountpoint to be changed (should be equal to default that is “/%(dataset_name)s”).

Parameters

  • share – share data

  • driver_options – Empty dict or dict with ‘size’ option.

Returns

dict with share size and its export locations.

manage_existing_snapshot(snapshot_instance, driver_options)

Manage existing share snapshot with manila.

Parameters

  • snapshot_instance – SnapshotInstance data

  • driver_options – expects only one optional key ‘size’.

Returns

dict with share snapshot instance fields for update, example:

{

‘size’: 1, ‘provider_location’: ‘path/to/some/dataset@some_snapshot_tag’,

}

migration_cancel(context, *args, **kwargs)

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, *args, **kwargs)

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, *args, **kwargs)

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, *args, **kwargs)

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_start(context, *args, **kwargs)

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, *args, **kwargs)

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.

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.

shrink_share(context, *args, **kwargs)

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

unmanage(share)

Removes the specified share from Manila management.

unmanage_snapshot(snapshot_instance)

Unmanage dataset snapshot.

update_access(context, *args, **kwargs)

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_replica_state(context, *args, **kwargs)

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, *args, **kwargs)

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’.

ensure_share_server_not_provided(f)
get_backend_configuration(backend_name)

The manila.share.drivers.zfsonlinux.utils Module

Module for storing ZFSonLinux driver utility stuff such as:

  • Common ZFS code

  • Share helpers

class ExecuteMixin

Bases: manila.share.driver.ExecuteMixin

execute(*cmd, **kwargs)

Common interface for running shell commands.

execute_with_retry(*cmd, **kwargs)

Retry wrapper over common shell interface.

get_zfs_option(dataset_name, option_name, **kwargs)

Returns value of requested zfs dataset option.

get_zpool_option(zpool_name, option_name, **kwargs)

Returns value of requested zpool option.

init_execute_mixin(*args, **kwargs)

Init method for mixin called in the end of driver’s __init__().

parse_zfs_answer(string)

Returns list of dicts with data returned by ZFS shell commands.

zfs(*cmd, **kwargs)

ZFS shell commands executor.

zfs_with_retry(*cmd, **kwargs)

ZFS shell commands executor.

class NASHelperBase(configuration)

Bases: object

Base class for share helpers of ‘ZFS on Linux’ driver.

abstract create_exports(dataset_name, executor)

Creates share exports.

abstract get_exports(dataset_name, service, executor)

Gets/reads share exports.

abstract remove_exports(dataset_name, executor)

Removes share exports.

abstract update_access(dataset_name, access_rules, add_rules, delete_rules, executor)

Update access rules for specified ZFS dataset.

abstract verify_setup()

Performs checks for required stuff.

class NFSviaZFSHelper(configuration)

Bases: manila.share.drivers.zfsonlinux.utils.ExecuteMixin, manila.share.drivers.zfsonlinux.utils.NASHelperBase

Helper class for handling ZFS datasets as NFS shares.

Kernel and Fuse versions of ZFS have different syntax for setting up access rules, and this Helper designed to satisfy both making autodetection.

create_exports(dataset_name, executor=None)

Creates NFS share exports for given ZFS dataset.

get_exports(dataset_name, executor=None)

Gets/reads NFS share export for given ZFS dataset.

property is_kernel_version

Says whether Kernel version of ZFS is used or not.

remove_exports(*args, **kwargs)

Removes share exports.

update_access(*args, **kwargs)

Update access rules for specified ZFS dataset.

verify_setup()

Performs checks for required stuff.

get_remote_shell_executor(ip, port, conn_timeout, login=None, password=None, privatekey=None, max_size=10)
zfs_dataset_synchronized(f)