Include openstack manila driver related documentation

docs/manila/alletrab10k/installation-enabling.md

@@ -0,0 +1,119 @@
+# Installation & Enabling the Driver
+
+The ``HPEAlletraMPB10000ShareDriver`` is installed with the OpenStack Shared
+File Systems (Manila) software.
+
+## Enabling the Driver in Manila
+
+Make the following changes in the ``/etc/manila/manila.conf`` file.
+
+```
+[DEFAULT]
+# Comma-separated list of backend names to enable.
+enabled_share_backends = alletra1
+# Enable the NFS share protocol.
+enabled_share_protocols = NFS
+
+[alletra1]
+# Name of the backend reported to the scheduler.
+share_backend_name = hpealletra1
+
+# The HPE Alletra MP B10000 share driver.
+share_driver = manila.share.drivers.hpe.alletra_mp_b10000.hpe_alletra_driver.HPEAlletraMPB10000ShareDriver
+
+# This driver does not support share servers (share networks).
+driver_handles_share_servers = False
+
+# Alletra WSAPI V3 Server URL, for example https://<alletra ip>:8080/api/v3
+hpealletra_wsapi_url = https://<alletra ip>:8080/api/v3
+
+# Alletra username with the 'edit' role.
+hpealletra_username = <username>
+
+# Alletra password for the user specified in hpealletra_username.
+hpealletra_password = <password>
+
+# Enable HTTP debugging to Alletra.
+hpealletra_debug = False
+```
+
+Save the changes to the ``manila.conf`` file and restart the manila-share
+service.
+
+The HPE Alletra MP B10000 share driver is now enabled on your OpenStack
+system. If you experience problems, review the Shared File Systems service log
+files for errors.
+
+The following table contains all the configuration options supported by the
+HPE Alletra MP B10000 share driver.
+
+| Configuration option = Default value | Description |
+| ------------------------------------ | ----------- |
+| hpealletra_wsapi_url = <> | (String) Alletra WSAPI V3 Server URL like https://<alletra ip>:8080/api/v3 |
+| hpealletra_username = <> | (String) Alletra username with the 'edit' role |
+| hpealletra_password = <> | (String) Alletra password for the user specified in hpealletra_username |
+| hpealletra_debug = False | (Boolean) Enable HTTP debugging to Alletra |
+| share_driver = <> | (String) Full class path of the HPE Alletra MP B10000 share driver |
+| share_backend_name = <> | (String) Name of the backend reported to the Manila scheduler |
+| driver_handles_share_servers = False | (Boolean) Must be set to False; share networks are not supported |
+| enabled_share_protocols = NFS | (List) Share protocols to enable; only NFS is supported by this driver |
+
+
+
+## Pre-Configuration on the HPE Alletra MP B10000
+
+Before configuring the Manila driver, verify that the file service is running
+on the array:
+
+```
+$ showfileservice
+```
+
+If the file service is not enabled, run:
+
+```
+$ setfileservice enable
+```
+
+If ``setfileservice enable`` fails, the file ports may not be configured
+correctly. Check the port persona of slot 4, ports 1 & 2 using ``showport``.
+The ports must be configured as file persona ports before the file service
+can be enabled.
+
+If the ports are iSCSI, delete and reconfigure them as file ports:
+
+```
+$ controliscsiport delete 0:4:1
+$ controliscsiport delete 0:4:2
+$ controliscsiport delete 1:4:1
+$ controliscsiport delete 1:4:2
+```
+
+If the ports are NVMe, run the following commands instead:
+
+```
+$ controlport nvme delete 0:4:1
+$ controlport nvme delete 0:4:2
+$ controlport nvme delete 1:4:1
+$ controlport nvme delete 1:4:2
+```
+
+After converting the ports, reboot the cluster:
+
+```
+$ shutdownsys reboot
+```
+
+After the cluster comes up, assign IP addresses to all four ports
+(0:4:1, 0:4:2, 1:4:1, 1:4:2), then enable the file service and verify:
+
+```
+$ setfileservice enable
+$ showfileservice
+```
+
+Also verify the WSAPI V3 service is enabled and running:
+
+```
+$ showwsapi
+```

docs/manila/alletrab10k/overview.md

@@ -0,0 +1,13 @@
+# Overview
+
+The HPE Manila driver provides integration between OpenStack File Storage (Manila)
+and the following storage families:
+
+- HPE Alletra MP B10000
+
+Supported protocols:
+
+- NFS
+
+The driver communicates with the storage array using the HPE Web Services API (WSAPI). It is supported from the G release (2026.1) of Openstack Manila.
+

docs/manila/alletrab10k/restrictions-limitations.md

@@ -0,0 +1,15 @@
+# Restrictions & Limitations
+
+The HPE Alletra MP B10000 share driver has the following restrictions:
+
+- Only the NFS protocol is supported; CIFS/SMB is not supported.
+- Share networks are not supported (``driver_handles_share_servers`` must be
+  ``False``).
+- Share shrink is not currently supported.
+- Snapshots are not supported.
+- Creating a share from a snapshot is not supported.
+- Share migration is not supported.
+- Share replication is not supported.
+- Share groups and consistency groups are not supported.
+- Security services (LDAP, Active Directory, Kerberos) are not supported.
+- Only IP-based access rules are supported for NFS shares.

docs/manila/alletrab10k/share-types.md

@@ -0,0 +1,77 @@
+# Share Types & Extra Specs
+
+Share type support for the HPE Alletra MP B10000 driver includes the ability to set the following capabilities in the OpenStack Shared File Systems API share type extra specs:
+
+- hpe_alletra_b10000:reduce
+- hpe_alletra_b10000:squash_option
+- compression
+- dedupe
+- thin_provisioning
+
+To work with the default filter scheduler, the key values are case sensitive and scoped with __hpe_alletra_b10000:__
+
+Manila requires that the share type includes the ``driver_handles_share_servers`` extra spec set to ``False``. To create a share type for the HPE Alletra MP B10000 backend:
+
+```
+$ openstack share type create alletra_nfs False
+$ openstack share type set alletra_nfs --extra-specs share_backend_name=hpealletra1
+```
+
+If share types are not used or a particular key is not set for a share type, the following defaults are used:
+
+- hpe_alletra_b10000:reduce - Defaults to ``true``.
+- hpe_alletra_b10000:squash_option - Defaults to ``root_squash``.
+- thin_provisioning - Defaults to ``true``.
+- compression/dedupe - Default to ``true``. (Same as reduce)
+
+Note
+
+Modifying share type extra specs after shares have been created is not
+recommended, as it will cause inconsistency between the share type definition
+and the actual backend share properties. Backend share characteristics like
+reduce, compression, and dedupe cannot be changed after creation.
+
+- hpe_alletra_b10000:reduce
+
+  Controls the ``compression`` and ``dedupe`` capabilities of the share. The valid values are ``true`` and ``false``.
+
+  - If reduce = true: compression = true, dedupe = true
+  - If reduce = false: compression = false, dedupe = false
+
+  The reduce setting is applied at share creation time and cannot be changed for existing shares. Alternatively, you can use the ``compression`` and ``dedupe`` keys directly instead of ``reduce``, but you cannot specify both in the same share type.
+
+  ```
+  $ openstack share type set alletra_nfs --extra-specs hpe_alletra_b10000:reduce=true
+  ```
+
+- hpe_alletra_b10000:squash_option
+
+  The NFS squash option applied to all access rules on the backend. The valid values are ``root_squash``, ``all_squash``, and ``no_root_squash``. If the share type is modified to change the squash option, the next share access rule update will use the new value.
+
+  ```
+  $ openstack share type set alletra_nfs --extra-specs hpe_alletra_b10000:squash_option=root_squash
+  ```
+
+- compression
+
+  Controls whether compression is enabled on the share. The valid values are ``true`` and ``false``. When specifying ``compression``, you must also specify ``dedupe`` with the same value. You cannot use ``compression`` together with ``hpe_alletra_b10000:reduce``.
+
+  ```
+  $ openstack share type set alletra_nfs --extra-specs compression=true dedupe=true
+  ```
+
+- dedupe
+
+  Controls whether data deduplication is enabled on the share. The valid values are ``true`` and ``false``. When specifying ``dedupe``, you must also specify ``compression`` with the same value. You cannot use ``dedupe`` together with ``hpe_alletra_b10000:reduce``.
+
+  ```
+  $ openstack share type set alletra_nfs --extra-specs dedupe=true compression=true
+  ```
+
+- thin_provisioning
+
+  Controls whether thin provisioning is enabled on the share. This extra spec must be set to ``true`` or not specified at all. Setting it to ``false`` is not supported by this driver.
+
+  ```
+  $ openstack share type set alletra_nfs --extra-specs thin_provisioning=true
+  ```

docs/manila/alletrab10k/supported-features-details.md

@@ -0,0 +1,74 @@
+# Details on Supported Features
+
+## Managing Share Access
+
+A share must have access rules configured before it can be accessed by
+clients. IP-based access rules are required for NFS shares.
+
+Note
+
+When no Manila access rules are configured, the driver blocks all IP addresses
+by setting a default access rule of 0.0.0.0 with read-only and root_squash
+permissions on the backend Alletra B10000 array. You must explicitly create
+access rules to allow client access.
+
+
+## Extending Shares
+
+The driver supports extending shares to increase their size.
+
+Note
+
+The share size shown in Manila includes filesystem metadata and other
+overhead. Client-usable space will be less than the displayed share size.
+
+## Managing Existing Shares
+
+The driver supports bringing existing shares on the HPE Alletra array into
+Manila management using the manage operation.
+
+### Prerequisites for the Manage Operation
+
+Before managing an existing share, ensure the following requirements are met:
+
+__Share type compatibility__: The backend share ``reduce`` value must match
+   the ``hpe_alletra_b10000:reduce`` value from the share type. If they don't
+   match, the manage operation will fail. Associate the correct share type.
+   The default reduce value (if the share type doesn't have this key) is
+   ``true``. Similarly, if the share type uses ``compression`` and ``dedupe``
+   parameters instead of ``reduce``, those values must also match the backend
+   share's compression and deduplication settings.
+
+__No existing access rules__: The backend share must have either an empty
+   access rules list or only the default 0.0.0.0 access rule with read-only
+   and root_squash. If other access rules exist, clear them from the backend
+   share before managing:
+
+   ```
+   $ setsharesetting -remove <ipaddr_list> <sharesetting_name>
+   ```
+
+__Filesystem size alignment__: The filesystem size of the backend fileshare
+   must be a multiple of 1024 MiB (1 GiB). If not, the manage operation will
+   fail. Manila logs will indicate how much MiB to expand the backend
+   filesystem.
+
+   To expand size by a specific amount on the alletra array cli (e.g., 500 MiB):
+
+   ```
+   $ setfilesystem -size 500 <filesystem_name>
+   ```
+
+## Ensure Shares Operation
+
+The driver supports the ``ensure_shares`` operation, which validates that
+shares exist on the backend and updates their status in Manila. Shares found
+on the backend are updated with the latest export locations. Shares not found
+on the backend are marked with the ``error`` state.
+
+The ensure_shares operation for the driver is executed only in case of service
+restarts after configuration changes in ``/etc/manila/manila.conf``.
+
+If the backend fileshare export path changes due to a file port IP change or
+other reasons, the administrator must manually trigger the ensure shares
+command in OpenStack to update the latest export paths.

docs/manila/alletrab10k/supported-operations.md

@@ -0,0 +1,7 @@
+# Supported Operations
+
+- Create and delete NFS shares
+- Allow and deny NFS share access (IP-based access rules)
+- Extend shares
+- Manage and unmanage existing shares
+- Ensure shares

docs/manila/alletrab10k/system-requirements.md

@@ -0,0 +1,15 @@
+# System Requirements
+
+__Software Requirements__
+
+- HPE Alletra MP B10000 OS v10.5 or later.
+
+__Network Requirements__
+
+- NFS: Network connectivity between the clients and the array's file ports.
+- WSAPI (V3) server must be enabled.
+
+__Storage Requirements__
+
+- The HPE Alletra MP B10000 file service must be enabled.
+- A user account with the ``edit`` role for WSAPI access.

docs/manila/alletrab10k/troubleshooting.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+## Common Issues
+
+__Share creation fails__
+
+  - Verify the HPE Alletra MP B10000 file service is enabled.
+  - Check connectivity to the WSAPI endpoint (``hpealletra_wsapi_url``).
+  - Ensure the configured user has sufficient permissions (``edit`` role).
+
+__Access rules not working__
+
+  - Verify network connectivity between the client and the array's file ports.
+  - Check that the IP address in the access rule is correct.
+  - Ensure the share type's ``squash_option`` is appropriate for your use case.
+
+__Manage operation fails__
+
+  - Clear all access rules from the backend share.
+  - Verify the filesystem size is a multiple of 1 GiB.
+  - Ensure the share type's ``reduce`` value matches the backend share.
+
+Note
+
+Set ``hpealletra_debug = True`` in the backend section of
+``/etc/manila/manila.conf`` to enable HTTP debugging to the Alletra array when
+diagnosing connectivity or API issues.

mkdocs.yml

@@ -36,3 +36,13 @@ nav:
           - Multipathing: nimble-alletra6k/multipathing.md
           - Consistency Group Replication: nimble-alletra6k/consistency-group-replication.md
       - Best Practices Guide: best-practices-guide.md
+  - Manila Driver:
+      - Alletra MP B10000:
+          - Overview: manila/alletrab10k/overview.md
+          - System Requirements: manila/alletrab10k/system-requirements.md
+          - Supported Operations: manila/alletrab10k/supported-operations.md
+          - Share Types & Extra Specs: manila/alletrab10k/share-types.md
+          - Installation & Enabling: manila/alletrab10k/installation-enabling.md
+          - Details on Supported Features: manila/alletrab10k/supported-features-details.md
+          - Restrictions & Limitations: manila/alletrab10k/restrictions-limitations.md
+          - Troubleshooting: manila/alletrab10k/troubleshooting.md