openstack/manila
Code Issues Proposed changes

Update manila's docs

Browse Source 
After manila's fork from cinder, its docs were not
updated well.

This info is used by doc-builder, see doc/README.rst

Partially implements: blueprint manila-documentation

Change-Id: Ic97584db291b60505d5d310a517c2866fc6fcf5f
This commit is contained in:
vponomaryov 2014-06-06 19:30:04 +03:00
parent 0c0d0b48ef
commit 08612d7524
18 changed files with 148 additions and 707 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/ext/manila_autodoc.py
View File

@ -1,3 +1,5 @@
from __future__ import print_function
import gettext import gettext
import os import os
@ -7,6 +9,6 @@ from manila import utils
def setup(app): def setup(app):
print "**Autodocumenting from %s" % os.path.abspath(os.curdir) print("**Autodocumenting from %s" % os.path.abspath(os.curdir))
rv = utils.execute('./generate_autodoc_index.sh') rv = utils.execute('./doc/generate_autodoc_index.sh')
print rv[0] print(rv[0])

2
doc/source/_theme/layout.html
View File

@ -73,7 +73,7 @@
<script type="text/javascript">$('#searchbox').show(0);</script> <script type="text/javascript">$('#searchbox').show(0);</script>
<p class="triangle-border right"> <p class="triangle-border right">
Psst... hey. You're reading the latest content, but it's for the Block Storage project only. You can read <a href="http://docs.openstack.org">all OpenStack docs</a> too. Psst... hey. You're reading the latest content, but it's for the Shared Filesystems project only. You can read <a href="http://docs.openstack.org">all OpenStack docs</a> too.
</p> </p>
{%- endif %} {%- endif %}

10
doc/source/devref/addmethod.openstackapi.rst
View File

@ -24,7 +24,7 @@ Routing
To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.groovie.org/ for more information. To map URLs to controllers+actions, OpenStack uses the Routes package, a clone of Rails routes for Python implementations. See http://routes.groovie.org/ for more information.
URLs are mapped to "action" methods on "controller" classes in ``manila/api/openstack/__init__/ApiRouter.__init__`` . URLs are mapped to "action" methods on "controller" classes in ``manila/api/v1/router.py``.
See http://routes.groovie.org/manual.html for all syntax, but you'll probably just need these two: See http://routes.groovie.org/manual.html for all syntax, but you'll probably just need these two:
- mapper.connect() lets you map a single URL to a single action on a controller. - mapper.connect() lets you map a single URL to a single action on a controller.
@ -33,9 +33,9 @@ See http://routes.groovie.org/manual.html for all syntax, but you'll probably ju
Controllers and actions Controllers and actions
----------------------- -----------------------
Controllers live in ``manila/api/openstack``, and inherit from manila.wsgi.Controller. Controllers live in ``manila/api/v1`` and ``manila/api/contrib``.
See ``manila/api/openstack/servers.py`` for an example. See ``manila/api/v1/shares.py`` for an example.
Action methods take parameters that are sucked out of the URL by mapper.connect() or .resource(). The first two parameters are self and the WebOb request, from which you can get the req.environ, req.body, req.headers, etc. Action methods take parameters that are sucked out of the URL by mapper.connect() or .resource(). The first two parameters are self and the WebOb request, from which you can get the req.environ, req.body, req.headers, etc.
@ -44,9 +44,9 @@ Serialization
Actions return a dictionary, and wsgi.Controller serializes that to JSON or XML based on the request's content-type. Actions return a dictionary, and wsgi.Controller serializes that to JSON or XML based on the request's content-type.
If you define a new controller, you'll need to define a ``_serialization_metadata`` attribute on the class, to tell wsgi.Controller how to convert your dictionary to XML. It needs to know the singular form of any list tag (e.g. ``<servers>`` list contains ``<server>`` tags) and which dictionary keys are to be XML attributes as opposed to subtags (e.g. ``<server id="4"/>`` instead of ``<server><id>4</id></server>``). If you define a new controller, you'll need to define a ``_serialization_metadata`` attribute on the class, to tell wsgi.Controller how to convert your dictionary to XML. It needs to know the singular form of any list tag (e.g. ``<shares>`` list contains ``<share>`` tags) and which dictionary keys are to be XML attributes as opposed to subtags (e.g. ``<share id="4"/>`` instead of ``<share><id>4</id></share>``).
See `manila/api/openstack/servers.py` for an example. See `manila/api/v1/shares.py` for an example.
Faults Faults
------ ------

129
doc/source/devref/api.rst
View File

@ -19,148 +19,57 @@ API Endpoint
============ ============
Manila has a system for managing multiple APIs on different subdomains. Manila has a system for managing multiple APIs on different subdomains.
Currently there is support for the OpenStack API, as well as the Amazon EC2 Currently there is support for the OpenStack API.
API.
Common Components Common Components
----------------- -----------------
The :mod:`manila.api` Module The :mod:`manila.api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api .. automodule:: manila.api
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`manila.api.cloud` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api.cloud The :mod:`manila.api.v1` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`manila.api.contrib` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api
:noindex:
:members:
:undoc-members:
:show-inheritance:
OpenStack API OpenStack API
------------- -------------
The :mod:`openstack` Module The :mod:`openstack` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api.openstack .. automodule:: manila.api.openstack
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api.openstack.auth
:noindex:
:members:
:undoc-members:
:show-inheritance:
EC2 API
-------
The :mod:`manila.api.ec2` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api.ec2
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cloud` Module
~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api.ec2.cloud
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`metadatarequesthandler` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.api.ec2.metadatarequesthandler
:noindex:
:members:
:undoc-members:
:show-inheritance:
Tests Tests
----- -----
The :mod:`api_unittest` Module The :mod:`api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api_unittest .. automodule:: manila.tests.api
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`api_integration` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api_integration
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`cloud_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.cloud_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.fakes` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api.fakes
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.test_wsgi` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api.test_wsgi
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api.openstack.test_api
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api.openstack.test_auth
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_faults` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.api.openstack.test_faults
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:

18
doc/source/devref/architecture.rst
View File

@ -1,6 +1,7 @@
.. ..
Copyright 2010-2011 United States Government as represented by the Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration. Administrator of the National Aeronautics and Space Administration.
Copyright 2014 Mirantis, Inc.
All Rights Reserved. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -16,11 +17,11 @@
under the License. under the License.
Manila System Architecture Manila System Architecture
======================== ==========================
The Manila Shared Filesystem Management Service is intended to be ran on one or more nodes. The Manila Shared Filesystem Management Service is intended to be ran on one or more nodes.
Manila uses a sql-based central database that is shared by all Manila services in the system. The amount and depth of the data fits into a sql database quite well. For small deployments this seems like an optimal solution. For larger deployments, and especially if security is a concern, manila will be moving towards multiple data stores with some kind of aggregation system. Manila uses a sql-based central database that is shared by all Manila services in the system. The amount and depth of the data fits into a sql database quite well. For small deployments this seems like an optimal solution. For larger deployments, and especially if security is a concern, Manila will be moving towards multiple data stores with some kind of aggregation system.
Components Components
---------- ----------
@ -46,8 +47,17 @@ Below you will a brief explanation of the different components.
* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) * DB: sql database for data storage. Used by all components (LINKS NOT SHOWN)
* Web Dashboard: potential external component that talks to the api * Web Dashboard: external component that talks to the api. Beta extended Horizon available here: https://github.com/NetApp/horizon/tree/manila
* api: component that receives http requests, converts commands and communicates with other components via the queue or http * api: component that receives http requests, converts commands and communicates with other components via the queue or http
* Auth Manager: component responsible for users/projects/and roles. Can backend to DB or LDAP. This is not a separate binary, but rather a python class that is used by most components in the system. * Auth Manager: component responsible for users/projects/and roles. Can backend to DB or LDAP. This is not a separate binary, but rather a python class that is used by most components in the system.
* scheduler: decides which host gets each volume * scheduler: decides which host will handle create share request.
* share: manages shared filesystems. * share: manages shared filesystems.
Further Challenges
------------------
* More efficient share/snapshot size calculation
* Integration with Nova for share automounts
* Non-vlan multitenancy
* Gateway mediated networking model with NFS-Ganesha
* Add support for bigger amount of backends

220
doc/source/devref/auth.rst
View File

@ -1,6 +1,7 @@
.. ..
Copyright 2010-2011 United States Government as represented by the Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration. Administrator of the National Aeronautics and Space Administration.
Copyright 2014 Mirantis, Inc.
All Rights Reserved. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -21,7 +22,7 @@ Authentication and Authorization
================================ ================================
The :mod:`manila.quota` Module The :mod:`manila.quota` Module
---------------------------- ------------------------------
.. automodule:: manila.quota .. automodule:: manila.quota
:noindex: :noindex:
@ -29,24 +30,10 @@ The :mod:`manila.quota` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`manila.policy` Module
------------------------------
The :mod:`manila.auth.signer` Module .. automodule:: manila.policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.auth.signer
:noindex:
:members:
:undoc-members:
:show-inheritance:
Auth Manager
------------
The :mod:`manila.auth.manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.auth.manager
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
@ -56,182 +43,23 @@ The :mod:`manila.auth.manager` Module
Tests Tests
----- -----
The :mod:`test_quota` Module
The :mod:`auth_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.auth_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`access_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.access_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`quota_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.quota_unittest .. automodule:: manila.tests.test_quota
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`test_policy` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Legacy Docs .. automodule:: manila.tests.test_policy
----------- :noindex:
:members:
Manila provides RBAC (Role-based access control) of the AWS-type APIs. We define the following roles: :undoc-members:
:show-inheritance:
Roles-Based Access Control of AWS-style APIs using SAML Assertions
“Achieving FIPS 199 Moderate certification of a hybrid cloud environment using CloudAudit and declarative C.I.A. classifications”
Introduction
------------
We will investigate one method for integrating an AWS-style API with US eAuthentication-compatible federated authentication systems, to achieve access controls and limits based on traditional operational roles.
Additionally, we will look at how combining this approach, with an implementation of the CloudAudit APIs, will allow us to achieve a certification under FIPS 199 Moderate classification for a hybrid cloud environment.
Relationship of US eAuth to RBAC
--------------------------------
Typical implementations of US eAuth authentication systems are structured as follows::
[ MS Active Directory or other federated LDAP user store ]
--> backends to…
[ SUN Identity Manager or other SAML Policy Controller ]
--> maps URLs to groups…
[ Apache Policy Agent in front of eAuth-secured Web Application ]
In more ideal implementations, the remainder of the application-specific account information is stored either in extended schema on the LDAP server itself, via the use of a translucent LDAP proxy, or in an independent datastore keyed off of the UID provided via SAML assertion.
.. _auth_roles:
Roles
-----
AWS API calls are traditionally secured via Access and Secret Keys, which are used to sign API calls, along with traditional timestamps to prevent replay attacks. The APIs can be logically grouped into sets that align with five typical roles:
* Base User
* System Administrator/Developer (currently have the same permissions)
* Network Administrator
* Project Manager
* Cloud Administrator/IT-Security (currently have the same permissions)
There is an additional, conceptual end-user that may or may not have API access:
* (EXTERNAL) End-user / Third-party User
Basic operations are available to any :
* Describe Instances
* Describe Images
* Describe Volumes
* Describe Keypairs
* Create Keypair
* Delete Keypair
* Create, Upload, Delete: Buckets and Keys (Object Store)
System Administrators/Developers/Project Manager:
* Create, Attach, Delete Volume (Block Store)
* Launch, Reboot, Terminate Instance
* Register/Unregister Machine Image (project-wide)
* Request / Review CloudAudit Scans
Project Manager:
* Add and remove other users (currently no api)
* Set roles (currently no api)
Network Administrator:
* Change Machine Image properties (public / private)
* Change Firewall Rules, define Security Groups
* Allocate, Associate, Deassociate Public IP addresses
Cloud Administrator/IT-Security:
* All permissions
Enhancements
------------
* SAML Token passing
* REST interfaces
* SOAP interfaces
Wrapping the SAML token into the API calls.
Then store the UID (fetched via backchannel) into the instance metadata, providing end-to-end auditability of ownership and responsibility, without PII.
CloudAudit APIs
---------------
* Request formats
* Response formats
* Stateless asynchronous queries
CloudAudit queries may spawn long-running processes (similar to launching instances, etc.) They need to return a ReservationId in the same fashion, which can be returned in further queries for updates.
RBAC of CloudAudit API calls is critical, since detailed system information is a system vulnerability.
Type declarations
-----------------
* Data declarations – Volumes and Objects
* System declarations – Instances
Existing API calls to launch instances specific a single, combined “type” flag. We propose to extend this with three additional type declarations, mapping to the “Confidentiality, Integrity, Availability” classifications of FIPS 199. An example API call would look like::
RunInstances type=m1.large number=1 secgroup=default key=mykey confidentiality=low integrity=low availability=low
These additional parameters would also apply to creation of block storage volumes (along with the existing parameter of ‘size’), and creation of object storage ‘buckets’. (C.I.A. classifications on a bucket would be inherited by the keys within this bucket.)
Request Brokering
-----------------
* Cloud Interop
* IMF Registration / PubSub
* Digital C&A
Establishing declarative semantics for individual API calls will allow the cloud environment to seamlessly proxy these API calls to external, third-party vendors – when the requested CIA levels match.
See related work within the Infrastructure 2.0 working group for more information on how the IMF Metadata specification could be utilized to manage registration of these vendors and their C&A credentials.
Dirty Cloud – Hybrid Data Centers
---------------------------------
* CloudAudit bridge interfaces
* Anything in the ARP table
A hybrid cloud environment provides dedicated, potentially co-located physical hardware with a network interconnect to the project or users’ cloud virtual network.
This interconnect is typically a bridged VPN connection. Any machines that can be bridged into a hybrid environment in this fashion (at Layer 2) must implement a minimum version of the CloudAudit spec, such that they can be queried to provide a complete picture of the IT-sec runtime environment.
Network discovery protocols (ARP, CDP) can be applied in this case, and existing protocols (SNMP location data, DNS LOC records) overloaded to provide CloudAudit information.
The Details
-----------
* Preliminary Roles Definitions
* Categorization of available API calls
* SAML assertion vocabulary
System limits System limits
@ -239,19 +67,7 @@ System limits
The following limits need to be defined and enforced: The following limits need to be defined and enforced:
* Total number of instances allowed (user / project) * Maximum cumulative size of shares and snapshots (GB)
* Total number of instances, per instance type (user / project) * Total number of shares
* Total number of volumes (user / project) * Total number of snapshots
* Maximum size of volume * Total number of share networks
* Cumulative size of all volumes
* Total use of object storage (GB)
* Total number of Public IPs
Further Challenges
------------------
* Prioritization of users / jobs in shared computing environments
* Incident response planning
* Limit launch of instances to specific security groups based on AMI
* Store AMIs in LDAP for added property control

8
doc/source/devref/database.rst
View File

@ -19,7 +19,7 @@ The Database Layer
================== ==================
The :mod:`manila.db.api` Module The :mod:`manila.db.api` Module
----------------------------- -------------------------------
.. automodule:: manila.db.api .. automodule:: manila.db.api
:noindex: :noindex:
@ -32,13 +32,13 @@ The Sqlalchemy Driver
--------------------- ---------------------
The :mod:`manila.db.sqlalchemy.api` Module The :mod:`manila.db.sqlalchemy.api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.db.sqlalchemy.api .. automodule:: manila.db.sqlalchemy.api
:noindex: :noindex:
The :mod:`manila.db.sqlalchemy.models` Module The :mod:`manila.db.sqlalchemy.models` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.db.sqlalchemy.models .. automodule:: manila.db.sqlalchemy.models
:noindex: :noindex:
@ -47,7 +47,7 @@ The :mod:`manila.db.sqlalchemy.models` Module
:show-inheritance: :show-inheritance:
The :mod:`manila.db.sqlalchemy.session` Module The :mod:`manila.db.sqlalchemy.session` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.db.sqlalchemy.session .. automodule:: manila.db.sqlalchemy.session
:noindex: :noindex:

21
doc/source/devref/development.environment.rst
View File

@ -19,21 +19,18 @@ Setting Up a Development Environment
==================================== ====================================
This page describes how to setup a working Python development This page describes how to setup a working Python development
environment that can be used in developing manila on Ubuntu, Fedora or environment that can be used in developing Manila on Ubuntu, Fedora or
Mac OS X. These instructions assume you're already familiar with Mac OS X. These instructions assume you're already familiar with
git. Refer to GettingTheCode_ for additional information. git. Refer to GettingTheCode_ for additional information.
.. _GettingTheCode: http://wiki.openstack.org/GettingTheCode .. _GettingTheCode: http://wiki.openstack.org/GettingTheCode
Following these instructions will allow you to run the manila unit Following these instructions will allow you to run the Manila unit
tests. If you want to be able to run manila (i.e., launch VM instances), tests. If you want to be able to run Manila (i.e., create NFS/CIFS shares),
you will also need to install libvirt and at least one of the you will also need to install dependent projects: Nova, Neutron, Cinder and Glance.
`supported hypervisors`_. Running manila is currently only supported on For this purpose 'devstack' project can be used (A documented shell script to build complete OpenStack development environments).
Linux, although you can run the unit tests on Mac OS X. See
:doc:`../quickstart` for how to get a working version of OpenStack
Compute running as quickly as possible.
.. _supported hypervisors: http://wiki.openstack.org/HypervisorSupportMatrix .. _DeployOpenstack: http://devstack.org/
Virtual environments Virtual environments
-------------------- --------------------
@ -41,7 +38,7 @@ Virtual environments
Manila development uses `virtualenv <http://pypi.python.org/pypi/virtualenv>`__ to track and manage Python Manila development uses `virtualenv <http://pypi.python.org/pypi/virtualenv>`__ to track and manage Python
dependencies while in development and testing. This allows you to dependencies while in development and testing. This allows you to
install all of the Python package dependencies in a virtual install all of the Python package dependencies in a virtual
environment or "virtualenv" (a special subdirectory of your manila environment or "virtualenv" (a special subdirectory of your Manila
directory), instead of installing the packages at the system level. directory), instead of installing the packages at the system level.
.. note:: .. note::
@ -85,14 +82,14 @@ MacPorts package for OpenSSL, you will see an error when running
``manila.tests.auth_unittest.AuthTestCase.test_209_can_generate_x509``. ``manila.tests.auth_unittest.AuthTestCase.test_209_can_generate_x509``.
The stock version of OpenSSL that ships with Mac OS X 10.6 (OpenSSL 0.9.8l) The stock version of OpenSSL that ships with Mac OS X 10.6 (OpenSSL 0.9.8l)
or Mac OS X 10.7 (OpenSSL 0.9.8r) works fine with manila. or Mac OS X 10.7 (OpenSSL 0.9.8r) works fine with Manila.
Getting the code Getting the code
---------------- ----------------
Grab the code from GitHub:: Grab the code from GitHub::
git clone https://github.com/openstack/manila.git git clone https://github.com/stackforge/manila.git
cd manila cd manila

41
doc/source/devref/fakes.rst
View File

@ -24,62 +24,51 @@ When the real thing isn't available and you have some development to do these
fake implementations of various drivers let you get on with your day. fake implementations of various drivers let you get on with your day.
The :mod:`manila.virt.fake` Module The :mod:`fake_compute` Module
-------------------------------- ------------------------------
.. automodule:: manila.virt.fake .. automodule:: manila.tests.fake_compute
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`manila.auth.fakeldap` Module The :mod:`fake_driver` Module
------------------------------------ -----------------------------
.. automodule:: manila.auth.fakeldap .. automodule:: manila.tests.fake_driver
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`manila.testing.fake.rabbit` Module The :mod:`fake_network` Module
------------------------------------------ ------------------------------
.. automodule:: manila.testing.fake.rabbit .. automodule:: manila.tests.fake_service_instance
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :class:`manila.volume.driver.FakeAOEDriver` Class The :mod:`fake_utils` Module
--------------------------------------------------- ----------------------------
.. autoclass:: manila.volume.driver.FakeAOEDriver .. automodule:: manila.tests.fake_utils
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :class:`manila.tests.service_unittest.FakeManager` Class The :mod:`fake_volume` Module
---------------------------------------------------------- ------------------------------
.. autoclass:: manila.tests.service_unittest.FakeManager .. automodule:: manila.tests.fake_volume
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`manila.tests.api.openstack.fakes` Module
------------------------------------------------
.. automodule:: manila.tests.api.openstack.fakes
:noindex:
:members:
:undoc-members:
:show-inheritance:

4
doc/source/devref/index.rst
View File

@ -32,7 +32,7 @@ Programming HowTos and Tutorials
Background Concepts for Manila Background Concepts for Manila
---------------------------- ------------------------------
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 3
@ -55,7 +55,7 @@ API Reference
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 3
../api/autoindex api
Module Reference Module Reference
---------------- ----------------

144
doc/source/devref/manila.rst
View File

@ -22,18 +22,8 @@ Libraries common throughout Manila or just ones that haven't been categorized
very well yet. very well yet.
The :mod:`manila.adminclient` Module
----------------------------------
.. automodule:: manila.adminclient
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`manila.context` Module The :mod:`manila.context` Module
------------------------------ --------------------------------
.. automodule:: manila.context .. automodule:: manila.context
:noindex: :noindex:
@ -43,7 +33,7 @@ The :mod:`manila.context` Module
The :mod:`manila.exception` Module The :mod:`manila.exception` Module
-------------------------------- ----------------------------------
.. automodule:: manila.exception .. automodule:: manila.exception
:noindex: :noindex:
@ -52,48 +42,8 @@ The :mod:`manila.exception` Module
:show-inheritance: :show-inheritance:
The :mod:`manila.flags` Module
----------------------------
.. automodule:: manila.flags
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`manila.process` Module
------------------------------
.. automodule:: manila.process
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`manila.rpc` Module
--------------------------
.. automodule:: manila.rpc
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`manila.server` Module
-----------------------------
.. automodule:: manila.server
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`manila.test` Module The :mod:`manila.test` Module
--------------------------- -----------------------------
.. automodule:: manila.test .. automodule:: manila.test
:noindex: :noindex:
@ -103,7 +53,7 @@ The :mod:`manila.test` Module
The :mod:`manila.utils` Module The :mod:`manila.utils` Module
---------------------------- ------------------------------
.. automodule:: manila.utils .. automodule:: manila.utils
:noindex: :noindex:
@ -112,18 +62,8 @@ The :mod:`manila.utils` Module
:show-inheritance: :show-inheritance:
The :mod:`manila.validate` Module
-------------------------------
.. automodule:: manila.validate
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`manila.wsgi` Module The :mod:`manila.wsgi` Module
--------------------------- -----------------------------
.. automodule:: manila.wsgi .. automodule:: manila.wsgi
:noindex: :noindex:
@ -135,80 +75,10 @@ The :mod:`manila.wsgi` Module
Tests Tests
----- -----
The :mod:`declare_conf` Module The :mod:`test_exception` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.declare_conf
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`conf_fixture` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.conf_fixture
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`flags_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.flags_unittest .. automodule:: manila.tests.test_exception
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`process_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.process_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`real_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.real_flags
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`rpc_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.rpc_unittest
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`runtime_conf` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.runtime_conf
:noindex:
:members:
:undoc-members:
:show-inheritance:
The :mod:`validator_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.validator_unittest
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:

4
doc/source/devref/rpc.rst
View File

@ -15,7 +15,7 @@
under the License. under the License.
AMQP and Manila AMQP and Manila
============= ===============
AMQP is the messaging technology chosen by the OpenStack cloud. The AMQP broker, either RabbitMQ or Qpid, sits between any two Manila components and allows them to communicate in a loosely coupled fashion. More precisely, Manila components (the compute fabric of OpenStack) use Remote Procedure Calls (RPC hereinafter) to communicate to one another; however such a paradigm is built atop the publish/subscribe paradigm so that the following benefits can be achieved: AMQP is the messaging technology chosen by the OpenStack cloud. The AMQP broker, either RabbitMQ or Qpid, sits between any two Manila components and allows them to communicate in a loosely coupled fashion. More precisely, Manila components (the compute fabric of OpenStack) use Remote Procedure Calls (RPC hereinafter) to communicate to one another; however such a paradigm is built atop the publish/subscribe paradigm so that the following benefits can be achieved:
@ -33,7 +33,7 @@ Manila uses direct, fanout, and topic-based exchanges. The architecture looks li
Manila implements RPC (both request+response, and one-way, respectively nicknamed 'rpc.call' and 'rpc.cast') over AMQP by providing an adapter class which take cares of marshaling and unmarshaling of messages into function calls. Each Manila service (for example Compute, Volume, etc.) create two queues at the initialization time, one which accepts messages with routing keys 'NODE-TYPE.NODE-ID' (for example compute.hostname) and another, which accepts messages with routing keys as generic 'NODE-TYPE' (for example compute). The former is used specifically when Manila-API needs to redirect commands to a specific node like 'euca-terminate instance'. In this case, only the compute node whose host's hypervisor is running the virtual machine can kill the instance. The API acts as a consumer when RPC calls are request/response, otherwise is acts as publisher only. Manila implements RPC (both request+response, and one-way, respectively nicknamed 'rpc.call' and 'rpc.cast') over AMQP by providing an adapter class which take cares of marshaling and unmarshaling of messages into function calls. Each Manila service (for example Compute, Volume, etc.) create two queues at the initialization time, one which accepts messages with routing keys 'NODE-TYPE.NODE-ID' (for example compute.hostname) and another, which accepts messages with routing keys as generic 'NODE-TYPE' (for example compute). The former is used specifically when Manila-API needs to redirect commands to a specific node like 'euca-terminate instance'. In this case, only the compute node whose host's hypervisor is running the virtual machine can kill the instance. The API acts as a consumer when RPC calls are request/response, otherwise is acts as publisher only.
Manila RPC Mappings Manila RPC Mappings
----------------- -------------------
The figure below shows the internals of a message broker node (referred to as a RabbitMQ node in the diagrams) when a single instance is deployed and shared in an OpenStack cloud. Every Manila component connects to the message broker and, depending on its personality (for example a compute node or a network node), may use the queue either as an Invoker (such as API or Scheduler) or a Worker (such as Compute, Volume or Network). Invokers and Workers do not actually exist in the Manila object model, but we are going to use them as an abstraction for sake of clarity. An Invoker is a component that sends messages in the queuing system via two operations: 1) rpc.call and ii) rpc.cast; a Worker is a component that receives messages from the queuing system and reply accordingly to rcp.call operations. The figure below shows the internals of a message broker node (referred to as a RabbitMQ node in the diagrams) when a single instance is deployed and shared in an OpenStack cloud. Every Manila component connects to the message broker and, depending on its personality (for example a compute node or a network node), may use the queue either as an Invoker (such as API or Scheduler) or a Worker (such as Compute, Volume or Network). Invokers and Workers do not actually exist in the Manila object model, but we are going to use them as an abstraction for sake of clarity. An Invoker is a component that sends messages in the queuing system via two operations: 1) rpc.call and ii) rpc.cast; a Worker is a component that receives messages from the queuing system and reply accordingly to rcp.call operations.

10
doc/source/devref/scheduler.rst
View File

@ -19,7 +19,7 @@ Scheduler
========= =========
The :mod:`manila.scheduler.manager` Module The :mod:`manila.scheduler.manager` Module
---------------------------------------- ------------------------------------------
.. automodule:: manila.scheduler.manager .. automodule:: manila.scheduler.manager
:noindex: :noindex:
@ -29,7 +29,7 @@ The :mod:`manila.scheduler.manager` Module
The :mod:`manila.scheduler.driver` Module The :mod:`manila.scheduler.driver` Module
--------------------------------------- -----------------------------------------
.. automodule:: manila.scheduler.driver .. automodule:: manila.scheduler.driver
:noindex: :noindex:
@ -39,7 +39,7 @@ The :mod:`manila.scheduler.driver` Module
The :mod:`manila.scheduler.simple` Driver The :mod:`manila.scheduler.simple` Driver
--------------------------------------- -----------------------------------------
.. automodule:: manila.scheduler.simple .. automodule:: manila.scheduler.simple
:noindex: :noindex:
@ -51,10 +51,10 @@ The :mod:`manila.scheduler.simple` Driver
Tests Tests
----- -----
The :mod:`scheduler_unittest` Module The :mod:`scheduler` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.scheduler_unittest .. automodule:: manila.tests.scheduler
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:

4
doc/source/devref/services.rst
View File

@ -26,7 +26,7 @@ Currently, Managers and Drivers are specified by flags and loaded using utils.lo
The :mod:`manila.service` Module The :mod:`manila.service` Module
------------------------------ --------------------------------
.. automodule:: manila.service .. automodule:: manila.service
:noindex: :noindex:
@ -36,7 +36,7 @@ The :mod:`manila.service` Module
The :mod:`manila.manager` Module The :mod:`manila.manager` Module
------------------------------ --------------------------------
.. automodule:: manila.manager .. automodule:: manila.manager
:noindex: :noindex:

8
doc/source/devref/share.rst
View File

@ -16,13 +16,13 @@
under the License. under the License.
Shared Filesystems Shared Filesystems
====================== ==================
.. todo:: rework .. todo:: rework
The :mod:`manila.share.manager` Module The :mod:`manila.share.manager` Module
------------------------------------- --------------------------------------
.. automodule:: manila.share.manager .. automodule:: manila.share.manager
:noindex: :noindex:
@ -43,10 +43,10 @@ The :mod:`manila.share.driver` Module
Tests Tests
----- -----
The :mod:`share_unittest` Module The :mod:`test_share` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: manila.tests.share_unittest .. automodule:: manila.tests.test_share
:noindex: :noindex:
:members: :members:
:undoc-members: :undoc-members:

4
doc/source/index.rst
View File

@ -16,9 +16,9 @@
under the License. under the License.
Welcome to Manila's developer documentation! Welcome to Manila's developer documentation!
========================================== ============================================
Manila is an OpenStack project to provide "block storage as a service". Manila is an OpenStack project to provide "Shared Filesystems as a service".
* **Component based architecture**: Quickly add new behaviors * **Component based architecture**: Quickly add new behaviors
* **Highly available**: Scale to very serious workloads * **Highly available**: Scale to very serious workloads

218
doc/source/man/manila-manage.rst
View File

@ -1,17 +1,17 @@
=========== =============
manila-manage manila-manage
=========== =============
------------------------------------------------------ -------------------------------------
control and manage cloud computer instances and images control and manage shared filesystems
------------------------------------------------------ -------------------------------------
:Author: openstack@lists.launchpad.net :Author: openstack@lists.launchpad.net
:Date: 2012-04-05 :Date: 2014-06-11
:Copyright: OpenStack LLC :Copyright: OpenStack LLC
:Version: 2012.1 :Version: 2014.2
:Manual section: 1 :Manual section: 1
:Manual group: cloud computing :Manual group: shared filesystems
SYNOPSIS SYNOPSIS
======== ========
@ -21,7 +21,8 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
=========== ===========
manila-manage controls cloud computing instances by managing manila users, manila projects, manila roles, shell selection, vpn connections, and floating IP address configuration. More information about OpenStack Manila is at http://manila.openstack.org. manila-manage controls shared filesystems service.
More information about OpenStack Manila is at https://wiki.openstack.org/wiki/Manila
OPTIONS OPTIONS
======= =======
@ -29,21 +30,18 @@ OPTIONS
The standard pattern for executing a manila-manage command is: The standard pattern for executing a manila-manage command is:
``manila-manage <category> <command> [<args>]`` ``manila-manage <category> <command> [<args>]``
For example, to obtain a list of all projects: For example, to obtain a list of all hosts:
``manila-manage project list`` ``manila-manage host list``
Run without arguments to see a list of available command categories: Run without arguments to see a list of available command categories:
``manila-manage`` ``manila-manage``
Categories are user, project, role, shell, vpn, and floating. Detailed descriptions are below. Categories are shell, logs, service, db, host, version and config. Detailed descriptions are below.
You can also run with a category argument such as user to see a list of all commands in that category:
``manila-manage user``
These sections describe the available categories and arguments for manila-manage. These sections describe the available categories and arguments for manila-manage.
Manila Db Manila Db
~~~~~~~ ~~~~~~~~~
``manila-manage db version`` ``manila-manage db version``
@ -53,83 +51,8 @@ Manila Db
Sync the database up to the most recent version. This is the standard way to create the db as well. Sync the database up to the most recent version. This is the standard way to create the db as well.
Manila User
~~~~~~~~~
``manila-manage user admin <username>``
Create an admin user with the name <username>.
``manila-manage user create <username>``
Create a normal user with the name <username>.
``manila-manage user delete <username>``
Delete the user with the name <username>.
``manila-manage user exports <username>``
Outputs a list of access key and secret keys for user to the screen
``manila-manage user list``
Outputs a list of all the user names to the screen.
``manila-manage user modify <accesskey> <secretkey> <admin?T/F>``
Updates the indicated user keys, indicating with T or F if the user is an admin user. Leave any argument blank if you do not want to update it.
Manila Project
~~~~~~~~~~~~
``manila-manage project add <projectname>``
Add a manila project with the name <projectname> to the database.
``manila-manage project create <projectname>``
Create a new manila project with the name <projectname> (you still need to do manila-manage project add <projectname> to add it to the database).
``manila-manage project delete <projectname>``
Delete a manila project with the name <projectname>.
``manila-manage project environment <projectname> <username>``
Exports environment variables for the named project to a file named manilarc.
``manila-manage project list``
Outputs a list of all the projects to the screen.
``manila-manage project quota <projectname>``
Outputs the size and specs of the project's instances including gigabytes, instances, floating IPs, volumes, and cores.
``manila-manage project remove <projectname>``
Deletes the project with the name <projectname>.
``manila-manage project zipfile``
Compresses all related files for a created project into a zip file manila.zip.
Manila Role
~~~~~~~~~
``manila-manage role add <username> <rolename> <(optional) projectname>``
Add a user to either a global or project-based role with the indicated <rolename> assigned to the named user. Role names can be one of the following five roles: cloudadmin, itsec, sysadmin, netadmin, developer. If you add the project name as the last argument then the role is assigned just for that project, otherwise the user is assigned the named role for all projects.
``manila-manage role has <username> <projectname>``
Checks the user or project and responds with True if the user has a global role with a particular project.
``manila-manage role remove <username> <rolename>``
Remove the indicated role from the user.
Manila Logs Manila Logs
~~~~~~~~~ ~~~~~~~~~~~
``manila-manage logs errors`` ``manila-manage logs errors``
@ -140,7 +63,7 @@ Manila Logs
Displays manila alerts from syslog. Displays manila alerts from syslog.
Manila Shell Manila Shell
~~~~~~~~~~ ~~~~~~~~~~~~
``manila-manage shell bpython`` ``manila-manage shell bpython``
@ -162,119 +85,44 @@ Manila Shell
Runs the named script from the specified path with flags set. Runs the named script from the specified path with flags set.
Manila VPN Manila Host
~~~~~~~~
``manila-manage vpn list``
Displays a list of projects, their IP prot numbers, and what state they're in.
``manila-manage vpn run <projectname>``
Starts the VPN for the named project.
``manila-manage vpn spawn``
Runs all VPNs.
Manila Floating IPs
~~~~~~~~~~~~~~~~~
``manila-manage floating create <ip_range> [--pool <pool>] [--interface <interface>]``
Creates floating IP addresses for the given range, optionally specifying
a floating pool and a network interface.
``manila-manage floating delete <ip_range>``
Deletes floating IP addresses in the range given.
``manila-manage floating list``
Displays a list of all floating IP addresses.
Manila Flavor
~~~~~~~~~~~ ~~~~~~~~~~~
``manila-manage flavor list`` ``manila-manage host list``
Outputs a list of all active flavors to the screen. Returns list of running manila hosts.
``manila-manage flavor list --all`` Manila Config
~~~~~~~~~~~~~
Outputs a list of all flavors (active and inactive) to the screen. ``manila-manage config list``
``manila-manage flavor create <name> <memory> <vCPU> <local_storage> <flavorID> <(optional) swap> <(optional) RXTX Quota> <(optional) RXTX Cap>`` Returns list of currently set config options and its values.
creates a flavor with the following positional arguments:
* memory (expressed in megabytes)
* vcpu(s) (integer)
* local storage (expressed in gigabytes)
* flavorid (unique integer)
* swap space (expressed in megabytes, defaults to zero, optional)
* RXTX quotas (expressed in gigabytes, defaults to zero, optional)
* RXTX cap (expressed in gigabytes, defaults to zero, optional)
``manila-manage flavor delete <name>`` Manila Service
~~~~~~~~~~~~~~
Delete the flavor with the name <name>. This marks the flavor as inactive and cannot be launched. However, the record stays in the database for archival and billing purposes. ``manila-manage service list``
``manila-manage flavor delete <name> --purge`` Returns list of manila services.
Purges the flavor with the name <name>. This removes this flavor from the database. Manila Version
~~~~~~~~~~~~~~
Manila Instance_type ``manila-manage version list``
~~~~~~~~~~~~~~~~~~
The instance_type command is provided as an alias for the flavor command. All the same subcommands and arguments from manila-manage flavor can be used.
Manila Images
~~~~~~~~~~~
``manila-manage image image_register <path> <owner>``
Registers an image with the image service.
``manila-manage image kernel_register <path> <owner>``
Registers a kernel with the image service.
``manila-manage image ramdisk_register <path> <owner>``
Registers a ramdisk with the image service.
``manila-manage image all_register <image_path> <kernel_path> <ramdisk_path> <owner>``
Registers an image kernel and ramdisk with the image service.
``manila-manage image convert <directory>``
Converts all images in directory from the old (Bexar) format to the new format.
Manila VM
~~~~~~~~~~~
``manila-manage vm list [host]``
Show a list of all instances. Accepts optional hostname (to show only instances on specific host).
``manila-manage live-migration <ec2_id> <destination host name>``
Live migrate instance from current host to destination host. Requires instance id (which comes from euca-describe-instance) and destination host name (which can be found from manila-manage service list).
Returns list of versions.
FILES FILES
======== =====
The manila-manage.conf file contains configuration information in the form of python-gflags. The manila-manage.conf file contains configuration information in the form of python-gflags.
SEE ALSO
========
* `OpenStack Manila <http://manila.openstack.org>`__
BUGS BUGS
==== ====
* Manila is sourced in Launchpad so you can view current bugs at `OpenStack Manila <http://manila.openstack.org>`__ * Manila is sourced in Launchpad so you can view current bugs at `OpenStack Manila <https://bugs.launchpad.net/manila>`__

2
test-requirements.txt
View File

@ -8,5 +8,5 @@ nosehtmloutput>=0.0.3
nosexcover nosexcover
openstack.nose_plugin>=0.7 openstack.nose_plugin>=0.7
psycopg2 psycopg2
sphinx>=1.1.2,<1.2 sphinx>=1.2.1,<1.3
testtools>=0.9.32,<0.9.35 testtools>=0.9.32,<0.9.35