Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Configuring the Shared File Systems service (manila)

With the Shared File Systems service (manila), you can provision shared file systems that multiple compute instances, bare-metal nodes, or containers can consume. Cloud administrators create share types to prepare the share service and enable end users to create and manage shares.

Prerequisites

  • An end user requires at least one share type to use the Shared File Systems service.
  • For back ends where driver_handles_share_servers=False, a cloud administrator configures the requisite networking in advance rather than dynamically in the shared file system back end.
  • For a CephFS through NFS back end, a cloud administrator deploys Red Hat OpenStack Platform (RHOSP) director with isolated networks and environment arguments and a custom network_data file to create an isolated StorageNFS network for NFS exports. After deployment, before the overcloud is used, the administrator creates a corresponding Networking service (neutron) StorageNFS shared provider network that maps to the isolated StorageNFS network of the data center.
  • For a Compute instance to connect to this shared provider network, the user must add an additional neutron port.

6.1. Configuring Shared File Systems service back ends

When cloud administrators use Red Hat OpenStack Platform (RHOSP) director to deploy the Shared File Systems service (manila), they can choose one or more supported back ends, such as native CephFS, CephFS-NFS, NetApp, Dell EMC Unity, and others.

For more information about native CephFS and CephFS-NFS, see Deploying Red Hat Ceph Storage and Red Hat OpenStack Platform together with director.

For a complete list of supported back-end appliances and drivers, see the Manila section of the Red Hat Knowledge Article, Component, Plug-In, and Driver Support in Red Hat OpenStack Platform.

6.1.1. Configuring multiple back ends

A back end is a storage system or technology that is paired with the Shared File Systems service (manila) driver to export file systems. The Shared File Systems service requires at least one back end to operate. In many cases, one back end is sufficient. However, you can also use multiple back ends in a single Shared File Systems service installation.

Important

Red Hat OpenStack Platform (RHOSP) does not support multiple instances of the same back end to a Shared File Systems service deployment. For example, you cannot add two Red Hat Ceph Storage clusters as back ends within the same deployment. CephFS native and CephFS-NFS are considered one back end with different protocols.

The scheduler for the Shared File Systems service determines the destination back end for share creation requests. A single back end in the Shared File Systems service can expose multiple storage pools.

When you configure multiple back ends, the scheduler chooses one storage pool to create a resource from all the pools exposed by all configured back ends. This process is abstracted from the end user. End users see only the capabilities that are exposed by the cloud administrator.

6.1.2. Deploying multiple back ends

By default, a standard Shared File Systems service (manila) deployment environment file has a single back end. Use the following example procedure to add multiple back ends to the Shared File Systems service and deploy an environment with a CephFS-NFS and a NetApp back end.

Prerequisites

  • At least two back ends.
  • If a back end requires a custom container, you must use one from the Red Hat Ecosystem Catalog instead of the standard Shared File Systems service container. For example, if you want to use a Dell EMC Unity storage system back end with Ceph, choose the Dell EMC Unity container from the catalog.

Procedure

  1. Create a storage customization YAML file. You can use this file to provide any values or overrides that suit your environment: 

    $ vi /home/stack/templates/storage_customizations.yaml
    Copy to Clipboard

  2. Configure the storage customization YAML file to include any overrides, including enabling multiple back ends: 

    parameter_defaults:
  ManilaEnabledShareProtocols:
    - NFS
  ManilaNetappLogin: '<login_name>'
  ManilaNetappPassword: '<password>'
  ManilaNetappServerHostname: '<netapp-hostname>'
  ManilaNetappVserver: ‘<netapp-vserver>’
  ManilaNetappDriverHandlesShareServers: 'false'
    Copy to Clipboard
    • Replace the values in angle brackets <> with the correct values for your YAML file.

  3. Specify the back-end templates by using the openstack overcloud deploy command. The example configuration enables the Shared File Systems service with a NetApp back end and a CephFS-NFS back end.

    Note

    Execute source ~/stackrc before issuing the openstack overcloud deploy command. 

    [stack@undercloud ~]$ source ~/stackrc
$ openstack overcloud deploy \
  --timeout 100 \
  --stack overcloud \
  --templates /usr/share/openstack-tripleo-heat-templates \
  -n /usr/share/openstack-tripleo-heat-templates/network_data_ganesha.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-mds.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/ceph-ansible/ceph-ansible.yaml \
  -r /home/stack/templates/roles/roles_data.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/manila-cephfsganesha-config.yaml \
-e /usr/share/openstack-tripleo-heat-templates/environments/manila-netapp-config.yaml \
-e /home/stack/templates/storage_customizations.yaml \
...
    Copy to Clipboard

Additional resources

6.1.3. Confirming deployment of multiple back ends

Use the manila service-list command to verify that your back ends deployed successfully. If you use a health check on multiple back ends, a ping test returns a response even if one of the back ends is unresponsive, so this is not a reliable way to verify your deployment.

Procedure

  1. Log in to the undercloud host as the stack user.

  2. Source the overcloudrc credentials file: 

    $ source ~/overcloudrc
    Copy to Clipboard

  3. Confirm the list of Shared File Systems service back ends: 

    $ manila service-list

+----+--------+--------+------+---------+-------+----------------------------+
| Id | Binary | Host | Zone | Status | State | Updated_at |
+----+--------+--------+------+---------+-------+----------------------------+
| 2 | manila-scheduler | hostgroup | nova | enabled | up | 2021-03-24T16:49:09.000000 |
| 5 | manila-share | hostgroup@cephfs | nova | enabled | up | 2021-03-24T16:49:12.000000 |
| 8 | manila-share | hostgroup@tripleo_netapp | nova | enabled | up | 2021-03-24T16:49:06.000000 |
    Copy to Clipboard

    The status of each successfully deployed back end shows enabled and the state shows up.

6.1.4. Overriding allowed NAS protocols

The Shared File Systems service can export shares in one of many network attached storage (NAS) protocols, such as NFS, CIFS, or CEPHFS. By default, the Shared File Systems service enables all of the NAS protocols supported by the back ends in a deployment.

As a Red Hat OpenStack Platform (RHOSP) administrator, you can override the ManilaEnabledShareProtocols parameter and list only the protocols that you want to allow in your cloud.

For example, if back ends in your deployment support both NFS and CIFS, you can override the default value and enable only one protocol.

Procedure

  1. Log in to the undercloud host as the stack user.

  2. Source the overcloudrc credentials file: 

    $ source ~/overcloudrc
    Copy to Clipboard

  3. Create a storage customization YAML file. This file can be used to provide any values or overrides that suit your environment: 

    $ vi /home/stack/templates/storage_customizations.yaml
    Copy to Clipboard

  4. Configure the ManilaEnabledShareProtocols parameter with the values that you want: 

    parameter_defaults:
  ManilaEnabledShareProtocols:
    - NFS
    - CEPHFS
    Copy to Clipboard

  5. Include the environment file that contains your new content in the openstack overcloud deploy command by using the -e option. Ensure that you include all other environment files that are relevant to your deployment. 

    $ openstack overcloud deploy \
...
-e /home/stack/templates/storage_customizations.yaml
    Copy to Clipboard
    Note

    The deployment does not validate the settings. The NAS protocols that you assign must be supported by the back ends in your Shared File Systems service deployment.

6.1.5. Viewing back-end capabilities

The scheduler component of the Shared File Systems service (manila) makes intelligent placement decisions based on several factors such as capacity, provisioning configuration, placement hints, and the capabilities that the back-end storage system driver detects and exposes.

Procedure

  • Run the following command to view the available capabilities: 

    $ manila pool-list --detail
+------------------------------------+----------------------------+
| Property                           | Value                      |
+------------------------------------+----------------------------+
| name                               | hostgroup@cephfs#cephfs    |
| pool_name                          | cephfs                     |
| total_capacity_gb                  | 1978                       |
| free_capacity_gb                   | 1812                       |
...
| driver_handles_share_servers       | False                      |
| snapshot_support                   | True                       |
| create_share_from_snapshot_support | False                      |
| revert_to_snapshot_support         | False                      |
| mount_snapshot_support             | False                      |
...
+------------------------------------+----------------------------+
+------------------------------------+-----------------------------------+
| Property                           | Value                             |
+------------------------------------+-----------------------------------+
| name                               | hostgroup@tripleo_netapp#aggr1_n1 |
| pool_name                          | aggr1_n1                          |
| total_capacity_gb                  | 6342.1                            |
| free_capacity_gb                   | 6161.99                           |
...
| driver_handles_share_servers       | False                             |
| mount_snapshot_support             | False                             |
| replication_type                   | None                              |
| replication_domain                 | None                              |
| sg_consistent_snapshot_support     | host                              |
| ipv4_support                       | True                              |
| ipv6_support                       | False                             |
+------------------------------------+-----------------------------------+
+------------------------------------+-----------------------------------+
| Property                           | Value                             |
+------------------------------------+-----------------------------------+
| name                               | hostgroup@tripleo_netapp#aggr1_n2 |
| pool_name                          | aggr1_n2                          |
| total_capacity_gb                  | 6342.1                            |
| free_capacity_gb                   | 6209.26                           |
...
| snapshot_support                   | True                              |
| create_share_from_snapshot_support | True                              |
| revert_to_snapshot_support         | True                              |
| driver_handles_share_servers       | False                             |
| mount_snapshot_support             | False                             |
| replication_type                   | None                              |
| replication_domain                 | None                              |
| sg_consistent_snapshot_support     | host                              |
| ipv4_support                       | True                              |
| ipv6_support                       | False                             |
+------------------------------------+-----------------------------------+
    Copy to Clipboard

Related information

To influence placement decisions, as an administrator, you can use share types and extra specifications. For more information about share types, see Creating share types.

6.2. Creating share types

Share types serve as hints to the Shared File Systems service scheduler to perform placement decisions. Red Hat OpenStack Platform (RHOSP) director configures the Shared File Systems service with a default share type named default, but does not create the share type.

Important

An end user requires at least one share type to use the Shared File Systems service.

Procedure

  1. After you deploy the overcloud, run the following command as the cloud administrator to create a share type: 

    $ manila type-create default <spec_driver_handles_share_servers>
    Copy to Clipboard

    The <spec_driver_handles_share_servers> parameter is a Boolean value:

    • For CephFS through NFS or native CephFS, the value is false.
    • For other back ends, the value can be true or false. Set <spec_driver_handles_share_servers> to match the value of the Manila<backend>DriverHandlesShareServers parameter. For example, if you use a NetApp back end, the parameter is called ManilaNetappDriverHandlesShareServers.

  2. Add specifications to the default share type or create additional share types to use with multiple configured back ends. For example, configure the default share type to select a CephFS back end and an additional share type that uses a NetApp driver_handles_share_servers=True back end: 

    (overcloud) [stack@undercloud-0 ~]$ manila type-create default false --extra-specs share_backend_name='cephfs'
(overcloud) [stack@undercloud-0 ~]$ manila type-create netapp true --extra-specs share_backend_name='tripleo_netapp'
    Copy to Clipboard
Note

By default, share types are public, which means they are visible to and usable by all cloud projects. However, you can create private share types for use within specific projects.

Additional resources

6.3. Comparing common capabilities of share types

Share types define the common capabilities of shares. Review the common capabilities of share types to understand what you can do with your shares.

Table 6.1. Capabilities of share types
CapabilityValuesDescription

driver_handles_share_servers

true or false

Grants permission to use share networks to create shares.

snapshot_support

true or false

Grants permission to create snapshots of shares.

create_share_from_snapshot_support

true or false

Grants permission to create clones of share snapshots.

revert_to_snapshot_support

true or false

Grants permission to revert your shares to the most recent snapshot.

mount_snapshot_support

true or false

Grants permission to export and mount your snapshots.

replication_type

dr

Grants permission to create replicas for disaster recovery. Only one active export is allowed at a time.

readable

Grants permission to create read-only replicas. Only one writable, active export is allowed at a time.

writable

Grants permission to create read/write replicas. Any number of active exports are allowed at a time per share.

availability_zones

a list of one or more availability zones

Grants permission to create shares only on the availability zones listed.

6.4. Planning networking for shared file systems

Shared file systems are accessed over a network. It is important to plan the networking on your cloud to ensure that end user clients can connect their shares to workloads that run on Red Hat OpenStack Platform (RHOSP) virtual machines, bare-metal servers, and containers.

Depending on the level of security and isolation required for end users, as an administrator, you can set the driver_handles_share_servers parameter to true or false.

If you set the driver_handles_share_servers parameter to true, this enables the service to export shares to end user-defined share networks with the help of isolated share servers.

When the driver_handles_share_servers parameter equals true, users can provision their workloads on self-service share networks. This ensures that their shares are exported by completely isolated NAS file servers on dedicated network segments.

The share networks used by end users can be the same as the private project networks that they can create. As an administrator, you must ensure that the physical network to which you map these isolated networks extends to your storage infrastructure.

You must also ensure that the network segmentation style by project networks is supported by the storage system used. Storage systems, such as NetApp ONTAP and Dell EMC PowerMax, Unity, and VNX, do not support virtual overlay segmentation styles such as GENEVE or VXLAN.

As an alternative, you can terminate the overlay networking at top-of-rack switches and use a more primitive form of networking for your project networks, such as VLAN. Another alternative is to allow VLAN segments on shared provider networks or provide access to a pre-existing segmented network that is already connected to your storage system.

If you set the driver_handles_share_servers parameter to false, users cannot create shares on their own share networks. Instead, they must connect their clients to the network configured by the cloud administrator.

When the driver_handles_share_servers parameter equals false, director can create a dedicated shared storage network for you. For example, when you deploy the native CephFS back end with standard director templates, director creates a shared provider network called Storage. When you deploy CephFS through the NFS back end, the shared provider network is called StorageNFS. Your end users must connect their clients to the shared storage network to access their shares.

Not all shared file system storage drivers support both modes of operation. Regardless of which mode you choose, the service ensures hard data path multi-tenancy isolation guarantees.

If you want to offer hard network path multi-tenancy isolation guarantees to tenant workloads as part of a self-service model, you must deploy with back ends that support the driver_handles_share_servers driver mode.

For information about network connectivity to the share, see Section 6.5, “Ensuring network connectivity to the share”

6.5. Ensuring network connectivity to the share

Clients that need to connect to a file share must have network connectivity to one or more of the export locations for that share.

There are many ways to configure networking with the Shared File Systems service, including using network plugins.

When the driver_handles_share_servers parameter for a share type equals true, a cloud user can create a share network with the details of a network to which the compute instance attaches and then reference it when creating shares.

When the driver_handles_share_servers parameter for a share type equals false, a cloud user must connect their compute instance to the shared storage network.

For more information about how to configure and validate network connectivity to a shared network, see Section 7.5, “Connecting to a shared network to access shares”.

6.6. Changing the default quotas in the Shared File Systems service

To prevent system capacities from being exhausted without notification, cloud administrators can configure quotas. Quotas are operational limits. The Shared File Systems service (manila) enforces some sensible limits by default. These limits are called default quotas. Cloud administrators can override default quotas so that individual projects have different consumption limits.

6.6.1. Updating quotas for projects, users, and share types

As a cloud administrator, you can list the quotas for a project or user by using the manila quota-show command.

You can update quotas for all users in a project, or a specific project user, or a share type used by the project users. You can update the following quotas for the target you choose:

  • shares: Number of shares that you can create.
  • snapshots: Number of snapshots that you can create.
  • gigabytes: Total size in GB that you can allocate for all shares.
  • snapshot-gigabytes: Total size in GB that you can allocate for all snapshots of shares.
  • share-networks: Total number of share networks that you can create.
  • share_groups: Total number of share groups that you can create.
  • share_group_snapshots: Total number of share group snapshots that you can create.
  • share-replicas: Total number of share replicas that you can create.
  • replica-gigabytes: Total size in GB that you can allocate across all share replicas.
Note

You can only specify share-type quotas at the project level. You cannot set share-type quotas for specific project users.

Important

In the following procedures, enter the values carefully. The Shared File Systems service does not detect or report incorrect values.

Procedure

  1. You can use the following commands to view quotas. If you include the --user option, you can view the quota for a specific user in the specified project. If you omit the --user option, you can view the quotas that apply to all users for the specified project.

    Similarly, if you include the optional --share-type, you can view the quota for a specific share type as it relates to the project. The --user and --share-type options are mutually exclusive. 

    $ manila quota-show
    Copy to Clipboard

    • Example for a project: 

      $ manila quota-show --project af2838436f3f4cf6896399dd97c4c050
+-----------------------+----------------------------------+
| Property              | Value                            |
+-----------------------+----------------------------------+
| gigabytes             | 1000                             |
| id                    | af2838436f3f4cf6896399dd97c4c050 |
| replica_gigabytes     | 1000                             |
| share_group_snapshots | 50                               |
| share_groups          | 49                               |
| share_networks        | 10                               |
| share_replicas        | 100                              |
| shares                | 50                               |
| snapshot_gigabytes    | 1000                             |
| snapshots             | 50                               |
+-----------------------+----------------------------------+
      Copy to Clipboard

    • Example for a project user: 

      $ manila quota-show --project af2838436f3f4cf6896399dd97c4c050 --user 81ebb491dd0e4c2aae0775dd564e76d1
+-----------------------+----------------------------------+
| Property              | Value                            |
+-----------------------+----------------------------------+
| gigabytes             | 500                              |
| id                    | af2838436f3f4cf6896399dd97c4c050 |
| replica_gigabytes     | 1000                             |
| share_group_snapshots | 50                               |
| share_groups          | 49                               |
| share_networks        | 10                               |
| share_replicas        | 100                              |
| shares                | 25                               |
| snapshot_gigabytes    | 1000                             |
| snapshots             | 50                               |
+-----------------------+----------------------------------+
      Copy to Clipboard

    • Example for a project for a specific share type: 

      $ manila quota-show --project af2838436f3f4cf6896399dd97c4c050 --share-type dhss_false
+---------------------+----------------------------------+
| Property            | Value                            |
+---------------------+----------------------------------+
| gigabytes           | 1000                             |
| id                  | af2838436f3f4cf6896399dd97c4c050 |
| replica_gigabytes   | 1000                             |
| share_replicas      | 100                              |
| shares              | 15                               |
| snapshot_gigabytes  | 1000                             |
| snapshots           | 50                               |
+---------------------+----------------------------------+
      Copy to Clipboard

  2. Use the manila quota-update command to update the quotas. You can update quotas for all project users, a specific project user, or a share type in a project:

    • Update quotas for all users in a project: 

      $ manila quota-update <id> [--shares <share_quota> --gigabytes <share_gigabytes_quota> …]
      Copy to Clipboard

      Replace <id> with the project ID. This value must be the project ID, not the project name.

    • Update quotas for a specific user in a project: 

      $  manila quota-update <id> --user <user_id> [--shares <new_share_quota> --gigabytes <new_share_gigabytes_quota> …]
      Copy to Clipboard
      • Replace <id> with the project ID. This value must be the project ID, not the project name.
      • Replace <user_id> with the user ID. The value must be the user ID, not the user name.

    • Update quotas for all users who use a specific share type: 

      $ manila quota-update <id> --share-type <share_type> [--shares <new_share_quota>30 --gigabytes <new-share_gigabytes_quota> …]
      Copy to Clipboard
      • Replace <id> with the project ID. This value must be the project ID, not the project name.
      • Replace <share_type> with the name or ID of the share type that you want to apply the quota to.

Verification

  • The quota-update command does not produce any output. Use the quota-show command to verify that a quota was successfully updated.

6.6.2. Resetting quotas for projects, users, and share types

You can remove quota overrides to return quotas to their default values. The target entity is restricted by the default quota that applies to all projects with no overrides.

Procedure

  • Use the manila quota-delete command to return quotas to default values. You can return quotas to default values for all project users, a specific project user, or a share type in a project:

    • Reset project quotas: 

      $ manila quota-delete --project <id>
      Copy to Clipboard

      Replace <id> with the project ID. This value must be the project ID, not the project name.

    • Reset quotas for a specific user: 

      $ manila quota-delete --project <id> --user <user_id>
      Copy to Clipboard
      • Replace <id> with the project ID. This value must be the project ID, not the project name.
      • Replace <user_id> with the user ID. The value must be the user ID, not the user name.

    • Reset quotas for a share type used by project users: 

      $ manila quota-delete --project <id> --share-type <share_type>
      Copy to Clipboard
      • Replace <id> with the project ID. This value must be the project ID, not the project name.
      • Replace <share_type> with the name or ID of the share type the quota must be reset for.

Verification

  1. The quota-delete command does not produce any output. Use the quota-show command to verify whether a quota was successfully reset.

  2. List the default quotas for all projects. Default quotas apply to projects that have no overrides. 

    $ manila quota-class-show default
    Copy to Clipboard

6.6.3. Updating the default quota values for Shared File Systems service projects

As a cloud administrator, you can update default quotas that apply to all projects that do not already have quota overrides.

Procedure

  1. View the usage statement of the manila quota-class-update command: 

    $ manila help quota-class-update
usage: manila quota-class-update [--shares <shares>] [--snapshots <snapshots>]
                                 [--gigabytes <gigabytes>]
                                 [--snapshot-gigabytes <snapshot_gigabytes>]
                                 [--share-networks <share_networks>]
                                 [--share-replicas <share_replicas>]
                                 [--replica-gigabytes <replica_gigabytes>]
                                 <class_name>
    Copy to Clipboard
    Note

    The parameter <class_name> is a positional argument. It identifies the quota class for which the quotas are set. Set the value of this parameter to default. No other quota classes are supported.

    You can update the values for any of the following optional parameters:

    • --shares <shares> Adds a new value for the shares quota.
    • --snapshots <snapshots> Adds a new value for the snapshots quota.
    • --gigabytes <gigabytes> Adds a new value for the gigabytes quota.
    • --snapshot-gigabytes <snapshot_gigabytes> or --snapshot_gigabytes <snapshot_gigabytes> Adds a new value for the snapshot_gigabytes quota.
    • --share-networks <share_networks> or --share_networks <share_networks> Adds a new value for the share_networks quota.
    • --share-replicas <share_replicas>, --share_replicas <share_replicas>, or --replicas <share_replicas> Adds a new value for the share_replicas quota.
    • --replica-gigabytes <replica_gigabytes> or --replica_gigabytes <replica_gigabytes> Adds a new value for the replica_gigabytes quota.

  2. Use the information from the usage statement to update the default quotas. The following example updates the default quotas for shares and gigabytes: 

    $ manila quota-class-update default --shares 30 --gigabytes 512
$ manila quota-class-show default
+-----------------------+---------+
| Property              | Value   |
+-----------------------+---------+
| gigabytes             | 512     |
| id                    | default |
| replica_gigabytes     | 1000    |
| share_group_snapshots | 50      |
| share_groups          | 50      |
| share_networks        | 10      |
| share_replicas        | 100     |
| shares                | 30      |
| snapshot_gigabytes    | 1000    |
| snapshots             | 50      |
+-----------------------+---------+
    Copy to Clipboard
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat