openstack/manila
Code Issues Proposed changes

Merge "Update admin guide for share network subnets change"

Browse Source
This commit is contained in:
Zuul 2020-06-04 17:08:57 +00:00 committed by Gerrit Code Review
commit bbea70d044
3 changed files with 177 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
doc/source/admin/shared-file-systems-share-networks.rst
View File

@ -4,10 +4,23 @@
Share networks Share networks
============== ==============
Share network is an entity that encapsulates interaction with the OpenStack Share networks are essential to allow end users a path to hard multi-tenancy.
Networking service. If the share driver that you selected runs in a mode When backed by isolated networks, the Shared File Systems service can
requiring Networking service interaction, specify the share network when guarantee hard network path isolation for the users' shares. Users can be
creating a new share network. allowed to designate their project networks as share networks. When a share
network is provided during share creation, the share driver sets up a virtual
share server (NAS server) on the share network and exports shares using this
NAS server. The share server itself is abstracted away from the user. You must
ensure that the storage system can connect the share servers it provisions to
the networks users can use as their share networks.
.. note::
Not all shared file systems storage backends support share networks.
Share networks can only be used when using a share type that has the
specification ``driver_handles_share_servers=True``. To see what storage
back ends support this specification, refer to the
:doc:`share_back_ends_feature_support_mapping`.
How to create share network How to create share network
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -28,8 +41,9 @@ To list networks in a project, run:
A share network stores network information that share servers can use where 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. 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 You must always specify a share network when creating a share with a share
network through which instances can access the share. type that requests hard multi-tenancy, i.e., has extra-spec
'driver_handles_share_servers=True'.
For more information about supported plug-ins for share networks, see For more information about supported plug-ins for share networks, see
:ref:`shared_file_systems_network_plugins`. :ref:`shared_file_systems_network_plugins`.
@ -51,7 +65,8 @@ To create a share network with private network and subnetwork, run:
.. code-block:: console .. code-block:: console
$ manila share-network-create --neutron-net-id 5ed5a854-21dc-4ed3-870a-117b7064eb21 \ $ 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" --neutron-subnet-id 74dcfb5a-b4d7-4855-86f5-a669729428dc --name my_share_net \
--description "My first share network" --availability-zone manila-zone-0
+-------------------+--------------------------------------+ +-------------------+--------------------------------------+
| Property | Value | | Property | Value |
+-------------------+--------------------------------------+ +-------------------+--------------------------------------+
@ -73,6 +88,18 @@ The ``segmentation_id``, ``cidr``, ``ip_version``, and ``network_type``
share network attributes are automatically set to the values determined by the share network attributes are automatically set to the values determined by the
network provider. network provider.
.. note::
You are able to specify the parameter ``availability_zone`` only with API
versions >= 2.51. From the version 2.51, a share network is able to span
multiple subnets in different availability zones. The network parameters
``neutron_net_id``, ``neutron_subnet_id``, ``segmentation_id``, ``cidr``,
``ip_version``, ``network_type``, ``gateway`` and ``mtu`` were moved to the
share network subnet and no longer pertain to the share network. If you do
not specify an availability zone during the share network creation, the
created subnet will be considered default by the Shared File Systems
Service. A default subnet is expected to be reachable from all availability
zones in the cloud.
To check the network list, run: To check the network list, run:
.. code-block:: console .. code-block:: console
@ -138,3 +165,119 @@ You also can see detailed information about the share network including
You also can add and remove the security services from the share network. You also can add and remove the security services from the share network.
For more detail, see :ref:`shared_file_systems_security_services`. For more detail, see :ref:`shared_file_systems_security_services`.
==============================================
Share network subnets (Since API version 2.51)
==============================================
Share network subnet is an entity that stores network data from the OpenStack
Networking service. A share network can span multiple share network subnets in
different availability zones.
How to create share network subnet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you create a share network, a primary share network subnet is
automatically created. The share network subnet stores network information
that share servers can use where shares are hosted. If a share network subnet
is not assigned to a specific availability zone, it is considered to be
available across all availability zones. Such a subnet is referred to as
``default`` subnet. A share network can have only one default subnet. However,
having a default subnet is not necessary. A share can be associated with only
one share network. To list share networks in a project, run:
.. code-block:: console
$ manila share-network-list
+--------------------------------------+-----------------------+
| id | name |
+--------------------------------------+-----------------------+
| 483a9787-5116-48b2-bd89-473022fad060 | sharenetwork1 |
| bcb9c650-a501-410d-a418-97f28b8ab61a | sharenetwork2 |
+--------------------------------------+-----------------------+
You can attach any number of share network subnets into a share network.
However, only one share network subnet is allowed per availability zone in a
given share network. If you try to create another subnet in a share network that
already contains a subnet in a specific availability zone, the operation will
be denied.
To create a share network subnet in a specific share network, run:
.. code-block:: console
$ manila share-network-subnet-create sharenetwork1 \
--availability-zone manila-zone-0 \
--neutron-net-id 5ed5a854-21dc-4ed3-870a-117b7064eb21 \
--neutron-subnet-id 74dcfb5a-b4d7-4855-86f5-a669729428dc
+--------------------+--------------------------------------+
| Property | Value |
+--------------------+--------------------------------------+
| id | 20f3cd2c-0faa-4b4b-a00a-4f188eb1cf38 |
| availability_zone | manila-zone-0 |
| share_network_id | 483a9787-5116-48b2-bd89-473022fad060 |
| share_network_name | sharenetwork1 |
| created_at | 2019-12-03T00:37:30.000000 |
| segmentation_id | None |
| neutron_subnet_id | 74dcfb5a-b4d7-4855-86f5-a669729428dc |
| updated_at | None |
| neutron_net_id | 5ed5a854-21dc-4ed3-870a-117b7064eb21 |
| ip_version | None |
| cidr | None |
| network_type | None |
| mtu | None |
| gateway | None |
+--------------------+--------------------------------------+
To list all the share network subnets of a given share network, you need to
show the share network, and then all subnets will be displayed, as shown below:
.. code-block:: console
$ manila share-network-show sharenetwork1
+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Property | Value |
+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| id | 483a9787-5116-48b2-bd89-473022fad060 |
| name | sharenetwork1 |
| project_id | 58ff89e14f9245d7843b8cf290525b5b |
| created_at | 2019-12-03T00:16:39.000000 |
| updated_at | 2019-12-03T00:31:58.000000 |
| description | None |
| share_network_subnets | [{'id': '20f3cd2c-0faa-4b4b-a00a-4f188eb1cf38', 'availability_zone': 'manila-zone-0', 'created_at': '2019-12-03T00:37:30.000000', 'updated_at': None, 'segmentation_id': None, 'neutron_net_id': '5ed5a854-21dc-4ed3-870a-117b7064eb21', 'neutron_subnet_id': '74dcfb5a-b4d7-4855-86f5-a669729428dc', 'ip_version': None, 'cidr': None, 'network_type': None, 'mtu': None, 'gateway': None}, {'id': '8b532c15-3ac7-4ea1-b1bc-732614a82313', 'availability_zone': None, 'created_at': '2019-12-03T00:16:39.000000', 'updated_at': None, 'segmentation_id': None, 'neutron_net_id': None, 'neutron_subnet_id': None, 'ip_version': None, 'cidr': None, 'network_type': None, 'mtu': None, 'gateway': None}] |
+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
To show a specific share network subnet, run:
.. code-block:: console
$ manila share-network-subnet-show sharenetwork1 20f3cd2c-0faa-4b4b-a00a-4f188eb1cf38
+--------------------+--------------------------------------+
| Property | Value |
+--------------------+--------------------------------------+
| id | 20f3cd2c-0faa-4b4b-a00a-4f188eb1cf38 |
| availability_zone | manila-zone-0 |
| share_network_id | 483a9787-5116-48b2-bd89-473022fad060 |
| share_network_name | sharenetwork1 |
| created_at | 2019-12-03T00:37:30.000000 |
| segmentation_id | None |
| neutron_subnet_id | 74dcfb5a-b4d7-4855-86f5-a669729428dc |
| updated_at | None |
| neutron_net_id | 5ed5a854-21dc-4ed3-870a-117b7064eb21 |
| ip_version | None |
| cidr | None |
| network_type | None |
| mtu | None |
| gateway | None |
+--------------------+--------------------------------------+
To delete a share network subnet, run:
.. code-block:: console
$ manila share-network-subnet-delete sharenetwork1 20f3cd2c-0faa-4b4b-a00a-4f188eb1cf38
If you want to remove a share network subnet, make sure that no other
resource is using the subnet, otherwise the Shared File Systems
Service will deny the operation.

19
doc/source/admin/shared-file-systems-share-replication.rst
View File

@ -125,6 +125,9 @@ type of replication. In the example, we assume a configuration of two
Availability Zones [1]_, Availability Zones [1]_,
called `availability_zone_1` and `availability_zone_2`. called `availability_zone_1` and `availability_zone_2`.
Since the Train release, some drivers operating in
``driver_handles_share_server=True`` mode support share replication.
Multiple availability zones are not necessary to use the replication feature. Multiple availability zones are not necessary to use the replication feature.
However, the use of an availability zone as a ``failure domain`` is encouraged. However, the use of an availability zone as a ``failure domain`` is encouraged.
@ -212,6 +215,11 @@ protocol, size and the availability zone.
| metadata | {} | | metadata | {} |
+-----------------------------+--------------------------------------+ +-----------------------------+--------------------------------------+
.. note::
If you are creating a share with the share type specification
``driver_handles_share_servers=True``, the share network parameter is
required for the operation to be performed.
Use the :command:`manila show` command to retrieve details of the share. Use the :command:`manila show` command to retrieve details of the share.
Specify the share ID or name as a parameter. Specify the share ID or name as a parameter.
@ -273,9 +281,7 @@ Create a share replica
Use the :command:`manila share-replica-create` command to create a share Use the :command:`manila share-replica-create` command to create a share
replica. Specify the share ID or name as a parameter. You may replica. Specify the share ID or name as a parameter. You may
optionally provide the `availability_zone` and `share_network_id`. In the optionally provide the `availability_zone`.
example below, `share_network_id` is not used since the ZFSonLinux driver
does not support it.
.. code-block:: console .. code-block:: console
@ -297,6 +303,13 @@ does not support it.
See details of the newly created share replica See details of the newly created share replica
.. note::
Since API version 2.51 (Train release), a share network is able to span
multiple subnets in different availability zones. So, when using a share
type with specification ``driver_handles_share_servers=True``, users must
ensure that the share network has a subnet in the availability zone that
they desire the share replica to be created in.
Use the :command:`manila share-replica-show` command to see details Use the :command:`manila share-replica-show` command to see details
of the newly created share replica. Specify the share replica's ID as a of the newly created share replica. Specify the share replica's ID as a
parameter. parameter.

11
doc/source/admin/shared-file-systems-share-server-management.rst
View File

@ -39,6 +39,7 @@ To bring a share server under the Shared File System service, use the
manila share-server-manage manila share-server-manage
[--driver_options [<key=value> [<key=value> ...]]] [--driver_options [<key=value> [<key=value> ...]]]
[--share_network_subnet <share-network-subnet>]]
<host> <share_network> <identifier> <host> <share_network> <identifier>
The positional arguments are: The positional arguments are:
@ -56,6 +57,16 @@ vary from driver to driver. Consult the driver-specific documentation to
determine if any specific parameters must be supplied. Ensure that the share determine if any specific parameters must be supplied. Ensure that the share
type has the ``driver_handles_share_servers = True`` extra-spec. type has the ``driver_handles_share_servers = True`` extra-spec.
The ``share_network_subnet`` is an optional parameter which was introduced in
Train release. Due to a change in the share networks structure, a share
network no longer contains the following attributes: ``neutron_net_id``,
``neutron_subnet_id``, ``gateway``, ``mtu``, ``network_type``, ``ip_version``,
``segmentation_id``. These attributes now pertain to the share network subnet
entity, and a share network can span multiple share network subnets in
different availability zones. If you do not specify a share network subnet,
the Shared File Systems Service will choose the default one (which does not
pertain to any availability zone).
If using an OpenStack Networking (Neutron) based plugin, ensure that: If using an OpenStack Networking (Neutron) based plugin, ensure that:
- There are some ports created, which correspond to the share server - There are some ports created, which correspond to the share server