Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE OpenStack Cloud 8

8 Shared File Systems

Shared File Systems service provides a set of services for management of shared file systems in a multi-project cloud environment. The service resembles OpenStack block-based storage management from the OpenStack Block Storage service project. With the Shared File Systems service, you can create a remote file system, mount the file system on your instances, and then read and write data from your instances to and from your file system.

The Shared File Systems service serves same purpose as the Amazon Elastic File System (EFS) does.

8.1 Introduction

The OpenStack File Share service allows you to offer shared file systems service to OpenStack users in your installation. The Shared File Systems service can run in a single-node or multiple node configuration. The Shared File Systems service can be configured to provision shares from one or more back ends, so it is required to declare at least one back end. Shared File System service contains several configurable components.

It is important to understand these components:

  • Share networks

  • Shares

  • Multi-tenancy

  • Back ends

The Shared File Systems service consists of four types of services, most of which are similar to those of the Block Storage service:

  • manila-api

  • manila-data

  • manila-scheduler

  • manila-share

Installation of first three - manila-api, manila-data, and manila-scheduler is common for almost all deployments. But configuration of manila-share is backend-specific and can differ from deployment to deployment.

8.2 Key concepts

8.2.1 Share

In the Shared File Systems service share is the fundamental resource unit allocated by the Shared File System service. It represents an allocation of a persistent, readable, and writable filesystems. Compute instances access these filesystems. Depending on the deployment configuration, clients outside of OpenStack can also access the filesystem.

Note
Note

A share is an abstract storage object that may or may not directly map to a "share" concept from the underlying storage provider. See the description of share instance for more details.

8.2.2 Share instance

This concept is tied with share and represents created resource on specific back end, when share represents abstraction between end user and back-end storages. In common cases, it is one-to-one relation. One single share has more than one share instance in two cases:

  • When share migration is being applied

  • When share replication is enabled

Therefore, each share instance stores information specific to real allocated resource on storage. And share represents the information that is common for share instances. A user with member role will not be able to work with it directly. Only a user with admin role has rights to perform actions against specific share instances.

8.2.3 Snapshot

A snapshot is a point-in-time, read-only copy of a share. You can create Snapshots from an existing, operational share regardless of whether a client has mounted the file system. A snapshot can serve as the content source for a new share. Specify the Create from snapshot option when creating a new share on the dashboard.

8.2.4 Storage Pools

With the Kilo release of OpenStack, Shared File Systems can use storage pools. The storage may present one or more logical storage resource pools that the Shared File Systems service will select as a storage location when provisioning shares.

8.2.5 Share Type

Share type is an abstract collection of criteria used to characterize shares. They are most commonly used to create a hierarchy of functional capabilities. This hierarchy represents tiered storage services levels. For example, an administrator might define a premium share type that indicates a greater level of performance than a basic share type. Premium represents the best performance level.

8.2.6 Share Access Rules

Share access rules define which users can access a particular share. For example, administrators can declare rules for NFS shares by listing the valid IP networks which will access the share. List the IP networks in CIDR notation.

8.2.7 Security Services

Security services``allow granular client access rules for administrators. They can declare rules for authentication or authorization to access ``share content. External services including LDAP, Active Directory, and Kerberos can be declared as resources. Examine and consult these resources when making an access decision for a particular share. You can associate Shares with multiple security services, but only one service per one type.

8.2.8 Share Networks

A share network is an object that defines a relationship between a project network and subnet, as defined in an OpenStack Networking service or Compute service. The share network is also defined in shares created by the same project. A project may find it desirable to provision shares such that only instances connected to a particular OpenStack-defined network have access to the share. Also, security services can be attached to share networks, because most of auth protocols require some interaction with network services.

The Shared File Systems service has the ability to work outside of OpenStack. That is due to the StandaloneNetworkPlugin. The plugin is compatible with any network platform, and does not require specific network services in OpenStack like Compute or Networking service. You can set the network parameters in the manila.conf file.

8.2.9 Share Servers

A share server is a logical entity that hosts the shares created on a specific share network. A share server may be a configuration object within the storage controller, or it may represent logical resources provisioned within an OpenStack deployment used to support the data path used to access shares.

Share servers interact with network services to determine the appropriate IP addresses on which to export shares according to the related share network. The Shared File Systems service has a pluggable network model that allows share servers to work with different implementations of the Networking service.

8.3 Share management

A share is a remote, mountable file system. You can mount a share to and access a share from several hosts by several users at a time.

You can create a share and associate it with a network, list shares, and show information for, update, and delete a specified share. You can also create snapshots of shares. To create a snapshot, you specify the ID of the share that you want to snapshot.

The shares are based on of the supported Shared File Systems protocols:

  • NFS. Network File System (NFS).

  • CIFS. Common Internet File System (CIFS).

  • GLUSTERFS. Gluster file system (GlusterFS).

  • HDFS. Hadoop Distributed File System (HDFS).

  • CEPHFS. Ceph File System (CephFS).

The Shared File Systems service provides set of drivers that enable you to use various network file storage devices, instead of the base implementation. That is the real purpose of the Shared File Systems service in production.

8.3.1 Share basic operations

8.3.1.1 General concepts

To create a file share, and access it, the following general concepts are prerequisite knowledge:

  1. To create a share, use manila create command and specify the required arguments: the size of the share and the shared file system protocol. NFS, CIFS, GlusterFS, HDFS, or CephFS share file system protocols are supported.

  2. You can also optionally specify the share network and the share type.

  3. After the share becomes available, use the manila show command to get the share export locations.

  4. After getting the share export locations, you can create an Section 8.3.1.8, “Manage access to share” for the share, mount it and work with files on the remote file system.

There are big number of the share drivers created by different vendors in the Shared File Systems service. As a Python class, each share driver can be set for the Section 8.10, “Multi-storage configuration” and run in the back end to manage the share operations.

Initially there are two driver modes for the back ends:

  • no share servers mode

  • share servers mode

Each share driver supports one or two of possible back end modes that can be configured in the manila.conf file. The configuration option driver_handles_share_servers in the manila.conf file sets the share servers mode or no share servers mode, and defines the driver mode for share storage lifecycle management:

Mode

Config option

Description

no share servers

driver_handles_share_servers = False

An administrator rather than a share driver manages the bare metal storage with some net interface instead of the presence of the share servers.

share servers

driver_handles_share_servers = True

The share driver creates the share server and manages, or handles, the share server life cycle.

It is Section 8.5, “Share types” which have the extra specifications that help scheduler to filter back ends and choose the appropriate back end for the user that requested to create a share. The required extra boolean specification for each share type is driver_handles_share_servers. As an administrator, you can create the share types with the specifications you need. For details of managing the share types and configuration the back ends, see Section 8.5, “Share types” and Section 8.10, “Multi-storage configuration” documentation.

You can create a share in two described above modes:

8.3.1.2 Create a share in no share servers mode

To create a file share in no share servers mode, you need to:

  1. To create a share, use manila create command and specify the required arguments: the size of the share and the shared file system protocol. NFS, CIFS, GlusterFS, HDFS, or CephFS share file system protocols are supported.

  2. You should specify the Section 8.5, “Share types” with driver_handles_share_servers = False extra specification.

  3. You must not specify the share network because no share servers are created. In this mode the Shared File Systems service expects that administrator has some bare metal storage with some net interface.

  4. The manila create command creates a share. This command does the following things:

    • The Section 8.10.1, “Scheduling” service will find the back end with driver_handles_share_servers = False mode due to filtering the extra specifications of the share type.

    • The share is created using the storage that is specified in the found back end.

  5. After the share becomes available, use the manila show command to get the share export locations.

In the example to create a share, the created already share type named my_type with driver_handles_share_servers = False extra specification is used.

Check share types that exist, run:

$ manila type-list
+------+---------+------------+------------+--------------------------------------+-------------------------+
| ID   | Name    | visibility | is_default | required_extra_specs                 | optional_extra_specs    |
+------+---------+------------+------------+--------------------------------------+-------------------------+
| %ID% | my_type | public     | -          | driver_handles_share_servers : False | snapshot_support : True |
+------+---------+------------+------------+--------------------------------------+-------------------------+

Create a private share with my_type share type, NFS shared file system protocol, and size 1 GB:

$ manila create nfs 1 --name Share1 --description "My share" --share-type my_type
+-----------------------------+--------------------------------------+
| Property                    | Value                                |
+-----------------------------+--------------------------------------+
| status                      | creating                             |
| share_type_name             | my_type                              |
| description                 | My share                             |
| availability_zone           | None                                 |
| share_network_id            | None                                 |
| share_server_id             | None                                 |
| host                        |                                      |
| access_rules_status         | active                               |
| snapshot_id                 | None                                 |
| is_public                   | False                                |
| task_state                  | None                                 |
| snapshot_support            | True                                 |
| id                          | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| size                        | 1                                    |
| name                        | Share1                               |
| share_type                  | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas                | False                                |
| replication_type            | None                                 |
| created_at                  | 2016-03-25T12:02:46.000000           |
| share_proto                 | NFS                                  |
| consistency_group_id        | None                                 |
| source_cgsnapshot_member_id | None                                 |
| project_id                  | 907004508ef4447397ce6741a8f037c1     |
| metadata                    | {}                                   |
+-----------------------------+--------------------------------------+

New share Share2 should have a status available:

$ manila show Share2
+-----------------------------+----------------------------------------------------------+
| Property                    | Value                                                    |
+-----------------------------+----------------------------------------------------------+
| status                      | available                                                |
| share_type_name             | my_type                                                  |
| description                 | My share                                                 |
| availability_zone           | nova                                                     |
| share_network_id            | None                                                     |
| export_locations            |                                                          |
|                             | path = 10.0.0.4:/shares/manila_share_a5fb1ab7_...        |
|                             | preferred = False                                        |
|                             | is_admin_only = False                                    |
|                             | id = 9e078eee-bcad-40b8-b4fe-1c916cf98ed1                |
|                             | share_instance_id = a5fb1ab7-0bbd-465b-ac14-05706294b6e9 |
|                             | path = 172.18.198.52:/shares/manila_share_a5fb1ab7_...   |
|                             | preferred = False                                        |
|                             | is_admin_only = True                                     |
|                             | id = 44933f59-e0e3-4483-bb88-72ba7c486f41                |
|                             | share_instance_id = a5fb1ab7-0bbd-465b-ac14-05706294b6e9 |
| share_server_id             | None                                                     |
| host                        | manila@paris#epsilon                                     |
| access_rules_status         | active                                                   |
| snapshot_id                 | None                                                     |
| is_public                   | False                                                    |
| task_state                  | None                                                     |
| snapshot_support            | True                                                     |
| id                          | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88                     |
| size                        | 1                                                        |
| name                        | Share1                                                   |
| share_type                  | 14ee8575-aac2-44af-8392-d9c9d344f392                     |
| has_replicas                | False                                                    |
| replication_type            | None                                                     |
| created_at                  | 2016-03-25T12:02:46.000000                               |
| share_proto                 | NFS                                                      |
| consistency_group_id        | None                                                     |
| source_cgsnapshot_member_id | None                                                     |
| project_id                  | 907004508ef4447397ce6741a8f037c1                         |
| metadata                    | {}                                                       |
+-----------------------------+----------------------------------------------------------+

8.3.1.3 Create a share in share servers mode

To create a file share in share servers mode, you need to:

  1. To create a share, use manila create command and specify the required arguments: the size of the share and the shared file system protocol. NFS, CIFS, GlusterFS, HDFS, or CephFS share file system protocols are supported.

  2. You should specify the Section 8.5, “Share types” with driver_handles_share_servers = True extra specification.

  3. You should specify the Section 8.11.1, “Share networks”.

  4. The manila create command creates a share. This command does the following things:

    • The Section 8.10.1, “Scheduling” service will find the back end with driver_handles_share_servers = True mode due to filtering the extra specifications of the share type.

    • The share driver will create a share server with the share network. For details of creating the resources, see the documentation of the specific share driver.

  5. After the share becomes available, use the manila show command to get the share export location.

In the example to create a share, the default share type and the already existing share network are used.

Note
Note

There is no default share type just after you started manila as the administrator. See Section 8.5, “Share types” to create the default share type. To create a share network, use Section 8.11.1, “Share networks”.

Check share types that exist, run:

$ manila type-list
+------+---------+------------+------------+--------------------------------------+-------------------------+
| ID   | Name    | visibility | is_default | required_extra_specs                 | optional_extra_specs    |
+------+---------+------------+------------+--------------------------------------+-------------------------+
| %id% | default | public     | YES        | driver_handles_share_servers : True  | snapshot_support : True |
+------+---------+------------+------------+--------------------------------------+-------------------------+

Check share networks that exist, run:

$ manila share-network-list
+--------------------------------------+--------------+
| id                                   | name         |
+--------------------------------------+--------------+
| c895fe26-92be-4152-9e6c-f2ad230efb13 | my_share_net |
+--------------------------------------+--------------+

Create a public share with my_share_net network, default share type, NFS shared file system protocol, and size 1 GB:

$ manila create nfs 1 \
    --name "Share2" \
    --description "My second share" \
    --share-type default \
    --share-network my_share_net \
    --metadata aim=testing \
    --public
+-----------------------------+--------------------------------------+
| Property                    | Value                                |
+-----------------------------+--------------------------------------+
| status                      | creating                             |
| share_type_name             | default                              |
| description                 | My second share                      |
| availability_zone           | None                                 |
| share_network_id            | c895fe26-92be-4152-9e6c-f2ad230efb13 |
| share_server_id             | None                                 |
| host                        |                                      |
| access_rules_status         | active                               |
| snapshot_id                 | None                                 |
| is_public                   | True                                 |
| task_state                  | None                                 |
| snapshot_support            | True                                 |
| id                          | 195e3ba2-9342-446a-bc93-a584551de0ac |
| size                        | 1                                    |
| name                        | Share2                               |
| share_type                  | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf |
| has_replicas                | False                                |
| replication_type            | None                                 |
| created_at                  | 2016-03-25T12:13:40.000000           |
| share_proto                 | NFS                                  |
| consistency_group_id        | None                                 |
| source_cgsnapshot_member_id | None                                 |
| project_id                  | 907004508ef4447397ce6741a8f037c1     |
| metadata                    | {u'aim': u'testing'}                 |
+-----------------------------+--------------------------------------+

The share also can be created from a share snapshot. For details, see Section 8.6, “Share snapshots”.

See the share in a share list:

$ manila list
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| ID                                   | Name    | Size | Share Proto | Status    | Is Public | Share Type Name | Host                 | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1  | 1    | NFS         | available | False     | my_type         | manila@paris#epsilon | nova              |
| 195e3ba2-9342-446a-bc93-a584551de0ac | Share2  | 1    | NFS         | available | True      | default         | manila@london#LONDON | nova              |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+

Check the share status and see the share export locations. After creating status share should have status available:

$ manila show Share2
+----------------------+----------------------------------------------------------------------+
| Property             | Value                                                                |
+----------------------+----------------------------------------------------------------------+
| status               | available                                                            |
| share_type_name      | default                                                              |
| description          | My second share                                                      |
| availability_zone    | nova                                                                 |
| share_network_id     | c895fe26-92be-4152-9e6c-f2ad230efb13                                 |
| export_locations     |                                                                      |
|                      | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
|                      | preferred = False                                                    |
|                      | is_admin_only = False                                                |
|                      | id = de6d4012-6158-46f0-8b28-4167baca51a7                            |
|                      | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965             |
|                      | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965   |
|                      | preferred = False                                                    |
|                      | is_admin_only = True                                                 |
|                      | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a                            |
|                      | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965             |
| share_server_id      | 2e9d2d02-883f-47b5-bb98-e053b8d1e683                                 |
| host                 | manila@london#LONDON                                                 |
| access_rules_status  | active                                                               |
| snapshot_id          | None                                                                 |
| is_public            | True                                                                 |
| task_state           | None                                                                 |
| snapshot_support     | True                                                                 |
| id                   | 195e3ba2-9342-446a-bc93-a584551de0ac                                 |
| size                 | 1                                                                    |
| name                 | Share2                                                               |
| share_type           | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf                                 |
| has_replicas         | False                                                                |
| replication_type     | None                                                                 |
| created_at           | 2016-03-25T12:13:40.000000                                           |
| share_proto          | NFS                                                                  |
| consistency_group_id | None                                                                 |
| project_id           | 907004508ef4447397ce6741a8f037c1                                     |
| metadata             | {u'aim': u'testing'}                                                 |
+----------------------+----------------------------------------------------------------------+

is_public defines the level of visibility for the share: whether other projects can or cannot see the share. By default, the share is private.

8.3.1.4 Update share

Update the name, or description, or level of visibility for all projects for the share if you need:

$ manila update Share2 --description "My second share. Updated" --is-public False

$ manila show Share2
+----------------------+----------------------------------------------------------------------+
| Property             | Value                                                                |
+----------------------+----------------------------------------------------------------------+
| status               | available                                                            |
| share_type_name      | default                                                              |
| description          | My second share. Updated                                             |
| availability_zone    | nova                                                                 |
| share_network_id     | c895fe26-92be-4152-9e6c-f2ad230efb13                                 |
| export_locations     |                                                                      |
|                      | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
|                      | preferred = False                                                    |
|                      | is_admin_only = False                                                |
|                      | id = de6d4012-6158-46f0-8b28-4167baca51a7                            |
|                      | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965             |
|                      | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965   |
|                      | preferred = False                                                    |
|                      | is_admin_only = True                                                 |
|                      | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a                            |
|                      | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965             |
| share_server_id      | 2e9d2d02-883f-47b5-bb98-e053b8d1e683                                 |
| host                 | manila@london#LONDON                                                 |
| access_rules_status  | active                                                               |
| snapshot_id          | None                                                                 |
| is_public            | False                                                                |
| task_state           | None                                                                 |
| snapshot_support     | True                                                                 |
| id                   | 195e3ba2-9342-446a-bc93-a584551de0ac                                 |
| size                 | 1                                                                    |
| name                 | Share2                                                               |
| share_type           | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf                                 |
| has_replicas         | False                                                                |
| replication_type     | None                                                                 |
| created_at           | 2016-03-25T12:13:40.000000                                           |
| share_proto          | NFS                                                                  |
| consistency_group_id | None                                                                 |
| project_id           | 907004508ef4447397ce6741a8f037c1                                     |
| metadata             | {u'aim': u'testing'}                                                 |
+----------------------+----------------------------------------------------------------------+

A share can have one of these status values:

Status

Description

creating

The share is being created.

deleting

The share is being deleted.

error

An error occurred during share creation.

error_deleting

An error occurred during share deletion.

available

The share is ready to use.

manage_starting

Share manage started.

manage_error

Share manage failed.

unmanage_starting

Share unmanage started.

unmanage_error

Share cannot be unmanaged.

unmanaged

Share was unmanaged.

extending

The extend, or increase, share size request was issued successfully.

extending_error

Extend share failed.

shrinking

Share is being shrunk.

shrinking_error

Failed to update quota on share shrinking.

shrinking_possible_data_loss_error

Shrink share failed due to possible data loss.

migrating

Share migration is in progress.

8.3.1.5 Share metadata

If you want to set the metadata key-value pairs on the share, run:

$ manila metadata Share2 set project=my_abc deadline=01/20/16

Get all metadata key-value pairs of the share:

$ manila metadata-show Share2
+----------+----------+
| Property | Value    |
+----------+----------+
| aim      | testing  |
| project  | my_abc   |
| deadline | 01/20/16 |
+----------+----------+

You can update the metadata:

$ manila metadata-update-all Share2 deadline=01/30/16
+----------+----------+
| Property | Value    |
+----------+----------+
| deadline | 01/30/16 |
+----------+----------+

You also can unset the metadata using manila metadata <share_name> unset <metadata_key(s)>.

8.3.1.6 Reset share state

As administrator, you can reset the state of a share.

Use manila reset-state [--state <state>] <share> command to reset share state, where state indicates which state to assign the share. Options include available, error, creating, deleting, error_deleting states.

$ manila reset-state Share2 --state deleting

$ manila show Share2
+----------------------+----------------------------------------------------------------------+
| Property             | Value                                                                |
+----------------------+----------------------------------------------------------------------+
| status               | deleting                                                             |
| share_type_name      | default                                                              |
| description          | My second share. Updated                                             |
| availability_zone    | nova                                                                 |
| share_network_id     | c895fe26-92be-4152-9e6c-f2ad230efb13                                 |
| export_locations     |                                                                      |
|                      | path = 10.254.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965 |
|                      | preferred = False                                                    |
|                      | is_admin_only = False                                                |
|                      | id = de6d4012-6158-46f0-8b28-4167baca51a7                            |
|                      | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965             |
|                      | path = 10.0.0.3:/shares/share-fe874928-39a2-441b-8d24-29e6f0fde965   |
|                      | preferred = False                                                    |
|                      | is_admin_only = True                                                 |
|                      | id = 602d0f5c-921b-4e45-bfdb-5eec8a89165a                            |
|                      | share_instance_id = fe874928-39a2-441b-8d24-29e6f0fde965             |
| share_server_id      | 2e9d2d02-883f-47b5-bb98-e053b8d1e683                                 |
| host                 | manila@london#LONDON                                                 |
| access_rules_status  | active                                                               |
| snapshot_id          | None                                                                 |
| is_public            | False                                                                |
| task_state           | None                                                                 |
| snapshot_support     | True                                                                 |
| id                   | 195e3ba2-9342-446a-bc93-a584551de0ac                                 |
| size                 | 1                                                                    |
| name                 | Share2                                                               |
| share_type           | bf6ada49-990a-47c3-88bc-c0cb31d5c9bf                                 |
| has_replicas         | False                                                                |
| replication_type     | None                                                                 |
| created_at           | 2016-03-25T12:13:40.000000                                           |
| share_proto          | NFS                                                                  |
| consistency_group_id | None                                                                 |
| project_id           | 907004508ef4447397ce6741a8f037c1                                     |
| metadata             | {u'deadline': u'01/30/16'}                                           |
+----------------------+----------------------------------------------------------------------+

8.3.1.7 Delete and force-delete share

You also can force-delete a share. The shares cannot be deleted in transitional states. The transitional states are creating, deleting, managing, unmanaging, migrating, extending, and shrinking statuses for the shares. Force-deletion deletes an object in any state. Use the policy.json file to grant permissions for this action to other roles.

Tip
Tip

The configuration file policy.json may be used from different places. The path /etc/manila/policy.json is one of expected paths by default.

Use manila delete <share_name_or_ID> command to delete a specified share:

$ manila delete %share_name_or_id%
Note
Note

If you specified Section 8.8, “Consistency groups” while creating a share, you should provide the --consistency-group parameter to delete the share:

$ manila delete %share_name_or_id% --consistency-group %consistency-group-id%

If you try to delete the share in one of the transitional state using soft-deletion you'll get an error:

$ manila delete Share2
Delete for share 195e3ba2-9342-446a-bc93-a584551de0ac failed: Invalid share: Share status must be one of ('available', 'error', 'inactive'). (HTTP 403) (Request-ID: req-9a77b9a0-17d2-4d97-8a7a-b7e23c27f1fe)
ERROR: Unable to delete any of the specified shares.

A share cannot be deleted in a transitional status, that it why an error from python-manilaclient appeared.

Print the list of all shares for all projects:

$ manila list --all-tenants
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| ID                                   | Name    | Size | Share Proto | Status    | Is Public | Share Type Name | Host                 | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1  | 1    | NFS         | available | False     | my_type         | manila@paris#epsilon | nova              |
| 195e3ba2-9342-446a-bc93-a584551de0ac | Share2  | 1    | NFS         | available | False     | default         | manila@london#LONDON | nova              |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+

Force-delete Share2 and check that it is absent in the list of shares, run:

$ manila force-delete Share2

$ manila list
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| ID                                   | Name    | Size | Share Proto | Status    | Is Public | Share Type Name | Host                 | Availability Zone |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+
| 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 | Share1  | 1    | NFS         | available | False     | my_type         | manila@paris#epsilon | nova              |
+--------------------------------------+---------+------+-------------+-----------+-----------+-----------------+----------------------+-------------------+

8.3.1.8 Manage access to share

The Shared File Systems service allows to grant or deny access to a specified share, and list the permissions for a specified share.

To grant or deny access to a share, specify one of these supported share access levels:

  • rw. Read and write (RW) access. This is the default value.

  • ro. Read-only (RO) access.

You must also specify one of these supported authentication methods:

  • ip. Authenticates an instance through its IP address. A valid format is XX.XX.XX.XX or XX.XX.XX.XX/XX. For example 0.0.0.0/0.

  • user. Authenticates by a specified user or group name. A valid value is an alphanumeric string that can contain some special characters and is from 4 to 32 characters long.

  • cert. Authenticates an instance through a TLS certificate. Specify the TLS identity as the IDENTKEY. A valid value is any string up to 64 characters long in the common name (CN) of the certificate. The meaning of a string depends on its interpretation.

  • cephx. Ceph authentication system. Specify the Ceph auth ID that needs to be authenticated and authorized for share access by the Ceph back end. A valid value must be non-empty, consist of ASCII printable characters, and not contain periods.

Try to mount NFS share with export path 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 on the node with IP address 10.0.0.13:

$ sudo mount -v -t nfs 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 /mnt/
mount.nfs: timeout set for Tue Oct  6 10:37:23 2015
mount.nfs: trying text-based options 'vers=4,addr=10.0.0.4,clientaddr=10.0.0.13'
mount.nfs: mount(2): Permission denied
mount.nfs: access denied by server while mounting 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9

An error message "Permission denied" appeared, so you are not allowed to mount a share without an access rule. Allow access to the share with ip access type and 10.0.0.13 IP address:

$ manila access-allow Share1 ip 10.0.0.13 --access-level rw
+--------------+--------------------------------------+
| Property     | Value                                |
+--------------+--------------------------------------+
| share_id     | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| access_type  | ip                                   |
| access_to    | 10.0.0.13                            |
| access_level | rw                                   |
| state        | new                                  |
| id           | de715226-da00-4cfc-b1ab-c11f3393745e |
+--------------+--------------------------------------+

Try to mount a share again. This time it is mounted successfully:

$ sudo mount -v -t nfs 10.0.0.4:/shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 /mnt/

Since it is allowed node on 10.0.0.13 read and write access, try to create a file on a mounted share:

$ cd /mnt
$ ls
lost+found
$ touch my_file.txt

Connect via SSH to the 10.0.0.4 node and check new file my_file.txt in the /shares/manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9 directory:

$ ssh 10.0.0.4
$ cd /shares
$ ls
manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9
$ cd manila_share_a5fb1ab7_0bbd_465b_ac14_05706294b6e9
$ ls
lost+found  my_file.txt

You have successfully created a file from instance that was given access by its IP address.

Allow access to the share with user access type:

$ manila access-allow Share1 user demo --access-level rw
+--------------+--------------------------------------+
| Property     | Value                                |
+--------------+--------------------------------------+
| share_id     | 10f5a2a1-36f5-45aa-a8e6-00e94e592e88 |
| access_type  | user                                 |
| access_to    | demo                                 |
| access_level | rw                                   |
| state        | new                                  |
| id           | 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a |
+--------------+--------------------------------------+
Note
Note

Different share features are supported by different share drivers. For the example, the Generic driver with the Block Storage service as a back-end doesn't support user and cert authentications methods. For details of supporting of features by different drivers, see Manila share features support mapping.

To verify that the access rules (ACL) were configured correctly for a share, you list permissions for a share:

$ manila access-list Share1
+--------------------------------------+-------------+------------+--------------+--------+
| id                                   | access type | access to  | access level | state  |
+--------------------------------------+-------------+------------+--------------+--------+
| 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user        | demo       | rw           | error  |
| de715226-da00-4cfc-b1ab-c11f3393745e | ip          | 10.0.0.13  | rw           | active |
+--------------------------------------+-------------+------------+--------------+--------+

Deny access to the share and check that deleted access rule is absent in the access rule list:

$ manila access-deny Share1 de715226-da00-4cfc-b1ab-c11f3393745e

$ manila access-list Share1
+--------------------------------------+-------------+-----------+--------------+-------+
| id                                   | access type | access to | access level | state |
+--------------------------------------+-------------+-----------+--------------+-------+
| 4f391c6b-fb4f-47f5-8b4b-88c5ec9d568a | user        | demo      | rw           | error |
+--------------------------------------+-------------+-----------+--------------+-------+

8.3.2 Manage and unmanage share

To manage a share means that an administrator, rather than a share driver, manages the storage lifecycle. This approach is appropriate when an administrator already has the custom non-manila share with its size, shared file system protocol, and export path, and an administrator wants to register it in the Shared File System service.

To unmanage a share means to unregister a specified share from the Shared File Systems service. Administrators can revert an unmanaged share to managed status if needed.

8.3.2.1 Unmanage a share

The unmanage operation is not supported for shares that were created on top of share servers and created with share networks. The Share service should have the option driver_handles_share_servers = False set in the manila.conf file. You can unmanage a share that has no dependent snapshots.

To unmanage managed share, run the manila unmanage <share> command. Then try to print the information about the share. The returned result should indicate that Shared File Systems service won't find the share:

$ manila unmanage share_for_docs
$ manila show share_for_docs
ERROR: No share with a name or ID of 'share_for_docs' exists.

8.3.2.2 Manage a share

To register the non-managed share in the File System service, run the manila manage command:

manila manage [--name <name>] [--description <description>]
              [--share_type <share-type>]
              [--driver_options [<key=value> [<key=value> ...]]]
              <service_host> <protocol> <export_path>

The positional arguments are:

  • service_host. The manage-share service host in host@backend#POOL format, which consists of the host name for the back end, the name of the back end, and the pool name for the back end.

  • protocol. The Shared File Systems protocol of the share to manage. Valid values are NFS, CIFS, GlusterFS, or HDFS.

  • export_path. The share export path in the format appropriate for the protocol:

    • NFS protocol. 10.0.0.1:/foo_path.

    • CIFS protocol. \\10.0.0.1\foo_name_of_cifs_share.

    • HDFS protocol. hdfs://10.0.0.1:foo_port/foo_share_name.

    • GlusterFS. 10.0.0.1:/foo_volume.

The driver_options is an optional set of one or more key and value pairs that describe driver options. Note that the share type must have the driver_handles_share_servers = False option. As a result, a special share type named for_managing was used in example.

To manage share, run:

$ manila manage \
    manila@paris#shares \
    nfs \
    1.0.0.4:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f \
    --name share_for_docs \
    --description "We manage share." \
    --share_type for_managing
+-----------------------------+--------------------------------------+
| Property                    | Value                                |
+-----------------------------+--------------------------------------+
| status                      | manage_starting                      |
| share_type_name             | for_managing                         |
| description                 | We manage share.                     |
| availability_zone           | None                                 |
| share_network_id            | None                                 |
| share_server_id             | None                                 |
| host                        | manila@paris#shares                  |
| access_rules_status         | active                               |
| snapshot_id                 | None                                 |
| is_public                   | False                                |
| task_state                  | None                                 |
| snapshot_support            | True                                 |
| id                          | ddfb1240-ed5e-4071-a031-b842035a834a |
| size                        | None                                 |
| name                        | share_for_docs                       |
| share_type                  | 14ee8575-aac2-44af-8392-d9c9d344f392 |
| has_replicas                | False                                |
| replication_type            | None                                 |
| created_at                  | 2016-03-25T15:22:43.000000           |
| share_proto                 | NFS                                  |
| consistency_group_id        | None                                 |
| source_cgsnapshot_member_id | None                                 |
| project_id                  | 907004508ef4447397ce6741a8f037c1     |
| metadata                    | {}                                   |
+-----------------------------+--------------------------------------+

Check that the share is available:

$ manila show share_for_docs
+----------------------+--------------------------------------------------------------------------+
| Property             | Value                                                                    |
+----------------------+--------------------------------------------------------------------------+
| status               | available                                                                |
| share_type_name      | for_managing                                                             |
| description          | We manage share.                                                         |
| availability_zone    | None                                                                     |
| share_network_id     | None                                                                     |
| export_locations     |                                                                          |
|                      | path = 1.0.0.4:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f |
|                      | preferred = False                                                        |
|                      | is_admin_only = False                                                    |
|                      | id = d4d048bf-4159-4a94-8027-e567192b8d30                                |
|                      | share_instance_id = 4c8e3887-4f9a-4775-bab4-e5840a09c34e                 |
|                      | path = 2.0.0.3:/shares/manila_share_6d2142d8_2b9b_4405_867f_8a48094c893f |
|                      | preferred = False                                                        |
|                      | is_admin_only = True                                                     |
|                      | id = 1dd4f0a3-778d-486a-a851-b522f6e7cf5f                                |
|                      | share_instance_id = 4c8e3887-4f9a-4775-bab4-e5840a09c34e                 |
| share_server_id      | None                                                                     |
| host                 | manila@paris#shares                                                      |
| access_rules_status  | active                                                                   |
| snapshot_id          | None                                                                     |
| is_public            | False                                                                    |
| task_state           | None                                                                     |
| snapshot_support     | True                                                                     |
| id                   | ddfb1240-ed5e-4071-a031-b842035a834a                                     |
| size                 | 1                                                                        |
| name                 | share_for_docs                                                           |
| share_type           | 14ee8575-aac2-44af-8392-d9c9d344f392                                     |
| has_replicas         | False                                                                    |
| replication_type     | None                                                                     |
| created_at           | 2016-03-25T15:22:43.000000                                               |
| share_proto          | NFS                                                                      |
| consistency_group_id | None                                                                     |
| project_id           | 907004508ef4447397ce6741a8f037c1                                         |
| metadata             | {}                                                                       |
+----------------------+--------------------------------------------------------------------------+

8.3.3 Manage and unmanage share snapshot

To manage a share snapshot means that an administrator, rather than a share driver, manages the storage lifecycle. This approach is appropriate when an administrator manages share snapshots outside of the Shared File Systems service and wants to register it with the service.

To unmanage a share snapshot means to unregister a specified share snapshot from the Shared File Systems service. Administrators can revert an unmanaged share snapshot to managed status if needed.

8.3.3.1 Unmanage a share snapshot

The unmanage operation is not supported for shares that were created on top of share servers and created with share networks. The Share service should have the option driver_handles_share_servers = False set in the manila.conf file.

To unmanage managed share snapshot, run the :command: manila snapshot-unmanage <share_snapshot> command. Then try to print the information about the share snapshot. The returned result should indicate that Shared File Systems service won't find the share snapshot:

$ manila snapshot-unmanage my_test_share_snapshot
$ manila snapshot-show my_test_share_snapshot
ERROR: No sharesnapshot with a name or ID of 'my_test_share_snapshot'
exists.

8.3.3.2 Manage a share snapshot

To register the non-managed share snapshot in the File System service, run the manila snapshot-manage command:

manila snapshot-manage [--name <name>] [--description <description>]
              [--driver_options [<key=value> [<key=value> ...]]]
              <share> <provider_location>

The positional arguments are:

  • share. Name or ID of the share.

  • provider_location. Provider location of the share snapshot on the backend.

The driver_options is an optional set of one or more key and value pairs that describe driver options.

To manage share snapshot, run:

$ manila snapshot-manage \
    9ba52cc6-c97e-4b40-8653-4bcbaaf9628d \
    4d1e2863-33dd-4243-bf39-f7354752097d \
    --name my_test_share_snapshot \
    --description "My test share snapshot" \
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | manage_starting                      |
| share_id          | 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d |
| user_id           | d9f4003655c94db5b16c591920be1f91     |
| description       | My test share snapshot               |
| created_at        | 2016-07-25T04:49:42.600980           |
| size              | None                                 |
| share_proto       | NFS                                  |
| provider_location | 4d1e2863-33dd-4243-bf39-f7354752097d |
| id                | 89c663b5-026d-45c7-a43b-56ef0ba0faab |
| project_id        | aaa33a0ca4324965a3e65ae47e864e94     |
| share_size        | 1                                    |
| name              | my_test_share_snapshot               |
+-------------------+--------------------------------------+

Check that the share snapshot is available:

$ manila snapshot-show my_test_share_snapshot
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | available                            |
| share_id          | 9ba52cc6-c97e-4b40-8653-4bcbaaf9628d |
| user_id           | d9f4003655c94db5b16c591920be1f91     |
| description       | My test share snapshot               |
| created_at        | 2016-07-25T04:49:42.000000           |
| size              | 1                                    |
| share_proto       | NFS                                  |
| provider_location | 4d1e2863-33dd-4243-bf39-f7354752097d |
| id                | 89c663b5-026d-45c7-a43b-56ef0ba0faab |
| project_id        | aaa33a0ca4324965a3e65ae47e864e94     |
| share_size        | 1                                    |
| name              | my_test_share_snapshot               |
+-------------------+--------------------------------------+

8.3.4 Resize share

To change file share size, use the manila extend command and the manila shrink command. For most drivers it is safe operation. If you want to be sure that your data is safe, you can make a share back up by creating a snapshot of it.

You can extend and shrink the share with the manila extend and manila shrink commands respectively, and specify the share with the new size that does not exceed the quota. For details, see Section 8.3.5, “Quotas and limits”. You also cannot shrink share size to 0 or to a greater value than the current share size.

While extending, the share has an extending status. This means that the increase share size request was issued successfully.

To extend the share and check the result, run:

$ manila extend docs_resize 2
$ manila show docs_resize
+----------------------+--------------------------------------------------------------------------+
| Property             | Value                                                                    |
+----------------------+--------------------------------------------------------------------------+
| status               | available                                                                |
| share_type_name      | my_type                                                                  |
| description          | None                                                                     |
| availability_zone    | nova                                                                     |
| share_network_id     | None                                                                     |
| export_locations     |                                                                          |
|                      | path = 1.0.0.4:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
|                      | preferred = False                                                        |
|                      | is_admin_only = False                                                    |
|                      | id = 3ffb76f4-92b9-4639-83fd-025bc3e302ff                                |
|                      | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8                 |
|                      | path = 2.0.0.3:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
|                      | preferred = False                                                        |
|                      | is_admin_only = True                                                     |
|                      | id = 1f0e263f-370d-47d3-95f6-1be64088b9da                                |
|                      | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8                 |
| share_server_id      | None                                                                     |
| host                 | manila@paris#shares                                                      |
| access_rules_status  | active                                                                   |
| snapshot_id          | None                                                                     |
| is_public            | False                                                                    |
| task_state           | None                                                                     |
| snapshot_support     | True                                                                     |
| id                   | b07dbebe-a328-403c-b402-c8871c89e3d1                                     |
| size                 | 2                                                                        |
| name                 | docs_resize                                                              |
| share_type           | 14ee8575-aac2-44af-8392-d9c9d344f392                                     |
| has_replicas         | False                                                                    |
| replication_type     | None                                                                     |
| created_at           | 2016-03-25T15:33:18.000000                                               |
| share_proto          | NFS                                                                      |
| consistency_group_id | None                                                                     |
| project_id           | 907004508ef4447397ce6741a8f037c1                                         |
| metadata             | {}                                                                       |
+----------------------+--------------------------------------------------------------------------+

While shrinking, the share has a shrinking status. This means that the decrease share size request was issued successfully. To shrink the share and check the result, run:

$ manila shrink docs_resize 1
$ manila show docs_resize
+----------------------+--------------------------------------------------------------------------+
| Property             | Value                                                                    |
+----------------------+--------------------------------------------------------------------------+
| status               | available                                                                |
| share_type_name      | my_type                                                                  |
| description          | None                                                                     |
| availability_zone    | nova                                                                     |
| share_network_id     | None                                                                     |
| export_locations     |                                                                          |
|                      | path = 1.0.0.4:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
|                      | preferred = False                                                        |
|                      | is_admin_only = False                                                    |
|                      | id = 3ffb76f4-92b9-4639-83fd-025bc3e302ff                                |
|                      | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8                 |
|                      | path = 2.0.0.3:/shares/manila_share_b8afc508_8487_442b_b170_ea65b07074a8 |
|                      | preferred = False                                                        |
|                      | is_admin_only = True                                                     |
|                      | id = 1f0e263f-370d-47d3-95f6-1be64088b9da                                |
|                      | share_instance_id = b8afc508-8487-442b-b170-ea65b07074a8                 |
| share_server_id      | None                                                                     |
| host                 | manila@paris#shares                                                      |
| access_rules_status  | active                                                                   |
| snapshot_id          | None                                                                     |
| is_public            | False                                                                    |
| task_state           | None                                                                     |
| snapshot_support     | True                                                                     |
| id                   | b07dbebe-a328-403c-b402-c8871c89e3d1                                     |
| size                 | 1                                                                        |
| name                 | docs_resize                                                              |
| share_type           | 14ee8575-aac2-44af-8392-d9c9d344f392                                     |
| has_replicas         | False                                                                    |
| replication_type     | None                                                                     |
| created_at           | 2016-03-25T15:33:18.000000                                               |
| share_proto          | NFS                                                                      |
| consistency_group_id | None                                                                     |
| project_id           | 907004508ef4447397ce6741a8f037c1                                         |
| metadata             | {}                                                                       |
+----------------------+--------------------------------------------------------------------------+

8.3.5 Quotas and limits

8.3.5.1 Limits

Limits are the resource limitations that are allowed for each project. An administrator can configure limits in the manila.conf file.

Users can query their rate and absolute limits.

To see the absolute limits, run:

$ manila absolute-limits
+----------------------------+-------+
| Name                       | Value |
+----------------------------+-------+
| maxTotalShareGigabytes     | 1000  |
| maxTotalShareNetworks      | 10    |
| maxTotalShareSnapshots     | 50    |
| maxTotalShares             | 50    |
| maxTotalSnapshotGigabytes  | 1000  |
| totalShareGigabytesUsed    | 1     |
| totalShareNetworksUsed     | 2     |
| totalShareSnapshotsUsed    | 1     |
| totalSharesUsed            | 1     |
| totalSnapshotGigabytesUsed | 1     |
+----------------------------+-------+

Rate limits control the frequency at which users can issue specific API requests. Administrators use rate limiting to configure limits on the type and number of API calls that can be made in a specific time interval. For example, a rate limit can control the number of GET requests processed during a one-minute period.

To set the API rate limits, modify the etc/manila/api-paste.ini file, which is a part of the WSGI pipeline and defines the actual limits. You need to restart manila-api service after you edit the etc/manila/api-paste.ini file.

[filter:ratelimit]
paste.filter_factory = manila.api.v1.limits:RateLimitingMiddleware.factory
limits = (POST, "*/shares", ^/shares, 120, MINUTE);(PUT, "*/shares", .*, 120, MINUTE);(DELETE, "*", .*, 120, MINUTE)

Also, add the ratelimit to noauth, keystone, keystone_nolimit parameters in the [composite:openstack_share_api] and [composite:openstack_share_api_v2] groups.

[composite:openstack_share_api]
use = call:manila.api.middleware.auth:pipeline_factory
noauth = cors faultwrap ssl ratelimit sizelimit noauth api
keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext api
keystone_nolimit = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext api

[composite:openstack_share_api_v2]
use = call:manila.api.middleware.auth:pipeline_factory
noauth = cors faultwrap ssl ratelimit sizelimit noauth apiv2
keystone = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2
keystone_nolimit = cors faultwrap ssl ratelimit sizelimit authtoken keystonecontext apiv2

To see the rate limits, run:

$ manila rate-limits
+--------+------------+-------+--------+--------+----------------------+
| Verb   | URI        | Value | Remain | Unit   | Next_Available       |
+--------+------------+-------+--------+--------+----------------------+
| DELETE | "*"        | 120   | 120    | MINUTE | 2015-10-20T15:17:20Z |
| POST   | "*/shares" | 120   | 120    | MINUTE | 2015-10-20T15:17:20Z |
| PUT    | "*/shares" | 120   | 120    | MINUTE | 2015-10-20T15:17:20Z |
+--------+------------+-------+--------+--------+----------------------+

8.3.5.2 Quotas

Quota sets provide quota management support.

To list the quotas for a project or user, use the manila quota-show command. If you specify the optional --user parameter, you get the quotas for this user in the specified project. If you omit this parameter, you get the quotas for the specified project.

Note
Note

The Shared File Systems service does not perform mapping of usernames and project names to IDs. Provide only ID values to get correct setup of quotas. Setting it by names you set quota for nonexistent project/user. In case quota is not set explicitly by project/user ID, The Shared File Systems service just applies default quotas.

$ manila quota-show --tenant %project_id% --user %user_id%
+--------------------+-------+
| Property           | Value |
+--------------------+-------+
| gigabytes          | 1000  |
| snapshot_gigabytes | 1000  |
| snapshots          | 50    |
| shares             | 50    |
| share_networks     | 10    |
+--------------------+-------+

There are default quotas for a project that are set from the manila.conf file. To list the default quotas for a project, use the manila quota-defaults command:

$ manila quota-defaults --tenant %project_id%
+--------------------+-------+
| Property           | Value |
+--------------------+-------+
| gigabytes          | 1000  |
| snapshot_gigabytes | 1000  |
| snapshots          | 50    |
| shares             | 50    |
| share_networks     | 10    |
+--------------------+-------+

The administrator can update the quotas for a specific project, or for a specific user by providing both the --tenant and --user optional arguments. It is possible to update the shares, snapshots, gigabytes, snapshot-gigabytes, and share-networks quotas.

$ manila quota-update %project_id% --user %user_id% --shares 49 --snapshots 49

As administrator, you can also permit or deny the force-update of a quota that is already used, or if the requested value exceeds the configured quota limit. To force-update a quota, use force optional key.

$ manila quota-update %project_id% --shares 51 --snapshots 51 --force

To revert quotas to default for a project or for a user, delete quotas:

$ manila quota-delete --tenant %project_id% --user %user_id%

8.4 Migrate shares

As an administrator, you can migrate a share with its data from one location to another in a manner that is transparent to users and workloads. You can use manila client commands to complete a share migration.

Possible use cases for data migration include:

  • Bring down a physical storage device for maintenance without disrupting workloads.

  • Modify the properties of a share.

  • Free up space in a thinly-provisioned back end.

Migrate a share with the manila migrate command, as shown in the following example:

$ manila migrate shareID destinationHost --force-host-copy True|False

In this example, --force-host-copy True forces the generic host-based migration mechanism and bypasses any driver optimizations. destinationHost is in this format host#pool which includes destination host and pool.

Note
Note

If the user is not an administrator, the migration fails.

8.5 Share types

A share type enables you to filter or choose back ends before you create a share and to set data for the share driver. A share type behaves in the same way as a Block Storage volume type behaves.

In the Shared File Systems configuration file manila.conf, the administrator can set the share type used by default for the share creation and then create a default share type.

To create a share type, use manila type-create command as:

manila type-create [--snapshot_support <snapshot_support>]
                   [--is_public <is_public>]
                   <name> <spec_driver_handles_share_servers>

where the name is the share type name, --is_public defines the level of the visibility for the share type, snapshot_support and spec_driver_handles_share_servers are the extra specifications used to filter back ends. Administrators can create share types with these extra specifications for the back ends filtering:

  • driver_handles_share_servers. Required. Defines the driver mode for share server lifecycle management. Valid values are true/1 and false/0. Set to True when the share driver can manage, or handle, the share server lifecycle. Set to False when an administrator, rather than a share driver, manages the bare metal storage with some net interface instead of the presence of the share servers.

  • snapshot_support. Filters back ends by whether they do or do not support share snapshots. Default is True. Set to True to find back ends that support share snapshots. Set to False to find back ends that do not support share snapshots.

Note
Note

The extra specifications set in the share types are operated in the Section 8.10.1, “Scheduling”.

Administrators can also set additional extra specifications for a share type for the following purposes:

  • Filter back ends. Unqualified extra specifications written in this format: extra_spec=value. For example, netapp_raid_type=raid4.

  • Set data for the driver. Qualified extra specifications always written with the prefix with a colon, except for the special capabilities prefix, in this format: vendor:extra_spec=value. For example, netapp:thin_provisioned=true.

The scheduler uses the special capabilities prefix for filtering. The scheduler can only create a share on a back end that reports capabilities matching the un-scoped extra-spec keys for the share type. For details, see Capabilities and Extra-Specs.

Each driver implementation determines which extra specification keys it uses. For details, see the documentation for the driver.

An administrator can use the policy.json file to grant permissions for share type creation with extra specifications to other roles.

You set a share type to private or public and Section 8.5.2, “Share type access” to the private share types. By default a share type is created as publicly accessible. Set --is_public to False to make the share type private.

8.5.1 Share type operations

To create a new share type you need to specify the name of the new share type. You also require an extra spec driver_handles_share_servers. The new share type can also be public.

$ manila type-create netapp1 False --is_public True

$ manila type-list
+-----+--------+-----------+-----------+-----------------------------------+-----------------------+
| ID  | Name   | Visibility| is_default| required_extra_specs              | optional_extra_specs  |
+-----+--------+-----------+-----------+-----------------------------------+-----------------------+
| c0..| netapp1| public    | -         | driver_handles_share_servers:False| snapshot_support:True |
+-----+--------+-----------+-----------+-----------------------------------+-----------------------+

You can set or unset extra specifications for a share type using manila type-key <share_type> set <key=value> command. Since it is up to each driver what extra specification keys it uses, see the documentation for the specified driver.

$ manila type-key netapp1 set thin_provisioned=True

It is also possible to view a list of current share types and extra specifications:

$ manila extra-specs-list
+-------------+---------+-------------------------------------+
| ID          | Name    | all_extra_specs                     |
+-------------+---------+-------------------------------------+
| c0086582-...| netapp1 | snapshot_support : True             |
|             |         | thin_provisioned : True             |
|             |         | driver_handles_share_servers : True |
+-------------+---------+-------------------------------------+

Use manila type-key <share_type> unset <key> to unset an extra specification.

The public or private share type can be deleted with the manila type-delete <share_type> command.

8.5.2 Share type access

You can manage access to a private share type for different projects. Administrators can provide access, remove access, and retrieve information about access for a specified private share.

Create a private type:

$ manila type-create my_type1 True --is_public False
+----------------------+--------------------------------------+
| Property             | Value                                |
+----------------------+--------------------------------------+
| required_extra_specs | driver_handles_share_servers : True  |
| Name                 | my_type1                             |
| Visibility           | private                              |
| is_default           | -                                    |
| ID                   | 06793be5-9a79-4516-89fe-61188cad4d6c |
| optional_extra_specs | snapshot_support : True              |
+----------------------+--------------------------------------+
Note
Note

If you run manila type-list only public share types appear. To see private share types, run manila type-list with --all optional argument.

Grant access to created private type for a demo and alt_demo projects by providing their IDs:

$ manila type-access-add my_type1 d8f9af6915404114ae4f30668a4f5ba7
$ manila type-access-add my_type1 e4970f57f1824faab2701db61ee7efdf

To view information about access for a private share, type my_type1:

$ manila type-access-list my_type1
+----------------------------------+
| Project_ID                       |
+----------------------------------+
| d8f9af6915404114ae4f30668a4f5ba7 |
| e4970f57f1824faab2701db61ee7efdf |
+----------------------------------+

After granting access to the share, the target project can see the share type in the list, and create private shares.

To deny access for a specified project, use manila type-access-remove <share_type> <project_id> command.

8.6 Share snapshots

The Shared File Systems service provides a snapshot mechanism to help users restore data by running the manila snapshot-create command.

To export a snapshot, create a share from it, then mount the new share to an instance. Copy files from the attached share into the archive.

To import a snapshot, create a new share with appropriate size, attach it to instance, and then copy a file from the archive to the attached file system.

Note
Note

You cannot delete a share while it has saved dependent snapshots.

Create a snapshot from the share:

$ manila snapshot-create Share1 --name Snapshot1 --description "Snapshot of Share1"
+-------------+--------------------------------------+
| Property    | Value                                |
+-------------+--------------------------------------+
| status      | creating                             |
| share_id    | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| name        | Snapshot1                            |
| created_at  | 2015-09-25T05:27:38.862040           |
| share_proto | NFS                                  |
| id          | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| size        | 1                                    |
| share_size  | 1                                    |
| description | Snapshot of Share1                   |
+-------------+--------------------------------------+

Update snapshot name or description if needed:

$ manila snapshot-rename Snapshot1 Snapshot_1 --description "Snapshot of Share1. Updated."

Check that status of a snapshot is available:

$ manila snapshot-show Snapshot1
+-------------+--------------------------------------+
| Property    | Value                                |
+-------------+--------------------------------------+
| status      | available                            |
| share_id    | aca648eb-8c03-4394-a5cc-755066b7eb66 |
| name        | Snapshot1                            |
| created_at  | 2015-09-25T05:27:38.000000           |
| share_proto | NFS                                  |
| id          | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| size        | 1                                    |
| share_size  | 1                                    |
| description | Snapshot of Share1                   |
+-------------+--------------------------------------+

To restore your data from a snapshot, use manila create with key --snapshot-id. This creates a new share from an existing snapshot. Create a share from a snapshot and check whether it is available:

$ manila create nfs 1 --name Share2 --metadata source=snapshot --description "Share from a snapshot." --snapshot-id 962e8126-35c3-47bb-8c00-f0ee37f42ddd
+-----------------------------+--------------------------------------+
| Property                    | Value                                |
+-----------------------------+--------------------------------------+
| status                      | None                                 |
| share_type_name             | default                              |
| description                 | Share from a snapshot.               |
| availability_zone           | None                                 |
| share_network_id            | None                                 |
| export_locations            | []                                   |
| share_server_id             | None                                 |
| host                        | None                                 |
| snapshot_id                 | 962e8126-35c3-47bb-8c00-f0ee37f42ddd |
| is_public                   | False                                |
| task_state                  | None                                 |
| snapshot_support            | True                                 |
| id                          | b6b0617c-ea51-4450-848e-e7cff69238c7 |
| size                        | 1                                    |
| name                        | Share2                               |
| share_type                  | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at                  | 2015-09-25T06:25:50.240417           |
| export_location             | None                                 |
| share_proto                 | NFS                                  |
| consistency_group_id        | None                                 |
| source_cgsnapshot_member_id | None                                 |
| project_id                  | 20787a7ba11946adad976463b57d8a2f     |
| metadata                    | {u'source': u'snapshot'}             |
+-----------------------------+--------------------------------------+

$ manila show Share2
+-----------------------------+-------------------------------------------+
| Property                    | Value                                     |
+-----------------------------+-------------------------------------------+
| status                      | available                                 |
| share_type_name             | default                                   |
| description                 | Share from a snapshot.                    |
| availability_zone           | nova                                      |
| share_network_id            | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a      |
| export_locations            | 10.254.0.3:/shares/share-1dc2a471-3d47-...|
| share_server_id             | 41b7829d-7f6b-4c96-aea5-d106c2959961      |
| host                        | manila@generic1#GENERIC1                  |
| snapshot_id                 | 962e8126-35c3-47bb-8c00-f0ee37f42ddd      |
| is_public                   | False                                     |
| task_state                  | None                                      |
| snapshot_support            | True                                      |
| id                          | b6b0617c-ea51-4450-848e-e7cff69238c7      |
| size                        | 1                                         |
| name                        | Share2                                    |
| share_type                  | c0086582-30a6-4060-b096-a42ec9d66b86      |
| created_at                  | 2015-09-25T06:25:50.000000                |
| share_proto                 | NFS                                       |
| consistency_group_id        | None                                      |
| source_cgsnapshot_member_id | None                                      |
| project_id                  | 20787a7ba11946adad976463b57d8a2f          |
| metadata                    | {u'source': u'snapshot'}                  |
+-----------------------------+-------------------------------------------+

You can soft-delete a snapshot using manila snapshot-delete <snapshot_name_or_ID>. If a snapshot is in busy state, and during the delete an error_deleting status appeared, administrator can force-delete it or explicitly reset the state.

Use snapshot-reset-state [--state <state>] <snapshot> to update the state of a snapshot explicitly. A valid value of a status are available, error, creating, deleting, error_deleting. If no state is provided, the available state will be used.

Use manila snapshot-force-delete <snapshot> to force-delete a specified share snapshot in any state.

8.7 Security services

A security service stores client configuration information used for authentication and authorization (AuthN/AuthZ). For example, a share server will be the client for an existing service such as LDAP, Kerberos, or Microsoft Active Directory.

You can associate a share with one to three security service types:

  • ldap: LDAP.

  • kerberos: Kerberos.

  • active_directory: Microsoft Active Directory.

You can configure a security service with these options:

  • A DNS IP address.

  • An IP address or host name.

  • A domain.

  • A user or group name.

  • The password for the user, if you specify a user name.

You can add the security service to the Section 8.11.1, “Share networks”.

To create a security service, specify the security service type, a description of a security service, DNS IP address used inside project's network, security service IP address or host name, domain, security service user or group used by project, and a password for the user. The share name is optional.

Create a ldap security service:

$ manila security-service-create ldap --dns-ip 8.8.8.8 --server 10.254.0.3 --name my_ldap_security_service
+-------------+--------------------------------------+
| Property    | Value                                |
+-------------+--------------------------------------+
| status      | new                                  |
| domain      | None                                 |
| password    | None                                 |
| name        | my_ldap_security_service             |
| dns_ip      | 8.8.8.8                              |
| created_at  | 2015-09-25T10:19:06.019527           |
| updated_at  | None                                 |
| server      | 10.254.0.3                           |
| user        | None                                 |
| project_id  | 20787a7ba11946adad976463b57d8a2f     |
| type        | ldap                                 |
| id          | 413479b2-0d20-4c58-a9d3-b129fa592d8e |
| description | None                                 |
+-------------+--------------------------------------+

To create kerberos security service, run:

$ manila security-service-create kerberos --server 10.254.0.3 --user demo --password secret --name my_kerberos_security_service --description "Kerberos security service"
+-------------+--------------------------------------+
| Property    | Value                                |
+-------------+--------------------------------------+
| status      | new                                  |
| domain      | None                                 |
| password    | secret                               |
| name        | my_kerberos_security_service         |
| dns_ip      | None                                 |
| created_at  | 2015-09-25T10:26:03.211849           |
| updated_at  | None                                 |
| server      | 10.254.0.3                           |
| user        | demo                                 |
| project_id  | 20787a7ba11946adad976463b57d8a2f     |
| type        | kerberos                             |
| id          | 7f46a447-2534-453d-924d-bd7c8e63bbec |
| description | Kerberos security service            |
+-------------+--------------------------------------+

To see the list of created security service use manila security-service-list:

$ manila security-service-list
+--------------------------------------+------------------------------+--------+----------+
| id                                   | name                         | status | type     |
+--------------------------------------+------------------------------+--------+----------+
| 413479b2-0d20-4c58-a9d3-b129fa592d8e | my_ldap_security_service     | new    | ldap     |
| 7f46a447-2534-453d-924d-bd7c8e63bbec | my_kerberos_security_service | new    | kerberos |
+--------------------------------------+------------------------------+--------+----------+

You can add a security service to the existing Section 8.11.1, “Share networks”, which is not yet used (a share network not associated with a share).

Add a security service to the share network with share-network-security-service-add specifying share network and security service. The command returns information about the security service. You can see view new attributes and share_networks using the associated share network ID.

$ manila share-network-security-service-add share_net2 my_ldap_security_service

$ manila security-service-show my_ldap_security_service
+----------------+-------------------------------------------+
| Property       | Value                                     |
+----------------+-------------------------------------------+
| status         | new                                       |
| domain         | None                                      |
| password       | None                                      |
| name           | my_ldap_security_service                  |
| dns_ip         | 8.8.8.8                                   |
| created_at     | 2015-09-25T10:19:06.000000                |
| updated_at     | None                                      |
| server         | 10.254.0.3                                |
| share_networks | [u'6d36c41f-d310-4aff-a0c2-ffd870e91cab'] |
| user           | None                                      |
| project_id     | 20787a7ba11946adad976463b57d8a2f          |
| type           | ldap                                      |
| id             | 413479b2-0d20-4c58-a9d3-b129fa592d8e      |
| description    | None                                      |
+----------------+-------------------------------------------+

It is possible to see the list of security services associated with a given share network. List security services for share_net2 share network with:

$ manila share-network-security-service-list share_net2
+--------------------------------------+--------------------------+--------+------+
| id                                   | name                     | status | type |
+--------------------------------------+--------------------------+--------+------+
| 413479b2-0d20-4c58-a9d3-b129fa592d8e | my_ldap_security_service | new    | ldap |
+--------------------------------------+--------------------------+--------+------+

You also can dissociate a security service from the share network and confirm that the security service now has an empty list of share networks:

$ manila share-network-security-service-remove share_net2 my_ldap_security_service

$ manila security-service-show my_ldap_security_service
+----------------+--------------------------------------+
| Property       | Value                                |
+----------------+--------------------------------------+
| status         | new                                  |
| domain         | None                                 |
| password       | None                                 |
| name           | my_ldap_security_service             |
| dns_ip         | 8.8.8.8                              |
| created_at     | 2015-09-25T10:19:06.000000           |
| updated_at     | None                                 |
| server         | 10.254.0.3                           |
| share_networks | []                                   |
| user           | None                                 |
| project_id     | 20787a7ba11946adad976463b57d8a2f     |
| type           | ldap                                 |
| id             | 413479b2-0d20-4c58-a9d3-b129fa592d8e |
| description    | None                                 |
+----------------+--------------------------------------+

The Shared File Systems service allows you to update a security service field using manila security-service-update command with optional arguments such as --dns-ip, --server, --domain, --user, --password, --name, or --description.

To remove a security service not associated with any share networks run:

$ manila security-service-delete my_ldap_security_service

8.8 Consistency groups

Consistency groups enable you to create snapshots from multiple file system shares at the same point in time. For example, a database might place its tables, logs, and configurations on separate shares. Store logs, tables, and configurations at the same point in time to effectively restore a database.

The Shared File System service allows you to create a snapshot of the consistency group and restore all shares that were associated with a consistency group.

Important
Important

The consistency groups and snapshots are an experimental Shared File Systems API in the Liberty release. Contributors can change or remove the experimental part of the Shared File Systems API in further releases without maintaining backward compatibility. Experimental APIs have an X-OpenStack-Manila-API-Experimental: true header in their HTTP requests.

8.8.1 Consistency groups

Note
Note

Before using consistency groups, make sure the Shared File System driver that you are running has consistency group support. You can check it in the manila-scheduler service reports. The consistency_group_support can have the following values:

  • pool or host. Consistency groups are supported. Specifies the level of consistency groups support.

  • false. Consistency groups are not supported.

The manila cg-create command creates a new consistency group. With this command, you can specify a share network, and one or more share types. In the example a consistency group cgroup1 was created by specifying two comma-separated share types:

$ manila cg-create --name cgroup1 --description "My first CG." --share-types my_type1,default --share-network my_share_net
+----------------------+--------------------------------------+
| Property             | Value                                |
+----------------------+--------------------------------------+
| status               | creating                             |
| description          | My first CG.                         |
| source_cgsnapshot_id | None                                 |
| created_at           | 2015-09-29T15:01:12.102472           |
| share_network_id     | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| share_server_id      | None                                 |
| host                 | None                                 |
| project_id           | 20787a7ba11946adad976463b57d8a2f     |
| share_types          | a4218aa5-f16a-42b3-945d-113496d40558 |
|                      | c0086582-30a6-4060-b096-a42ec9d66b86 |
| id                   | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| name                 | cgroup1                              |
+----------------------+--------------------------------------+

Check that consistency group status is available:

$ manila cg-show cgroup1
+----------------------+--------------------------------------+
| Property             | Value                                |
+----------------------+--------------------------------------+
| status               | available                            |
| description          | My first CG.                         |
| source_cgsnapshot_id | None                                 |
| created_at           | 2015-09-29T15:05:40.000000           |
| share_network_id     | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| share_server_id      | None                                 |
| host                 | manila@generic1#GENERIC1             |
| project_id           | 20787a7ba11946adad976463b57d8a2f     |
| share_types          | c0086582-30a6-4060-b096-a42ec9d66b86 |
|                      | a4218aa5-f16a-42b3-945d-113496d40558 |
| id                   | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| name                 | cgroup1                              |
+----------------------+--------------------------------------+

To add a share to the consistency group, create a share by adding the --consistency-group option where you specify the ID of the consistency group in available status:

$ manila create nfs 1 --name "Share2" --description "My second share" \
--share-type default --share-network my_share_net --consistency-group cgroup1
+-----------------------------+--------------------------------------+
| Property                    | Value                                |
+-----------------------------+--------------------------------------+
| status                      | None                                 |
| share_type_name             | default                              |
| description                 | My second share                      |
| availability_zone           | None                                 |
| share_network_id            | None                                 |
| export_locations            | []                                   |
| share_server_id             | None                                 |
| host                        | None                                 |
| snapshot_id                 | None                                 |
| is_public                   | False                                |
| task_state                  | None                                 |
| snapshot_support            | True                                 |
| id                          | 7bcd888b-681b-4836-ac9c-c3add4e62537 |
| size                        | 1                                    |
| name                        | Share2                               |
| share_type                  | c0086582-30a6-4060-b096-a42ec9d66b86 |
| created_at                  | 2015-09-29T15:09:24.156387           |
| export_location             | None                                 |
| share_proto                 | NFS                                  |
| consistency_group_id        | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| source_cgsnapshot_member_id | None                                 |
| project_id                  | 20787a7ba11946adad976463b57d8a2f     |
| metadata                    | {}                                   |
+-----------------------------+--------------------------------------+

Administrators can rename the consistency group, or change its description using the manila cg-update command. Delete the group with the manila cg-delete command.

As an administrator, you can also reset the state of a consistency group and force delete a specified consistency group in any state. Use the policy.json file to grant permissions for these actions to other roles.

Use manila cg-reset-state [--state <state>] <consistency_group> to update the state of a consistency group explicitly. A valid value of a status are available, error, creating, deleting, error_deleting. If no state is provided, available will be used.

$ manila cg-reset-state cgroup1 --state error

Use manila cg-delete <consistency_group> [<consistency_group> ...] to soft-delete one or more consistency groups.

Note
Note

A consistency group can be deleted only if it has no dependent Section 8.8.2, “Consistency group snapshots”.

$ manila cg-delete cgroup1

Use manila cg-delete --force <consistency_group> [<consistency_group> ...] to force-delete a specified consistency group in any state.

$ manila cg-delete --force cgroup1

8.8.2 Consistency group snapshots

To create a snapshot, specify the ID or name of the consistency group. After creating a consistency group snapshot, it is possible to generate a new consistency group.

Create a snapshot of consistency group cgroup1:

$ manila cg-snapshot-create cgroup1 --name CG_snapshot1 --description "A snapshot of the first CG."
+----------------------+--------------------------------------+
| Property             | Value                                |
+----------------------+--------------------------------------+
| status               | creating                             |
| name                 | CG_snapshot1                         |
| created_at           | 2015-09-29T15:26:16.839704           |
| consistency_group_id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| project_id           | 20787a7ba11946adad976463b57d8a2f     |
| id                   | 876ad24c-1efd-4607-a2b1-6a2c90034fa5 |
| description          | A snapshot of the first CG.          |
+----------------------+--------------------------------------+

Check the status of created consistency group snapshot:

$ manila cg-snapshot-show CG_snapshot1
+----------------------+--------------------------------------+
| Property             | Value                                |
+----------------------+--------------------------------------+
| status               | available                            |
| name                 | CG_snapshot1                         |
| created_at           | 2015-09-29T15:26:22.000000           |
| consistency_group_id | 6fdd91bc-7a48-48b4-8e40-0f4f98d0ecd6 |
| project_id           | 20787a7ba11946adad976463b57d8a2f     |
| id                   | 876ad24c-1efd-4607-a2b1-6a2c90034fa5 |
| description          | A snapshot of the first CG.          |
+----------------------+--------------------------------------+

Administrators can rename a consistency group snapshot, change its description using the cg-snapshot-update command, or delete it with the cg-snapshot-delete command.

A consistency group snapshot can have members. To add a member, include the --consistency-group optional parameter in the create share command. This ID must match the ID of the consistency group from which the consistency group snapshot was created. Then, while restoring data, and operating with consistency group snapshots, you can quickly find which shares belong to a specified consistency group.

You created the share Share2 in cgroup1 consistency group. Since you made a snapshot of it, you can see that the only member of the consistency group snapshot is Share2 share:

$ manila cg-snapshot-members CG_snapshot1
+--------------+------+----------------------------+----------------+--------------+--------------+
| Id           | Size | Created_at                 | Share_protocol | Share_id     | Share_type_id|
+--------------+------+----------------------------+----------------+--------------+--------------+
| 5c62af2b-... | 1    | 2015-09-29T15:26:22.000000 | NFS            | 7bcd888b-... | c0086582-... |
+--------------+------+----------------------------+----------------+--------------+--------------+

After you create a consistency group snapshot, you can create a consistency group from the new snapshot:

$ manila cg-create --source-cgsnapshot-id 876ad24c-1efd-4607-a2b1-6a2c90034fa5 --name cgroup2 --description "A consistency group from a CG snapshot."
+----------------------+-----------------------------------------+
| Property             | Value                                   |
+----------------------+-----------------------------------------+
| status               | creating                                |
| description          | A consistency group from a CG snapshot. |
| source_cgsnapshot_id | 876ad24c-1efd-4607-a2b1-6a2c90034fa5    |
| created_at           | 2015-09-29T15:47:47.937991              |
| share_network_id     | None                                    |
| share_server_id      | None                                    |
| host                 | manila@generic1#GENERIC1                |
| project_id           | 20787a7ba11946adad976463b57d8a2f        |
| share_types          | c0086582-30a6-4060-b096-a42ec9d66b86    |
|                      | a4218aa5-f16a-42b3-945d-113496d40558    |
| id                   | ffee08d9-c86c-45e5-861e-175c731daca2    |
| name                 | cgroup2                                 |
+----------------------+-----------------------------------------+

Check the consistency group list. Two groups now appear:

$ manila cg-list
+-------------------+---------+-----------------------------------------+-----------+
| id                | name    | description                             | status    |
+-------------------+---------+-----------------------------------------+-----------+
| 6fdd91bc-7a48-... | cgroup1 | My first CG.                            | available |
| ffee08d9-c86c-... | cgroup2 | A consistency group from a CG snapshot. | available |
+-------------------+---------+-----------------------------------------+-----------+

Check a list of the shares. New share with ba52454e-2ea3-47fa-a683-3176a01295e6 ID appeared after the consistency group cgroup2 was built from a snapshot with a member.

$ manila list
+------+-------+-----+------------+----------+----------+-----------+--------------------------+
| ID   | Name  | Size| Share Proto| Status   | Is Public| Share Type| Host                     |
+------+-------+-----+------------+----------+----------+-----------+--------------------------+
| 7bc..| Share2| 1   | NFS        | available| False    | c008658...| manila@generic1#GENERIC1 |
| ba5..| None  | 1   | NFS        | available| False    | c008658...| manila@generic1#GENERIC1 |
+------+-------+-----+------------+----------+----------+-----------+--------------------------+

Print detailed information about new share:

Note
Note

Pay attention on the source_cgsnapshot_member_id and consistency_group_id fields in a new share. It has source_cgsnapshot_member_id that is equal to the ID of the consistency group snapshot and consistency_group_id that is equal to the ID of cgroup2 created from a snapshot.

$ manila show ba52454e-2ea3-47fa-a683-3176a01295e6
+-----------------------------+---------------------------------------------------------------+
| Property                    | Value                                                         |
+-----------------------------+---------------------------------------------------------------+
| status                      | available                                                     |
| share_type_name             | default                                                       |
| description                 | None                                                          |
| availability_zone           | None                                                          |
| share_network_id            | None                                                          |
| export_locations            | 10.254.0.5:/shares/share-5acadf4d-f81a-4515-b5ce-3ab641ab4d1e |
| share_server_id             | None                                                          |
| host                        | manila@generic1#GENERIC1                                      |
| snapshot_id                 | None                                                          |
| is_public                   | False                                                         |
| task_state                  | None                                                          |
| snapshot_support            | True                                                          |
| id                          | ba52454e-2ea3-47fa-a683-3176a01295e6                          |
| size                        | 1                                                             |
| name                        | None                                                          |
| share_type                  | c0086582-30a6-4060-b096-a42ec9d66b86                          |
| created_at                  | 2015-09-29T15:47:48.000000                                    |
| share_proto                 | NFS                                                           |
| consistency_group_id        | ffee08d9-c86c-45e5-861e-175c731daca2                          |
| source_cgsnapshot_member_id | 5c62af2b-0870-4d00-b3fa-174831eb15ca                          |
| project_id                  | 20787a7ba11946adad976463b57d8a2f                              |
| metadata                    | {}                                                            |
+-----------------------------+---------------------------------------------------------------+

As an administrator, you can also reset the state of a consistency group snapshot with the cg-snapshot-reset-state command, and force delete a specified consistency group snapshot in any state using the cg-snapshot-delete command with the --force key. Use the policy.json file to grant permissions for these actions to other roles.

8.9 Share replication

Replication of data has a number of use cases in the cloud. One use case is High Availability of the data in a shared file system, used for example, to support a production database. Another use case is ensuring Data Protection; i.e being prepared for a disaster by having a replication location that will be ready to back up your primary data source.

The Shared File System service supports user facing APIs that allow users to create shares that support replication, add and remove share replicas and manage their snapshots and access rules. Three replication types are currently supported and they vary in the semantics associated with the primary share and the secondary copies.

Important
Important

Share replication is an experimental Shared File Systems API in the Mitaka release. Contributors can change or remove the experimental part of the Shared File Systems API in further releases without maintaining backward compatibility. Experimental APIs have an X-OpenStack-Manila-API-Experimental: true header in their HTTP requests.

8.9.1 Replication types supported

Before using share replication, make sure the Shared File System driver that you are running supports this feature. You can check it in the manila-scheduler service reports. The replication_type capability reported can have one of the following values:

writable

The driver supports creating writable share replicas. All share replicas can be accorded read/write access and would be synchronously mirrored.

readable

The driver supports creating read-only share replicas. All secondary share replicas can be accorded read access. Only the primary (or active share replica) can be written into.

dr

The driver supports creating dr (abbreviated from Disaster Recovery) share replicas. A secondary share replica is inaccessible until after a promotion.

None

The driver does not support Share Replication.

Note
Note

The term active share replica refers to the primary share. In writable style of replication, all share replicas are active, and there could be no distinction of a primary share. In readable and dr styles of replication, a secondary share replica may be referred to as passive, non-active or simply, replica.

8.9.2 Configuration

Two new configuration options have been introduced to support Share Replication.

replica_state_update_interval

Specify this option in the DEFAULT section of your manila.conf. The Shared File Systems service requests periodic update of the replica_state of all non-active share replicas. The update occurs with respect to an interval corresponding to this option. If it is not specified, it defaults to 300 seconds.

replication_domain

Specify this option in the backend stanza when using a multi-backend style configuration. The value can be any ASCII string. Two backends that can replicate between each other would have the same replication_domain. This comes from the premise that the Shared File Systems service expects Share Replication to be performed between symmetric backends. This option is required for using the Share Replication feature.

8.9.3 Health of a share replica

Apart from the status attribute, share replicas have the replica_state attribute to denote the state of data replication on the storage backend. The primary share replica will have it's replica_state attribute set to active. The secondary share replicas may have one of the following as their replica_state:

in_sync

The share replica is up to date with the active share replica (possibly within a backend-specific recovery point objective).

out_of_sync

The share replica is out of date (all new share replicas start out in this replica_state).

error

When the scheduler fails to schedule this share replica or some potentially irrecoverable error occurred with regard to updating data for this replica.

8.9.4 Promotion or failover

For readable and dr types of replication, we refer to the task of switching a non-active share replica with the active replica as promotion. For the writable style of replication, promotion does not make sense since all share replicas are active (or writable) at all times.

The status attribute of the non-active replica being promoted will be set to replication_change during its promotion. This has been classified as a busy state and thus API interactions with the share are restricted while one of its share replicas is in this state.

8.9.5 Share replication workflows

The following examples have been implemented with the ZFSonLinux driver that is a reference implementation in the Shared File Systems service. It operates in driver_handles_share_servers=False mode and supports the readable type of replication. In the example, we assume a configuration of two Availability Zones (configuration option: storage_availability_zone), called availability_zone_1 and availability_zone_2.

Multiple availability zones are not necessary to use the replication feature. However, the use of an availability zone as a failure domain is encouraged.

Pay attention to the network configuration for the ZFS driver. Here, we assume a configuration of zfs_service_ip and zfs_share_export_ip from two separate networks. The service network is reachable from the host where the manila-share service is running. The share export IP is from a network that allows user access.

See Configuring the ZFSonLinux driver for information on how to set up the ZFSonLinux driver.

8.9.5.1 Creating a share that supports replication

Create a new share type and specify the replication_type as an extra-spec within the share-type being used.

Use the manila type-create command to create a new share type. Specify the name and the value for the extra-spec driver_handles_share_servers.

$ manila type-create readable_type_replication False
+----------------------+--------------------------------------+
| Property             | Value                                |
+----------------------+--------------------------------------+
| required_extra_specs | driver_handles_share_servers : False |
| Name                 | readable_type_replication            |
| Visibility           | public                               |
| is_default           | -                                    |
| ID                   | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 |
| optional_extra_specs | snapshot_support : True              |
+----------------------+--------------------------------------+

Use the manila type-key command to set an extra-spec to the share type.

$ manila type-key readable_type_replication set replication_type=readable
Note
Note

This command has no output. To verify the extra-spec, use the manila extra-specs-list command and specify the share type's name or ID as a parameter.

Create a share with the share type

Use the manila create command to create a share. Specify the share protocol, size and the availability zone.

$ manila create NFS 1 --share_type readable_type_replication --name my_share --description "This share will have replicas" --az availability_zone_1
+-----------------------------+--------------------------------------+
| Property                    | Value                                |
+-----------------------------+--------------------------------------+
| status                      | creating                             |
| share_type_name             | readable_type_replication            |
| description                 | This share will have replicas        |
| availability_zone           | availability_zone_1                  |
| share_network_id            | None                                 |
| share_server_id             | None                                 |
| host                        |                                      |
| access_rules_status         | active                               |
| snapshot_id                 | None                                 |
| is_public                   | False                                |
| task_state                  | None                                 |
| snapshot_support            | True                                 |
| id                          | e496ed61-8f2e-436b-b299-32c3e90991cc |
| size                        | 1                                    |
| name                        | my_share                             |
| share_type                  | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074 |
| has_replicas                | False                                |
| replication_type            | readable                             |
| created_at                  | 2016-03-29T20:22:18.000000           |
| share_proto                 | NFS                                  |
| consistency_group_id        | None                                 |
| source_cgsnapshot_member_id | None                                 |
| project_id                  | 48a5ca76ac69405e99dc1c13c5195186     |
| metadata                    | {}                                   |
+-----------------------------+--------------------------------------+

Use the manila show command to retrieve details of the share. Specify the share ID or name as a parameter.

$ manila show my_share
+-----------------------------+--------------------------------------------------------------------+
| Property                    | Value                                                              |
+-----------------------------+--------------------------------------------------------------------+
| status                      | available                                                          |
| share_type_name             | readable_type_replication                                          |
| description                 | This share will have replicas                                      |
| availability_zone           | availability_zone_1                                                |
| share_network_id            | None                                                               |
| export_locations            |                                                                    |
|                             | path =                                                             |
|                             |10.32.62.26:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28|
|                             | preferred = False                                                  |
|                             | is_admin_only = False                                              |
|                             | id = e1d754b5-ec06-42d2-afff-3e98c0013faf                          |
|                             | share_instance_id = 38efc042-50c2-4825-a6d8-cba2a8277b28           |
|                             | path =                                                             |
|                             |172.21.0.23:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28|
|                             | preferred = False                                                  |
|                             | is_admin_only = True                                               |
|                             | id = 6f843ecd-a7ea-4939-86de-e1e01d9e8672                          |
|                             | share_instance_id = 38efc042-50c2-4825-a6d8-cba2a8277b28           |
| share_server_id             | None                                                               |
| host                        | openstack4@zfsonlinux_1#alpha                                      |
| access_rules_status         | active                                                             |
| snapshot_id                 | None                                                               |
| is_public                   | False                                                              |
| task_state                  | None                                                               |
| snapshot_support            | True                                                               |
| id                          | e496ed61-8f2e-436b-b299-32c3e90991cc                               |
| size                        | 1                                                                  |
| name                        | my_share                                                           |
| share_type                  | 3b3ee3f7-6e43-4aa1-859d-0b0511c43074                               |
| has_replicas                | False                                                              |
| replication_type            | readable                                                           |
| created_at                  | 2016-03-29T20:22:18.000000                                         |
| share_proto                 | NFS                                                                |
| consistency_group_id        | None                                                               |
| source_cgsnapshot_member_id | None                                                               |
| project_id                  | 48a5ca76ac69405e99dc1c13c5195186                                   |
| metadata                    | {}                                                                 |
+-----------------------------+--------------------------------------------------------------------+
Note
Note

When you create a share that supports replication, an active replica is created for you. You can verify this with the manila share-replica-list command.

8.9.5.2 Creating and promoting share replicas

Create a share replica

Use the manila share-replica-create command to create a share replica. Specify the share ID or name as a parameter. You may optionally provide the availability_zone and share_network_id. In the example below, share_network_id is not used since the ZFSonLinux driver does not support it.

$ manila share-replica-create my_share --az availability_zone_2
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | creating                             |
| share_id          | e496ed61-8f2e-436b-b299-32c3e90991cc |
| availability_zone | availability_zone_2                  |
| created_at        | 2016-03-29T20:24:53.148992           |
| updated_at        | None                                 |
| share_network_id  | None                                 |
| share_server_id   | None                                 |
| host              |                                      |
| replica_state     | None                                 |
| id                | 78a5ef96-6c36-42e0-b50b-44efe7c1807e |
+-------------------+--------------------------------------+

See details of the newly created share replica

Use the manila share-replica-show command to see details of the newly created share replica. Specify the share replica's ID as a parameter.

$ manila share-replica-show 78a5ef96-6c36-42e0-b50b-44efe7c1807e
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | available                            |
| share_id          | e496ed61-8f2e-436b-b299-32c3e90991cc |
| availability_zone | availability_zone_2                  |
| created_at        | 2016-03-29T20:24:53.000000           |
| updated_at        | 2016-03-29T20:24:58.000000           |
| share_network_id  | None                                 |
| share_server_id   | None                                 |
| host              | openstack4@zfsonlinux_2#beta         |
| replica_state     | in_sync                              |
| id                | 78a5ef96-6c36-42e0-b50b-44efe7c1807e |
+-------------------+--------------------------------------+

See all replicas of the share

Use the manila share-replica-list command to see all the replicas of the share. Specify the share ID or name as an optional parameter.

$ manila share-replica-list --share-id my_share
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| ID                                   | Status    | Replica State | Share ID                             | Host                          | Availability Zone   | Updated At                 |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | active        | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:22:19.000000 |
| 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | in_sync       | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta  | availability_zone_2 | 2016-03-29T20:24:58.000000 |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+

Promote the secondary share replica to be the new active replica

Use the manila share-replica-promote command to promote a non-active share replica to become the active replica. Specify the non-active replica's ID as a parameter.

$ manila share-replica-promote 78a5ef96-6c36-42e0-b50b-44efe7c1807e
Note
Note

This command has no output.

The promotion may take time. During the promotion, the replica_state attribute of the share replica being promoted will be set to replication_change.

$ manila share-replica-list --share-id my_share
+--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| ID                                   | Status    |    Replica State   | Share ID                             | Host                          | Availability Zone   | Updated At                 |
+--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| 38efc042-50c2-4825-a6d8-cba2a8277b28 | available |       active       | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:32:19.000000 |
| 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | replication_change | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta  | availability_zone_2 | 2016-03-29T20:32:19.000000 |
+--------------------------------------+-----------+--------------------+--------------------------------------+-------------------------------+---------------------+----------------------------+

Once the promotion is complete, the replica_state will be set to active.

$ manila share-replica-list --share-id my_share
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| ID                                   | Status    | Replica State | Share ID                             | Host                          | Availability Zone   | Updated At                 |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+
| 38efc042-50c2-4825-a6d8-cba2a8277b28 | available | in_sync       | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_1#alpha | availability_zone_1 | 2016-03-29T20:32:19.000000 |
| 78a5ef96-6c36-42e0-b50b-44efe7c1807e | available | active        | e496ed61-8f2e-436b-b299-32c3e90991cc | openstack4@zfsonlinux_2#beta  | availability_zone_2 | 2016-03-29T20:32:19.000000 |
+--------------------------------------+-----------+---------------+--------------------------------------+-------------------------------+---------------------+----------------------------+

8.9.5.3 Access rules

Create an IP access rule for the share

Use the manila access-allow command to add an access rule. Specify the share ID or name, protocol and the target as parameters.

$ manila access-allow my_share ip 0.0.0.0/0 --access-level rw
+--------------+--------------------------------------+
| Property     | Value                                |
+--------------+--------------------------------------+
| share_id     | e496ed61-8f2e-436b-b299-32c3e90991cc |
| access_type  | ip                                   |
| access_to    | 0.0.0.0/0                            |
| access_level | rw                                   |
| state        | new                                  |
| id           | 8b339cdc-c1e0-448f-bf6d-f068ee6e8f45 |
+--------------+--------------------------------------+
Note
Note

Access rules are not meant to be different across the replicas of the share. However, as per the type of replication, drivers may choose to modify the access level prescribed. In the above example, even though read/write access was requested for the share, the driver will provide read-only access to the non-active replica to the same target, because of the semantics of the replication type: readable. However, the target will have read/write access to the (currently) non-active replica when it is promoted to become the active replica.

The manila access-deny command can be used to remove a previously applied access rule.

List the export locations of the share

Use the manila share-export-locations-list command to list the export locations of a share.

$ manila share-export-location-list my_share
+--------------------------------------+---------------------------------------------------------------------------+-----------+
| ID                                   | Path                                                                      | Preferred |
+--------------------------------------+---------------------------------------------------------------------------+-----------+
| 3ed3fbf5-2fa1-4dc0-8440-a0af72398cb6 | 10.32.62.21:/beta/subdir/manila_share_78a5ef96_6c36_42e0_b50b_44efe7c1807e| False     |
| 6f843ecd-a7ea-4939-86de-e1e01d9e8672 | 172.21.0.23:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28      | False     |
| e1d754b5-ec06-42d2-afff-3e98c0013faf | 10.32.62.26:/alpha/manila_share_38efc042_50c2_4825_a6d8_cba2a8277b28      | False     |
| f3c5585f-c2f7-4264-91a7-a4a1e754e686 | 172.21.0.29:/beta/subdir/manila_share_78a5ef96_6c36_42e0_b50b_44efe7c1807e| False     |
+--------------------------------------+---------------------------------------------------------------------------+-----------+

Identify the export location corresponding to the share replica on the user accessible network and you may mount it on the target node.

Note
Note

As an administrator, you can list the export locations for a particular share replica by using the manila share-instance-export-location-list command and specifying the share replica's ID as a parameter.

8.9.5.4 Snapshots

Create a snapshot of the share

Use the manila snapshot-create command to create a snapshot of the share. Specify the share ID or name as a parameter.

$ manila snapshot-create my_share --name "my_snapshot"
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | creating                             |
| share_id          | e496ed61-8f2e-436b-b299-32c3e90991cc |
| description       | None                                 |
| created_at        | 2016-03-29T21:14:03.000000           |
| share_proto       | NFS                                  |
| provider_location | None                                 |
| id                | 06cdccaf-93a0-4e57-9a39-79fb1929c649 |
| size              | 1                                    |
| share_size        | 1                                    |
| name              | my_snapshot                          |
+-------------------+--------------------------------------+

Show the details of the snapshot

Use the manila snapshot-show to view details of a snapshot. Specify the snapshot ID or name as a parameter.

$ manila snapshot-show my_snapshot
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | available                            |
| share_id          | e496ed61-8f2e-436b-b299-32c3e90991cc |
| description       | None                                 |
| created_at        | 2016-03-29T21:14:03.000000           |
| share_proto       | NFS                                  |
| provider_location | None                                 |
| id                | 06cdccaf-93a0-4e57-9a39-79fb1929c649 |
| size              | 1                                    |
| share_size        | 1                                    |
| name              | my_snapshot                          |
+-------------------+--------------------------------------+
Note
Note

The status attribute of a snapshot will transition from creating to available only when it is present on all the share replicas that have their replica_state attribute set to active or in_sync.

Likewise, the replica_state attribute of a share replica will transition from out_of_sync to in_sync only when all available snapshots are present on it.

8.9.5.5 Planned failovers

As an administrator, you can use the manila share-replica-resync command to attempt to sync data between active and non-active share replicas of a share before promotion. This will ensure that share replicas have the most up-to-date data and their relationships can be safely switched.

$ manila share-replica-resync 38efc042-50c2-4825-a6d8-cba2a8277b28
Note
Note

This command has no output.

8.9.5.6 Updating attributes

If an error occurs while updating data or replication relationships (during a promotion), the Shared File Systems service may not be able to determine the consistency or health of a share replica. It may require administrator intervention to make any fixes on the storage backend as necessary. In such a situation, state correction within the Shared File Systems service is possible.

As an administrator, you can:

Reset the status attribute of a share replica

Use the manila share-replica-reset-state command to reset the status attribute. Specify the share replica's ID as a parameter and use the --state option to specify the state intended.

$ manila share-replica-reset-state 38efc042-50c2-4825-a6d8-cba2a8277b28 --state=available
Note
Note

This command has no output.

Reset the replica_state attribute

Use the manila share-replica-reset-replica-state command to reset the replica_state attribute. Specify the share replica's ID and use the --state option to specify the state intended.

$ manila share-replica-reset-replica-state 38efc042-50c2-4825-a6d8-cba2a8277b28 --state=out_of_sync
Note
Note

This command has no output.

Force delete a specified share replica in any state

Use the manila share-replica-delete command with the '--force' key to remove the share replica, regardless of the state it is in.

$ manila share-replica-show 9513de5d-0384-4528-89fb-957dd9b57680
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| status            | error                                |
| share_id          | e496ed61-8f2e-436b-b299-32c3e90991cc |
| availability_zone | availability_zone_1                  |
| created_at        | 2016-03-30T01:32:47.000000           |
| updated_at        | 2016-03-30T01:34:25.000000           |
| share_network_id  | None                                 |
| share_server_id   | None                                 |
| host              | openstack4@zfsonlinux_1#alpha        |
| replica_state     | out_of_sync                          |
| id                | 38efc042-50c2-4825-a6d8-cba2a8277b28 |
+-------------------+--------------------------------------+

$ manila share-replica-delete --force 38efc042-50c2-4825-a6d8-cba2a8277b28
Note
Note

This command has no output.

Use the policy.json file to grant permissions for these actions to other roles.

8.9.5.7 Deleting share replicas

Use the manila share-replica-delete command with the share replica's ID to delete a share replica.

$ manila share-replica-delete 38efc042-50c2-4825-a6d8-cba2a8277b28
Note
Note

This command has no output.

Note
Note

You cannot delete the last active replica with this command. You should use the manila delete command to remove the share.

8.10 Multi-storage configuration

The Shared File Systems service can provide access to multiple file storage back ends. In general, the workflow with multiple back ends looks similar to the Block Storage service one, see Section 7.2.4, “Configure multiple-storage back ends”.

Using manila.conf, you can spawn multiple share services. To do it, you should set the enabled_share_backends flag in the manila.conf file. This flag defines the comma-separated names of the configuration stanzas for the different back ends. One name is associated to one configuration group for a back end.

The following example runs three configured share services:

[DEFAULT]
enabled_share_backends=backendEMC2,backendGeneric1,backendNetApp

[backendGeneric1]
share_driver=manila.share.drivers.generic.GenericShareDriver
share_backend_name=one_name_for_two_backends
service_instance_user=ubuntu_user
service_instance_password=ubuntu_user_password
service_image_name=ubuntu_image_name
path_to_private_key=/home/foouser/.ssh/id_rsa
path_to_public_key=/home/foouser/.ssh/id_rsa.pub

[backendEMC2]
share_driver=manila.share.drivers.emc.driver.EMCShareDriver
share_backend_name=backendEMC2
emc_share_backend=vnx
emc_nas_server=1.1.1.1
emc_nas_password=password
emc_nas_login=user
emc_nas_server_container=server_3
emc_nas_pool_name="Pool 2"

[backendNetApp]
share_driver = manila.share.drivers.netapp.common.NetAppDriver
driver_handles_share_servers = True
share_backend_name=backendNetApp
netapp_login=user
netapp_password=password
netapp_server_hostname=1.1.1.1
netapp_root_volume_aggregate=aggr01

To spawn separate groups of share services, you can use separate configuration files. If it is necessary to control each back end in a separate way, you should provide a single configuration file per each back end.

8.10.1 Scheduling

The Shared File Systems service uses a scheduler to provide unified access for a variety of different types of shared file systems. The scheduler collects information from the active shared services, and makes decisions such as what shared services will be used to create a new share. To manage this process, the Shared File Systems service provides Share types API.

A share type is a list from key-value pairs called extra-specs. The scheduler uses required and un-scoped extra-specs to look up the shared service most suitable for a new share with the specified share type. For more information about extra-specs and their type, see Capabilities and Extra-Specs section in developer documentation.

The general scheduler workflow:

  1. Share services report information about their existing pool number, their capacities, and their capabilities.

  2. When a request on share creation arrives, the scheduler picks a service and pool that best serves the request, using share type filters and back end capabilities. If back end capabilities pass through, all filters request the selected back end where the target pool resides.

  3. The share driver receives a reply on the request status, and lets the target pool serve the request as the scheduler instructs. The scoped and un-scoped share types are available for the driver implementation to use as needed.

8.10.2 Manage shares services

The Shared File Systems service provides API that allows to manage running share services (Share services API). Using the manila service-list command, it is possible to get a list of all kinds of running services. To select only share services, you can pick items that have field binary equal to manila-share. Also, you can enable or disable share services using raw API requests. Disabling means that share services are excluded from the scheduler cycle and new shares will not be placed on the disabled back end. However, shares from this service stay available.

8.11 Networking

Unlike the OpenStack Block Storage service, the Shared File Systems service must connect to the Networking service. The share service requires the option to self-manage share servers. For client authentication and authorization, you can configure the Shared File Systems service to work with different network authentication services, like LDAP, Kerberos protocols, or Microsoft Active Directory.

8.11.1 Share networks

Share network is an entity that encapsulates interaction with the OpenStack Networking service. If the share driver that you selected runs in a mode requiring Networking service interaction, specify the share network when creating a new share network.

8.11.1.1 How to create share network

To list networks in a project, run:

$ openstack network list
+--------------+---------+--------------------+
| ID           | Name    | Subnets            |
+--------------+---------+--------------------+
| bee7411d-... | public  | 884a6564-0f11-...  |
|              |         | e6da81fa-5d5f-...  |
| 5ed5a854-... | private | 74dcfb5a-b4d7-...  |
|              |         | cc297be2-5213-...  |
+--------------+---------+--------------------+

A share network stores network information that share servers can use where shares are hosted. You can associate a share with a single share network. When you create or update a share, you can optionally specify the ID of a share network through which instances can access the share.

When you create a share network, you can specify only one type of network:

  • OpenStack Networking (neutron). Specify a network ID and subnet ID. In this case manila.network.nova_network_plugin.NeutronNetworkPlugin will be used.

  • Legacy networking (nova-network). Specify a network ID. In this case manila.network.nova_network_plugin.NoveNetworkPlugin will be used.

For more information about supported plug-ins for share networks, see Section 8.11.2, “Network plug-ins”.

A share network has these attributes:

  • The IP block in Classless Inter-Domain Routing (CIDR) notation from which to allocate the network.

  • The IP version of the network.

  • The network type, which is vlan, vxlan, gre, or flat.

If the network uses segmentation, a segmentation identifier. For example, VLAN, VXLAN, and GRE networks use segmentation.

To create a share network with private network and subnetwork, run:

$ manila share-network-create --neutron-net-id 5ed5a854-21dc-4ed3-870a-117b7064eb21 \
--neutron-subnet-id 74dcfb5a-b4d7-4855-86f5-a669729428dc --name my_share_net --description "My first share network"
+-------------------+--------------------------------------+
| Property          | Value                                |
+-------------------+--------------------------------------+
| name              | my_share_net                         |
| segmentation_id   | None                                 |
| created_at        | 2015-09-24T12:06:32.602174           |
| neutron_subnet_id | 74dcfb5a-b4d7-4855-86f5-a669729428dc |
| updated_at        | None                                 |
| network_type      | None                                 |
| neutron_net_id    | 5ed5a854-21dc-4ed3-870a-117b7064eb21 |
| ip_version        | None                                 |
| nova_net_id       | None                                 |
| cidr              | None                                 |
| project_id        | 20787a7ba11946adad976463b57d8a2f     |
| id                | 5c3cbabb-f4da-465f-bc7f-fadbe047b85a |
| description       | My first share network               |
+-------------------+--------------------------------------+

The segmentation_id, cidr, ip_version, and network_type share network attributes are automatically set to the values determined by the network provider.

To check the network list, run:

$ manila share-network-list
+--------------------------------------+--------------+
| id                                   | name         |
+--------------------------------------+--------------+
| 5c3cbabb-f4da-465f-bc7f-fadbe047b85a | my_share_net |
+--------------------------------------+--------------+

If you configured the generic driver with driver_handles_share_servers = True (with the share servers) and already had previous operations in the Shared File Systems service, you can see manila_service_network in the neutron list of networks. This network was created by the generic driver for internal use.

$ openstack network list
+--------------+------------------------+--------------------+
| ID           | Name                   | Subnets            |
+--------------+------------------------+--------------------+
| 3b5a629a-e...| manila_service_network | 4f366100-50...     |
| bee7411d-... | public                 | 884a6564-0f11-...  |
|              |                        | e6da81fa-5d5f-...  |
| 5ed5a854-... | private                | 74dcfb5a-b4d7-...  |
|              |                        | cc297be2-5213-...  |
+--------------+------------------------+--------------------+

You also can see detailed information about the share network including network_type, and segmentation_id fields:

$ openstack network show manila_service_network
+---------------------------+--------------------------------------+
| Field                     | Value                                |
+---------------------------+--------------------------------------+
| admin_state_up            | UP                                   |
| availability_zone_hints   |                                      |
| availability_zones        | nova                                 |
| created_at                | 2016-12-13T09:31:30Z                 |
| description               |                                      |
| id                        | 3b5a629a-e7a1-46a3-afb2-ab666fb884bc |
| ipv4_address_scope        | None                                 |
| ipv6_address_scope        | None                                 |
| mtu                       | 1450                                 |
| name                      | manila_service_network               |
| port_security_enabled     | True                                 |
| project_id                | f6ac448a469b45e888050cf837b6e628     |
| provider:network_type     | vxlan                                |
| provider:physical_network | None                                 |
| provider:segmentation_id  | 73                                   |
| revision_number           | 7                                    |
| router:external           | Internal                             |
| shared                    | False                                |
| status                    | ACTIVE                               |
| subnets                   | 682e3329-60b0-440f-8749-83ef53dd8544 |
| tags                      | []                                   |
| updated_at                | 2016-12-13T09:31:36Z                 |
+---------------------------+--------------------------------------+

You also can add and remove the security services from the share network. For more detail, see Section 8.7, “Security services”.

8.11.2 Network plug-ins

The Shared File Systems service architecture defines an abstraction layer for network resource provisioning and allowing administrators to choose from a different options for how network resources are assigned to their projects’ networked storage. There are a set of network plug-ins that provide a variety of integration approaches with the network services that are available with OpenStack.

The Shared File Systems service may need a network resource provisioning if share service with specified driver works in mode, when a share driver manages lifecycle of share servers on its own. This behavior is defined by a flag driver_handles_share_servers in share service configuration. When driver_handles_share_servers is set to True, a share driver will be called to create share servers for shares using information provided within a share network. This information will be provided to one of the enabled network plug-ins that will handle reservation, creation and deletion of network resources including IP addresses and network interfaces.

8.11.2.1 What network plug-ins are available?

There are three different network plug-ins and five python classes in the Shared File Systems service:

  1. Network plug-in for using the OpenStack Networking service. It allows to use any network segmentation that the Networking service supports. It is up to each share driver to support at least one network segmentation type.

    1. manila.network.neutron.neutron_network_plugin.NeutronNetworkPlugin. This is a default network plug-in. It requires the neutron_net_id and the neutron_subnet_id to be provided when defining the share network that will be used for the creation of share servers. The user may define any number of share networks corresponding to the various physical network segments in a project environment.

    2. manila.network.neutron.neutron_network_plugin. NeutronSingleNetworkPlugin. This is a simplification of the previous case. It accepts values for neutron_net_id and neutron_subnet_id from the manila.conf configuration file and uses one network for all shares.

    When only a single network is needed, the NeutronSingleNetworkPlugin (1.b) is a simple solution. Otherwise NeutronNetworkPlugin (1.a) should be chosen.

  2. Network plug-in for working with OpenStack Networking from the Compute service. It supports either flat networks or VLAN-segmented networks.

    1. manila.network.nova_network_plugin.NovaNetworkPlugin. This plug-in serves the networking needs when Nova networking is configured in the cloud instead of Neutron. It requires a single parameter, nova_net_id.

    2. manila.network.nova_network_plugin.NovaSingleNetworkPlugin. This plug-in works the same way as manila.network.nova_network_plugin.NovaNetworkPlugin, except it takes nova_net_id from the Shared File Systems service configuration file and creates the share servers using only one network.

    When only a single network is needed, the NovaSingleNetworkPlugin (2.b) is a simple solution. Otherwise NovaNetworkPlugin (2.a) should be chosen.

  3. Network plug-in for specifying networks independently from OpenStack networking services.

    1. manila.network.standalone_network_plugin.StandaloneNetworkPlugin. This plug-in uses a pre-existing network that is available to the manila-share host. This network may be handled either by OpenStack or be created independently by any other means. The plug-in supports any type of network - flat and segmented. As above, it is completely up to the share driver to support the network type for which the network plug-in is configured.

Note
Note

These network plug-ins were introduced in the OpenStack Kilo release. In the OpenStack Juno version, only NeutronNetworkPlugin is available.

More information about network plug-ins can be found in Manila developer documentation

8.12 Troubleshoot Shared File Systems service

8.12.1 Failures in Share File Systems service during a share creation

8.12.1.1 Problem

New shares can enter error state during the creation process.

8.12.1.2 Solution

  1. Make sure, that share services are running in debug mode. If the debug mode is not set, you will not get any tips from logs how to fix your issue.

  2. Find what share service holds a specified share. To do that, run command manila show <share_id_or_name> and find a share host in the output. Host uniquely identifies what share service holds the broken share.

  3. Look thought logs of this share service. Usually, it can be found at /etc/var/log/manila-share.log. This log should contain kind of traceback with extra information to help you to find the origin of issues.

8.12.2 No valid host was found

8.12.2.1 Problem

If a share type contains invalid extra specs, the scheduler will not be able to locate a valid host for the shares.

8.12.2.2 Solution

To diagnose this issue, make sure that scheduler service is running in debug mode. Try to create a new share and look for message Failed to schedule create_share: No valid host was found. in /etc/var/log/manila-scheduler.log.

To solve this issue look carefully through the list of extra specs in the share type, and the list of share services reported capabilities. Make sure that extra specs are pointed in the right way.

8.12.3 Created share is unreachable

8.12.3.1 Problem

By default, a new share does not have any active access rules.

8.12.3.2 Solution

To provide access to new share, you need to create appropriate access rule with the right value. The value must defines access.

8.12.4 Service becomes unavailable after upgrade

8.12.4.1 Problem

After upgrading the Shared File Systems service from version v1 to version v2.x, you must update the service endpoint in the OpenStack Identity service. Otherwise, the service may become unavailable.

8.12.4.2 Solution

  1. To get the service type related to the Shared File Systems service, run:

    # openstack endpoint list
    
    # openstack endpoint show <share-service-type>

    You will get the endpoints expected from running the Shared File Systems service.

  2. Make sure that these endpoints are updated. Otherwise, delete the outdated endpoints and create new ones.

8.12.5 Failures during management of internal resources

8.12.5.1 Problem

The Shared File System service manages internal resources effectively. Administrators may need to manually adjust internal resources to handle failures.

8.12.5.2 Solution

Some drivers in the Shared File Systems service can create service entities, like servers and networks. If it is necessary, you can log in to project service and take manual control over it.

Print this page