From 215a2bba2adfda4284979d7a428e7177c357aac0 Mon Sep 17 00:00:00 2001 From: Srinesh A R Date: Tue, 21 Jul 2026 16:28:20 +0530 Subject: [PATCH] Include openstack manila driver related documentation --- .../alletrab10k/installation-enabling.md | 119 ++++++++++++++++++ docs/manila/alletrab10k/overview.md | 13 ++ .../alletrab10k/restrictions-limitations.md | 15 +++ docs/manila/alletrab10k/share-types.md | 77 ++++++++++++ .../alletrab10k/supported-features-details.md | 74 +++++++++++ .../alletrab10k/supported-operations.md | 7 ++ .../manila/alletrab10k/system-requirements.md | 15 +++ docs/manila/alletrab10k/troubleshooting.md | 27 ++++ mkdocs.yml | 10 ++ 9 files changed, 357 insertions(+) create mode 100644 docs/manila/alletrab10k/installation-enabling.md create mode 100644 docs/manila/alletrab10k/overview.md create mode 100644 docs/manila/alletrab10k/restrictions-limitations.md create mode 100644 docs/manila/alletrab10k/share-types.md create mode 100644 docs/manila/alletrab10k/supported-features-details.md create mode 100644 docs/manila/alletrab10k/supported-operations.md create mode 100644 docs/manila/alletrab10k/system-requirements.md create mode 100644 docs/manila/alletrab10k/troubleshooting.md diff --git a/docs/manila/alletrab10k/installation-enabling.md b/docs/manila/alletrab10k/installation-enabling.md new file mode 100644 index 0000000..87370b4 --- /dev/null +++ b/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://:8080/api/v3 +hpealletra_wsapi_url = https://:8080/api/v3 + +# Alletra username with the 'edit' role. +hpealletra_username = + +# Alletra password for the user specified in hpealletra_username. +hpealletra_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://: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 +``` diff --git a/docs/manila/alletrab10k/overview.md b/docs/manila/alletrab10k/overview.md new file mode 100644 index 0000000..c26faae --- /dev/null +++ b/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. + diff --git a/docs/manila/alletrab10k/restrictions-limitations.md b/docs/manila/alletrab10k/restrictions-limitations.md new file mode 100644 index 0000000..7d4f31e --- /dev/null +++ b/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. diff --git a/docs/manila/alletrab10k/share-types.md b/docs/manila/alletrab10k/share-types.md new file mode 100644 index 0000000..fddc80b --- /dev/null +++ b/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 + ``` diff --git a/docs/manila/alletrab10k/supported-features-details.md b/docs/manila/alletrab10k/supported-features-details.md new file mode 100644 index 0000000..b219ce7 --- /dev/null +++ b/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 + ``` + +__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 + ``` + +## 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. diff --git a/docs/manila/alletrab10k/supported-operations.md b/docs/manila/alletrab10k/supported-operations.md new file mode 100644 index 0000000..7d596f5 --- /dev/null +++ b/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 diff --git a/docs/manila/alletrab10k/system-requirements.md b/docs/manila/alletrab10k/system-requirements.md new file mode 100644 index 0000000..e06046a --- /dev/null +++ b/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. diff --git a/docs/manila/alletrab10k/troubleshooting.md b/docs/manila/alletrab10k/troubleshooting.md new file mode 100644 index 0000000..f29ed13 --- /dev/null +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 379dad2..4f9016c 100644 --- a/mkdocs.yml +++ b/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