manila — Summary

Reverse-specification of manila — branch stable/2026.2

• Repository: https://opendev.org/openstack/manila — specified branch: stable/2026.2 @ 4fbc4b4f3688 — analysed on: 2026-10-29
• Scope: the whole service — manila-api, manila-scheduler, manila-share, manila-data — files 00–05 and the rewrite pack (07, _rewrite/) for OpenKeel's Go re-implementation on a CSI back end (Longhorn volumes behind per-tenant NFS gateways, DHSS=True). Clients whose expectations are specified: python-manilaclient / OSC, Skyline, manila-ui (Horizon), Manila CSI driver (cloud-provider-openstack). Change history: 06.

Overview

Manila is OpenStack's Shared File Systems service: it provisions file shares (NFS, CIFS, CephFS…) on storage back ends, controls which clients may mount them (access rules), and manages snapshots, replicas, share groups, transfers, backups and quotas. manila-api exposes the microversioned REST API v2 (2.0–2.99) and records intents in the database; manila-scheduler chooses a back-end pool with filters and weighers fed by capability reports; manila-share runs one service per configured back end and drives it through a share driver; manila-data copies data for host-assisted migration and data-manager backups. The processes talk over RabbitMQ (oslo.messaging RPC casts, a few calls, fanout capability reports) and share a MariaDB database. Keystone authenticates every request; Nova, Neutron, Cinder and Glance are used only by drivers that handle share servers (DHSS=True).

Architecture

flowchart LR
  client[python-manilaclient / OSC / Skyline / manila-ui / Manila CSI] -->|HTTPS REST v2| api[manila-api]
  api -->|keystonemiddleware| ks[Keystone]
  api -->|SQL| db[(MariaDB)]
  api -->|AMQP cast| mq{{RabbitMQ}}
  mq -->|create_share_instance| sch[manila-scheduler]
  sch -->|cast host@backend| mq
  mq --> sh[manila-share per back end]
  sh -->|fanout update_service_capabilities| mq
  sh -->|driver| be[(storage back end / CSI PVC)]
  mq --> data[manila-data]
  sh -->|SQL| db
  sch -->|SQL| db
  sh -.->|DHSS=True drivers| nova[Nova / Neutron / Cinder / Glance]
  api -->|notifications| mq

Processes

External dependencies

Key figures

• 258 REST operations (each also without /{project_id}), 70 of them body actions; 101 microversion entries; 64 experimental variants; 230 default policy rules; 102 JSON schemas.
• 65 RPC methods (51 share, 8 scheduler, 6 data), 20 periodic tasks, 2 service timers, 1 startup processing (ensure_driver_resources).
• 266 exception classes in manila/exception.py (296 in the repository); 297 handler-level HTTP conversions; 35 user-message detail codes.
• 53 tables (migrations) / 52 (models), 50 differences.
• Conformance: 29 client scenarios (4 on a DHSS=True back end), 283 exchanges, 247 RPC frames, 29 Neutron calls, reproducible on re-run (29/29); 119 exchanges from 894 unit API tests.

Files

Points of attention

• The analysed commit is the security fix for bugs 2161412 / 2168962: before it, any project could change access rules, back up, replicate or soft-delete another project's public share (06).
• A DHSS=False back end offers no network isolation between tenants: every project reaches the same NFS servers and Manila only filters by client IP. OpenKeel's back end is therefore specified as DHSS=True, with one NFS gateway pod per tenant share network in front of Longhorn volumes (07 § 3.5). Projects must create a share network, and the CSI driver needs shareNetworkID.
• Response-body validation after the write: POST /resource-locks by a user whose id is not UUID-like (LDAP / federated users) answers 400 while the lock exists and blocks the share (02 § 4).
• **share_transfer:get is never enforced** (@authorize above @api_version, manila/api/v2/share_transfer.py:49 (decorators on the two lines above)).
• A full Neutron subnet is reported as a port quota problem (user message 027 instead of 033): the IpAddressGenerationFailureClient branch is unreachable (manila/network/neutron/api.py:194-201).
• **Data-manager backups store the exception object in fail_reason** (manila/data/manager.py:417-419): the error update itself can fail.
• Default microversion is the minimum (2.0) and there is no latest; project ids in URLs must match [0-9a-f\-]+.
• The same exception gives different statuses on different endpoints (InvalidShare 403 on delete, 400 elsewhere; ShareBusyException 400/403/409…).
• A DHSS=False share accepts a share_network_id (200) then fails in the share manager.
• Locks are host-local by default (oslo.concurrency files, tooz file backend): two share services for one back end on two hosts are unsafe; periodic tasks have no leader election.
• GET /v2/ (version discovery used by gophercloud and manilaclient) requires a token.
• The models do not compile for MySQL (String without length) and differ from the migrations in 50 places; Manila's migrations do not run on SQLite as written.

Blind spots / [inferred]

• The 40+ vendor drivers (manila/share/drivers/) are not specified: OpenKeel replaces them with a DHSS=True CSI-backed driver (per-tenant NFS gateways); its mapping (07 § 3.5) is a design proposal [inferred].
• DHSS=True is exercised against a fake Neutron and the DummyDriver (security services, multi-AZ subnets and share server migration are not); share migration, share-server migration, encryption, QoS and data-manager backups are documented from the code but not exercised end-to-end.
• Nullability and foreign-key differences of the schema diff were observed on SQLite only [inferred].
• The CSI driver's requests are reproduced from gophercloud v2.15.0 source, not executed by gophercloud itself.

Source: reverse-spec-manila/00-summary_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.