Red Hat Training

A Red Hat training course is available for Red Hat OpenStack Platform

CephFS Back End Guide for the Shared File System Service

Red Hat OpenStack Platform 11

Deploying a CephFS Back End for the Shared File System Service in a Red Hat OpenStack Platform Overcloud

OpenStack Documentation Team


This document describes a test deployment of OpenStack Shared File System Service that uses a CephFS back end. The back end used by this deployment is enabled through the manila.share.drivers.cephfs.cephfs_native driver.
Red Hat CephFS integration is currently available as a Technology Preview, and as such this deployment should not be used in production. For more information about Technology Previews, see:

1. Introduction


Red Hat Ceph file system (CephFS) is available only as a Technology Preview, and therefore not fully supported by Red Hat. The deployment scenario described in this document should only be used for testing, and should not be deployed in a production environment.

For more information about Technology Preview features, see Scope of Coverage Details.

The OpenStack Shared File Systems service (openstack-manila) provides the means to easily provision shared file systems that can be consumed by multiple instances. In the past, OpenStack users needed to manually deploy shared file systems before mounting them on instances. The OpenStack Shared File Systems service, on the other hand, allows users to easily provision shares from a pre-configured storage pool, ready to be mounted securely. This pool, in turn, can be independently managed and scaled to meet demand.

This release includes a technology preview of the necessary driver for Red Hat CephFS (namely, manila.share.drivers.cephfs.cephfs_native.CephFSNativeDriver). This driver allows the Shared File System service to use CephFS as a back end.

While you can manually configure the Shared File System service by directly editing its node’s /etc/manila/manila.conf file, any settings can be overwritten by the Red Hat OpenStack Platform director in future overcloud updates. As such, the recommended method for configuring a Shared File System back end is through the director. Doing so involves writing a custom environment file.

With this release, the director can now deploy the Shared File System with a CephFS back end on the overcloud. This document explains how to do so.

2. Requirements

To test this feature, you need an existing Red Hat OpenStack Platform environment with an integrated Ceph back end. See Creating an Overcloud with Ceph Storage Nodes (from Red Hat Ceph Storage for the Overcloud) for instructions on how to deploy such an environment.

In addition, this scenario assumes that:

  • The Shared File System service will still be installed on the Controller nodes, as is the default behavior; and
  • You intend to only use a single instance of the Ceph File Sysem as the only back end for your Shared File System Service.

2.1. Limitations and Restrictions

Given the current state of the involved components, the test scenario in this document has the following limitations and restrictions:

  1. Untrusted instance users pose a security risk to the Ceph Storage cluster, as they would have direct access to the public network of the Ceph Storage cluster. Ensure that the cluster you are using is quarantined from the production environment, and that only trusted users have access to the test environment.
  2. This release only allows read-write access to shares.

3. Edit the Environment File

The environment file contains the back end settings you want to define. It also contains other settings relevant to the deployment of the Shared File System service. For more information about environment files, see Environment Files (from the Director Installation and Usage guide).

This release includes an integrated environment file for defining a CephFS back end. This file is located in the following path of the undercloud node:


This file provides default settings for deploying a Shared File System service.

Create an environment file which will contain the settings necessary for your environment — namely, ~/templates/manila-cephfsnative-config.yaml. The following snippet shows the default values used by the director when deploying the Shared File System service:


parameter_defaults: # 1
  ManilaCephFSNativeBackendName: cephfsnative
  ManilaCephFSNativeDriverHandlesShareServers: false # 2
  ManilaCephFSNativeCephFSConfPath: '/etc/ceph/ceph.conf' # 3
  ManilaCephFSNativeCephFSAuthId: 'manila' # 4
  ManilaCephFSNativeCephFSClusterName: 'ceph'
  ManilaCephFSNativeCephFSEnableSnapshots: true

The parameter_defaults header signifies the start of your configuration. Specifically, it allows you to override default values set in resource_registry. This includes values set by OS::Tripleo::Services::ManilaBackendCephFs, which sets defaults for a CephFS back end.
With ManilaCephFSNativeDriverHandlesShareServers set to false, the driver will not handle the lifecycle of the share server.
ManilaCephFSNativeCephFSConfPath: sets the path to the configuration file of the Ceph cluster.
ManilaCephFSNativeCephFSAuthId: is the Ceph auth ID that the director will create for share access.

4. Deploy the Shared File System Service with a CephFS Back End

Once you create /home/stack/templates/manila-cephfsnative-config.yaml, log in as the stack user on the undercloud. Then, deploy the Shared File System service with a CephFS back end by including the following environment files:

  • /usr/share/openstack-tripleo-heat-templates/environments/services/ceph-mds.yaml - enables the Ceph MDS, which is required by Shared File System service when using a CephFS back end.
  • /usr/share/openstack-tripleo-heat-templates/environments/manila-cephfsnative-config.yaml - deploys the Ceph cluster.
  • /home/stack/templates/manila-cephfsnative-config.yaml - created earlier in Section 3, “Edit the Environment File”, and contains any settings to override defaults set in /usr/share/openstack-tripleo-heat-templates/environments/manila-cephfsnative-config.yaml.

For example, if your OpenStack and Ceph settings are defined in /home/stack/templates/storage-environment.yaml, run:

$ openstack overcloud deploy --templates \
   -e /home/stack/templates/storage-environment.yaml \
   -e /usr/share/openstack-tripleo-heat-templates/environments/manila-cephfsnative-config.yaml \
   -e /usr/share/openstack-tripleo-heat-templates/environments/services/ceph-mds.yaml \
   -e /home/stack/templates/manila-cephfsnative-config.yaml \

If you passed any extra environment files when you created the overcloud, pass them again here using the -e option to avoid making undesired changes to the overcloud. For more information, see Modifying the Overcloud Environment (from Director Installation and Usage).

Legal Notice

Copyright © 2017 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.