Manila/Concepts

= Manila Concepts =

This is a guide to various terms used in the Manila project, explaining what they mean, who they apply to, and where they matter.

share
A share is a unit of storage with a protocol, a size, and an access list. Shares are the basic primitive provided by Manila. All shares exist on a backend. Some shares are associated with share_networks and share_servers. The main protocols supported are NFS and CIFS, but other protocols are supported as well.
 * Tenants can create, delete, list, get details, snapshot, and modify access for shares.
 * Administrators typically don't interact with shares except to debug problems.
 * Inside Manila, a share is just a row in a database table.
 * Vendors/drivers implement shares using software and/or hardware however they wish.

snapshot
A snapshot is a point in time copy of a share. Snapshots can only be used to create new shares (containing the snapshotted data). Shares can not be deleted until all associated snapshots are deleted.
 * Tenants can create, delete, and list snapshots, and can create new shares from snapshots.
 * Administrators typically don't interact with snapshots, except to debug problems.
 * Inside Manila, a snapshot is just a row in a database table, linked to a share.
 * Vendors/drivers implements snapshots using whatever technology makes sense for their backend.

share_type
A share_type is an administrator-defined "type of service", comprised of a tenant visible description, and a list of non-tenant-visible key/value pairs (extra_specs) which the Manila scheduler uses to make scheduling decisions. Every share_type must have the manages_shares_servers=True/False extra_spec.
 * Tenants can list share_types and can use them to create new shares.
 * Administrators create and delete share_types, and manage the extra_specs that give them meaning inside Manila.
 * Inside Manila, share_types are used by the scheduler to make scheduling decisions, and used by drivers to control share creation.
 * Vendors/drivers can see the share_type and associated extra_specs when creating new shares, and can configure backend-specific options based on those values.

extra_spec
Extra_specs are the key/value pairs associated with share_types. The valid keys and values are defined by Manila and its drivers. Extra_specs may be qualified (has a colon) or unqualified (has no colon).
 * Tenants see specific common specifications like ``driver_handles_share_servers``, ``snapshot_support``, ``create_share_from_snapshot_support`` etc.
 * Administrators manage the extra_specs associated with share_types.
 * Inside Manila, the scheduler uses unqualified extra_specs to make scheduling decisions, based on capabilities published by the backends/drivers.
 * Vendors/drivers publish capabilities back to the scheduler which match the names of the extra_specs. Qualified extra_specs are only used inside the drivers.
 * See more details regarding share type extra specifications here.

share_network
A share_network is a tenant-defined object that informs Manila about the security and network configuration for a group of shares. Share_networks are only relevant for backends that manage share_servers. A share network contains a security_service and one or more networks/subnets. You must provide a share_network when creating a share with a share type that has the extra-spec ``driver_handles_share_servers`` set to True.


 * Tenants create share_networks using security_services and networks/subnets. Tenants specify the share_network when creating new shares, if appropriate.
 * Administrators should not care about share_networks.
 * Inside Manila, share_networks are associated with share_servers, and used to create share_servers. Every share_server has exactly one share_network, but share_networks can be associated with multiple share_servers.
 * Vendors/drivers use the information in the share_network to create share_servers.
 * See more information regarding share networks here.

security_service
A security_service is a set of options that defines a security domain for a particular shared filesystem protocol, such as an Active Directory domain or a Kerberos domain. The security_service contains all of the information necessary for Manila to create a server that joins the given domain.
 * Tenants provide the details for the security_service.
 * Administrators should not care about security_services.
 * Inside Manila, a security_service is associated with share_networks.
 * Vendors/drivers use the information in the security_service to configure newly created share_servers.

share_server
A share_server is a tracking object used internally by Manila to store network details for any virtual machines, SVMs, or other resources created dynamically by the backend to serve data to specific tenants. Many backends and drivers have no use for share_servers. They exist specifically for backends that follow the model of storage-VM-per-tenant so that tenant data may be securely separate at the network layer and so that Manila can create shares in the security domain specified by the tenant (which requires storage VMs on every technology I'm aware of).
 * Tenants never see share_servers.
 * Administrators can list and delete share_servers, but should only need to do so to debug problems.
 * Inside Manila, share_servers are just a row in a database table, associated with a share_network and some network allocations.
 * Vendors/drivers must publish to the share manager whether they support management of share_servers. For those that don't, share_servers are ignored. For those that do, Manila will create share_servers when needed with the help of the driver.

network/subnet
Networks and subnets are defined by nova-network or neutron. They are relevant for some backends (particularly the generic backend). They are specified as part of share_networks. They are used to tell Manila what virtual networks a share should be reachable from, for cases when Manila must configure network connectivity between a backend and a tenant network.
 * Tenants provide network/subnet information as part of the share_network.
 * Administrators should not care about share_networks.
 * Inside Manila, the network/subnet values are interpreted by network plugins for backends that have them.
 * Vendors/drivers may use the network/subnet values when creating share_servers. In particular the generic driver does this.

backend
A backend is an instance of the manila-share service, defined by a section in manila.conf. Each backend has exactly 1 driver. Backends may be replicated for high availability.
 * Tenants never see backends.
 * Administrators set up backends in the manila.conf file and manage the service running on one or more controller nodes.
 * Inside Manila, backends are RPC endpoints that the API and scheduler service send requests to. The backend translates RPC requests into driver interface calls. Backends also send periodic updates to the scheduler to report capabilities.
 * Vendors/drivers run in the context of a backend.

share driver
A share driver is the piece of code that maps standard Manila operations into vendor-specific operations on an actual storage controller.
 * Tenants know nothing about share drivers.
 * Administrators specify the driver to run in each backend as one of the config options in manila.conf, with some knowledge of the actual infrastructure being used behind Manila.
 * Inside Manila, share drivers run in the backend.
 * Vendors write the share drivers, contribute them, and maintain them.

network plugin
Network plugins provide a way for the administrator to tell Manila how to manage network resources for drivers/backends that manage share_servers.
 * Tenants
 * Administrators
 * Inside Manila,
 * Vendors/drivers

storage controller
Typically a metal box with spinning disks, ethernet ports, and some kind of software that allows network clients to read/write files on the disks. There are also software-only storage controllers that run on arbitrary hardware, clustered controllers which may allow multiple physical devices to appear as a single storage controller, or purely virtual storage controllers.
 * Tenants interact with the storage controller through the data path, such as CIFS or NFS.
 * Administrators purchase, install, and manage storage controllers to provide the underlying infrastructure for Manila.
 * Inside Manila, the storage controllers are abstracted by the share drivers.
 * Vendors build and sell storage controllers, and write drivers for them.