Manage shares¶

Overview¶

With the Manila share attachment feature, users can easily attach file shares provided by Manila to their instances, and mount them within the instance. This feature eliminates the need for users to manually connect to and mount shares provided by Manila within their instances.

Use Cases¶

The Manila share attachment feature can be used in the following scenarios:

As an operator I want the Manila datapath to be separate to any tenant accessible networks.
As a user I want to attach Manila shares directly to my instance and have a simple interface with which to mount them within the instance.

As a user I want to detach a directly attached Manila share from my instance.
As a user I want to track the Manila shares attached to my instance.

Prerequisites¶

To use the Manila share attachment feature, you must have an OpenStack environment with Manila and Nova installed and configured. Additionally, your environment must meet the following requirements:

The compute host running your instance must have QEMU version 5.0 or higher and libvirt version 6.2 or higher. If these requirements are met, the COMPUTE_STORAGE_VIRTIO_FS trait should be enabled on your compute host.
All compute nodes must be upgraded to a nova version that enables the use of virtiofs.
Additionally this initial implementation will require that the associated instances use file backed memory or huge pages. This is a requirement of virtio-fs.
Kernel drivers and user land tools to support mounting NFS and CEPHFS shares.
A kernel version of >= 5.4 within the instance guest OS to support mounting virtiofs shares.

Configure instance shared memory¶

This can be achieved by either configuring the instance with hw:mem_page_size extra spec.

or, you can enable the COMPUTE_MEM_BACKING_FILE trait by configuring the file_backed_memory feature in libvirt for nova-compute. This will allow the use of file-backed memory.

COMPUTE_MEM_BACKING_FILE support requires that operators configure one or more hosts with file backed memory. Ensuring the instance will land on one of these hosts can be achieved by creating an AZ englobing these hosts. And then instruct users to deploy their instances in this AZ. Alternatively, operators can guide the scheduler to choose a suitable host by adding trait:COMPUTE_MEM_BACKING_FILE=required as an extra spec or image property.

Limitations¶

You must have an instance in the SHUTOFF state to attach or detach a share.
Due to current virtiofs implementation in Qemu / libvirt, the following Nova features are blocked for VMs with shares attached:
- evacuate
- live_migrate
- rebuild
- resize(migrate)
- resume
- shelve
- volume snapshot

Known bugs¶

Due to a bug, the configuration drive is not refreshed at the appropriate time, causing the shares to remain invisible on the configuration drive. You can use the metadata service instead.
The share backup process removes share access and locks because it requires exclusive access for backup consistency. This operation disrupts the share attachment, making it inaccessible for the VM.

To use this feature correctly, follow these steps:
1. Stop the VM.
2. Detach the share from the VM (Nova removes the lock).
3. Perform the backup using the Manila API.
4. Reattach the share (Nova reapplies the lock).
5. Start the VM.
Nova does not send the user’s token alongside Nova’s service token, Manila will only recognize Nova as the requester during access creation. Consequently, the audit trail log will lack information indicating that Nova is acting on behalf of a user request. This is a significant limitation of the current implementation.
The share is not marked as an error if the VM fails to delete.

Managing shares¶

Attaching a Share¶

To attach a Manila share to an instance, use the POST /servers/{server_id}/shares API, and specify the share_id of the share you want to attach. The tag parameter is optional and can be used to provide a string used to mount the share within the instance. If you do not provide a tag, the share_id will be used instead.

After issuing the attach request, the share’s attachment state is recorded in the database and should quickly transition to attaching and then to inactive. The user should verify that the status reaches inactive before proceeding with any new operations; this transition should occur unless an error arises.

$ openstack server add share 9736bced-44f6-48fc-b913-f34c3ed95067 3d3aafde-b4cb-45ab-8ac6-31ff93f69536 --tag mytag
+-----------------+--------------------------------------------------------------------------------------+
| Field           | Value                                                                                |
+-----------------+--------------------------------------------------------------------------------------+
| Export Location | 192.168.122.76:/opt/stack/data/manila/mnt/share-25a777f7-a582-465c-a94c-7293707cc5cb |
| Share ID        | 3d3aafde-b4cb-45ab-8ac6-31ff93f69536                                                 |
| Status          | inactive                                                                             |
| Tag             | mytag                                                                                |
| UUID            | b70403ee-f598-4552-b9e9-173343deff79                                                 |
+-----------------+--------------------------------------------------------------------------------------+

Then, when you power on the instance, the required operations will be done to attach the share, and set it as active if there are no errors. If the attach operation fails, the VM start operation will also fail.

$ openstack server share show  9736bced-44f6-48fc-b913-f34c3ed95067 3d3aafde-b4cb-45ab-8ac6-31ff93f69536
+-----------------+--------------------------------------------------------------------------------------+
| Field           | Value                                                                                |
+-----------------+--------------------------------------------------------------------------------------+
| Export Location | 192.168.122.76:/opt/stack/data/manila/mnt/share-25a777f7-a582-465c-a94c-7293707cc5cb |
| Share ID        | 3d3aafde-b4cb-45ab-8ac6-31ff93f69536                                                 |
| Status          | active                                                                               |
| Tag             | mytag                                                                                |
| UUID            | b70403ee-f598-4552-b9e9-173343deff79                                                 |
+-----------------+--------------------------------------------------------------------------------------+

After connecting to the VM, you can retrieve the tags of the attached share by querying the OpenStack metadata service.

Note: Here, we can see 2 shares attached to the instance with a defined tag (mytag) and another one with the default tag.

Note2: Using this mechanism, shares can be easily mounted automatically when the machine starts up.

$ curl -s -H "Metadata-Flavor: OpenStack" http://169.254.169.254/openstack/latest/meta_data.json | jq .devices
[
  {
    "type": "share",
    "share_id": "3d3aafde-b4cb-45ab-8ac6-31ff93f69536",
    "tag": "mytag",
    "bus": "none",
    "address": "none"
  },
  {
    "type": "share",
    "share_id": "894a530c-6fa0-4aa1-97c9-4489d205c5ed",
    "tag": "894a530c-6fa0-4aa1-97c9-4489d205c5ed",
    "bus": "none",
    "address": "none"
  }
]

To mount the attached share, use the mount command with the virtiofs file system type, and the tag provided in the response body.

user@instance $ mount -t virtiofs $tag /mnt/mount/path

Listing Attached Shares¶

To list all shares attached to an instance, use the GET /servers/{server_id}/shares API.

$ openstack server share list 9736bced-44f6-48fc-b913-f34c3ed95067
+--------------------------------------+----------+--------------------------------------+
| Share ID                             | Status   | Tag                                  |
+--------------------------------------+----------+--------------------------------------+
| 3d3aafde-b4cb-45ab-8ac6-31ff93f69536 | inactive | mytag                                |
| 894a530c-6fa0-4aa1-97c9-4489d205c5ed | inactive | 894a530c-6fa0-4aa1-97c9-4489d205c5ed |
| 9238fc76-5b21-4b8e-80ef-26d74d192f71 | inactive | 9238fc76-5b21-4b8e-80ef-26d74d192f71 |
+--------------------------------------+----------+--------------------------------------+

Manage shares

Manage shares¶

Overview¶

Use Cases¶

Prerequisites¶

Configure instance shared memory¶

Limitations¶

Known bugs¶

Managing shares¶

Listing Attached Shares¶

nova 30.1.0.dev167

Page Contents

Manage shares

Manage shares¶

Overview¶

Use Cases¶

Prerequisites¶

Configure instance shared memory¶

Limitations¶

Known bugs¶

Managing shares¶

Attaching a Share¶

Detaching a Share¶

Listing Attached Shares¶

Showing Details of an Attached Share¶

Notification of Share Attachment and Detachment¶

nova 30.1.0.dev167

Page Contents