diff --git a/doc/source/admin/shared-file-systems-share-networks.rst b/doc/source/admin/shared-file-systems-share-networks.rst index ddbdd33bb4..58b9be42db 100644 --- a/doc/source/admin/shared-file-systems-share-networks.rst +++ b/doc/source/admin/shared-file-systems-share-networks.rst @@ -4,10 +4,23 @@ Share networks ============== -Share network is an entity that encapsulates interaction with the OpenStack -Networking service. If the share driver that you selected runs in a mode -requiring Networking service interaction, specify the share network when -creating a new share network. +Share networks are essential to allow end users a path to hard multi-tenancy. +When backed by isolated networks, the Shared File Systems service can +guarantee hard network path isolation for the users' shares. Users can be +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -28,8 +41,9 @@ To list networks in a project, run: A share network stores network information that share servers can use where shares are hosted. You can associate a share with a single share network. -When you create or update a share, you can optionally specify the ID of a share -network through which instances can access the share. +You must always specify a share network when creating a share with a 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 :ref:`shared_file_systems_network_plugins`. @@ -51,7 +65,8 @@ To create a share network with private network and subnetwork, run: .. code-block:: console $ 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 | +-------------------+--------------------------------------+ @@ -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 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: .. 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. 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. diff --git a/doc/source/admin/shared-file-systems-share-replication.rst b/doc/source/admin/shared-file-systems-share-replication.rst index 1376fcfc23..907b18a7b4 100644 --- a/doc/source/admin/shared-file-systems-share-replication.rst +++ b/doc/source/admin/shared-file-systems-share-replication.rst @@ -125,6 +125,9 @@ type of replication. In the example, we assume a configuration of two Availability Zones [1]_, 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. However, the use of an availability zone as a ``failure domain`` is encouraged. @@ -212,6 +215,11 @@ protocol, size and the availability zone. | 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. 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 replica. Specify the share ID or name as a parameter. You may -optionally provide the `availability_zone` and `share_network_id`. In the -example below, `share_network_id` is not used since the ZFSonLinux driver -does not support it. +optionally provide the `availability_zone`. .. code-block:: console @@ -297,6 +303,13 @@ does not support it. 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 of the newly created share replica. Specify the share replica's ID as a parameter. diff --git a/doc/source/admin/shared-file-systems-share-server-management.rst b/doc/source/admin/shared-file-systems-share-server-management.rst index 291b6583ec..43bb600b0d 100644 --- a/doc/source/admin/shared-file-systems-share-server-management.rst +++ b/doc/source/admin/shared-file-systems-share-server-management.rst @@ -39,6 +39,7 @@ To bring a share server under the Shared File System service, use the manila share-server-manage [--driver_options [ [ ...]]] + [--share_network_subnet ]] 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 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: - There are some ports created, which correspond to the share server