openstack/nova
Code Issues Proposed changes

Merge lp:~termie/nova/trunkdoc (via patch, since bzr though it was already merged)

Browse Source
This commit is contained in:
Todd Willey 2010-11-07 14:51:40 -05:00
parent a999c8de9e
commit 2c01c32571
34 changed files with 330 additions and 1522 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
doc/README.rst Normal file
View File

@ -0,0 +1,33 @@
=================
Building the docs
=================
It is really easy. You'll need sphinx (the python one) and if you are using the virtualenv you'll need to install it in the virtualenv specifically so that it can load the nova modules.
Use `make`
==========
Just type make::
% make
Look in the Makefile for more targets.
Manually
========
1. Generate the code.rst file so that Sphinx will pull in our docstrings::
% ./generate_autodoc_index.sh > source/code.rst
2. Run `sphinx_build`::
% sphinx-build -b html source build/html
The docs have been built
========================
Check out the `build` directory to find them. Yay!

10
doc/find_undocumented_classes.sh
View File

@ -8,13 +8,13 @@ for x in `find ${NOVA_DIR} -name '*.py'`; do
if [ `basename ${x} .py` == "__init__" ] ; then if [ `basename ${x} .py` == "__init__" ] ; then
continue continue
fi fi
relative=nova.`echo ${x} | sed -e 's$^'${NOVA_DIR}'$$' -e 's/.py$//' -e 's$/$.$g'` relative=nova`echo ${x} | sed -e 's$^'${NOVA_DIR}'$$' -e 's/.py$//' -e 's$/$.$g'`
modules="${modules} ${relative}" modules="${modules} ${relative}"
done done
for mod in ${modules} ; do for mod in ${modules} ; do
op=`grep ${mod} ${DOCS_DIR}/*.rst` if [ ! -f "${DOCS_DIR}/${mod}.rst" ];
if [ -z "${op}" ] ; then then
echo ${mod} echo ${mod}
fi fi
done done

19
doc/generate_autodoc_index.sh Normal file
View File

@ -0,0 +1,19 @@
#!/bin/sh
SOURCEDIR=source
for x in `./find_autodoc_modules.sh`;
do
echo "Generating ${SOURCEDIR}/${x}.rst"
echo "${SOURCEDIR}/${x}.rst" >> .autogenerated
( cat <<EOF
The :mod:\`${x}\` Module
=====================
.. automodule:: ${x}
:members:
:undoc-members:
:show-inheritance:
EOF
) > ${SOURCEDIR}/${x}.rst
done

37
doc/source/Makefile
View File

@ -4,16 +4,19 @@
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXOPTS = SPHINXOPTS =
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
SPHINXSOURCE = source
PAPER = PAPER =
BUILDDIR = _build BUILDDIR = build
# Internal variables. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest .PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
.DEFAULT_GOAL = html
help: help:
@echo "Please use \`make <target>' where <target> is one of" @echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files" @echo " html to make standalone HTML files"
@ -29,34 +32,44 @@ help:
clean: clean:
-rm -rf $(BUILDDIR)/* -rm -rf $(BUILDDIR)/*
-rm -rf nova.sqlite
cat .autogenerated | xargs rm
rm .autogenerated
html: module_autodoc: generate_autodoc_index.sh
@echo "Generating module autodocs."
./generate_autodoc_index.sh
source/code.rst: module_autodoc
@# pass
html: source/code.rst
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo @echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml: dirhtml: source/code.rst
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo @echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
pickle: pickle: source/code.rst
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo @echo
@echo "Build finished; now you can process the pickle files." @echo "Build finished; now you can process the pickle files."
json: json: source/code.rst
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo @echo
@echo "Build finished; now you can process the JSON files." @echo "Build finished; now you can process the JSON files."
htmlhelp: htmlhelp: source/code.rst
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo @echo
@echo "Build finished; now you can run HTML Help Workshop with the" \ @echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp." ".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp: qthelp: source/code.rst
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo @echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
@ -65,25 +78,25 @@ qthelp:
@echo "To view the help file:" @echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc"
latex: latex: source/code.rst
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo @echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex." "run these through (pdf)latex."
changes: changes: source/code.rst
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo @echo
@echo "The overview file is in $(BUILDDIR)/changes." @echo "The overview file is in $(BUILDDIR)/changes."
linkcheck: linkcheck: source/code.rst
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo @echo
@echo "Link check complete; look for any errors in the above output " \ @echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt." "or in $(BUILDDIR)/linkcheck/output.txt."
doctest: doctest: source/code.rst
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \ @echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt." "results in $(BUILDDIR)/doctest/output.txt."

267
doc/source/devguide/api.rst
View File

@ -1,267 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
API Endpoint Programming Guide
==============================
Nova has a system for managing multiple APIs on different subdomains.
Currently there is support for the OpenStack API, as well as the Amazon EC2
API.
Common Components
-----------------
The :mod:`nova.api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api
:members:
:undoc-members:
:show-inheritance:
The :mod:`cloud` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.cloud
:members:
:undoc-members:
:show-inheritance:
OpenStack API
-------------
The :mod:`openstack` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack
:members:
:undoc-members:
:show-inheritance:
The :mod:`auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.auth
:members:
:undoc-members:
:show-inheritance:
The :mod:`backup_schedules` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.backup_schedules
:members:
:undoc-members:
:show-inheritance:
The :mod:`faults` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.faults
:members:
:undoc-members:
:show-inheritance:
The :mod:`flavors` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.flavors
:members:
:undoc-members:
:show-inheritance:
The :mod:`images` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.images
:members:
:undoc-members:
:show-inheritance:
The :mod:`ratelimiting` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.ratelimiting
:members:
:undoc-members:
:show-inheritance:
The :mod:`servers` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.servers
:members:
:undoc-members:
:show-inheritance:
The :mod:`sharedipgroups` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.openstack.sharedipgroups
:members:
:undoc-members:
:show-inheritance:
EC2 API
-------
The :mod:`nova.api.ec2` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.ec2
:members:
:undoc-members:
:show-inheritance:
The :mod:`admin` Module
~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.ec2.admin
:members:
:undoc-members:
:show-inheritance:
The :mod:`apirequest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.ec2.apirequest
:members:
:undoc-members:
:show-inheritance:
The :mod:`cloud` Module
~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.ec2.cloud
:members:
:undoc-members:
:show-inheritance:
The :mod:`images` Module
~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.ec2.images
:members:
:undoc-members:
:show-inheritance:
The :mod:`metadatarequesthandler` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.ec2.metadatarequesthandler
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`api_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`api_integration` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api_integration
:members:
:undoc-members:
:show-inheritance:
The :mod:`cloud_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.cloud_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.fakes` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.fakes
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.test_wsgi` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.test_wsgi
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_api` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_api
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_auth` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_auth
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_faults` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_faults
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_flavors` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_flavors
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_images` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_images
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_ratelimiting` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_ratelimiting
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_servers` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_servers
:members:
:undoc-members:
:show-inheritance:
The :mod:`test_sharedipgroups` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.api.openstack.test_sharedipgroups
:members:
:undoc-members:
:show-inheritance:

258
doc/source/devguide/auth.rst
View File

@ -1,258 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _auth:
Authentication and Authorization Programming Guide
==================================================
The :mod:`quota` Module
-----------------------
.. automodule:: nova.quota
:members:
:undoc-members:
:show-inheritance:
Auth Manager
------------
The :mod:`manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.manager
:members:
:undoc-members:
:show-inheritance:
Drivers
-------
The :mod:`ldapdriver` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.ldapdriver
:members:
:undoc-members:
:show-inheritance:
The :mod:`dbdriver` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.dbdriver
:members:
:undoc-members:
:show-inheritance:
API Integration
---------------
The :mod:`signer` Module
~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.signer
:members:
:undoc-members:
:show-inheritance:
Related Tests
-------------
The :mod:`auth_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.auth_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`access_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.access_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`quota_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.quota_unittest
:members:
:undoc-members:
:show-inheritance:
legacy docs
-----------
Nova provides RBAC (Role-based access control) of the AWS-type APIs. We define the following roles:
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
-------------
The following limits need to be defined and enforced:
* Total number of instances allowed (user / project)
* Total number of instances, per instance type (user / project)
* Total number of volumes (user / project)
* Maximum size of volume
* 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

146
doc/source/devguide/compute.rst
View File

@ -1,146 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Virtualization Programming Guide
================================
This page contains the Compute Package documentation.
Manager
-------
Documentation for the compute manager and related files. For reading about
a specific virtualization backend, read Drivers_.
The :mod:`manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.manager
:members:
:undoc-members:
:show-inheritance:
The :mod:`connection` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.virt.connection
:members:
:undoc-members:
:show-inheritance:
The :mod:`disk` Module
~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.disk
:members:
:undoc-members:
:show-inheritance:
The :mod:`images` Module
~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.virt.images
:members:
:undoc-members:
:show-inheritance:
The :mod:`instance_types` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.instance_types
:members:
:undoc-members:
:show-inheritance:
The :mod:`power_state` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.power_state
:members:
:undoc-members:
:show-inheritance:
Drivers
-------
Libvirt Implementations
~~~~~~~~~~~~~~~~~~~~~~~
The libvirt driver is capable of supporting KVM, QEMU, and UML.
The :mod:`libvirt_conn` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.virt.libvirt_conn
:members:
:undoc-members:
:show-inheritance:
XEN
~~~
The :mod:`xenapi` Module
^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.virt.xenapi
:members:
:undoc-members:
:show-inheritance:
FAKE
~~~~
.. automodule:: nova.virt.fake
:members:
:undoc-members:
:show-inheritance:
Monitoring
----------
The :mod:`monitor` Module
~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.monitor
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`compute_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.compute_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`virt_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.virt_unittest
:members:
:undoc-members:
:show-inheritance:

61
doc/source/devguide/database.rst
View File

@ -1,61 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Database Programming Guide
==========================
The :mod:`api` Module
---------------------
.. automodule:: nova.db.api
:members:
:undoc-members:
:show-inheritance:
Drivers
-------
Driver: Sqlalchemy
~~~~~~~~~~~~~~~~~~
The :mod:`sqlalchemy.api` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.db.sqlalchemy.api
The :mod:`sqlalchemy.models` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.db.sqlalchemy.models
:members:
:undoc-members:
:show-inheritance:
The :mod:`sqlalchemy.session` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.db.sqlalchemy.session
:members:
:undoc-members:
:show-inheritance:
Tests
-----
Tests are lacking for the db api layer and for the sqlalchemy driver.
Failures in the drivers would be dectected in other test cases, though.

72
doc/source/devguide/fakes.rst
View File

@ -1,72 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Fakes Programming Guide
=======================
.. todo:: document general info about fakes
The :mod:`virt.fake` Module
---------------------------
.. automodule:: nova.virt.fake
:members:
:undoc-members:
:show-inheritance:
:noindex:
The :mod:`fakeldap` Module
--------------------------
.. automodule:: nova.auth.fakeldap
:members:
:undoc-members:
:show-inheritance:
The :mod:`fakerabbit` Module
----------------------------
.. automodule:: nova.fakerabbit
:members:
:undoc-members:
:show-inheritance:
The :class:`FakeAOEDriver` Class
--------------------------------
.. autoclass:: nova.volume.driver.FakeAOEDriver
:members:
:undoc-members:
:show-inheritance:
The :class:`service_unittest.FakeManager` Class
-----------------------------------------------
.. autoclass:: nova.tests.service_unittest.FakeManager
:members:
:undoc-members:
:show-inheritance:
The :mod:`api.openstack.fakes` Module
------------------------------------------------
.. automodule:: nova.tests.api.openstack.fakes
:members:
:undoc-members:
:show-inheritance:

27
doc/source/devguide/glance.rst
View File

@ -1,27 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Glance Integration Programming Guide
====================================
The :mod:`image.service` Module
-------------------------------
.. automodule:: nova.image.service
:members:
:undoc-members:
:show-inheritance:

124
doc/source/devguide/network.rst
View File

@ -1,124 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Networking Programming Guide
============================
.. todo::
* document hardware specific commands (maybe in admin guide?) (todd)
* document a map between flags and managers/backends (todd)
The :mod:`Manager` module
-------------------------
.. automodule:: nova.network.manager
:members:
:undoc-members:
:show-inheritance:
The :mod:`LinuxNet` driver
--------------------------
.. automodule:: nova.network.linux_net
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`network_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.network_unittest
:members:
:undoc-members:
:show-inheritance:
legacy docs
-----------
The nova networking components manage private networks, public IP addressing, VPN connectivity, and firewall rules.
Components
----------
There are several key components:
* NetworkController (Manages address and vlan allocation)
* RoutingNode (NATs public IPs to private IPs, and enforces firewall rules)
* AddressingNode (runs DHCP services for private networks)
* BridgingNode (a subclass of the basic nova ComputeNode)
* TunnelingNode (provides VPN connectivity)
Component Diagram
-----------------
Overview::
(PUBLIC INTERNET)
| \
/ \ / \
[RoutingNode] ... [RN] [TunnelingNode] ... [TN]
| \ / | |
| < AMQP > | |
[AddressingNode]-- (VLAN) ... | (VLAN)... (VLAN) --- [AddressingNode]
\ | \ /
/ \ / \ / \ / \
[BridgingNode] ... [BridgingNode]
[NetworkController] ... [NetworkController]
\ /
< AMQP >
|
/ \
[CloudController]...[CloudController]
While this diagram may not make this entirely clear, nodes and controllers communicate exclusively across the message bus (AMQP, currently).
State Model
-----------
Network State consists of the following facts:
* VLAN assignment (to a project)
* Private Subnet assignment (to a security group) in a VLAN
* Private IP assignments (to running instances)
* Public IP allocations (to a project)
* Public IP associations (to a private IP / running instance)
While copies of this state exist in many places (expressed in IPTables rule chains, DHCP hosts files, etc), the controllers rely only on the distributed "fact engine" for state, queried over RPC (currently AMQP). The NetworkController inserts most records into this datastore (allocating addresses, etc) - however, individual nodes update state e.g. when running instances crash.
The Public Traffic Path
-----------------------
Public Traffic::
(PUBLIC INTERNET)
|
<NAT> <-- [RoutingNode]
|
[AddressingNode] --> |
( VLAN )
| <-- [BridgingNode]
|
<RUNNING INSTANCE>
The RoutingNode is currently implemented using IPTables rules, which implement both NATing of public IP addresses, and the appropriate firewall chains. We are also looking at using Netomata / Clusto to manage NATting within a switch or router, and/or to manage firewall rules within a hardware firewall appliance.
Similarly, the AddressingNode currently manages running DNSMasq instances for DHCP services. However, we could run an internal DHCP server (using Scapy ala Clusto), or even switch to static addressing by inserting the private address into the disk image the same way we insert the SSH keys. (See compute for more details).

190
doc/source/devguide/nova.rst
View File

@ -1,190 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Nova Libraries Programming Guide
================================
The :mod:`adminclient` Module
-----------------------------
.. automodule:: nova.adminclient
:members:
:undoc-members:
:show-inheritance:
The :mod:`context` Module
-------------------------
.. automodule:: nova.context
:members:
:undoc-members:
:show-inheritance:
The :mod:`exception` Module
---------------------------
.. automodule:: nova.exception
:members:
:undoc-members:
:show-inheritance:
The :mod:`flags` Module
-----------------------
.. automodule:: nova.flags
:members:
:undoc-members:
:show-inheritance:
The :mod:`process` Module
-------------------------
.. automodule:: nova.process
:members:
:undoc-members:
:show-inheritance:
The :mod:`rpc` Module
---------------------
.. automodule:: nova.rpc
:members:
:undoc-members:
:show-inheritance:
The :mod:`server` Module
------------------------
.. automodule:: nova.server
:members:
:undoc-members:
:show-inheritance:
The :mod:`test` Module
----------------------
.. automodule:: nova.test
:members:
:undoc-members:
:show-inheritance:
The :mod:`twistd` Module
------------------------
.. automodule:: nova.twistd
:members:
:undoc-members:
:show-inheritance:
The :mod:`utils` Module
-----------------------
.. automodule:: nova.utils
:members:
:undoc-members:
:show-inheritance:
The :mod:`validate` Module
--------------------------
.. automodule:: nova.validate
:members:
:undoc-members:
:show-inheritance:
The :mod:`wsgi` Module
----------------------
.. automodule:: nova.wsgi
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`declare_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.declare_flags
:members:
:undoc-members:
:show-inheritance:
The :mod:`fake_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.fake_flags
:members:
:undoc-members:
:show-inheritance:
The :mod:`flags_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.flags_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`process_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.process_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`real_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.real_flags
:members:
:undoc-members:
:show-inheritance:
The :mod:`rpc_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.rpc_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`runtime_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.runtime_flags
:members:
:undoc-members:
:show-inheritance:
The :mod:`twistd_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.twistd_unittest
:members:
:undoc-members:
:show-inheritance:
The :mod:`validator_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.validator_unittest
:members:
:undoc-members:
:show-inheritance:

62
doc/source/devguide/objectstore.rst
View File

@ -1,62 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Objectstore Programming Guide
=============================
The :mod:`handler` Module
-------------------------
.. automodule:: nova.objectstore.handler
:members:
:undoc-members:
:show-inheritance:
The :mod:`bucket` Module
------------------------
.. automodule:: nova.objectstore.bucket
:members:
:undoc-members:
:show-inheritance:
The :mod:`stored` Module
------------------------
.. automodule:: nova.objectstore.stored
:members:
:undoc-members:
:show-inheritance:
The :mod:`image` Module
-----------------------
.. automodule:: nova.objectstore.image
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`objectstore_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.objectstore_unittest
:members:
:undoc-members:
:show-inheritance:

62
doc/source/devguide/scheduler.rst
View File

@ -1,62 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Scheduler Programming Guide
===========================
The :mod:`manager` Module
-------------------------
.. automodule:: nova.scheduler.manager
:members:
:undoc-members:
:show-inheritance:
The :mod:`driver` Module
------------------------
.. automodule:: nova.scheduler.driver
:members:
:undoc-members:
:show-inheritance:
The :mod:`chance` Module
------------------------
.. automodule:: nova.scheduler.chance
:members:
:undoc-members:
:show-inheritance:
The :mod:`simple` Module
------------------------
.. automodule:: nova.scheduler.simple
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`scheduler_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.scheduler_unittest
:members:
:undoc-members:
:show-inheritance:

60
doc/source/devguide/volume.rst
View File

@ -1,60 +0,0 @@
..
Copyright 2010 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Volume Programming Guide
=========================
.. todo:: rework after iSCSI merge (see 'Old Docs') (todd or vish)
The :mod:`nova.volume.manager` Module
-------------------------------------
.. automodule:: nova.volume.manager
:members:
:undoc-members:
:show-inheritance:
The :mod:`nova.volume.driver` Module
-------------------------------------
.. automodule:: nova.volume.driver
:members:
:undoc-members:
:show-inheritance:
:exclude-members: FakeAOEDriver
Tests
-----
.. automodule:: nova.tests.volume_unittest
:members:
:undoc-members:
:show-inheritance:
Old Docs
--------
Nova uses ata-over-ethernet (AoE) to export storage volumes from multiple storage nodes. These AoE exports are attached (using libvirt) directly to running instances.
Nova volumes are exported over the primary system VLAN (usually VLAN 1), and not over individual VLANs.
AoE exports are numbered according to a "shelf and blade" syntax. In order to avoid collisions, we currently perform an AoE-discover of existing exports, and then grab the next unused number. (This obviously has race condition problems, and should be replaced by allocating a shelf-id to each storage node.)
The underlying volumes are LVM logical volumes, created on demand within a single large volume group.

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

@ -15,8 +15,8 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
API Endpoint Programming Guide API Endpoint
============================== ============
Nova has a system for managing multiple APIs on different subdomains. Nova 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, as well as the Amazon EC2
@ -33,7 +33,7 @@ The :mod:`nova.api` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`cloud` Module The :mod:`nova.api.cloud` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.cloud .. automodule:: nova.api.cloud

0
doc/source/devguide/architecture.rst → doc/source/devref/architecture.rst
View File

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

@ -17,10 +17,10 @@
.. _auth: .. _auth:
Authentication and Authorization Programming Guide Authentication and Authorization
================================================== ================================
The :mod:`quota` Module The :mod:`nova.quota` Module
----------------------- -----------------------
.. automodule:: nova.quota .. automodule:: nova.quota
@ -28,40 +28,8 @@ The :mod:`quota` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Auth Manager
------------
The :mod:`manager` Module The :mod:`nova.auth.signer` Module
~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.manager
:members:
:undoc-members:
:show-inheritance:
Drivers
-------
The :mod:`ldapdriver` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.ldapdriver
:members:
:undoc-members:
:show-inheritance:
The :mod:`dbdriver` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.dbdriver
:members:
:undoc-members:
:show-inheritance:
API Integration
---------------
The :mod:`signer` Module
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.signer .. automodule:: nova.auth.signer
@ -69,8 +37,39 @@ The :mod:`signer` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Related Tests
------------- Auth Manager
------------
The :mod:`nova.auth.manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.manager
:members:
:undoc-members:
:show-inheritance:
The :mod:`nova.auth.ldapdriver` Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.ldapdriver
:members:
:undoc-members:
:show-inheritance:
The :mod:`nova.auth.dbdriver` Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.auth.dbdriver
:members:
:undoc-members:
:show-inheritance:
Tests
-----
The :mod:`auth_unittest` Module The :mod:`auth_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -80,6 +79,7 @@ The :mod:`auth_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`access_unittest` Module The :mod:`access_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -88,6 +88,7 @@ The :mod:`access_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`quota_unittest` Module The :mod:`quota_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -96,7 +97,8 @@ The :mod:`quota_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
legacy docs
Legacy Docs
----------- -----------
Nova provides RBAC (Role-based access control) of the AWS-type APIs. We define the following roles: Nova provides RBAC (Role-based access control) of the AWS-type APIs. We define the following roles:
@ -104,12 +106,14 @@ Nova provides RBAC (Role-based access control) of the AWS-type APIs. We define t
Roles-Based Access Control of AWS-style APIs using SAML Assertions 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” “Achieving FIPS 199 Moderate certification of a hybrid cloud environment using CloudAudit and declarative C.I.A. classifications”
Introduction 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. 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. 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 Relationship of US eAuth to RBAC
-------------------------------- --------------------------------
@ -125,6 +129,7 @@ In more ideal implementations, the remainder of the application-specific account
.. _auth_roles: .. _auth_roles:
Roles Roles
----- -----
@ -172,6 +177,7 @@ Cloud Administrator/IT-Security:
* All permissions * All permissions
Enhancements Enhancements
------------ ------------
@ -182,6 +188,7 @@ Enhancements
Wrapping the SAML token into the API calls. 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. Then store the UID (fetched via backchannel) into the instance metadata, providing end-to-end auditability of ownership and responsibility, without PII.
CloudAudit APIs CloudAudit APIs
--------------- ---------------
@ -192,6 +199,7 @@ CloudAudit APIs
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. 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. RBAC of CloudAudit API calls is critical, since detailed system information is a system vulnerability.
Type declarations Type declarations
----------------- -----------------
* Data declarations – Volumes and Objects * Data declarations – Volumes and Objects
@ -203,17 +211,19 @@ Existing API calls to launch instances specific a single, combined “type” fl
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.) 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 Request Brokering
----------------- -----------------
* Cloud Interop * Cloud Interop
* IMF Registration / PubSub * IMF Registration / PubSub
* Digital C&A * 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. 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. 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 Dirty Cloud – Hybrid Data Centers
--------------------------------- ---------------------------------
@ -226,12 +236,14 @@ This interconnect is typically a bridged VPN connection. Any machines that can b
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. 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 The Details
----------- -----------
* Preliminary Roles Definitions * Preliminary Roles Definitions
* Categorization of available API calls * Categorization of available API calls
* SAML assertion vocabulary * SAML assertion vocabulary
System limits System limits
------------- -------------
@ -249,10 +261,8 @@ The following limits need to be defined and enforced:
Further Challenges 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
* 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

13
doc/source/devguide/cloudpipe.rst → doc/source/devref/cloudpipe.rst
View File

@ -23,11 +23,13 @@ Cloudpipe -- Per Project Vpns
Cloudpipe is a method for connecting end users to their project insnances in vlan mode. Cloudpipe is a method for connecting end users to their project insnances in vlan mode.
Overview Overview
-------- --------
The support code for cloudpipe implements admin commands (via nova-manage) to automatically create a vm for a project that allows users to vpn into the private network of their project. Access to this vpn is provided through a public port on the network host for the project. This allows users to have free access to the virtual machines in their project without exposing those machines to the public internet. The support code for cloudpipe implements admin commands (via nova-manage) to automatically create a vm for a project that allows users to vpn into the private network of their project. Access to this vpn is provided through a public port on the network host for the project. This allows users to have free access to the virtual machines in their project without exposing those machines to the public internet.
Cloudpipe Image Cloudpipe Image
--------------- ---------------
@ -35,6 +37,7 @@ The cloudpipe image is basically just a linux instance with openvpn installed.
It is also useful to have a cron script that will periodically redownload the metadata and copy the new crl. This will keep revoked users from connecting and will disconnect any users that are connected with revoked certificates when their connection is renegotiated (every hour). It is also useful to have a cron script that will periodically redownload the metadata and copy the new crl. This will keep revoked users from connecting and will disconnect any users that are connected with revoked certificates when their connection is renegotiated (every hour).
Cloudpipe Launch Cloudpipe Launch
---------------- ----------------
@ -46,6 +49,7 @@ When you use nova-manage to launch a cloudpipe for a user, it goes through the f
#. zips up the info and puts it b64 encoded as user data #. zips up the info and puts it b64 encoded as user data
#. launches an m1.tiny instance with the above settings using the flag-specified vpn image #. launches an m1.tiny instance with the above settings using the flag-specified vpn image
Vpn Access Vpn Access
---------- ----------
@ -59,7 +63,8 @@ Certificates and Revocation
If the use_project_ca flag is set (required to for cloudpipes to work securely), then each project has its own ca. This ca is used to sign the certificate for the vpn, and is also passed to the user for bundling images. When a certificate is revoked using nova-manage, a new Certificate Revocation List (crl) is generated. As long as cloudpipe has an updated crl, it will block revoked users from connecting to the vpn. If the use_project_ca flag is set (required to for cloudpipes to work securely), then each project has its own ca. This ca is used to sign the certificate for the vpn, and is also passed to the user for bundling images. When a certificate is revoked using nova-manage, a new Certificate Revocation List (crl) is generated. As long as cloudpipe has an updated crl, it will block revoked users from connecting to the vpn.
The :mod:`cloudpipe` Module
The :mod:`nova.cloudpipe.pipelib` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.cloudpipe.pipelib .. automodule:: nova.cloudpipe.pipelib
@ -67,7 +72,8 @@ The :mod:`cloudpipe` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`api.cloudpipe` Module
The :mod:`nova.api.cloudpipe` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.api.cloudpipe .. automodule:: nova.api.cloudpipe
@ -75,7 +81,8 @@ The :mod:`api.cloudpipe` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`crypto` Module
The :mod:`nova.crypto` Module
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.crypto .. automodule:: nova.crypto

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

@ -16,19 +16,18 @@
under the License. under the License.
Virtualization Programming Guide Virtualization
================================ ==============
This page contains the Compute Package documentation.
Manager Compute
------- -------
Documentation for the compute manager and related files. For reading about Documentation for the compute manager and related files. For reading about
a specific virtualization backend, read Drivers_. a specific virtualization backend, read Drivers_.
The :mod:`manager` Module The :mod:`nova.compute.manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.manager .. automodule:: nova.compute.manager
@ -36,7 +35,7 @@ The :mod:`manager` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`connection` Module The :mod:`nova.virt.connection` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.virt.connection .. automodule:: nova.virt.connection
@ -44,7 +43,7 @@ The :mod:`connection` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`disk` Module The :mod:`nova.compute.disk` Module
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.disk .. automodule:: nova.compute.disk
@ -52,7 +51,7 @@ The :mod:`disk` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`images` Module The :mod:`nova.virt.images` Module
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.virt.images .. automodule:: nova.virt.images
@ -61,7 +60,7 @@ The :mod:`images` Module
:show-inheritance: :show-inheritance:
The :mod:`instance_types` Module The :mod:`nova.compute.instance_types` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.instance_types .. automodule:: nova.compute.instance_types
@ -70,7 +69,7 @@ The :mod:`instance_types` Module
:show-inheritance: :show-inheritance:
The :mod:`power_state` Module The :mod:`nova.compute.power_state` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.power_state .. automodule:: nova.compute.power_state
@ -82,42 +81,38 @@ The :mod:`power_state` Module
Drivers Drivers
------- -------
Libvirt Implementations
~~~~~~~~~~~~~~~~~~~~~~~
The libvirt driver is capable of supporting KVM, QEMU, and UML. The :mod:`nova.virt.libvirt_conn` Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`libvirt_conn` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.virt.libvirt_conn .. automodule:: nova.virt.libvirt_conn
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
XEN
~~~
The :mod:`xenapi` Module The :mod:`nova.virt.xenapi` Driver
^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.virt.xenapi .. automodule:: nova.virt.xenapi
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
FAKE
~~~~ The :mod:`nova.virt.fake` Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.virt.fake .. automodule:: nova.virt.fake
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Monitoring Monitoring
---------- ----------
The :mod:`monitor` Module The :mod:`nova.compute.monitor` Module
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.compute.monitor .. automodule:: nova.compute.monitor

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

@ -15,10 +15,10 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Database Programming Guide The Database Layer
========================== ==================
The :mod:`api` Module The :mod:`nova.db.api` Module
--------------------- ---------------------
.. automodule:: nova.db.api .. automodule:: nova.db.api
@ -27,33 +27,31 @@ The :mod:`api` Module
:show-inheritance: :show-inheritance:
Drivers The Sqlalchemy Driver
------- ---------------------
Driver: Sqlalchemy The :mod:`nova.db.sqlalchemy.api` Module
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :mod:`sqlalchemy.api` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. automodule:: nova.db.sqlalchemy.api .. automodule:: nova.db.sqlalchemy.api
The :mod:`sqlalchemy.models` Module The :mod:`nova.db.sqlalchemy.models` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.db.sqlalchemy.models .. automodule:: nova.db.sqlalchemy.models
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`sqlalchemy.session` Module The :mod:`nova.db.sqlalchemy.session` Module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.db.sqlalchemy.session .. automodule:: nova.db.sqlalchemy.session
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Tests Tests
----- -----

0
doc/source/devguide/development.environment.rst → doc/source/devref/development.environment.rst
View File

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

@ -15,13 +15,16 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Fakes Programming Guide Fake Drivers
======================= ============
.. todo:: document general info about fakes .. todo:: document general info about fakes
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.
The :mod:`virt.fake` Module
The :mod:`nova.virt.fake` Module
--------------------------- ---------------------------
.. automodule:: nova.virt.fake .. automodule:: nova.virt.fake
@ -29,8 +32,9 @@ The :mod:`virt.fake` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
:noindex: :noindex:
The :mod:`fakeldap` Module
The :mod:`nova.auth.fakeldap` Module
-------------------------- --------------------------
.. automodule:: nova.auth.fakeldap .. automodule:: nova.auth.fakeldap
@ -38,7 +42,8 @@ The :mod:`fakeldap` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`fakerabbit` Module
The :mod:`nova.fakerabbit` Module
---------------------------- ----------------------------
.. automodule:: nova.fakerabbit .. automodule:: nova.fakerabbit
@ -46,7 +51,8 @@ The :mod:`fakerabbit` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :class:`FakeAOEDriver` Class
The :class:`nova.volume.driver.FakeAOEDriver` Class
-------------------------------- --------------------------------
.. autoclass:: nova.volume.driver.FakeAOEDriver .. autoclass:: nova.volume.driver.FakeAOEDriver
@ -54,7 +60,8 @@ The :class:`FakeAOEDriver` Class
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :class:`service_unittest.FakeManager` Class
The :class:`nova.tests.service_unittest.FakeManager` Class
----------------------------------------------- -----------------------------------------------
.. autoclass:: nova.tests.service_unittest.FakeManager .. autoclass:: nova.tests.service_unittest.FakeManager
@ -62,7 +69,8 @@ The :class:`service_unittest.FakeManager` Class
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`api.openstack.fakes` Module
The :mod:`nova.tests.api.openstack.fakes` Module
------------------------------------------------ ------------------------------------------------
.. automodule:: nova.tests.api.openstack.fakes .. automodule:: nova.tests.api.openstack.fakes

6
doc/source/devref/glance.rst
View File

@ -15,10 +15,10 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Glance Integration Programming Guide Glance Integration - The Future of File Storage
==================================== ===============================================
The :mod:`image.service` Module The :mod:`nova.image.service` Module
------------------------------- -------------------------------
.. automodule:: nova.image.service .. automodule:: nova.image.service

9
doc/source/devguide/index.rst → doc/source/devref/index.rst
View File

@ -15,13 +15,14 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Nova Development Guide Nova Development Reference
====================== ==========================
Nova is written in python. Nova is written in Python.
Prerequisites Prerequisites
------------- -------------
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
@ -34,7 +35,7 @@ Contents
-------- --------
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 3
services services
database database

15
doc/source/devref/network.rst
View File

@ -15,24 +15,25 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Networking Programming Guide Networking
============================ ==========
.. todo:: .. todo::
* document hardware specific commands (maybe in admin guide?) (todd) * document hardware specific commands (maybe in admin guide?) (todd)
* document a map between flags and managers/backends (todd) * document a map between flags and managers/backends (todd)
The :mod:`Manager` module
------------------------- The :mod:`nova.network.manager` Module
--------------------------------------
.. automodule:: nova.network.manager .. automodule:: nova.network.manager
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`LinuxNet` driver The :mod:`nova.network.linux_net` Driver
-------------------------- ----------------------------------------
.. automodule:: nova.network.linux_net .. automodule:: nova.network.linux_net
:members: :members:
@ -51,7 +52,7 @@ The :mod:`network_unittest` Module
:show-inheritance: :show-inheritance:
legacy docs Legacy docs
----------- -----------
The nova networking components manage private networks, public IP addressing, VPN connectivity, and firewall rules. The nova networking components manage private networks, public IP addressing, VPN connectivity, and firewall rules.

52
doc/source/devref/nova.rst
View File

@ -15,10 +15,14 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Nova Libraries Programming Guide Common and Misc Libraries
================================ =========================
The :mod:`adminclient` Module Libraries common throughout Nova or just ones that haven't been categorized
very well yet.
The :mod:`nova.adminclient` Module
----------------------------- -----------------------------
.. automodule:: nova.adminclient .. automodule:: nova.adminclient
@ -26,7 +30,8 @@ The :mod:`adminclient` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`context` Module
The :mod:`nova.context` Module
------------------------- -------------------------
.. automodule:: nova.context .. automodule:: nova.context
@ -34,7 +39,8 @@ The :mod:`context` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`exception` Module
The :mod:`nova.exception` Module
--------------------------- ---------------------------
.. automodule:: nova.exception .. automodule:: nova.exception
@ -42,7 +48,8 @@ The :mod:`exception` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`flags` Module
The :mod:`nova.flags` Module
----------------------- -----------------------
.. automodule:: nova.flags .. automodule:: nova.flags
@ -50,7 +57,8 @@ The :mod:`flags` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`process` Module
The :mod:`nova.process` Module
------------------------- -------------------------
.. automodule:: nova.process .. automodule:: nova.process
@ -58,7 +66,8 @@ The :mod:`process` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`rpc` Module
The :mod:`nova.rpc` Module
--------------------- ---------------------
.. automodule:: nova.rpc .. automodule:: nova.rpc
@ -66,7 +75,8 @@ The :mod:`rpc` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`server` Module
The :mod:`nova.server` Module
------------------------ ------------------------
.. automodule:: nova.server .. automodule:: nova.server
@ -74,7 +84,8 @@ The :mod:`server` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`test` Module
The :mod:`nova.test` Module
---------------------- ----------------------
.. automodule:: nova.test .. automodule:: nova.test
@ -82,7 +93,8 @@ The :mod:`test` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`twistd` Module
The :mod:`nova.twistd` Module
------------------------ ------------------------
.. automodule:: nova.twistd .. automodule:: nova.twistd
@ -90,7 +102,8 @@ The :mod:`twistd` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`utils` Module
The :mod:`nova.utils` Module
----------------------- -----------------------
.. automodule:: nova.utils .. automodule:: nova.utils
@ -98,7 +111,8 @@ The :mod:`utils` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`validate` Module
The :mod:`nova.validate` Module
-------------------------- --------------------------
.. automodule:: nova.validate .. automodule:: nova.validate
@ -106,7 +120,8 @@ The :mod:`validate` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`wsgi` Module
The :mod:`nova.wsgi` Module
---------------------- ----------------------
.. automodule:: nova.wsgi .. automodule:: nova.wsgi
@ -114,6 +129,7 @@ The :mod:`wsgi` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Tests Tests
----- -----
@ -125,6 +141,7 @@ The :mod:`declare_flags` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`fake_flags` Module The :mod:`fake_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -133,6 +150,7 @@ The :mod:`fake_flags` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`flags_unittest` Module The :mod:`flags_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -141,6 +159,7 @@ The :mod:`flags_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`process_unittest` Module The :mod:`process_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -149,6 +168,7 @@ The :mod:`process_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`real_flags` Module The :mod:`real_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -157,6 +177,7 @@ The :mod:`real_flags` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`rpc_unittest` Module The :mod:`rpc_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -165,6 +186,7 @@ The :mod:`rpc_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`runtime_flags` Module The :mod:`runtime_flags` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -173,6 +195,7 @@ The :mod:`runtime_flags` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`twistd_unittest` Module The :mod:`twistd_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -181,6 +204,7 @@ The :mod:`twistd_unittest` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`validator_unittest` Module The :mod:`validator_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

16
doc/source/devref/objectstore.rst
View File

@ -15,10 +15,10 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Objectstore Programming Guide Objectstore - File Storage Service
============================= ==================================
The :mod:`handler` Module The :mod:`nova.objectstore.handler` Module
------------------------- -------------------------
.. automodule:: nova.objectstore.handler .. automodule:: nova.objectstore.handler
@ -26,7 +26,8 @@ The :mod:`handler` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`bucket` Module
The :mod:`nova.objectstore.bucket` Module
------------------------ ------------------------
.. automodule:: nova.objectstore.bucket .. automodule:: nova.objectstore.bucket
@ -34,7 +35,8 @@ The :mod:`bucket` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`stored` Module
The :mod:`nova.objectstore.stored` Module
------------------------ ------------------------
.. automodule:: nova.objectstore.stored .. automodule:: nova.objectstore.stored
@ -42,7 +44,8 @@ The :mod:`stored` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`image` Module
The :mod:`nova.objecstore.image` Module
----------------------- -----------------------
.. automodule:: nova.objectstore.image .. automodule:: nova.objectstore.image
@ -50,6 +53,7 @@ The :mod:`image` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Tests Tests
----- -----

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

@ -15,10 +15,10 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Scheduler Programming Guide Scheduler
=========================== =========
The :mod:`manager` Module The :mod:`nova.scheduler.manager` Module
------------------------- -------------------------
.. automodule:: nova.scheduler.manager .. automodule:: nova.scheduler.manager
@ -26,7 +26,8 @@ The :mod:`manager` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`driver` Module
The :mod:`nova.scheduler.driver` Module
------------------------ ------------------------
.. automodule:: nova.scheduler.driver .. automodule:: nova.scheduler.driver
@ -34,7 +35,8 @@ The :mod:`driver` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`chance` Module
The :mod:`nova.scheduler.chance` Driver
------------------------ ------------------------
.. automodule:: nova.scheduler.chance .. automodule:: nova.scheduler.chance
@ -42,7 +44,8 @@ The :mod:`chance` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
The :mod:`simple` Module
The :mod:`nova.scheduler.simple` Driver
------------------------ ------------------------
.. automodule:: nova.scheduler.simple .. automodule:: nova.scheduler.simple
@ -50,6 +53,7 @@ The :mod:`simple` Module
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Tests Tests
----- -----

37
doc/source/devguide/services.rst → doc/source/devref/services.rst
View File

@ -17,53 +17,34 @@
.. _service_manager_driver: .. _service_manager_driver:
Services Managers and Drivers Services, Managers and Drivers
============================= ==============================
The responsibilities of Services, Managers, and Drivers, can be a bit confusing to people that are new to nova. This document attempts to outline the division of responsibilities to make understanding the system a little bit easier. The responsibilities of Services, Managers, and Drivers, can be a bit confusing to people that are new to nova. This document attempts to outline the division of responsibilities to make understanding the system a little bit easier.
Currently, Managers and Drivers are specified by flags and loaded using utils.load_object(). This method allows for them to be implemented as singletons, classes, modules or objects. As long as the path specified by the flag leads to an object (or a callable that returns an object) that responds to getattr, it should work as a manager or driver. Currently, Managers and Drivers are specified by flags and loaded using utils.load_object(). This method allows for them to be implemented as singletons, classes, modules or objects. As long as the path specified by the flag leads to an object (or a callable that returns an object) that responds to getattr, it should work as a manager or driver.
Service
-------
A service is a very thin wrapper around a Manager object. It exposes the manager's public methods to other components of the system via rpc. It will report state periodically to the database and is responsible for initiating any periodic tasts that need to be executed on a given host. The :mod:`nova.service` Module
------------------------------
The :mod:`service` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.service .. automodule:: nova.service
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Manager
-------
Managers are responsible for a certain aspect of the sytem. It is a logical grouping of code relating to a portion of the system. In general other components should be using the manager to make changes to the components that it is responsible for. The :mod:`nova.manager` Module
------------------------------
For example, other components that need to deal with volumes in some way, should do so by calling methods on the VolumeManager instead of directly changing fields in the database. This allows us to keep all of the code relating to volumes in the same place.
We have adopted a basic strategy of Smart managers and dumb data, which means rather than attaching methods to data objects, components should call manager methods that act on the data.
Methods on managers that can be executed locally should be called directly. If a particular method must execute on a remote host, this should be done via rpc to the service that wraps the manager
Managers should be responsible for most of the db access, and non-implementation specific data. Anything implementation specific that can't be generalized should be done by the Driver.
In general, we prefer to have one manager with multiple drivers for different implementations, but sometimes it makes sense to have multiple managers. You can think of it this way: Abstract different overall strategies at the manager level(FlatNetwork vs VlanNetwork), and different implementations at the driver level(LinuxNetDriver vs CiscoNetDriver).
Managers will often provide methods for initial setup of a host or periodic tasksto a wrapping service.
The :mod:`manager` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.manager .. automodule:: nova.manager
:members: :members:
:undoc-members: :undoc-members:
:show-inheritance: :show-inheritance:
Driver
------ Implementation-Specific Drivers
-------------------------------
A manager will generally load a driver for some of its tasks. The driver is responsible for specific implementation details. Anything running shell commands on a host, or dealing with other non-python code should probably be happening in a driver. A manager will generally load a driver for some of its tasks. The driver is responsible for specific implementation details. Anything running shell commands on a host, or dealing with other non-python code should probably be happening in a driver.

7
doc/source/devref/volume.rst
View File

@ -15,8 +15,8 @@
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
Volume Programming Guide Storage Volumes, Disks
========================= ======================
.. todo:: rework after iSCSI merge (see 'Old Docs') (todd or vish) .. todo:: rework after iSCSI merge (see 'Old Docs') (todd or vish)
@ -41,6 +41,9 @@ The :mod:`nova.volume.driver` Module
Tests Tests
----- -----
The :mod:`volume_unittest` Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: nova.tests.volume_unittest .. automodule:: nova.tests.volume_unittest
:members: :members:
:undoc-members: :undoc-members:

2
doc/source/index.rst
View File

@ -45,7 +45,7 @@ Contents
concepts.and.introduction concepts.and.introduction
adminguide/index adminguide/index
devguide/index devref/index
reaching.out reaching.out
Recommended System Configuration Recommended System Configuration

34
nova/manager.py
View File

@ -15,8 +15,40 @@
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations # License for the specific language governing permissions and limitations
# under the License. # under the License.
""" """
Base class for managers of different parts of the system Managers are responsible for a certain aspect of the sytem. It is a logical
grouping of code relating to a portion of the system. In general other
components should be using the manager to make changes to the components that
it is responsible for.
For example, other components that need to deal with volumes in some way,
should do so by calling methods on the VolumeManager instead of directly
changing fields in the database. This allows us to keep all of the code
relating to volumes in the same place.
We have adopted a basic strategy of Smart managers and dumb data, which means
rather than attaching methods to data objects, components should call manager
methods that act on the data.
Methods on managers that can be executed locally should be called directly. If
a particular method must execute on a remote host, this should be done via rpc
to the service that wraps the manager
Managers should be responsible for most of the db access, and
non-implementation specific data. Anything implementation specific that can't
be generalized should be done by the Driver.
In general, we prefer to have one manager with multiple drivers for different
implementations, but sometimes it makes sense to have multiple managers. You
can think of it this way: Abstract different overall strategies at the manager
level(FlatNetwork vs VlanNetwork), and different implementations at the driver
level(LinuxNetDriver vs CiscoNetDriver).
Managers will often provide methods for initial setup of a host or periodic
tasksto a wrapping service.
This module provides Manager, a base class for managers.
""" """
from nova import utils from nova import utils

6
nova/service.py
View File

@ -17,7 +17,11 @@
# under the License. # under the License.
""" """
Generic Node baseclass for all workers that run on hosts A service is a very thin wrapper around a Manager object. It exposes the
manager's public methods to other components of the system via rpc. It will
report state periodically to the database and is responsible for initiating any periodic tasts that need to be executed on a given host.
This module contains Service, a generic baseclass for all workers.
""" """
import inspect import inspect