From bc4712e35ecec7f4e693cf4df5ca95633323d3fc Mon Sep 17 00:00:00 2001 From: Goutham Pacha Ravi Date: Tue, 23 Aug 2016 20:22:36 -0400 Subject: [PATCH] Manila install guide: Fix wrong instructions Previously only the DHSS=True mode was documented in post install steps. The assumption that the generic driver was being configured existed in other places as well. * add DHSS=False documentation as necessary with the LVM driver. * correct assumptions in other places to clarify usage of appropriate share driver modes. Change-Id: Ic1356453e510e8f360269fb45a41379329ce68c2 Closes-Bug: #1616257 --- .../controller-node-common-configuration.rst | 11 + .../common/dhss-false-mode-configuration.rst | 6 +- .../source/common/dhss-false-mode-intro.rst | 1 + ...s-false-mode-using-shared-file-systems.rst | 176 ++++++++++++ .../common/dhss-true-mode-configuration.rst | 16 +- .../source/common/dhss-true-mode-intro.rst | 14 +- ...ss-true-mode-using-shared-file-systems.rst | 269 ++++++++++++++++++ .../share-node-common-configuration.rst | 10 + .../common/share-node-share-server-modes.rst | 34 ++- .../get-started-with-shared-file-systems.rst | 25 +- install-guide/source/index.rst | 41 ++- install-guide/source/install-share-node.rst | 10 +- install-guide/source/post-install.rst | 204 +------------ 13 files changed, 576 insertions(+), 241 deletions(-) create mode 100644 install-guide/source/common/dhss-false-mode-using-shared-file-systems.rst create mode 100644 install-guide/source/common/dhss-true-mode-using-shared-file-systems.rst diff --git a/install-guide/source/common/controller-node-common-configuration.rst b/install-guide/source/common/controller-node-common-configuration.rst index d4f257c6..a7220987 100644 --- a/install-guide/source/common/controller-node-common-configuration.rst +++ b/install-guide/source/common/controller-node-common-configuration.rst @@ -29,6 +29,17 @@ rootwrap_config = /etc/manila/rootwrap.conf api_paste_config = /etc/manila/api-paste.ini + .. important:: + + The ``default_share_type`` option specifies the default share type to + be used when shares are created without specifying the share type in + the request. The default share type that is specified in the + configuration file has to be created with the necessary required + extra-specs (such as ``driver_handles_share_servers``) set + appropriately with reference to the driver mode used. This is further + explained in the section discussing the setup and configuration of the + share node. + * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, configure Identity service access: diff --git a/install-guide/source/common/dhss-false-mode-configuration.rst b/install-guide/source/common/dhss-false-mode-configuration.rst index b8d6e2cf..b7e53ab5 100644 --- a/install-guide/source/common/dhss-false-mode-configuration.rst +++ b/install-guide/source/common/dhss-false-mode-configuration.rst @@ -61,15 +61,15 @@ Configure components #. Edit the ``/etc/manila/manila.conf`` file and complete the following actions: - * In the ``[DEFAULT]`` section, enable the LVM driver and the NFS/CIFS - protocols: + * In the ``[DEFAULT]`` section, enable the LVM driver and the NFS + protocol: .. code-block:: ini [DEFAULT] ... enabled_share_backends = lvm - enabled_share_protocols = NFS,CIFS + enabled_share_protocols = NFS .. note:: diff --git a/install-guide/source/common/dhss-false-mode-intro.rst b/install-guide/source/common/dhss-false-mode-intro.rst index fa611163..069f6a44 100644 --- a/install-guide/source/common/dhss-false-mode-intro.rst +++ b/install-guide/source/common/dhss-false-mode-intro.rst @@ -1,5 +1,6 @@ Shared File Systems Option 1: No driver support for share servers management ---------------------------------------------------------------------------- + For simplicity, this configuration references the same storage node configuration for the Block Storage service. However, the LVM driver requires a separate empty local block storage device to avoid conflict diff --git a/install-guide/source/common/dhss-false-mode-using-shared-file-systems.rst b/install-guide/source/common/dhss-false-mode-using-shared-file-systems.rst new file mode 100644 index 00000000..e144a2fe --- /dev/null +++ b/install-guide/source/common/dhss-false-mode-using-shared-file-systems.rst @@ -0,0 +1,176 @@ +Creating shares with Shared File Systems Option 1 (DHSS = False) +---------------------------------------------------------------- + +Create a share type +------------------- + +Disable DHSS (``driver_handles_share_servers``) before creating a share using +the LVM driver. + +#. Source the admin credentials to gain access to admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc + +#. Create a default share type with DHSS disabled. A default share type will + allow you to create shares with this driver, without having to specify + the share type explicitly during share creation. + + .. code-block:: console + + $ manila type-create default_share_type False + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | required_extra_specs | driver_handles_share_servers : False | + | Name | default_share_type | + | Visibility | public | + | is_default | - | + | ID | 3df065c8-6ca4-4b80-a5cb-e633c0439097 | + | optional_extra_specs | snapshot_support : True | + +----------------------+--------------------------------------+ + + Set this default share type in ``manila.conf`` under the ``[DEFAULT]`` + section and restart the ``manila-api`` service before proceeding. + Unless you do so, the default share type will not be effective. + + .. note:: + + Creating and configuring a default share type is optional. If you wish + to use the shared file system service with a variety of share types, + where each share creation request could specify a type, please refer to + the Share types usage documentation `here + _`. + +Create a share +-------------- + +#. Source the ``demo`` credentials to perform + the following steps as a non-administrative project: + + .. code-block:: console + + $ . demo-openrc + +#. Create an NFS share. Since a default share type has been created and + configured, it need not be specified in the request. + + .. code-block:: console + + $ manila create NFS 1 --name share1 + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | creating | + | share_type_name | default_share_type | + | description | None | + | availability_zone | None | + | share_network_id | None | + | host | | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 55c401b3-3112-4294-aa9f-3cc355a4e361 | + | size | 1 | + | name | share1 | + | share_type | 3df065c8-6ca4-4b80-a5cb-e633c0439097 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-30T19:10:33.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 3a46a53a377642a284e1d12efabb3b5a | + | metadata | {} | + +-----------------------------+--------------------------------------+ + +#. After some time, the share status should change from ``creating`` + to ``available``: + + .. code-block:: console + + $ manila list + +--------------------------------------+--------+------+-------------+-----------+-----------+--------------------+-----------------------------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+--------+------+-------------+-----------+-----------+--------------------+-----------------------------+-------------------+ + | 55c401b3-3112-4294-aa9f-3cc355a4e361 | share1 | 1 | NFS | available | False | default_share_type | storage@lvm#lvm-single-pool | nova | + +--------------------------------------+--------+------+-------------+-----------+-----------+--------------------+-----------------------------+-------------------+ + +#. Determine export IP address of the share: + + .. code-block:: console + + $ manila show share1 + +-----------------------------+------------------------------------------------------------------------------------+ + | Property | Value | + +-----------------------------+------------------------------------------------------------------------------------+ + | status | available | + | share_type_name | default_share_type | + | description | None | + | availability_zone | nova | + | share_network_id | None | + | export_locations | | + | | path = 10.0.0.41:/var/lib/manila/mnt/share-8e13a98f-c310-41df-ac90-fc8bce4910b8 | + | | id = 3c8d0ada-cadf-48dd-85b8-d4e8c3b1e204 | + | | preferred = False | + | host | storage@lvm#lvm-single-pool | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 55c401b3-3112-4294-aa9f-3cc355a4e361 | + | size | 1 | + | name | share1 | + | share_type | c6dfcfc6-9920-420e-8b0a-283d578efef5 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-30T19:10:33.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 3a46a53a377642a284e1d12efabb3b5a | + | metadata | {} | + +-----------------------------+------------------------------------------------------------------------------------+ + +Allow access to the share +------------------------- + +#. Configure access to the new share before attempting to mount it via + the network. The compute instance (whose IP address is referenced by the + INSTANCE_IP below) must have network connectivity to the network specified + in the share network. + + .. code-block:: console + + $ manila access-allow share1 ip INSTANCE_IP + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | share_id | 55c401b3-3112-4294-aa9f-3cc355a4e361 | + | access_type | ip | + | access_to | 10.0.0.46 | + | access_level | rw | + | state | new | + | id | f88eab01-7197-44bf-ad0f-d6ca6f99fc96 | + +--------------+--------------------------------------+ + +Mount the share on a compute instance +------------------------------------- + +#. Log into your compute instance and create a folder where the mount will + be placed: + + .. code-block:: console + + $ mkdir ~/test_folder + +#. Mount the NFS share in the compute instance using the export location of + the share: + + .. code-block:: console + + # mount -vt nfs 10.0.0.41:/var/lib/manila/mnt/share-8e13a98f-c310-41df-ac90-fc8bce4910b8 ~/test_folder diff --git a/install-guide/source/common/dhss-true-mode-configuration.rst b/install-guide/source/common/dhss-true-mode-configuration.rst index e2318c53..23b9da59 100644 --- a/install-guide/source/common/dhss-true-mode-configuration.rst +++ b/install-guide/source/common/dhss-true-mode-configuration.rst @@ -4,15 +4,15 @@ Configure components #. Edit the ``/etc/manila/manila.conf`` file and complete the following actions: - * In the ``[DEFAULT]`` section, enable the generic driver and the NFS/CIFS - protocols: + * In the ``[DEFAULT]`` section, enable the generic driver and the NFS + protocol: .. code-block:: ini [DEFAULT] ... enabled_share_backends = generic - enabled_share_protocols = NFS,CIFS + enabled_share_protocols = NFS .. note:: @@ -82,3 +82,13 @@ Configure components You can also use SSH keys instead of password authentication for service instance credentials. + + .. important:: + + The ``service_image_name``, ``service_instance_flavor_id``, + ``service_instance_user`` and ``service_instance_password`` are with + reference to the service image that is used by the driver to create + share servers. A sample service image for use with the ``generic`` + driver is available in the ``manila-image-elements`` project. Its + creation is explained in the post installation steps (See: + :ref:`post-install`). diff --git a/install-guide/source/common/dhss-true-mode-intro.rst b/install-guide/source/common/dhss-true-mode-intro.rst index fa775e54..adf23378 100644 --- a/install-guide/source/common/dhss-true-mode-intro.rst +++ b/install-guide/source/common/dhss-true-mode-intro.rst @@ -2,14 +2,16 @@ Shared File Systems Option 2: Driver support for share servers management ------------------------------------------------------------------------- For simplicity, this configuration references the same storage node -configuration for the Block Storage service. +as the one used for the Block Storage service. .. note:: This guide describes how to configure the Shared File Systems service to use the ``generic`` driver with the driver handles share server mode - (DHSS) enabled. This mode requires Compute (nova), Networking (neutron) and - Block storage (cinder) services for managing share servers. The information - used for creating share servers is configured as share networks. Generic - driver with DHSS enabled also requires network to be attached to a public - router. \ No newline at end of file + (DHSS) enabled. This driver requires Compute service (nova), Image service + (glance) and Networking service (neutron) for creating and managing share + servers; and Block storage service (cinder) for creating shares. The + information used for creating share servers is configured as share + networks. Generic driver with DHSS enabled also requires the tenant's + private network (where the compute instances are running) to be attached + to a public router. \ No newline at end of file diff --git a/install-guide/source/common/dhss-true-mode-using-shared-file-systems.rst b/install-guide/source/common/dhss-true-mode-using-shared-file-systems.rst new file mode 100644 index 00000000..1d629366 --- /dev/null +++ b/install-guide/source/common/dhss-true-mode-using-shared-file-systems.rst @@ -0,0 +1,269 @@ +Creating shares with Shared File Systems Option 2 (DHSS = True) +--------------------------------------------------------------- + +Before being able to create a share, manila with the generic driver and +the DHSS (``driver_handles_share_servers``) mode enabled requires the +definition of at least an image, a network and a share-network for being +used to create a share server. For that `back end` configuration, the share +server is an instance where NFS shares are served. + +.. note:: + + This configuration automatically creates a cinder volume for every share. + The cinder volumes are attached to share servers according to the + definition of a share network. + + +#. Source the admin credentials to gain access to admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc.sh + +#. Create a default share type with DHSS enabled. A default share type will + allow you to create shares with this driver, without having to specify + the share type explicitly during share creation. + + .. code-block:: console + + $ manila type-create default_share_type True + +----------------------+--------------------------------------+ + | Property | Value | + +----------------------+--------------------------------------+ + | required_extra_specs | driver_handles_share_servers : True | + | Name | default_share_type | + | Visibility | public | + | is_default | - | + | ID | 8a35da28-0f74-490d-afff-23664ecd4f01 | + | optional_extra_specs | snapshot_support : True | + +----------------------+--------------------------------------+ + + Set this default share type in ``manila.conf`` under the ``[DEFAULT]`` + section and restart the ``manila-api`` service before proceeding. + Unless you do so, the default share type will not be effective. + + .. note:: + + Creating and configuring a default share type is optional. If you wish + to use the shared file system service with a variety of share types, + where each share creation request could specify a type, please refer to + the Share types usage documentation `here + _`. + +#. Create a manila share server image in the Image service. You may skip this + step and use any existing image. However, for mounting a share, the service + image must contain the NFS packages as appropriate for the operating system. + Whatever image you choose to be the service image, be sure to set the + configuration values ``service_image_name``, ``service_instance_flavor_id``, + ``service_instance_user`` and ``service_instance_password`` in + ``manila.conf``. + + .. note:: + + Any changes made to ``manila.conf`` while the ``manila-share`` service + is running will require a restart of the service to be effective. + + .. note:: + + As an alternative to specifying a plain-text + ``service_instance_password`` in your configuration, a key-pair may be + specified with options ``path_to_public_key`` and + ``path_to_private_key`` to configure and allow password-less SSH access + between the `share node` and the share server/s created. + + .. code-block:: console + + $ glance image-create \ + --copy-from http://tarballs.openstack.org/manila-image-elements/images/manila-service-image-master.qcow2 \ + --name "manila-service-image" \ + --disk-format qcow2 \ + --container-format bare \ + --visibility public --progress + [=============================>] 100% + +------------------+--------------------------------------+ + | Property | Value | + +------------------+--------------------------------------+ + | checksum | 48a08e746cf0986e2bc32040a9183445 | + | container_format | bare | + | created_at | 2016-01-26T19:52:24Z | + | disk_format | qcow2 | + | id | 1fc7f29e-8fe6-44ef-9c3c-15217e83997c | + | min_disk | 0 | + | min_ram | 0 | + | name | manila-service-image | + | owner | e2c965830ecc4162a002bf16ddc91ab7 | + | protected | False | + | size | 306577408 | + | status | active | + | tags | [] | + | updated_at | 2016-01-26T19:52:28Z | + | virtual_size | None | + | visibility | public | + +------------------+--------------------------------------+ + +#. List available networks in order to get id and subnets of the private + network: + + .. code-block:: console + + $ neutron net-list + +--------------------------------------+---------+----------------------------------------------------+ + | id | name | subnets | + +--------------------------------------+---------+----------------------------------------------------+ + | 0e62efcd-8cee-46c7-b163-d8df05c3c5ad | public | 5cc70da8-4ee7-4565-be53-b9c011fca011 10.3.31.0/24 | + | 7c6f9b37-76b4-463e-98d8-27e5686ed083 | private | 3482f524-8bff-4871-80d4-5774c2730728 172.16.1.0/24 | + +--------------------------------------+---------+----------------------------------------------------+ + +#. Source the ``demo`` credentials to perform + the following steps as a non-administrative project: + + .. code-block:: console + + $ . demo-openrc.sh + + .. code-block:: console + + $ manila share-network-create --name demo-share-network1 \ + --neutron-net-id PRIVATE_NETWORK_ID \ + --neutron-subnet-id PRIVATE_NETWORK_SUBNET_ID + +-------------------+--------------------------------------+ + | Property | Value | + +-------------------+--------------------------------------+ + | name | demo-share-network1 | + | segmentation_id | None | + | created_at | 2016-01-26T20:03:41.877838 | + | neutron_subnet_id | 3482f524-8bff-4871-80d4-5774c2730728 | + | updated_at | None | + | network_type | None | + | neutron_net_id | 7c6f9b37-76b4-463e-98d8-27e5686ed083 | + | ip_version | None | + | nova_net_id | None | + | cidr | None | + | project_id | e2c965830ecc4162a002bf16ddc91ab7 | + | id | 58b2f0e6-5509-4830-af9c-97f525a31b14 | + | description | None | + +-------------------+--------------------------------------+ + +Create a share +-------------- + +#. Create an NFS share using the share network. Since a default share type has + been created and configured, it need not be specified in the request. + + .. code-block:: console + + $ manila create NFS 1 --name demo-share1 --share-network demo-share-network1 + +-----------------------------+--------------------------------------+ + | Property | Value | + +-----------------------------+--------------------------------------+ + | status | None | + | share_type_name | default_share_type | + | description | None | + | availability_zone | None | + | share_network_id | 58b2f0e6-5509-4830-af9c-97f525a31b14 | + | host | None | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 016ca18f-bdd5-48e1-88c0-782e4c1aa28c | + | size | 1 | + | name | demo-share1 | + | share_type | 8a35da28-0f74-490d-afff-23664ecd4f01 | + | created_at | 2016-01-26T20:08:50.502877 | + | export_location | None | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 48e8c35b2ac6495d86d4be61658975e7 | + | metadata | {} | + +-----------------------------+--------------------------------------+ + +#. After some time, the share status should change from ``creating`` + to ``available``: + + .. code-block:: console + + $ manila list + +--------------------------------------+-------------+------+-------------+-----------+-----------+------------------------+-----------------------------+-------------------+ + | ID | Name | Size | Share Proto | Status | Is Public | Share Type Name | Host | Availability Zone | + +--------------------------------------+-------------+------+-------------+-----------+-----------+------------------------+-----------------------------+-------------------+ + | 5f8a0574-a95e-40ff-b898-09fd8d6a1fac | demo-share1 | 1 | NFS | available | False | default_share_type | storagenode@generic#GENERIC | nova | + +--------------------------------------+-------------+------+-------------+-----------+-----------+------------------------+-----------------------------+-------------------+ + +#. Determine export IP address of the share: + + .. code-block:: console + + $ manila show demo-share1 + +-----------------------------+------------------------------------------------------------------------------------+ + | Property | Value | + +-----------------------------+------------------------------------------------------------------------------------+ + | status | available | + | share_type_name | default_share_type | + | description | None | + | availability_zone | nova | + | share_network_id | 58b2f0e6-5509-4830-af9c-97f525a31b14 | + | export_locations | | + | | path = 10.254.0.6:/shares/share-0bfd69a1-27f0-4ef5-af17-7cd50bce6550 | + | | id = e525cbca-b3cc-4adf-a1cb-b1bf48fa2422 | + | | preferred = False | + | host | storagenode@generic#GENERIC | + | access_rules_status | active | + | snapshot_id | None | + | is_public | False | + | task_state | None | + | snapshot_support | True | + | id | 5f8a0574-a95e-40ff-b898-09fd8d6a1fac | + | size | 1 | + | name | demo-share1 | + | share_type | 8a35da28-0f74-490d-afff-23664ecd4f01 | + | has_replicas | False | + | replication_type | None | + | created_at | 2016-03-30T19:10:33.000000 | + | share_proto | NFS | + | consistency_group_id | None | + | source_cgsnapshot_member_id | None | + | project_id | 48e8c35b2ac6495d86d4be61658975e7 | + | metadata | {} | + +-----------------------------+------------------------------------------------------------------------------------+ + +Allow access to the share +------------------------- + +#. Configure access to the new share before attempting to mount it via + the network. The compute instance (whose IP address is referenced by the + INSTANCE_IP below) must have network connectivity to the network specified + in the share network. + + .. code-block:: console + + $ manila access-allow demo-share1 ip INSTANCE_IP + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | share_id | 5f8a0574-a95e-40ff-b898-09fd8d6a1fac | + | access_type | ip | + | access_to | 10.0.0.46 | + | access_level | rw | + | state | new | + | id | aefeab01-7197-44bf-ad0f-d6ca6f99fc96 | + +--------------+--------------------------------------+ + + +Mount the share on a compute instance +------------------------------------- + +#. Log into your compute instance and create a folder where the mount will + be placed: + + .. code-block:: console + + $ mkdir ~/test_folder + +#. Mount the NFS share in the compute instance using the export location of + the share: + + .. code-block:: console + + $ mount -vt nfs 10.254.0.6:/shares/share-0bfd69a1-27f0-4ef5-af17-7cd50bce6550 ~/test_folder diff --git a/install-guide/source/common/share-node-common-configuration.rst b/install-guide/source/common/share-node-common-configuration.rst index 1a6eeeed..f701e35d 100644 --- a/install-guide/source/common/share-node-common-configuration.rst +++ b/install-guide/source/common/share-node-common-configuration.rst @@ -27,6 +27,16 @@ default_share_type = default_share_type rootwrap_config = /etc/manila/rootwrap.conf + .. important:: + + The ``default_share_type`` option specifies the default share type to + be used when shares are created without specifying the share type in + the request. The default share type that is specified in the + configuration file has to be created with the necessary required + extra-specs (such as ``driver_handles_share_servers``) set + appropriately with reference to the driver mode used. This is + explained in further steps. + * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, configure Identity service access: diff --git a/install-guide/source/common/share-node-share-server-modes.rst b/install-guide/source/common/share-node-share-server-modes.rst index ed1a1d9b..436b212a 100644 --- a/install-guide/source/common/share-node-share-server-modes.rst +++ b/install-guide/source/common/share-node-share-server-modes.rst @@ -5,25 +5,31 @@ Option 1 -------- Deploying the service without driver support for share management. In this mode, the service does not do anything related to networking. The -operator must ensure network connectivity between instances and the NFS -server. This tutorial demonstrates setting up the LVM driver to support this -driver mode. It requires LVM and NFS packages as well as an additional disk -for the ``manila-share`` LVM volume group. This driver -mode may be referred to as ``driver_handles_share_servers = False`` mode, or -simply ``DHSS=False`` mode. +operator must ensure network connectivity between instances and the NAS +protocol based server. + +This tutorial demonstrates setting up the LVM driver which creates LVM volumes +on the share node and exports them with the help of an NFS server that is +installed locally on the share node. It therefore requires LVM and NFS packages +as well as an additional disk for the ``manila-share`` LVM volume group. + +This driver mode may be referred to as ``driver_handles_share_servers = False`` +mode, or simply ``DHSS=False`` mode. Option 2 -------- Deploying the service with driver support for share management. In this mode, the service runs with a back end driver that creates and manages -share servers. This tutorial demonstrates setting up the Generic driver. -This driver requires Compute (nova), Networking (neutron) and Block -storage (cinder) services for managing share servers. The information used for -creating share servers is configured with the help of share networks. This -option uses the generic driver with the handling of share servers capacity -and requires attaching the ``selfservice`` network to a router. This driver -mode may be referred to as ``driver_handles_share_servers = True`` mode, or -simply ``DHSS=True`` mode. +share servers. This tutorial demonstrates setting up the ``Generic`` driver. +This driver requires Compute service (nova), Image service (glance) and +Networking service (neutron) for creating and managing share servers; and +Block storage service (cinder) for creating shares. + +The information used for creating share servers is configured with the help of +share networks. + +This driver mode may be referred to as ``driver_handles_share_servers = True`` +mode, or simply ``DHSS=True`` mode. .. warning:: diff --git a/install-guide/source/get-started-with-shared-file-systems.rst b/install-guide/source/get-started-with-shared-file-systems.rst index b5b8e496..7b27b137 100644 --- a/install-guide/source/get-started-with-shared-file-systems.rst +++ b/install-guide/source/get-started-with-shared-file-systems.rst @@ -3,7 +3,7 @@ Shared File Systems service overview ==================================== The OpenStack Shared File Systems service (manila) provides file storage to a -virtual machine. The Shared File Systems service provides an infrastructure +virtual machine. The Shared File Systems service provides an abstraction for managing and provisioning of file shares. The service also enables management of share types as well as share snapshots if a driver supports them. @@ -11,26 +11,27 @@ them. The Shared File Systems service consists of the following components: manila-api - A WSGI app that authenticates and routes requests throughout the Shared File - Systems service. It supports the OpenStack APIs. + A WSGI app that authenticates and routes requests to the Shared File + Systems service. manila-data - A standalone service whose purpose is to receive requests, process data - operations such as copying, share migration or backup, and send back a - response after an operation has been completed. + A standalone service whose purpose is to process data operations such as + copying, share migration or backup. manila-scheduler Schedules and routes requests to the appropriate share service. The scheduler uses configurable filters and weighers to route requests. The - Filter Scheduler is the default and enables filters on things like Capacity, - Availability Zone, Share Types, and Capabilities as well as custom filters. + Filter Scheduler is the default and enables filters on various attributes + of back ends, such as, Capacity, Availability Zone and other capabilities. manila-share Manages back-end devices that provide shared file systems. A manila-share - process can run in one of two modes, with or without handling of share - servers. Share servers export file shares via share networks. When share - servers are not used, the networking requirements are handled outside of - Manila. + service talks to back-end devices by using share back-end drivers as + interfaces. A share driver may operate in one of two modes, with or + without handling of share servers. Share servers export file shares + via share networks. When share servers are not managed by a driver + within the shared file systems service, networking requirements should + be handled out of band of the shared file systems service. Messaging queue Routes information between the Shared File Systems processes. diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst index 8f828207..d00a5d20 100644 --- a/install-guide/source/index.rst +++ b/install-guide/source/index.rst @@ -27,20 +27,37 @@ on controllers, compute nodes, or storage nodes. .. important:: For simplicity, this guide describes configuring the Shared File Systems - service to use the ``generic`` back end with the driver handles - share server mode (DHSS) enabled that uses the `Compute service` - (`nova`), `Networking service` (`neutron`) and `Block storage service` - (`cinder`). + service to use one of either: - Networking service configuration requires the capability of networks being - attached to a public router in order to create share networks. + * the ``generic`` back end with the ``driver_handles_share_servers`` mode + (DHSS) enabled that uses the `Compute service` (`nova`), + `Image service` (`glance`), `Networking service` (`neutron`) and + `Block storage service` (`cinder`); or, + * the ``LVM`` back end with ``driver_handles_share_servers`` mode (DHSS) + disabled. - Before you proceed, ensure that Compute, Networking and Block storage - services are properly working. For networking service, ensure that option - 2 is properly configured. + The storage protocol used and referenced in this guide is ``NFS``. As + stated above, the Shared File System service supports different storage + protocols depending on the back end chosen. -For more information, see the `Configuration Reference + For the ``generic`` back end, networking service configuration requires + the capability of networks being attached to a public router in order to + create share networks. If using this back end, ensure that Compute, + Networking and Block storage services are properly working before you + proceed. For networking service, ensure that option 2 (deploying the + networking service with support for self-service networks) is properly + configured. + + This installation tutorial also assumes that installation and configuration + of OpenStack packages, Network Time Protocol, database engine and + message queue has been completed as per the instructions in the `OpenStack + Installation Tutorial. `_. The + `Identity Service` (`keystone`) has to be pre-configured with suggested + client environment scripts. + +For more information on various Shared File Systems storage back ends, +see the `Shared File Systems Configuration Reference. `_. -This chapter assumes a working setup of OpenStack following the `OpenStack -Installation Tutorial `_ +To learn more about installation dependencies noted above, see the `OpenStack +Installation Tutorial. `_ diff --git a/install-guide/source/install-share-node.rst b/install-guide/source/install-share-node.rst index 0be037fd..c613aeee 100644 --- a/install-guide/source/install-share-node.rst +++ b/install-guide/source/install-share-node.rst @@ -6,9 +6,15 @@ Install and configure a share node This section describes how to install and configure a share node for the Shared File Systems service. -.. Note:: +.. note:: + The manila-share process can run in two modes, with and without handling of - share servers. In general it depends of the driver support. + share servers. Some drivers may support either modes; while some may only + support one of the two modes. See the `Configuration Reference + `_ + to determine if the driver you choose supports the driver mode desired. + This tutorial describes setting up each driver mode using an example driver + for the mode. Note that installation and configuration vary by distribution. diff --git a/install-guide/source/post-install.rst b/install-guide/source/post-install.rst index 8a93f126..bfbb17ff 100644 --- a/install-guide/source/post-install.rst +++ b/install-guide/source/post-install.rst @@ -1,196 +1,22 @@ .. _post-install: -Creating shared file systems -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Creating and using shared file systems +====================================== -Before being able to create a share, manila with the generic driver and -the DHSS mode enabled requires the definition of at least an image, -a network and a share-network for being used to create a share server. -For that `back end` configuration, the share server is an instance where -NFS/CIFS shares are served. +Depending on the option chosen while installing the share node (Option with +share server management and one without); the steps to create and use your +shared file systems will vary. When the Shared File Systems service handles +the creation and management of share servers, you would need to specify the +``share network`` with the request to create a share. Either modes will vary +in their respective share type definition. When using the driver mode with +automatic handling of share servers, a service image is needed as specified +in your configuration. The instructions below enumerate the steps for both +driver modes. Follow what is appropriate for your installation. -.. note:: - - This configuration automatically creates a cinder volume for every share. - The cinder volumes are attached to share servers according to the - definition of a share network. - -Determine the configuration of the share server ------------------------------------------------ - -#. Source the admin credentials to gain access to admin-only CLI commands: - - .. code-block:: console - - $ . admin-openrc.sh - -#. Create a default share type before running manila-share service: - - .. code-block:: console - - $ manila type-create default_share_type True - +--------------------------------------+--------------------+------------+------------+-------------------------------------+-------------------------+ - | ID | Name | Visibility | is_default | required_extra_specs | optional_extra_specs | - +--------------------------------------+--------------------+------------+------------+-------------------------------------+-------------------------+ - | 8a35da28-0f74-490d-afff-23664ecd4f01 | default_share_type | public | - | driver_handles_share_servers : True | snapshot_support : True | - +--------------------------------------+--------------------+------------+------------+-------------------------------------+-------------------------+ - -#. Create a manila share server image to the Image service: - - .. code-block:: console - - $ glance image-create \ - --copy-from http://tarballs.openstack.org/manila-image-elements/images/manila-service-image-master.qcow2 \ - --name "manila-service-image" \ - --disk-format qcow2 \ - --container-format bare \ - --visibility public --progress - [=============================>] 100% - +------------------+--------------------------------------+ - | Property | Value | - +------------------+--------------------------------------+ - | checksum | 48a08e746cf0986e2bc32040a9183445 | - | container_format | bare | - | created_at | 2016-01-26T19:52:24Z | - | disk_format | qcow2 | - | id | 1fc7f29e-8fe6-44ef-9c3c-15217e83997c | - | min_disk | 0 | - | min_ram | 0 | - | name | manila-service-image | - | owner | e2c965830ecc4162a002bf16ddc91ab7 | - | protected | False | - | size | 306577408 | - | status | active | - | tags | [] | - | updated_at | 2016-01-26T19:52:28Z | - | virtual_size | None | - | visibility | public | - +------------------+--------------------------------------+ - -#. List available networks in order to get id and subnets of the private - network: - - .. code-block:: console - - $ neutron net-list - +--------------------------------------+---------+----------------------------------------------------+ - | id | name | subnets | - +--------------------------------------+---------+----------------------------------------------------+ - | 0e62efcd-8cee-46c7-b163-d8df05c3c5ad | public | 5cc70da8-4ee7-4565-be53-b9c011fca011 10.3.31.0/24 | - | 7c6f9b37-76b4-463e-98d8-27e5686ed083 | private | 3482f524-8bff-4871-80d4-5774c2730728 172.16.1.0/24 | - +--------------------------------------+---------+----------------------------------------------------+ - -#. Source the ``demo`` credentials to perform - the following steps as a non-administrative project: - - .. code-block:: console - - $ . demo-openrc.sh - - .. code-block:: console - - $ manila share-network-create --name demo-share-network1 \ - --neutron-net-id PRIVATE_NETWORK_ID \ - --neutron-subnet-id PRIVATE_NETWORK_SUBNET_ID - +-------------------+--------------------------------------+ - | Property | Value | - +-------------------+--------------------------------------+ - | name | demo-share-network1 | - | segmentation_id | None | - | created_at | 2016-01-26T20:03:41.877838 | - | neutron_subnet_id | 3482f524-8bff-4871-80d4-5774c2730728 | - | updated_at | None | - | network_type | None | - | neutron_net_id | 7c6f9b37-76b4-463e-98d8-27e5686ed083 | - | ip_version | None | - | nova_net_id | None | - | cidr | None | - | project_id | e2c965830ecc4162a002bf16ddc91ab7 | - | id | 58b2f0e6-5509-4830-af9c-97f525a31b14 | - | description | None | - +-------------------+--------------------------------------+ - -Create a share --------------- - -#. Create a NFS share using the share network: - - .. code-block:: console - - $ manila create NFS 1 --name demo-share1 --share-network demo-share-network1 - +-----------------------------+--------------------------------------+ - | Property | Value | - +-----------------------------+--------------------------------------+ - | status | None | - | share_type_name | None | - | description | None | - | availability_zone | None | - | share_network_id | None | - | export_locations | [] | - | host | None | - | snapshot_id | None | - | is_public | False | - | task_state | None | - | snapshot_support | True | - | id | 016ca18f-bdd5-48e1-88c0-782e4c1aa28c | - | size | 1 | - | name | demo-share1 | - | share_type | None | - | created_at | 2016-01-26T20:08:50.502877 | - | export_location | None | - | share_proto | NFS | - | consistency_group_id | None | - | source_cgsnapshot_member_id | None | - | project_id | 48e8c35b2ac6495d86d4be61658975e7 | - | metadata | {} | - +-----------------------------+--------------------------------------+ - -#. After some time, the share status should change from ``creating`` - to ``available``: - - .. code-block:: console - - $ manila list - +--------------------------------------+-------------+------+-------------+-----------+-----------+--------------------------------------+---------------------------------------------------------------+-----------------------------+-------------------+ - | ID | Name | Size | Share Proto | Status | Is Public | Share Type | Export location | Host | Availability Zone | - +--------------------------------------+-------------+------+-------------+-----------+-----------+--------------------------------------+---------------------------------------------------------------+-----------------------------+-------------------+ - | 5f8a0574-a95e-40ff-b898-09fd8d6a1fac | demo-share1 | 1 | NFS | available | False | 8a35da28-0f74-490d-afff-23664ecd4f01 | 10.254.0.6:/shares/share-0bfd69a1-27f0-4ef5-af17-7cd50bce6550 | storagenode@generic#GENERIC | nova | - +--------------------------------------+-------------+------+-------------+-----------+-----------+--------------------------------------+---------------------------------------------------------------+-----------------------------+-------------------+ - -#. Configure user access to the new share before attempting to mount it via - the network: - - .. important :: - - The image used for launching an instance and mounting a share must have - the NFS packages provided by the distro. Example: The cirros image - created at the image service section is not enough. - - .. important :: - - Use an instance that is connected to the private network used to create - the share-network. - - .. code-block:: console - - $ manila access-allow demo-share1 ip INSTANCE_PRIVATE_NETWORK_IP - -Mount the share from an instance --------------------------------- - -#. Create a folder where the mount will be placed: - - .. code-block:: console - - $ mkdir ~/test_folder - -#. Mount the NFS share in the instance using the export location of the share: - - .. code-block:: console - - $ mount -v 10.254.0.6:/shares/share-0bfd69a1-27f0-4ef5-af17-7cd50bce6550 ~/test_folder +.. include:: common/dhss-false-mode-using-shared-file-systems.rst +.. include:: common/dhss-true-mode-using-shared-file-systems.rst For more information about how to manage shares, see the -`OpenStack User Guide -`__. +`OpenStack End User Guide +`_