From c3054a9a55371fe3acf37589df7d81c6381d7220 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Fri, 5 Nov 2010 18:31:26 -0400 Subject: Document nova.sh environment. --- doc/source/adminguide/quickstart.rst | 52 +++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 7 deletions(-) (limited to 'doc/source') diff --git a/doc/source/adminguide/quickstart.rst b/doc/source/adminguide/quickstart.rst index 718ea7d14..7e746e3f2 100644 --- a/doc/source/adminguide/quickstart.rst +++ b/doc/source/adminguide/quickstart.rst @@ -18,16 +18,54 @@ Nova Quickstart =============== -.. todo:: +The `contrib/nova.sh` file in the source distribution is a script that +will quickly set up nova to run on a single machine. It is tested against +Ubuntu only, but other distributions are forthcoming. - * Document the assumptions about pluggable interfaces (sqlite3 instead of - mysql, etc) (todd) - * Document env vars that can change things (USE_MYSQL, HOST_IP) (todd) +Environment Variables +--------------------- +By tweaking the environment that nova.sh run in, you can build slightly +different configurations (though for more complex setups you should see +:doc:`/adminguide/getting.started` and :doc:`/adminguide/multi.node.install`). -The `contrib/novascript.sh` file in the source distribution is a script that -will quickly set up nova to run on a single machine. It is tested against -Ubuntu only, but other distributions are forthcoming. +HOST_IP +~~~~~~~ + +**Default**: address of first interface from the ifconfig command +**Values**: 127.0.0.1, or any other valid address + +TEST +~~~~ + +**Default**: 0 +**Values**: 1, run tests after checkout and initial setup + +USE_MYSQL +~~~~~~~~~ + +**Default**: 0, use sqlite3 +**Values**: 1, use mysql instead of sqlite3 + +MYSQL_PASS +~~~~~~~~~~ + +Only useful if $USE_MYSQL=1. + +**Default**: nova +**Values**: value of root password for mysql + +USE_LDAP +~~~~~~~~ + +**Default**: 0, use :mod:`nova.auth.dbdriver` +**Values**: 1, use :mod:`nova.auth.ldapdriver` + +LIBVIRT_TYPE +~~~~~~~~~~~~ + +**Default**: qemu +**Values**: uml, kvm Usage ----- -- cgit From a8a61d61db0b00e0b397c807ac8ca89e39a26c5b Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Fri, 5 Nov 2010 19:52:12 -0400 Subject: Fix docstrings for wsigfied methods. --- doc/source/devguide/cloudpipe.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc/source') diff --git a/doc/source/devguide/cloudpipe.rst b/doc/source/devguide/cloudpipe.rst index d632a40e6..5264a0f39 100644 --- a/doc/source/devguide/cloudpipe.rst +++ b/doc/source/devguide/cloudpipe.rst @@ -67,6 +67,14 @@ The :mod:`cloudpipe` Module :undoc-members: :show-inheritance: +The :mod:`api.cloudpipe` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.api.cloudpipe + :members: + :undoc-members: + :show-inheritance: + The :mod:`crypto` Module ~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit From 12a0d661d69281811885f9bd4e7f3b1ec3a758a8 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Fri, 5 Nov 2010 19:53:31 -0400 Subject: remove finished todo --- doc/source/devguide/api.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc/source') diff --git a/doc/source/devguide/api.rst b/doc/source/devguide/api.rst index d1d50d745..cad0e820a 100644 --- a/doc/source/devguide/api.rst +++ b/doc/source/devguide/api.rst @@ -18,8 +18,6 @@ API Endpoint Programming Guide ============================== -.. todo:: get actual docstrings from ec2/osapi_verions instead of @wsgify - 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. -- cgit From 9dcc76485b6fe4cf4218b9fdca45a75a392e508b Mon Sep 17 00:00:00 2001 From: Andy Smith Date: Mon, 8 Nov 2010 00:06:19 +0900 Subject: Build autodocs for all our libraries. Also updates doc build process and adds a README for it. --- doc/source/Makefile | 89 ----------------------------------------------------- 1 file changed, 89 deletions(-) delete mode 100644 doc/source/Makefile (limited to 'doc/source') diff --git a/doc/source/Makefile b/doc/source/Makefile deleted file mode 100644 index b2f74e85a..000000000 --- a/doc/source/Makefile +++ /dev/null @@ -1,89 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nova.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc" - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." -- cgit From 006b3ab0c7b8699e63df2a2884c53abd3ba37658 Mon Sep 17 00:00:00 2001 From: Andy Smith Date: Mon, 8 Nov 2010 02:00:48 +0900 Subject: Switch to module-per-file for the module index. Rename development guide to development reference. --- doc/source/devguide/api.rst | 267 ------------------------ doc/source/devguide/architecture.rst | 52 ----- doc/source/devguide/auth.rst | 258 ----------------------- doc/source/devguide/cloudpipe.rst | 85 -------- doc/source/devguide/compute.rst | 146 ------------- doc/source/devguide/database.rst | 61 ------ doc/source/devguide/development.environment.rst | 21 -- doc/source/devguide/fakes.rst | 72 ------- doc/source/devguide/glance.rst | 27 --- doc/source/devguide/index.rst | 60 ------ doc/source/devguide/network.rst | 124 ----------- doc/source/devguide/nova.rst | 190 ----------------- doc/source/devguide/objectstore.rst | 62 ------ doc/source/devguide/scheduler.rst | 62 ------ doc/source/devguide/services.rst | 72 ------- doc/source/devguide/volume.rst | 60 ------ doc/source/devref/api.rst | 267 ++++++++++++++++++++++++ doc/source/devref/architecture.rst | 52 +++++ doc/source/devref/auth.rst | 258 +++++++++++++++++++++++ doc/source/devref/cloudpipe.rst | 85 ++++++++ doc/source/devref/compute.rst | 146 +++++++++++++ doc/source/devref/database.rst | 61 ++++++ doc/source/devref/development.environment.rst | 21 ++ doc/source/devref/fakes.rst | 72 +++++++ doc/source/devref/glance.rst | 27 +++ doc/source/devref/index.rst | 60 ++++++ doc/source/devref/network.rst | 124 +++++++++++ doc/source/devref/nova.rst | 190 +++++++++++++++++ doc/source/devref/objectstore.rst | 62 ++++++ doc/source/devref/scheduler.rst | 62 ++++++ doc/source/devref/services.rst | 72 +++++++ doc/source/devref/volume.rst | 60 ++++++ doc/source/index.rst | 2 +- 33 files changed, 1620 insertions(+), 1620 deletions(-) delete mode 100644 doc/source/devguide/api.rst delete mode 100644 doc/source/devguide/architecture.rst delete mode 100644 doc/source/devguide/auth.rst delete mode 100644 doc/source/devguide/cloudpipe.rst delete mode 100644 doc/source/devguide/compute.rst delete mode 100644 doc/source/devguide/database.rst delete mode 100644 doc/source/devguide/development.environment.rst delete mode 100644 doc/source/devguide/fakes.rst delete mode 100644 doc/source/devguide/glance.rst delete mode 100644 doc/source/devguide/index.rst delete mode 100644 doc/source/devguide/network.rst delete mode 100644 doc/source/devguide/nova.rst delete mode 100644 doc/source/devguide/objectstore.rst delete mode 100644 doc/source/devguide/scheduler.rst delete mode 100644 doc/source/devguide/services.rst delete mode 100644 doc/source/devguide/volume.rst create mode 100644 doc/source/devref/api.rst create mode 100644 doc/source/devref/architecture.rst create mode 100644 doc/source/devref/auth.rst create mode 100644 doc/source/devref/cloudpipe.rst create mode 100644 doc/source/devref/compute.rst create mode 100644 doc/source/devref/database.rst create mode 100644 doc/source/devref/development.environment.rst create mode 100644 doc/source/devref/fakes.rst create mode 100644 doc/source/devref/glance.rst create mode 100644 doc/source/devref/index.rst create mode 100644 doc/source/devref/network.rst create mode 100644 doc/source/devref/nova.rst create mode 100644 doc/source/devref/objectstore.rst create mode 100644 doc/source/devref/scheduler.rst create mode 100644 doc/source/devref/services.rst create mode 100644 doc/source/devref/volume.rst (limited to 'doc/source') diff --git a/doc/source/devguide/api.rst b/doc/source/devguide/api.rst deleted file mode 100644 index cad0e820a..000000000 --- a/doc/source/devguide/api.rst +++ /dev/null @@ -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: - diff --git a/doc/source/devguide/architecture.rst b/doc/source/devguide/architecture.rst deleted file mode 100644 index 1e23e1361..000000000 --- a/doc/source/devguide/architecture.rst +++ /dev/null @@ -1,52 +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 System Architecture -======================== - -Nova is built on a shared-nothing, messaging-based architecture. All of the major nova components can be run on multiple servers. This means that most component to component communication must go via message queue. In order to avoid blocking each component while waiting for a response, we use deferred objects, with a callback that gets triggered when a response is received. - -Nova recently moved to using a sql-based central database that is shared by all components 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, nova will be moving towards multiple data stores with some kind of aggregation system. - -Components ----------- - -Below you will find a helpful explanation of the different components. - -:: - - /- ( LDAP ) - [ Auth Manager ] --- - | \- ( DB ) - | - | [ scheduler ] - [ volume ] - ( ATAoE/iSCSI ) - | / - [ Web Dashboard ] -> [ api ] -- < AMQP > ------ [ network ] - ( Flat/Vlan ) - | \ - < HTTP > [ scheduler ] - [ compute ] - ( libvirt/xen ) - | | - [ objectstore ] < - retrieves images - -* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) -* Web Dashboard: potential external component that talks to the api -* api: component that receives http requests, converts commands and communicates with other components via the queue or http (in the case of objectstore) -* 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. -* objectstore: twisted http server that replicates s3 api and allows storage and retrieval of images -* scheduler: decides which host gets each vm and volume -* volume: manages dynamically attachable block devices. -* network: manages ip forwarding, bridges, and vlans -* compute: manages communication with hypervisor and virtual machines. diff --git a/doc/source/devguide/auth.rst b/doc/source/devguide/auth.rst deleted file mode 100644 index 77d97f68b..000000000 --- a/doc/source/devguide/auth.rst +++ /dev/null @@ -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 - - - diff --git a/doc/source/devguide/cloudpipe.rst b/doc/source/devguide/cloudpipe.rst deleted file mode 100644 index 5264a0f39..000000000 --- a/doc/source/devguide/cloudpipe.rst +++ /dev/null @@ -1,85 +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. - - -.. _cloudpipe: - -Cloudpipe -- Per Project Vpns -============================= - -Cloudpipe is a method for connecting end users to their project insnances in vlan mode. - -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. - -Cloudpipe Image ---------------- - -The cloudpipe image is basically just a linux instance with openvpn installed. It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip. The autorun script will configure and run openvpn to run using the data from nova. - -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 ----------------- - -When you use nova-manage to launch a cloudpipe for a user, it goes through the following process: - -#. creates a keypair called -vpn and saves it in the keys directory -#. creates a security group -vpn and opens up 1194 and icmp -#. creates a cert and private key for the vpn instance and saves it in the CA/projects// directory -#. 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 - -Vpn Access ----------- - -In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance. This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world. The network for each project is given a specific high-numbered port on the public ip of the network host. This port is automatically forwarded to 1194 on the vpn instance. - -If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database. This will be turned into a nova-manage command or a flag soon. - - -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. - -The :mod:`cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.cloudpipe.pipelib - :members: - :undoc-members: - :show-inheritance: - -The :mod:`api.cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.api.cloudpipe - :members: - :undoc-members: - :show-inheritance: - -The :mod:`crypto` Module -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.crypto - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/source/devguide/compute.rst b/doc/source/devguide/compute.rst deleted file mode 100644 index e4c6c6ae7..000000000 --- a/doc/source/devguide/compute.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/database.rst b/doc/source/devguide/database.rst deleted file mode 100644 index b58ea147d..000000000 --- a/doc/source/devguide/database.rst +++ /dev/null @@ -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. diff --git a/doc/source/devguide/development.environment.rst b/doc/source/devguide/development.environment.rst deleted file mode 100644 index 34104c964..000000000 --- a/doc/source/devguide/development.environment.rst +++ /dev/null @@ -1,21 +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. - -Setting up a development environment -==================================== - -.. todo:: write this diff --git a/doc/source/devguide/fakes.rst b/doc/source/devguide/fakes.rst deleted file mode 100644 index 61622754c..000000000 --- a/doc/source/devguide/fakes.rst +++ /dev/null @@ -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: - diff --git a/doc/source/devguide/glance.rst b/doc/source/devguide/glance.rst deleted file mode 100644 index 3d0f4ebec..000000000 --- a/doc/source/devguide/glance.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/index.rst b/doc/source/devguide/index.rst deleted file mode 100644 index 6232a3181..000000000 --- a/doc/source/devguide/index.rst +++ /dev/null @@ -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. - -Nova Development Guide -====================== - -Nova is written in python. - -Prerequisites -------------- -.. toctree:: - :maxdepth: 1 - - ../concepts.and.introduction - architecture - development.environment - - -Contents --------- - -.. toctree:: - :maxdepth: 1 - - services - database - volume - compute - network - auth - api - scheduler - fakes - nova - cloudpipe - objectstore - glance - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/devguide/network.rst b/doc/source/devguide/network.rst deleted file mode 100644 index 318286383..000000000 --- a/doc/source/devguide/network.rst +++ /dev/null @@ -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) - | - <-- [RoutingNode] - | - [AddressingNode] --> | - ( VLAN ) - | <-- [BridgingNode] - | - - -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). diff --git a/doc/source/devguide/nova.rst b/doc/source/devguide/nova.rst deleted file mode 100644 index 58125dc80..000000000 --- a/doc/source/devguide/nova.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/objectstore.rst b/doc/source/devguide/objectstore.rst deleted file mode 100644 index 4087b5dd0..000000000 --- a/doc/source/devguide/objectstore.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/scheduler.rst b/doc/source/devguide/scheduler.rst deleted file mode 100644 index df820c2f2..000000000 --- a/doc/source/devguide/scheduler.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/services.rst b/doc/source/devguide/services.rst deleted file mode 100644 index 517a51901..000000000 --- a/doc/source/devguide/services.rst +++ /dev/null @@ -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. - -.. _service_manager_driver: - -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. - -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:`service` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.service - :members: - :undoc-members: - :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. - -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 - :members: - :undoc-members: - :show-inheritance: - -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. - -Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. - -It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/devguide/volume.rst b/doc/source/devguide/volume.rst deleted file mode 100644 index 19b750870..000000000 --- a/doc/source/devguide/volume.rst +++ /dev/null @@ -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. - - diff --git a/doc/source/devref/api.rst b/doc/source/devref/api.rst new file mode 100644 index 000000000..cad0e820a --- /dev/null +++ b/doc/source/devref/api.rst @@ -0,0 +1,267 @@ +.. + 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: + diff --git a/doc/source/devref/architecture.rst b/doc/source/devref/architecture.rst new file mode 100644 index 000000000..1e23e1361 --- /dev/null +++ b/doc/source/devref/architecture.rst @@ -0,0 +1,52 @@ +.. + 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 System Architecture +======================== + +Nova is built on a shared-nothing, messaging-based architecture. All of the major nova components can be run on multiple servers. This means that most component to component communication must go via message queue. In order to avoid blocking each component while waiting for a response, we use deferred objects, with a callback that gets triggered when a response is received. + +Nova recently moved to using a sql-based central database that is shared by all components 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, nova will be moving towards multiple data stores with some kind of aggregation system. + +Components +---------- + +Below you will find a helpful explanation of the different components. + +:: + + /- ( LDAP ) + [ Auth Manager ] --- + | \- ( DB ) + | + | [ scheduler ] - [ volume ] - ( ATAoE/iSCSI ) + | / + [ Web Dashboard ] -> [ api ] -- < AMQP > ------ [ network ] - ( Flat/Vlan ) + | \ + < HTTP > [ scheduler ] - [ compute ] - ( libvirt/xen ) + | | + [ objectstore ] < - retrieves images + +* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) +* Web Dashboard: potential external component that talks to the api +* api: component that receives http requests, converts commands and communicates with other components via the queue or http (in the case of objectstore) +* 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. +* objectstore: twisted http server that replicates s3 api and allows storage and retrieval of images +* scheduler: decides which host gets each vm and volume +* volume: manages dynamically attachable block devices. +* network: manages ip forwarding, bridges, and vlans +* compute: manages communication with hypervisor and virtual machines. diff --git a/doc/source/devref/auth.rst b/doc/source/devref/auth.rst new file mode 100644 index 000000000..77d97f68b --- /dev/null +++ b/doc/source/devref/auth.rst @@ -0,0 +1,258 @@ +.. + 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 + + + diff --git a/doc/source/devref/cloudpipe.rst b/doc/source/devref/cloudpipe.rst new file mode 100644 index 000000000..5264a0f39 --- /dev/null +++ b/doc/source/devref/cloudpipe.rst @@ -0,0 +1,85 @@ +.. + 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. + + +.. _cloudpipe: + +Cloudpipe -- Per Project Vpns +============================= + +Cloudpipe is a method for connecting end users to their project insnances in vlan mode. + +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. + +Cloudpipe Image +--------------- + +The cloudpipe image is basically just a linux instance with openvpn installed. It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip. The autorun script will configure and run openvpn to run using the data from nova. + +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 +---------------- + +When you use nova-manage to launch a cloudpipe for a user, it goes through the following process: + +#. creates a keypair called -vpn and saves it in the keys directory +#. creates a security group -vpn and opens up 1194 and icmp +#. creates a cert and private key for the vpn instance and saves it in the CA/projects// directory +#. 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 + +Vpn Access +---------- + +In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance. This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world. The network for each project is given a specific high-numbered port on the public ip of the network host. This port is automatically forwarded to 1194 on the vpn instance. + +If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database. This will be turned into a nova-manage command or a flag soon. + + +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. + +The :mod:`cloudpipe` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.cloudpipe.pipelib + :members: + :undoc-members: + :show-inheritance: + +The :mod:`api.cloudpipe` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.api.cloudpipe + :members: + :undoc-members: + :show-inheritance: + +The :mod:`crypto` Module +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.crypto + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/source/devref/compute.rst b/doc/source/devref/compute.rst new file mode 100644 index 000000000..e4c6c6ae7 --- /dev/null +++ b/doc/source/devref/compute.rst @@ -0,0 +1,146 @@ +.. + 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: diff --git a/doc/source/devref/database.rst b/doc/source/devref/database.rst new file mode 100644 index 000000000..b58ea147d --- /dev/null +++ b/doc/source/devref/database.rst @@ -0,0 +1,61 @@ +.. + 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. diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst new file mode 100644 index 000000000..34104c964 --- /dev/null +++ b/doc/source/devref/development.environment.rst @@ -0,0 +1,21 @@ +.. + 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. + +Setting up a development environment +==================================== + +.. todo:: write this diff --git a/doc/source/devref/fakes.rst b/doc/source/devref/fakes.rst new file mode 100644 index 000000000..61622754c --- /dev/null +++ b/doc/source/devref/fakes.rst @@ -0,0 +1,72 @@ +.. + 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: + diff --git a/doc/source/devref/glance.rst b/doc/source/devref/glance.rst new file mode 100644 index 000000000..3d0f4ebec --- /dev/null +++ b/doc/source/devref/glance.rst @@ -0,0 +1,27 @@ +.. + 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: diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 000000000..a14460405 --- /dev/null +++ b/doc/source/devref/index.rst @@ -0,0 +1,60 @@ +.. + 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 Development Reference +========================== + +Nova is written in python. + +Prerequisites +------------- +.. toctree:: + :maxdepth: 1 + + ../concepts.and.introduction + architecture + development.environment + + +Contents +-------- + +.. toctree:: + :maxdepth: 3 + + services + database + volume + compute + network + auth + api + scheduler + fakes + nova + cloudpipe + objectstore + glance + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/devref/network.rst b/doc/source/devref/network.rst new file mode 100644 index 000000000..318286383 --- /dev/null +++ b/doc/source/devref/network.rst @@ -0,0 +1,124 @@ +.. + 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) + | + <-- [RoutingNode] + | + [AddressingNode] --> | + ( VLAN ) + | <-- [BridgingNode] + | + + +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). diff --git a/doc/source/devref/nova.rst b/doc/source/devref/nova.rst new file mode 100644 index 000000000..58125dc80 --- /dev/null +++ b/doc/source/devref/nova.rst @@ -0,0 +1,190 @@ +.. + 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: diff --git a/doc/source/devref/objectstore.rst b/doc/source/devref/objectstore.rst new file mode 100644 index 000000000..4087b5dd0 --- /dev/null +++ b/doc/source/devref/objectstore.rst @@ -0,0 +1,62 @@ +.. + 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: diff --git a/doc/source/devref/scheduler.rst b/doc/source/devref/scheduler.rst new file mode 100644 index 000000000..df820c2f2 --- /dev/null +++ b/doc/source/devref/scheduler.rst @@ -0,0 +1,62 @@ +.. + 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: diff --git a/doc/source/devref/services.rst b/doc/source/devref/services.rst new file mode 100644 index 000000000..517a51901 --- /dev/null +++ b/doc/source/devref/services.rst @@ -0,0 +1,72 @@ +.. + 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. + +.. _service_manager_driver: + +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. + +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:`service` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.service + :members: + :undoc-members: + :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. + +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 + :members: + :undoc-members: + :show-inheritance: + +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. + +Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. + +It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/devref/volume.rst b/doc/source/devref/volume.rst new file mode 100644 index 000000000..19b750870 --- /dev/null +++ b/doc/source/devref/volume.rst @@ -0,0 +1,60 @@ +.. + 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. + + diff --git a/doc/source/index.rst b/doc/source/index.rst index 4ef75c432..f96d5ff80 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,7 +45,7 @@ Contents concepts.and.introduction adminguide/index - devguide/index + devref/index reaching.out Recommended System Configuration -- cgit From 7ca2d7593e7faf36bab9d6cb1c8b0ba16494679f Mon Sep 17 00:00:00 2001 From: Andy Smith Date: Mon, 8 Nov 2010 02:54:28 +0900 Subject: Normalization of Dev reference docs. --- doc/source/devref/api.rst | 6 ++-- doc/source/devref/auth.rst | 74 ++++++++++++++++++++++----------------- doc/source/devref/cloudpipe.rst | 13 +++++-- doc/source/devref/compute.rst | 41 ++++++++++------------ doc/source/devref/database.rst | 26 +++++++------- doc/source/devref/fakes.rst | 26 +++++++++----- doc/source/devref/glance.rst | 6 ++-- doc/source/devref/index.rst | 3 +- doc/source/devref/network.rst | 15 ++++---- doc/source/devref/nova.rst | 52 +++++++++++++++++++-------- doc/source/devref/objectstore.rst | 16 +++++---- doc/source/devref/scheduler.rst | 16 +++++---- doc/source/devref/services.rst | 37 +++++--------------- doc/source/devref/volume.rst | 7 ++-- 14 files changed, 187 insertions(+), 151 deletions(-) (limited to 'doc/source') diff --git a/doc/source/devref/api.rst b/doc/source/devref/api.rst index cad0e820a..e9b79d8dd 100644 --- a/doc/source/devref/api.rst +++ b/doc/source/devref/api.rst @@ -15,8 +15,8 @@ License for the specific language governing permissions and limitations under the License. -API Endpoint Programming Guide -============================== +API Endpoint +============ 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 @@ -33,7 +33,7 @@ The :mod:`nova.api` Module :undoc-members: :show-inheritance: -The :mod:`cloud` Module +The :mod:`nova.api.cloud` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.cloud diff --git a/doc/source/devref/auth.rst b/doc/source/devref/auth.rst index 77d97f68b..ee82df5ab 100644 --- a/doc/source/devref/auth.rst +++ b/doc/source/devref/auth.rst @@ -17,10 +17,10 @@ .. _auth: -Authentication and Authorization Programming Guide -================================================== +Authentication and Authorization +================================ -The :mod:`quota` Module +The :mod:`nova.quota` Module ----------------------- .. automodule:: nova.quota @@ -28,10 +28,20 @@ The :mod:`quota` Module :undoc-members: :show-inheritance: + +The :mod:`nova.auth.signer` Module +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.auth.signer + :members: + :undoc-members: + :show-inheritance: + + Auth Manager ------------ -The :mod:`manager` Module +The :mod:`nova.auth.manager` Module ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.manager @@ -39,10 +49,8 @@ The :mod:`manager` Module :undoc-members: :show-inheritance: -Drivers -------- -The :mod:`ldapdriver` Module +The :mod:`nova.auth.ldapdriver` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.ldapdriver @@ -50,7 +58,7 @@ The :mod:`ldapdriver` Module :undoc-members: :show-inheritance: -The :mod:`dbdriver` Module +The :mod:`nova.auth.dbdriver` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.dbdriver @@ -58,19 +66,10 @@ The :mod:`dbdriver` Module :undoc-members: :show-inheritance: -API Integration ---------------- -The :mod:`signer` Module -~~~~~~~~~~~~~~~~~~~~~~~~ +Tests +----- -.. automodule:: nova.auth.signer - :members: - :undoc-members: - :show-inheritance: - -Related Tests -------------- The :mod:`auth_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,6 +79,7 @@ The :mod:`auth_unittest` Module :undoc-members: :show-inheritance: + The :mod:`access_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -88,6 +88,7 @@ The :mod:`access_unittest` Module :undoc-members: :show-inheritance: + The :mod:`quota_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -96,7 +97,8 @@ The :mod:`quota_unittest` Module :undoc-members: :show-inheritance: -legacy docs + +Legacy Docs ----------- 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 “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 -------------------------------- @@ -125,6 +129,7 @@ In more ideal implementations, the remainder of the application-specific account .. _auth_roles: + Roles ----- @@ -172,6 +177,7 @@ Cloud Administrator/IT-Security: * All permissions + Enhancements ------------ @@ -182,6 +188,7 @@ Enhancements 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 --------------- @@ -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. RBAC of CloudAudit API calls is critical, since detailed system information is a system vulnerability. + Type declarations ----------------- * 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.) + Request Brokering ----------------- - * Cloud Interop - * IMF Registration / PubSub - * Digital C&A +* 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 --------------------------------- @@ -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. + The Details ----------- - * Preliminary Roles Definitions - * Categorization of available API calls - * SAML assertion vocabulary +* Preliminary Roles Definitions +* Categorization of available API calls +* SAML assertion vocabulary + System limits ------------- @@ -249,10 +261,8 @@ The following limits need to be defined and enforced: 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 diff --git a/doc/source/devref/cloudpipe.rst b/doc/source/devref/cloudpipe.rst index 5264a0f39..d6d456a6b 100644 --- a/doc/source/devref/cloudpipe.rst +++ b/doc/source/devref/cloudpipe.rst @@ -23,11 +23,13 @@ Cloudpipe -- Per Project Vpns Cloudpipe is a method for connecting end users to their project insnances in vlan mode. + 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. + 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). + 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 #. launches an m1.tiny instance with the above settings using the flag-specified vpn image + 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. -The :mod:`cloudpipe` Module + +The :mod:`nova.cloudpipe.pipelib` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.cloudpipe.pipelib @@ -67,7 +72,8 @@ The :mod:`cloudpipe` Module :undoc-members: :show-inheritance: -The :mod:`api.cloudpipe` Module + +The :mod:`nova.api.cloudpipe` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.cloudpipe @@ -75,7 +81,8 @@ The :mod:`api.cloudpipe` Module :undoc-members: :show-inheritance: -The :mod:`crypto` Module + +The :mod:`nova.crypto` Module ~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.crypto diff --git a/doc/source/devref/compute.rst b/doc/source/devref/compute.rst index e4c6c6ae7..741ea6041 100644 --- a/doc/source/devref/compute.rst +++ b/doc/source/devref/compute.rst @@ -16,19 +16,18 @@ 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 a specific virtualization backend, read Drivers_. -The :mod:`manager` Module +The :mod:`nova.compute.manager` Module ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.manager @@ -36,7 +35,7 @@ The :mod:`manager` Module :undoc-members: :show-inheritance: -The :mod:`connection` Module +The :mod:`nova.virt.connection` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.connection @@ -44,7 +43,7 @@ The :mod:`connection` Module :undoc-members: :show-inheritance: -The :mod:`disk` Module +The :mod:`nova.compute.disk` Module ~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.disk @@ -52,7 +51,7 @@ The :mod:`disk` Module :undoc-members: :show-inheritance: -The :mod:`images` Module +The :mod:`nova.virt.images` Module ~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.images @@ -61,7 +60,7 @@ The :mod:`images` Module :show-inheritance: -The :mod:`instance_types` Module +The :mod:`nova.compute.instance_types` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.instance_types @@ -70,7 +69,7 @@ The :mod:`instance_types` Module :show-inheritance: -The :mod:`power_state` Module +The :mod:`nova.compute.power_state` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.power_state @@ -82,42 +81,38 @@ The :mod:`power_state` Module Drivers ------- -Libvirt Implementations -~~~~~~~~~~~~~~~~~~~~~~~ -The libvirt driver is capable of supporting KVM, QEMU, and UML. - -The :mod:`libvirt_conn` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.virt.libvirt_conn` Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.libvirt_conn :members: :undoc-members: :show-inheritance: -XEN -~~~ -The :mod:`xenapi` Module -^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.virt.xenapi` Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.xenapi :members: :undoc-members: :show-inheritance: -FAKE -~~~~ + +The :mod:`nova.virt.fake` Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.fake :members: :undoc-members: :show-inheritance: + Monitoring ---------- -The :mod:`monitor` Module +The :mod:`nova.compute.monitor` Module ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.monitor diff --git a/doc/source/devref/database.rst b/doc/source/devref/database.rst index b58ea147d..1b41990ab 100644 --- a/doc/source/devref/database.rst +++ b/doc/source/devref/database.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Database Programming Guide -========================== +The Database Layer +================== -The :mod:`api` Module +The :mod:`nova.db.api` Module --------------------- .. automodule:: nova.db.api @@ -27,33 +27,31 @@ The :mod:`api` Module :show-inheritance: -Drivers -------- - -Driver: Sqlalchemy -~~~~~~~~~~~~~~~~~~ +The Sqlalchemy Driver +--------------------- -The :mod:`sqlalchemy.api` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.db.sqlalchemy.api` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.api -The :mod:`sqlalchemy.models` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.db.sqlalchemy.models` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.models :members: :undoc-members: :show-inheritance: -The :mod:`sqlalchemy.session` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.db.sqlalchemy.session` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.session :members: :undoc-members: :show-inheritance: + Tests ----- diff --git a/doc/source/devref/fakes.rst b/doc/source/devref/fakes.rst index 61622754c..adba57969 100644 --- a/doc/source/devref/fakes.rst +++ b/doc/source/devref/fakes.rst @@ -15,13 +15,16 @@ License for the specific language governing permissions and limitations under the License. -Fakes Programming Guide -======================= +Fake Drivers +============ .. 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 @@ -29,8 +32,9 @@ The :mod:`virt.fake` Module :undoc-members: :show-inheritance: :noindex: - -The :mod:`fakeldap` Module + + +The :mod:`nova.auth.fakeldap` Module -------------------------- .. automodule:: nova.auth.fakeldap @@ -38,7 +42,8 @@ The :mod:`fakeldap` Module :undoc-members: :show-inheritance: -The :mod:`fakerabbit` Module + +The :mod:`nova.fakerabbit` Module ---------------------------- .. automodule:: nova.fakerabbit @@ -46,7 +51,8 @@ The :mod:`fakerabbit` Module :undoc-members: :show-inheritance: -The :class:`FakeAOEDriver` Class + +The :class:`nova.volume.driver.FakeAOEDriver` Class -------------------------------- .. autoclass:: nova.volume.driver.FakeAOEDriver @@ -54,7 +60,8 @@ The :class:`FakeAOEDriver` Class :undoc-members: :show-inheritance: -The :class:`service_unittest.FakeManager` Class + +The :class:`nova.tests.service_unittest.FakeManager` Class ----------------------------------------------- .. autoclass:: nova.tests.service_unittest.FakeManager @@ -62,7 +69,8 @@ The :class:`service_unittest.FakeManager` Class :undoc-members: :show-inheritance: -The :mod:`api.openstack.fakes` Module + +The :mod:`nova.tests.api.openstack.fakes` Module ------------------------------------------------ .. automodule:: nova.tests.api.openstack.fakes diff --git a/doc/source/devref/glance.rst b/doc/source/devref/glance.rst index 3d0f4ebec..8a9dd7d80 100644 --- a/doc/source/devref/glance.rst +++ b/doc/source/devref/glance.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations 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 diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index a14460405..39d4c560e 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -18,10 +18,11 @@ Nova Development Reference ========================== -Nova is written in python. +Nova is written in Python. Prerequisites ------------- + .. toctree:: :maxdepth: 1 diff --git a/doc/source/devref/network.rst b/doc/source/devref/network.rst index 318286383..9b70b7830 100644 --- a/doc/source/devref/network.rst +++ b/doc/source/devref/network.rst @@ -15,24 +15,25 @@ License for the specific language governing permissions and limitations under the License. -Networking Programming Guide -============================ +Networking +========== .. todo:: * document hardware specific commands (maybe in admin guide?) (todd) * document a map between flags and managers/backends (todd) -The :mod:`Manager` module -------------------------- + +The :mod:`nova.network.manager` Module +-------------------------------------- .. automodule:: nova.network.manager :members: :undoc-members: :show-inheritance: -The :mod:`LinuxNet` driver --------------------------- +The :mod:`nova.network.linux_net` Driver +---------------------------------------- .. automodule:: nova.network.linux_net :members: @@ -51,7 +52,7 @@ The :mod:`network_unittest` Module :show-inheritance: -legacy docs +Legacy docs ----------- The nova networking components manage private networks, public IP addressing, VPN connectivity, and firewall rules. diff --git a/doc/source/devref/nova.rst b/doc/source/devref/nova.rst index 58125dc80..ff2b6ce9f 100644 --- a/doc/source/devref/nova.rst +++ b/doc/source/devref/nova.rst @@ -15,10 +15,14 @@ License for the specific language governing permissions and limitations 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 @@ -26,7 +30,8 @@ The :mod:`adminclient` Module :undoc-members: :show-inheritance: -The :mod:`context` Module + +The :mod:`nova.context` Module ------------------------- .. automodule:: nova.context @@ -34,7 +39,8 @@ The :mod:`context` Module :undoc-members: :show-inheritance: -The :mod:`exception` Module + +The :mod:`nova.exception` Module --------------------------- .. automodule:: nova.exception @@ -42,7 +48,8 @@ The :mod:`exception` Module :undoc-members: :show-inheritance: -The :mod:`flags` Module + +The :mod:`nova.flags` Module ----------------------- .. automodule:: nova.flags @@ -50,7 +57,8 @@ The :mod:`flags` Module :undoc-members: :show-inheritance: -The :mod:`process` Module + +The :mod:`nova.process` Module ------------------------- .. automodule:: nova.process @@ -58,7 +66,8 @@ The :mod:`process` Module :undoc-members: :show-inheritance: -The :mod:`rpc` Module + +The :mod:`nova.rpc` Module --------------------- .. automodule:: nova.rpc @@ -66,7 +75,8 @@ The :mod:`rpc` Module :undoc-members: :show-inheritance: -The :mod:`server` Module + +The :mod:`nova.server` Module ------------------------ .. automodule:: nova.server @@ -74,7 +84,8 @@ The :mod:`server` Module :undoc-members: :show-inheritance: -The :mod:`test` Module + +The :mod:`nova.test` Module ---------------------- .. automodule:: nova.test @@ -82,7 +93,8 @@ The :mod:`test` Module :undoc-members: :show-inheritance: -The :mod:`twistd` Module + +The :mod:`nova.twistd` Module ------------------------ .. automodule:: nova.twistd @@ -90,7 +102,8 @@ The :mod:`twistd` Module :undoc-members: :show-inheritance: -The :mod:`utils` Module + +The :mod:`nova.utils` Module ----------------------- .. automodule:: nova.utils @@ -98,7 +111,8 @@ The :mod:`utils` Module :undoc-members: :show-inheritance: -The :mod:`validate` Module + +The :mod:`nova.validate` Module -------------------------- .. automodule:: nova.validate @@ -106,7 +120,8 @@ The :mod:`validate` Module :undoc-members: :show-inheritance: -The :mod:`wsgi` Module + +The :mod:`nova.wsgi` Module ---------------------- .. automodule:: nova.wsgi @@ -114,6 +129,7 @@ The :mod:`wsgi` Module :undoc-members: :show-inheritance: + Tests ----- @@ -125,6 +141,7 @@ The :mod:`declare_flags` Module :undoc-members: :show-inheritance: + The :mod:`fake_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -133,6 +150,7 @@ The :mod:`fake_flags` Module :undoc-members: :show-inheritance: + The :mod:`flags_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,6 +159,7 @@ The :mod:`flags_unittest` Module :undoc-members: :show-inheritance: + The :mod:`process_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -149,6 +168,7 @@ The :mod:`process_unittest` Module :undoc-members: :show-inheritance: + The :mod:`real_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -157,6 +177,7 @@ The :mod:`real_flags` Module :undoc-members: :show-inheritance: + The :mod:`rpc_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,6 +186,7 @@ The :mod:`rpc_unittest` Module :undoc-members: :show-inheritance: + The :mod:`runtime_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -173,6 +195,7 @@ The :mod:`runtime_flags` Module :undoc-members: :show-inheritance: + The :mod:`twistd_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -181,6 +204,7 @@ The :mod:`twistd_unittest` Module :undoc-members: :show-inheritance: + The :mod:`validator_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/devref/objectstore.rst b/doc/source/devref/objectstore.rst index 4087b5dd0..473f32026 100644 --- a/doc/source/devref/objectstore.rst +++ b/doc/source/devref/objectstore.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Objectstore Programming Guide -============================= +Objectstore - File Storage Service +================================== -The :mod:`handler` Module +The :mod:`nova.objectstore.handler` Module ------------------------- .. automodule:: nova.objectstore.handler @@ -26,7 +26,8 @@ The :mod:`handler` Module :undoc-members: :show-inheritance: -The :mod:`bucket` Module + +The :mod:`nova.objectstore.bucket` Module ------------------------ .. automodule:: nova.objectstore.bucket @@ -34,7 +35,8 @@ The :mod:`bucket` Module :undoc-members: :show-inheritance: -The :mod:`stored` Module + +The :mod:`nova.objectstore.stored` Module ------------------------ .. automodule:: nova.objectstore.stored @@ -42,7 +44,8 @@ The :mod:`stored` Module :undoc-members: :show-inheritance: -The :mod:`image` Module + +The :mod:`nova.objecstore.image` Module ----------------------- .. automodule:: nova.objectstore.image @@ -50,6 +53,7 @@ The :mod:`image` Module :undoc-members: :show-inheritance: + Tests ----- diff --git a/doc/source/devref/scheduler.rst b/doc/source/devref/scheduler.rst index df820c2f2..d3a6132e5 100644 --- a/doc/source/devref/scheduler.rst +++ b/doc/source/devref/scheduler.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Scheduler Programming Guide -=========================== +Scheduler +========= -The :mod:`manager` Module +The :mod:`nova.scheduler.manager` Module ------------------------- .. automodule:: nova.scheduler.manager @@ -26,7 +26,8 @@ The :mod:`manager` Module :undoc-members: :show-inheritance: -The :mod:`driver` Module + +The :mod:`nova.scheduler.driver` Module ------------------------ .. automodule:: nova.scheduler.driver @@ -34,7 +35,8 @@ The :mod:`driver` Module :undoc-members: :show-inheritance: -The :mod:`chance` Module + +The :mod:`nova.scheduler.chance` Driver ------------------------ .. automodule:: nova.scheduler.chance @@ -42,7 +44,8 @@ The :mod:`chance` Module :undoc-members: :show-inheritance: -The :mod:`simple` Module + +The :mod:`nova.scheduler.simple` Driver ------------------------ .. automodule:: nova.scheduler.simple @@ -50,6 +53,7 @@ The :mod:`simple` Module :undoc-members: :show-inheritance: + Tests ----- diff --git a/doc/source/devref/services.rst b/doc/source/devref/services.rst index 517a51901..fe84e20d8 100644 --- a/doc/source/devref/services.rst +++ b/doc/source/devref/services.rst @@ -17,53 +17,34 @@ .. _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. 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:`service` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :mod:`nova.service` Module +------------------------------ .. automodule:: nova.service :members: :undoc-members: :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. - -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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :mod:`nova.manager` Module +------------------------------ .. automodule:: nova.manager :members: :undoc-members: :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. diff --git a/doc/source/devref/volume.rst b/doc/source/devref/volume.rst index 19b750870..abec38ba8 100644 --- a/doc/source/devref/volume.rst +++ b/doc/source/devref/volume.rst @@ -15,8 +15,8 @@ License for the specific language governing permissions and limitations under the License. -Volume Programming Guide -========================= +Storage Volumes, Disks +====================== .. todo:: rework after iSCSI merge (see 'Old Docs') (todd or vish) @@ -41,6 +41,9 @@ The :mod:`nova.volume.driver` Module Tests ----- +The :mod:`volume_unittest` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. automodule:: nova.tests.volume_unittest :members: :undoc-members: -- cgit From f8e6abff40da7c73efa7b79f9fab7d83169c3983 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 14:15:06 -0500 Subject: Doc updates: * quieter build (fewer warnings) * move api reference out of root directory * auto glob api reference into a TOC * remove old dev entries for new-fangled auto-generated docs --- doc/source/devref/api.rst | 267 ------------------------------------- doc/source/devref/auth.rst | 268 -------------------------------------- doc/source/devref/cloudpipe.rst | 9 +- doc/source/devref/compute.rst | 141 -------------------- doc/source/devref/database.rst | 59 --------- doc/source/devref/fakes.rst | 80 ------------ doc/source/devref/glance.rst | 27 ---- doc/source/devref/index.rst | 25 ++-- doc/source/devref/network.rst | 125 ------------------ doc/source/devref/nova.rst | 214 ------------------------------ doc/source/devref/objectstore.rst | 66 ---------- doc/source/devref/scheduler.rst | 66 ---------- doc/source/devref/services.rst | 2 + doc/source/devref/volume.rst | 63 --------- 14 files changed, 19 insertions(+), 1393 deletions(-) delete mode 100644 doc/source/devref/api.rst delete mode 100644 doc/source/devref/auth.rst delete mode 100644 doc/source/devref/compute.rst delete mode 100644 doc/source/devref/database.rst delete mode 100644 doc/source/devref/fakes.rst delete mode 100644 doc/source/devref/glance.rst delete mode 100644 doc/source/devref/network.rst delete mode 100644 doc/source/devref/nova.rst delete mode 100644 doc/source/devref/objectstore.rst delete mode 100644 doc/source/devref/scheduler.rst delete mode 100644 doc/source/devref/volume.rst (limited to 'doc/source') diff --git a/doc/source/devref/api.rst b/doc/source/devref/api.rst deleted file mode 100644 index e9b79d8dd..000000000 --- a/doc/source/devref/api.rst +++ /dev/null @@ -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 -============ - -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:`nova.api.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: - diff --git a/doc/source/devref/auth.rst b/doc/source/devref/auth.rst deleted file mode 100644 index ee82df5ab..000000000 --- a/doc/source/devref/auth.rst +++ /dev/null @@ -1,268 +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 -================================ - -The :mod:`nova.quota` Module ------------------------ - -.. automodule:: nova.quota - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.auth.signer` Module -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.auth.signer - :members: - :undoc-members: - :show-inheritance: - - -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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. 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 diff --git a/doc/source/devref/cloudpipe.rst b/doc/source/devref/cloudpipe.rst index d6d456a6b..31bd85e81 100644 --- a/doc/source/devref/cloudpipe.rst +++ b/doc/source/devref/cloudpipe.rst @@ -65,27 +65,30 @@ If the use_project_ca flag is set (required to for cloudpipes to work securely), The :mod:`nova.cloudpipe.pipelib` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.cloudpipe.pipelib + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.api.cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.cloudpipe + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.crypto` Module -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.crypto + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/compute.rst b/doc/source/devref/compute.rst deleted file mode 100644 index 741ea6041..000000000 --- a/doc/source/devref/compute.rst +++ /dev/null @@ -1,141 +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 -============== - - -Compute -------- - -Documentation for the compute manager and related files. For reading about -a specific virtualization backend, read Drivers_. - - -The :mod:`nova.compute.manager` Module -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.compute.manager - :members: - :undoc-members: - :show-inheritance: - -The :mod:`nova.virt.connection` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.virt.connection - :members: - :undoc-members: - :show-inheritance: - -The :mod:`nova.compute.disk` Module -~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.compute.disk - :members: - :undoc-members: - :show-inheritance: - -The :mod:`nova.virt.images` Module -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.virt.images - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.compute.instance_types` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.compute.instance_types - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.compute.power_state` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.compute.power_state - :members: - :undoc-members: - :show-inheritance: - - -Drivers -------- - - -The :mod:`nova.virt.libvirt_conn` Driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.virt.libvirt_conn - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.virt.xenapi` Driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.virt.xenapi - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.virt.fake` Driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.virt.fake - :members: - :undoc-members: - :show-inheritance: - - -Monitoring ----------- - -The :mod:`nova.compute.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: diff --git a/doc/source/devref/database.rst b/doc/source/devref/database.rst deleted file mode 100644 index 1b41990ab..000000000 --- a/doc/source/devref/database.rst +++ /dev/null @@ -1,59 +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. - -The Database Layer -================== - -The :mod:`nova.db.api` Module ---------------------- - -.. automodule:: nova.db.api - :members: - :undoc-members: - :show-inheritance: - - -The Sqlalchemy Driver ---------------------- - -The :mod:`nova.db.sqlalchemy.api` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.db.sqlalchemy.api - -The :mod:`nova.db.sqlalchemy.models` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.db.sqlalchemy.models - :members: - :undoc-members: - :show-inheritance: - -The :mod:`nova.db.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. diff --git a/doc/source/devref/fakes.rst b/doc/source/devref/fakes.rst deleted file mode 100644 index adba57969..000000000 --- a/doc/source/devref/fakes.rst +++ /dev/null @@ -1,80 +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. - -Fake Drivers -============ - -.. 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:`nova.virt.fake` Module ---------------------------- - -.. automodule:: nova.virt.fake - :members: - :undoc-members: - :show-inheritance: - :noindex: - - -The :mod:`nova.auth.fakeldap` Module --------------------------- - -.. automodule:: nova.auth.fakeldap - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.fakerabbit` Module ----------------------------- - -.. automodule:: nova.fakerabbit - :members: - :undoc-members: - :show-inheritance: - - -The :class:`nova.volume.driver.FakeAOEDriver` Class --------------------------------- - -.. autoclass:: nova.volume.driver.FakeAOEDriver - :members: - :undoc-members: - :show-inheritance: - - -The :class:`nova.tests.service_unittest.FakeManager` Class ------------------------------------------------ - -.. autoclass:: nova.tests.service_unittest.FakeManager - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.tests.api.openstack.fakes` Module ------------------------------------------------- - -.. automodule:: nova.tests.api.openstack.fakes - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/source/devref/glance.rst b/doc/source/devref/glance.rst deleted file mode 100644 index 8a9dd7d80..000000000 --- a/doc/source/devref/glance.rst +++ /dev/null @@ -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 - The Future of File Storage -=============================================== - -The :mod:`nova.image.service` Module -------------------------------- - -.. automodule:: nova.image.service - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 39d4c560e..66deabf2d 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -31,25 +31,22 @@ Prerequisites development.environment -Contents --------- +Guides +------ .. toctree:: - :maxdepth: 3 + :maxdepth: 1 services - database - volume - compute - network - auth - api - scheduler - fakes - nova cloudpipe - objectstore - glance + +API Reference +------------- + +.. toctree:: + :glob: + + /api/* Indices and tables diff --git a/doc/source/devref/network.rst b/doc/source/devref/network.rst deleted file mode 100644 index 9b70b7830..000000000 --- a/doc/source/devref/network.rst +++ /dev/null @@ -1,125 +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 -========== - -.. todo:: - - * document hardware specific commands (maybe in admin guide?) (todd) - * document a map between flags and managers/backends (todd) - - -The :mod:`nova.network.manager` Module --------------------------------------- - -.. automodule:: nova.network.manager - :members: - :undoc-members: - :show-inheritance: - -The :mod:`nova.network.linux_net` 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) - | - <-- [RoutingNode] - | - [AddressingNode] --> | - ( VLAN ) - | <-- [BridgingNode] - | - - -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). diff --git a/doc/source/devref/nova.rst b/doc/source/devref/nova.rst deleted file mode 100644 index ff2b6ce9f..000000000 --- a/doc/source/devref/nova.rst +++ /dev/null @@ -1,214 +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. - -Common and Misc Libraries -========================= - -Libraries common throughout Nova or just ones that haven't been categorized -very well yet. - - -The :mod:`nova.adminclient` Module ------------------------------ - -.. automodule:: nova.adminclient - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.context` Module -------------------------- - -.. automodule:: nova.context - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.exception` Module ---------------------------- - -.. automodule:: nova.exception - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.flags` Module ------------------------ - -.. automodule:: nova.flags - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.process` Module -------------------------- - -.. automodule:: nova.process - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.rpc` Module ---------------------- - -.. automodule:: nova.rpc - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.server` Module ------------------------- - -.. automodule:: nova.server - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.test` Module ----------------------- - -.. automodule:: nova.test - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.twistd` Module ------------------------- - -.. automodule:: nova.twistd - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.utils` Module ------------------------ - -.. automodule:: nova.utils - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.validate` Module --------------------------- - -.. automodule:: nova.validate - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.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: diff --git a/doc/source/devref/objectstore.rst b/doc/source/devref/objectstore.rst deleted file mode 100644 index 473f32026..000000000 --- a/doc/source/devref/objectstore.rst +++ /dev/null @@ -1,66 +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 - File Storage Service -================================== - -The :mod:`nova.objectstore.handler` Module -------------------------- - -.. automodule:: nova.objectstore.handler - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.objectstore.bucket` Module ------------------------- - -.. automodule:: nova.objectstore.bucket - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.objectstore.stored` Module ------------------------- - -.. automodule:: nova.objectstore.stored - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.objecstore.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: diff --git a/doc/source/devref/scheduler.rst b/doc/source/devref/scheduler.rst deleted file mode 100644 index d3a6132e5..000000000 --- a/doc/source/devref/scheduler.rst +++ /dev/null @@ -1,66 +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 -========= - -The :mod:`nova.scheduler.manager` Module -------------------------- - -.. automodule:: nova.scheduler.manager - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.scheduler.driver` Module ------------------------- - -.. automodule:: nova.scheduler.driver - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.scheduler.chance` Driver ------------------------- - -.. automodule:: nova.scheduler.chance - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.scheduler.simple` Driver ------------------------- - -.. 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: diff --git a/doc/source/devref/services.rst b/doc/source/devref/services.rst index fe84e20d8..f5bba5c12 100644 --- a/doc/source/devref/services.rst +++ b/doc/source/devref/services.rst @@ -29,6 +29,7 @@ The :mod:`nova.service` Module ------------------------------ .. automodule:: nova.service + :noindex: :members: :undoc-members: :show-inheritance: @@ -38,6 +39,7 @@ The :mod:`nova.manager` Module ------------------------------ .. automodule:: nova.manager + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/volume.rst b/doc/source/devref/volume.rst deleted file mode 100644 index abec38ba8..000000000 --- a/doc/source/devref/volume.rst +++ /dev/null @@ -1,63 +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. - -Storage Volumes, Disks -====================== - -.. 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 ------ - -The :mod:`volume_unittest` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. 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. - - -- cgit From a999c8de9e51da2beda13fdbb66dfb0bad42f250 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 14:46:17 -0500 Subject: back out stacked merge --- doc/source/Makefile | 89 ++++++++ doc/source/devguide/api.rst | 267 ++++++++++++++++++++++++ doc/source/devguide/architecture.rst | 52 +++++ doc/source/devguide/auth.rst | 258 +++++++++++++++++++++++ doc/source/devguide/cloudpipe.rst | 85 ++++++++ doc/source/devguide/compute.rst | 146 +++++++++++++ doc/source/devguide/database.rst | 61 ++++++ doc/source/devguide/development.environment.rst | 21 ++ doc/source/devguide/fakes.rst | 72 +++++++ doc/source/devguide/glance.rst | 27 +++ doc/source/devguide/index.rst | 60 ++++++ doc/source/devguide/network.rst | 124 +++++++++++ doc/source/devguide/nova.rst | 190 +++++++++++++++++ doc/source/devguide/objectstore.rst | 62 ++++++ doc/source/devguide/scheduler.rst | 62 ++++++ doc/source/devguide/services.rst | 72 +++++++ doc/source/devguide/volume.rst | 60 ++++++ doc/source/devref/architecture.rst | 52 ----- doc/source/devref/cloudpipe.rst | 95 --------- doc/source/devref/development.environment.rst | 21 -- doc/source/devref/index.rst | 58 ----- doc/source/devref/services.rst | 55 ----- doc/source/index.rst | 2 +- 23 files changed, 1709 insertions(+), 282 deletions(-) create mode 100644 doc/source/Makefile create mode 100644 doc/source/devguide/api.rst create mode 100644 doc/source/devguide/architecture.rst create mode 100644 doc/source/devguide/auth.rst create mode 100644 doc/source/devguide/cloudpipe.rst create mode 100644 doc/source/devguide/compute.rst create mode 100644 doc/source/devguide/database.rst create mode 100644 doc/source/devguide/development.environment.rst create mode 100644 doc/source/devguide/fakes.rst create mode 100644 doc/source/devguide/glance.rst create mode 100644 doc/source/devguide/index.rst create mode 100644 doc/source/devguide/network.rst create mode 100644 doc/source/devguide/nova.rst create mode 100644 doc/source/devguide/objectstore.rst create mode 100644 doc/source/devguide/scheduler.rst create mode 100644 doc/source/devguide/services.rst create mode 100644 doc/source/devguide/volume.rst delete mode 100644 doc/source/devref/architecture.rst delete mode 100644 doc/source/devref/cloudpipe.rst delete mode 100644 doc/source/devref/development.environment.rst delete mode 100644 doc/source/devref/index.rst delete mode 100644 doc/source/devref/services.rst (limited to 'doc/source') diff --git a/doc/source/Makefile b/doc/source/Makefile new file mode 100644 index 000000000..b2f74e85a --- /dev/null +++ b/doc/source/Makefile @@ -0,0 +1,89 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nova.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/source/devguide/api.rst b/doc/source/devguide/api.rst new file mode 100644 index 000000000..cad0e820a --- /dev/null +++ b/doc/source/devguide/api.rst @@ -0,0 +1,267 @@ +.. + 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: + diff --git a/doc/source/devguide/architecture.rst b/doc/source/devguide/architecture.rst new file mode 100644 index 000000000..1e23e1361 --- /dev/null +++ b/doc/source/devguide/architecture.rst @@ -0,0 +1,52 @@ +.. + 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 System Architecture +======================== + +Nova is built on a shared-nothing, messaging-based architecture. All of the major nova components can be run on multiple servers. This means that most component to component communication must go via message queue. In order to avoid blocking each component while waiting for a response, we use deferred objects, with a callback that gets triggered when a response is received. + +Nova recently moved to using a sql-based central database that is shared by all components 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, nova will be moving towards multiple data stores with some kind of aggregation system. + +Components +---------- + +Below you will find a helpful explanation of the different components. + +:: + + /- ( LDAP ) + [ Auth Manager ] --- + | \- ( DB ) + | + | [ scheduler ] - [ volume ] - ( ATAoE/iSCSI ) + | / + [ Web Dashboard ] -> [ api ] -- < AMQP > ------ [ network ] - ( Flat/Vlan ) + | \ + < HTTP > [ scheduler ] - [ compute ] - ( libvirt/xen ) + | | + [ objectstore ] < - retrieves images + +* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) +* Web Dashboard: potential external component that talks to the api +* api: component that receives http requests, converts commands and communicates with other components via the queue or http (in the case of objectstore) +* 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. +* objectstore: twisted http server that replicates s3 api and allows storage and retrieval of images +* scheduler: decides which host gets each vm and volume +* volume: manages dynamically attachable block devices. +* network: manages ip forwarding, bridges, and vlans +* compute: manages communication with hypervisor and virtual machines. diff --git a/doc/source/devguide/auth.rst b/doc/source/devguide/auth.rst new file mode 100644 index 000000000..77d97f68b --- /dev/null +++ b/doc/source/devguide/auth.rst @@ -0,0 +1,258 @@ +.. + 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 + + + diff --git a/doc/source/devguide/cloudpipe.rst b/doc/source/devguide/cloudpipe.rst new file mode 100644 index 000000000..5264a0f39 --- /dev/null +++ b/doc/source/devguide/cloudpipe.rst @@ -0,0 +1,85 @@ +.. + 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. + + +.. _cloudpipe: + +Cloudpipe -- Per Project Vpns +============================= + +Cloudpipe is a method for connecting end users to their project insnances in vlan mode. + +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. + +Cloudpipe Image +--------------- + +The cloudpipe image is basically just a linux instance with openvpn installed. It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip. The autorun script will configure and run openvpn to run using the data from nova. + +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 +---------------- + +When you use nova-manage to launch a cloudpipe for a user, it goes through the following process: + +#. creates a keypair called -vpn and saves it in the keys directory +#. creates a security group -vpn and opens up 1194 and icmp +#. creates a cert and private key for the vpn instance and saves it in the CA/projects// directory +#. 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 + +Vpn Access +---------- + +In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance. This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world. The network for each project is given a specific high-numbered port on the public ip of the network host. This port is automatically forwarded to 1194 on the vpn instance. + +If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database. This will be turned into a nova-manage command or a flag soon. + + +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. + +The :mod:`cloudpipe` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.cloudpipe.pipelib + :members: + :undoc-members: + :show-inheritance: + +The :mod:`api.cloudpipe` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.api.cloudpipe + :members: + :undoc-members: + :show-inheritance: + +The :mod:`crypto` Module +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.crypto + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/source/devguide/compute.rst b/doc/source/devguide/compute.rst new file mode 100644 index 000000000..e4c6c6ae7 --- /dev/null +++ b/doc/source/devguide/compute.rst @@ -0,0 +1,146 @@ +.. + 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: diff --git a/doc/source/devguide/database.rst b/doc/source/devguide/database.rst new file mode 100644 index 000000000..b58ea147d --- /dev/null +++ b/doc/source/devguide/database.rst @@ -0,0 +1,61 @@ +.. + 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. diff --git a/doc/source/devguide/development.environment.rst b/doc/source/devguide/development.environment.rst new file mode 100644 index 000000000..34104c964 --- /dev/null +++ b/doc/source/devguide/development.environment.rst @@ -0,0 +1,21 @@ +.. + 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. + +Setting up a development environment +==================================== + +.. todo:: write this diff --git a/doc/source/devguide/fakes.rst b/doc/source/devguide/fakes.rst new file mode 100644 index 000000000..61622754c --- /dev/null +++ b/doc/source/devguide/fakes.rst @@ -0,0 +1,72 @@ +.. + 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: + diff --git a/doc/source/devguide/glance.rst b/doc/source/devguide/glance.rst new file mode 100644 index 000000000..3d0f4ebec --- /dev/null +++ b/doc/source/devguide/glance.rst @@ -0,0 +1,27 @@ +.. + 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: diff --git a/doc/source/devguide/index.rst b/doc/source/devguide/index.rst new file mode 100644 index 000000000..6232a3181 --- /dev/null +++ b/doc/source/devguide/index.rst @@ -0,0 +1,60 @@ +.. + 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 Development Guide +====================== + +Nova is written in python. + +Prerequisites +------------- +.. toctree:: + :maxdepth: 1 + + ../concepts.and.introduction + architecture + development.environment + + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + services + database + volume + compute + network + auth + api + scheduler + fakes + nova + cloudpipe + objectstore + glance + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/devguide/network.rst b/doc/source/devguide/network.rst new file mode 100644 index 000000000..318286383 --- /dev/null +++ b/doc/source/devguide/network.rst @@ -0,0 +1,124 @@ +.. + 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) + | + <-- [RoutingNode] + | + [AddressingNode] --> | + ( VLAN ) + | <-- [BridgingNode] + | + + +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). diff --git a/doc/source/devguide/nova.rst b/doc/source/devguide/nova.rst new file mode 100644 index 000000000..58125dc80 --- /dev/null +++ b/doc/source/devguide/nova.rst @@ -0,0 +1,190 @@ +.. + 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: diff --git a/doc/source/devguide/objectstore.rst b/doc/source/devguide/objectstore.rst new file mode 100644 index 000000000..4087b5dd0 --- /dev/null +++ b/doc/source/devguide/objectstore.rst @@ -0,0 +1,62 @@ +.. + 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: diff --git a/doc/source/devguide/scheduler.rst b/doc/source/devguide/scheduler.rst new file mode 100644 index 000000000..df820c2f2 --- /dev/null +++ b/doc/source/devguide/scheduler.rst @@ -0,0 +1,62 @@ +.. + 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: diff --git a/doc/source/devguide/services.rst b/doc/source/devguide/services.rst new file mode 100644 index 000000000..517a51901 --- /dev/null +++ b/doc/source/devguide/services.rst @@ -0,0 +1,72 @@ +.. + 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. + +.. _service_manager_driver: + +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. + +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:`service` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.service + :members: + :undoc-members: + :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. + +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 + :members: + :undoc-members: + :show-inheritance: + +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. + +Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. + +It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/devguide/volume.rst b/doc/source/devguide/volume.rst new file mode 100644 index 000000000..19b750870 --- /dev/null +++ b/doc/source/devguide/volume.rst @@ -0,0 +1,60 @@ +.. + 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. + + diff --git a/doc/source/devref/architecture.rst b/doc/source/devref/architecture.rst deleted file mode 100644 index 1e23e1361..000000000 --- a/doc/source/devref/architecture.rst +++ /dev/null @@ -1,52 +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 System Architecture -======================== - -Nova is built on a shared-nothing, messaging-based architecture. All of the major nova components can be run on multiple servers. This means that most component to component communication must go via message queue. In order to avoid blocking each component while waiting for a response, we use deferred objects, with a callback that gets triggered when a response is received. - -Nova recently moved to using a sql-based central database that is shared by all components 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, nova will be moving towards multiple data stores with some kind of aggregation system. - -Components ----------- - -Below you will find a helpful explanation of the different components. - -:: - - /- ( LDAP ) - [ Auth Manager ] --- - | \- ( DB ) - | - | [ scheduler ] - [ volume ] - ( ATAoE/iSCSI ) - | / - [ Web Dashboard ] -> [ api ] -- < AMQP > ------ [ network ] - ( Flat/Vlan ) - | \ - < HTTP > [ scheduler ] - [ compute ] - ( libvirt/xen ) - | | - [ objectstore ] < - retrieves images - -* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) -* Web Dashboard: potential external component that talks to the api -* api: component that receives http requests, converts commands and communicates with other components via the queue or http (in the case of objectstore) -* 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. -* objectstore: twisted http server that replicates s3 api and allows storage and retrieval of images -* scheduler: decides which host gets each vm and volume -* volume: manages dynamically attachable block devices. -* network: manages ip forwarding, bridges, and vlans -* compute: manages communication with hypervisor and virtual machines. diff --git a/doc/source/devref/cloudpipe.rst b/doc/source/devref/cloudpipe.rst deleted file mode 100644 index 31bd85e81..000000000 --- a/doc/source/devref/cloudpipe.rst +++ /dev/null @@ -1,95 +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. - - -.. _cloudpipe: - -Cloudpipe -- Per Project Vpns -============================= - -Cloudpipe is a method for connecting end users to their project insnances in vlan mode. - - -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. - - -Cloudpipe Image ---------------- - -The cloudpipe image is basically just a linux instance with openvpn installed. It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip. The autorun script will configure and run openvpn to run using the data from nova. - -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 ----------------- - -When you use nova-manage to launch a cloudpipe for a user, it goes through the following process: - -#. creates a keypair called -vpn and saves it in the keys directory -#. creates a security group -vpn and opens up 1194 and icmp -#. creates a cert and private key for the vpn instance and saves it in the CA/projects// directory -#. 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 - - -Vpn Access ----------- - -In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance. This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world. The network for each project is given a specific high-numbered port on the public ip of the network host. This port is automatically forwarded to 1194 on the vpn instance. - -If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database. This will be turned into a nova-manage command or a flag soon. - - -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. - - -The :mod:`nova.cloudpipe.pipelib` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.cloudpipe.pipelib - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.api.cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.api.cloudpipe - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.crypto` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.crypto - :noindex: - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst deleted file mode 100644 index 34104c964..000000000 --- a/doc/source/devref/development.environment.rst +++ /dev/null @@ -1,21 +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. - -Setting up a development environment -==================================== - -.. todo:: write this diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst deleted file mode 100644 index 66deabf2d..000000000 --- a/doc/source/devref/index.rst +++ /dev/null @@ -1,58 +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 Development Reference -========================== - -Nova is written in Python. - -Prerequisites -------------- - -.. toctree:: - :maxdepth: 1 - - ../concepts.and.introduction - architecture - development.environment - - -Guides ------- - -.. toctree:: - :maxdepth: 1 - - services - cloudpipe - -API Reference -------------- - -.. toctree:: - :glob: - - /api/* - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/devref/services.rst b/doc/source/devref/services.rst deleted file mode 100644 index f5bba5c12..000000000 --- a/doc/source/devref/services.rst +++ /dev/null @@ -1,55 +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. - -.. _service_manager_driver: - -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. - -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. - - -The :mod:`nova.service` Module ------------------------------- - -.. automodule:: nova.service - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -The :mod:`nova.manager` Module ------------------------------- - -.. automodule:: nova.manager - :noindex: - :members: - :undoc-members: - :show-inheritance: - - -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. - -Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. - -It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/index.rst b/doc/source/index.rst index f96d5ff80..4ef75c432 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,7 +45,7 @@ Contents concepts.and.introduction adminguide/index - devref/index + devguide/index reaching.out Recommended System Configuration -- cgit From 2c01c325719473fc764deec607a2b634ada5579a Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 14:51:40 -0500 Subject: Merge lp:~termie/nova/trunkdoc (via patch, since bzr though it was already merged) --- doc/source/Makefile | 37 ++-- doc/source/devguide/api.rst | 267 ------------------------ doc/source/devguide/architecture.rst | 52 ----- doc/source/devguide/auth.rst | 258 ----------------------- doc/source/devguide/cloudpipe.rst | 85 -------- doc/source/devguide/compute.rst | 146 ------------- doc/source/devguide/database.rst | 61 ------ doc/source/devguide/development.environment.rst | 21 -- doc/source/devguide/fakes.rst | 72 ------- doc/source/devguide/glance.rst | 27 --- doc/source/devguide/index.rst | 60 ------ doc/source/devguide/network.rst | 124 ----------- doc/source/devguide/nova.rst | 190 ----------------- doc/source/devguide/objectstore.rst | 62 ------ doc/source/devguide/scheduler.rst | 62 ------ doc/source/devguide/services.rst | 72 ------- doc/source/devguide/volume.rst | 60 ------ doc/source/devref/api.rst | 6 +- doc/source/devref/architecture.rst | 52 +++++ doc/source/devref/auth.rst | 74 ++++--- doc/source/devref/cloudpipe.rst | 92 ++++++++ doc/source/devref/compute.rst | 41 ++-- doc/source/devref/database.rst | 26 ++- doc/source/devref/development.environment.rst | 21 ++ doc/source/devref/fakes.rst | 26 ++- doc/source/devref/glance.rst | 6 +- doc/source/devref/index.rst | 61 ++++++ doc/source/devref/network.rst | 15 +- doc/source/devref/nova.rst | 52 +++-- doc/source/devref/objectstore.rst | 16 +- doc/source/devref/scheduler.rst | 16 +- doc/source/devref/services.rst | 53 +++++ doc/source/devref/volume.rst | 7 +- doc/source/index.rst | 2 +- 34 files changed, 471 insertions(+), 1751 deletions(-) delete mode 100644 doc/source/devguide/api.rst delete mode 100644 doc/source/devguide/architecture.rst delete mode 100644 doc/source/devguide/auth.rst delete mode 100644 doc/source/devguide/cloudpipe.rst delete mode 100644 doc/source/devguide/compute.rst delete mode 100644 doc/source/devguide/database.rst delete mode 100644 doc/source/devguide/development.environment.rst delete mode 100644 doc/source/devguide/fakes.rst delete mode 100644 doc/source/devguide/glance.rst delete mode 100644 doc/source/devguide/index.rst delete mode 100644 doc/source/devguide/network.rst delete mode 100644 doc/source/devguide/nova.rst delete mode 100644 doc/source/devguide/objectstore.rst delete mode 100644 doc/source/devguide/scheduler.rst delete mode 100644 doc/source/devguide/services.rst delete mode 100644 doc/source/devguide/volume.rst create mode 100644 doc/source/devref/architecture.rst create mode 100644 doc/source/devref/cloudpipe.rst create mode 100644 doc/source/devref/development.environment.rst create mode 100644 doc/source/devref/index.rst create mode 100644 doc/source/devref/services.rst (limited to 'doc/source') diff --git a/doc/source/Makefile b/doc/source/Makefile index b2f74e85a..f1391ea41 100644 --- a/doc/source/Makefile +++ b/doc/source/Makefile @@ -4,16 +4,19 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build +SPHINXSOURCE = source PAPER = -BUILDDIR = _build +BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 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 +.DEFAULT_GOAL = html + help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @@ -29,34 +32,44 @@ help: clean: -rm -rf $(BUILDDIR)/* + -rm -rf nova.sqlite + cat .autogenerated | xargs rm + rm .autogenerated + +module_autodoc: generate_autodoc_index.sh + @echo "Generating module autodocs." + ./generate_autodoc_index.sh + +source/code.rst: module_autodoc + @# pass -html: +html: source/code.rst $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: +dirhtml: source/code.rst $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -pickle: +pickle: source/code.rst $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." -json: +json: source/code.rst $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." -htmlhelp: +htmlhelp: source/code.rst $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." -qthelp: +qthelp: source/code.rst $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ @@ -65,25 +78,25 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc" -latex: +latex: source/code.rst $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ "run these through (pdf)latex." -changes: +changes: source/code.rst $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." -linkcheck: +linkcheck: source/code.rst $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." -doctest: +doctest: source/code.rst $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/source/devguide/api.rst b/doc/source/devguide/api.rst deleted file mode 100644 index cad0e820a..000000000 --- a/doc/source/devguide/api.rst +++ /dev/null @@ -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: - diff --git a/doc/source/devguide/architecture.rst b/doc/source/devguide/architecture.rst deleted file mode 100644 index 1e23e1361..000000000 --- a/doc/source/devguide/architecture.rst +++ /dev/null @@ -1,52 +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 System Architecture -======================== - -Nova is built on a shared-nothing, messaging-based architecture. All of the major nova components can be run on multiple servers. This means that most component to component communication must go via message queue. In order to avoid blocking each component while waiting for a response, we use deferred objects, with a callback that gets triggered when a response is received. - -Nova recently moved to using a sql-based central database that is shared by all components 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, nova will be moving towards multiple data stores with some kind of aggregation system. - -Components ----------- - -Below you will find a helpful explanation of the different components. - -:: - - /- ( LDAP ) - [ Auth Manager ] --- - | \- ( DB ) - | - | [ scheduler ] - [ volume ] - ( ATAoE/iSCSI ) - | / - [ Web Dashboard ] -> [ api ] -- < AMQP > ------ [ network ] - ( Flat/Vlan ) - | \ - < HTTP > [ scheduler ] - [ compute ] - ( libvirt/xen ) - | | - [ objectstore ] < - retrieves images - -* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) -* Web Dashboard: potential external component that talks to the api -* api: component that receives http requests, converts commands and communicates with other components via the queue or http (in the case of objectstore) -* 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. -* objectstore: twisted http server that replicates s3 api and allows storage and retrieval of images -* scheduler: decides which host gets each vm and volume -* volume: manages dynamically attachable block devices. -* network: manages ip forwarding, bridges, and vlans -* compute: manages communication with hypervisor and virtual machines. diff --git a/doc/source/devguide/auth.rst b/doc/source/devguide/auth.rst deleted file mode 100644 index 77d97f68b..000000000 --- a/doc/source/devguide/auth.rst +++ /dev/null @@ -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 - - - diff --git a/doc/source/devguide/cloudpipe.rst b/doc/source/devguide/cloudpipe.rst deleted file mode 100644 index 5264a0f39..000000000 --- a/doc/source/devguide/cloudpipe.rst +++ /dev/null @@ -1,85 +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. - - -.. _cloudpipe: - -Cloudpipe -- Per Project Vpns -============================= - -Cloudpipe is a method for connecting end users to their project insnances in vlan mode. - -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. - -Cloudpipe Image ---------------- - -The cloudpipe image is basically just a linux instance with openvpn installed. It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip. The autorun script will configure and run openvpn to run using the data from nova. - -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 ----------------- - -When you use nova-manage to launch a cloudpipe for a user, it goes through the following process: - -#. creates a keypair called -vpn and saves it in the keys directory -#. creates a security group -vpn and opens up 1194 and icmp -#. creates a cert and private key for the vpn instance and saves it in the CA/projects// directory -#. 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 - -Vpn Access ----------- - -In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance. This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world. The network for each project is given a specific high-numbered port on the public ip of the network host. This port is automatically forwarded to 1194 on the vpn instance. - -If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database. This will be turned into a nova-manage command or a flag soon. - - -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. - -The :mod:`cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.cloudpipe.pipelib - :members: - :undoc-members: - :show-inheritance: - -The :mod:`api.cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.api.cloudpipe - :members: - :undoc-members: - :show-inheritance: - -The :mod:`crypto` Module -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.crypto - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/source/devguide/compute.rst b/doc/source/devguide/compute.rst deleted file mode 100644 index e4c6c6ae7..000000000 --- a/doc/source/devguide/compute.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/database.rst b/doc/source/devguide/database.rst deleted file mode 100644 index b58ea147d..000000000 --- a/doc/source/devguide/database.rst +++ /dev/null @@ -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. diff --git a/doc/source/devguide/development.environment.rst b/doc/source/devguide/development.environment.rst deleted file mode 100644 index 34104c964..000000000 --- a/doc/source/devguide/development.environment.rst +++ /dev/null @@ -1,21 +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. - -Setting up a development environment -==================================== - -.. todo:: write this diff --git a/doc/source/devguide/fakes.rst b/doc/source/devguide/fakes.rst deleted file mode 100644 index 61622754c..000000000 --- a/doc/source/devguide/fakes.rst +++ /dev/null @@ -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: - diff --git a/doc/source/devguide/glance.rst b/doc/source/devguide/glance.rst deleted file mode 100644 index 3d0f4ebec..000000000 --- a/doc/source/devguide/glance.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/index.rst b/doc/source/devguide/index.rst deleted file mode 100644 index 6232a3181..000000000 --- a/doc/source/devguide/index.rst +++ /dev/null @@ -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. - -Nova Development Guide -====================== - -Nova is written in python. - -Prerequisites -------------- -.. toctree:: - :maxdepth: 1 - - ../concepts.and.introduction - architecture - development.environment - - -Contents --------- - -.. toctree:: - :maxdepth: 1 - - services - database - volume - compute - network - auth - api - scheduler - fakes - nova - cloudpipe - objectstore - glance - - -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/devguide/network.rst b/doc/source/devguide/network.rst deleted file mode 100644 index 318286383..000000000 --- a/doc/source/devguide/network.rst +++ /dev/null @@ -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) - | - <-- [RoutingNode] - | - [AddressingNode] --> | - ( VLAN ) - | <-- [BridgingNode] - | - - -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). diff --git a/doc/source/devguide/nova.rst b/doc/source/devguide/nova.rst deleted file mode 100644 index 58125dc80..000000000 --- a/doc/source/devguide/nova.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/objectstore.rst b/doc/source/devguide/objectstore.rst deleted file mode 100644 index 4087b5dd0..000000000 --- a/doc/source/devguide/objectstore.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/scheduler.rst b/doc/source/devguide/scheduler.rst deleted file mode 100644 index df820c2f2..000000000 --- a/doc/source/devguide/scheduler.rst +++ /dev/null @@ -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: diff --git a/doc/source/devguide/services.rst b/doc/source/devguide/services.rst deleted file mode 100644 index 517a51901..000000000 --- a/doc/source/devguide/services.rst +++ /dev/null @@ -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. - -.. _service_manager_driver: - -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. - -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:`service` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: nova.service - :members: - :undoc-members: - :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. - -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 - :members: - :undoc-members: - :show-inheritance: - -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. - -Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. - -It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/devguide/volume.rst b/doc/source/devguide/volume.rst deleted file mode 100644 index 19b750870..000000000 --- a/doc/source/devguide/volume.rst +++ /dev/null @@ -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. - - diff --git a/doc/source/devref/api.rst b/doc/source/devref/api.rst index cad0e820a..e9b79d8dd 100644 --- a/doc/source/devref/api.rst +++ b/doc/source/devref/api.rst @@ -15,8 +15,8 @@ License for the specific language governing permissions and limitations under the License. -API Endpoint Programming Guide -============================== +API Endpoint +============ 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 @@ -33,7 +33,7 @@ The :mod:`nova.api` Module :undoc-members: :show-inheritance: -The :mod:`cloud` Module +The :mod:`nova.api.cloud` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.cloud diff --git a/doc/source/devref/architecture.rst b/doc/source/devref/architecture.rst new file mode 100644 index 000000000..1e23e1361 --- /dev/null +++ b/doc/source/devref/architecture.rst @@ -0,0 +1,52 @@ +.. + 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 System Architecture +======================== + +Nova is built on a shared-nothing, messaging-based architecture. All of the major nova components can be run on multiple servers. This means that most component to component communication must go via message queue. In order to avoid blocking each component while waiting for a response, we use deferred objects, with a callback that gets triggered when a response is received. + +Nova recently moved to using a sql-based central database that is shared by all components 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, nova will be moving towards multiple data stores with some kind of aggregation system. + +Components +---------- + +Below you will find a helpful explanation of the different components. + +:: + + /- ( LDAP ) + [ Auth Manager ] --- + | \- ( DB ) + | + | [ scheduler ] - [ volume ] - ( ATAoE/iSCSI ) + | / + [ Web Dashboard ] -> [ api ] -- < AMQP > ------ [ network ] - ( Flat/Vlan ) + | \ + < HTTP > [ scheduler ] - [ compute ] - ( libvirt/xen ) + | | + [ objectstore ] < - retrieves images + +* DB: sql database for data storage. Used by all components (LINKS NOT SHOWN) +* Web Dashboard: potential external component that talks to the api +* api: component that receives http requests, converts commands and communicates with other components via the queue or http (in the case of objectstore) +* 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. +* objectstore: twisted http server that replicates s3 api and allows storage and retrieval of images +* scheduler: decides which host gets each vm and volume +* volume: manages dynamically attachable block devices. +* network: manages ip forwarding, bridges, and vlans +* compute: manages communication with hypervisor and virtual machines. diff --git a/doc/source/devref/auth.rst b/doc/source/devref/auth.rst index 77d97f68b..ee82df5ab 100644 --- a/doc/source/devref/auth.rst +++ b/doc/source/devref/auth.rst @@ -17,10 +17,10 @@ .. _auth: -Authentication and Authorization Programming Guide -================================================== +Authentication and Authorization +================================ -The :mod:`quota` Module +The :mod:`nova.quota` Module ----------------------- .. automodule:: nova.quota @@ -28,10 +28,20 @@ The :mod:`quota` Module :undoc-members: :show-inheritance: + +The :mod:`nova.auth.signer` Module +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.auth.signer + :members: + :undoc-members: + :show-inheritance: + + Auth Manager ------------ -The :mod:`manager` Module +The :mod:`nova.auth.manager` Module ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.manager @@ -39,10 +49,8 @@ The :mod:`manager` Module :undoc-members: :show-inheritance: -Drivers -------- -The :mod:`ldapdriver` Module +The :mod:`nova.auth.ldapdriver` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.ldapdriver @@ -50,7 +58,7 @@ The :mod:`ldapdriver` Module :undoc-members: :show-inheritance: -The :mod:`dbdriver` Module +The :mod:`nova.auth.dbdriver` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.dbdriver @@ -58,19 +66,10 @@ The :mod:`dbdriver` Module :undoc-members: :show-inheritance: -API Integration ---------------- -The :mod:`signer` Module -~~~~~~~~~~~~~~~~~~~~~~~~ +Tests +----- -.. automodule:: nova.auth.signer - :members: - :undoc-members: - :show-inheritance: - -Related Tests -------------- The :mod:`auth_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,6 +79,7 @@ The :mod:`auth_unittest` Module :undoc-members: :show-inheritance: + The :mod:`access_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -88,6 +88,7 @@ The :mod:`access_unittest` Module :undoc-members: :show-inheritance: + The :mod:`quota_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -96,7 +97,8 @@ The :mod:`quota_unittest` Module :undoc-members: :show-inheritance: -legacy docs + +Legacy Docs ----------- 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 “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 -------------------------------- @@ -125,6 +129,7 @@ In more ideal implementations, the remainder of the application-specific account .. _auth_roles: + Roles ----- @@ -172,6 +177,7 @@ Cloud Administrator/IT-Security: * All permissions + Enhancements ------------ @@ -182,6 +188,7 @@ Enhancements 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 --------------- @@ -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. RBAC of CloudAudit API calls is critical, since detailed system information is a system vulnerability. + Type declarations ----------------- * 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.) + Request Brokering ----------------- - * Cloud Interop - * IMF Registration / PubSub - * Digital C&A +* 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 --------------------------------- @@ -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. + The Details ----------- - * Preliminary Roles Definitions - * Categorization of available API calls - * SAML assertion vocabulary +* Preliminary Roles Definitions +* Categorization of available API calls +* SAML assertion vocabulary + System limits ------------- @@ -249,10 +261,8 @@ The following limits need to be defined and enforced: 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 diff --git a/doc/source/devref/cloudpipe.rst b/doc/source/devref/cloudpipe.rst new file mode 100644 index 000000000..d6d456a6b --- /dev/null +++ b/doc/source/devref/cloudpipe.rst @@ -0,0 +1,92 @@ +.. + 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. + + +.. _cloudpipe: + +Cloudpipe -- Per Project Vpns +============================= + +Cloudpipe is a method for connecting end users to their project insnances in vlan mode. + + +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. + + +Cloudpipe Image +--------------- + +The cloudpipe image is basically just a linux instance with openvpn installed. It needs a simple script to grab user data from the metadata server, b64 decode it into a zip file, and run the autorun.sh script from inside the zip. The autorun script will configure and run openvpn to run using the data from nova. + +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 +---------------- + +When you use nova-manage to launch a cloudpipe for a user, it goes through the following process: + +#. creates a keypair called -vpn and saves it in the keys directory +#. creates a security group -vpn and opens up 1194 and icmp +#. creates a cert and private key for the vpn instance and saves it in the CA/projects// directory +#. 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 + + +Vpn Access +---------- + +In vlan networking mode, the second ip in each private network is reserved for the cloudpipe instance. This gives a consistent ip to the instance so that nova-network can create forwarding rules for access from the outside world. The network for each project is given a specific high-numbered port on the public ip of the network host. This port is automatically forwarded to 1194 on the vpn instance. + +If specific high numbered ports do not work for your users, you can always allocate and associate a public ip to the instance, and then change the vpn_public_ip and vpn_public_port in the database. This will be turned into a nova-manage command or a flag soon. + + +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. + + +The :mod:`nova.cloudpipe.pipelib` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.cloudpipe.pipelib + :members: + :undoc-members: + :show-inheritance: + + +The :mod:`nova.api.cloudpipe` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.api.cloudpipe + :members: + :undoc-members: + :show-inheritance: + + +The :mod:`nova.crypto` Module +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. automodule:: nova.crypto + :members: + :undoc-members: + :show-inheritance: + diff --git a/doc/source/devref/compute.rst b/doc/source/devref/compute.rst index e4c6c6ae7..741ea6041 100644 --- a/doc/source/devref/compute.rst +++ b/doc/source/devref/compute.rst @@ -16,19 +16,18 @@ 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 a specific virtualization backend, read Drivers_. -The :mod:`manager` Module +The :mod:`nova.compute.manager` Module ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.manager @@ -36,7 +35,7 @@ The :mod:`manager` Module :undoc-members: :show-inheritance: -The :mod:`connection` Module +The :mod:`nova.virt.connection` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.connection @@ -44,7 +43,7 @@ The :mod:`connection` Module :undoc-members: :show-inheritance: -The :mod:`disk` Module +The :mod:`nova.compute.disk` Module ~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.disk @@ -52,7 +51,7 @@ The :mod:`disk` Module :undoc-members: :show-inheritance: -The :mod:`images` Module +The :mod:`nova.virt.images` Module ~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.images @@ -61,7 +60,7 @@ The :mod:`images` Module :show-inheritance: -The :mod:`instance_types` Module +The :mod:`nova.compute.instance_types` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.instance_types @@ -70,7 +69,7 @@ The :mod:`instance_types` Module :show-inheritance: -The :mod:`power_state` Module +The :mod:`nova.compute.power_state` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.power_state @@ -82,42 +81,38 @@ The :mod:`power_state` Module Drivers ------- -Libvirt Implementations -~~~~~~~~~~~~~~~~~~~~~~~ -The libvirt driver is capable of supporting KVM, QEMU, and UML. - -The :mod:`libvirt_conn` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.virt.libvirt_conn` Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.libvirt_conn :members: :undoc-members: :show-inheritance: -XEN -~~~ -The :mod:`xenapi` Module -^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.virt.xenapi` Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.xenapi :members: :undoc-members: :show-inheritance: -FAKE -~~~~ + +The :mod:`nova.virt.fake` Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.fake :members: :undoc-members: :show-inheritance: + Monitoring ---------- -The :mod:`monitor` Module +The :mod:`nova.compute.monitor` Module ~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.monitor diff --git a/doc/source/devref/database.rst b/doc/source/devref/database.rst index b58ea147d..1b41990ab 100644 --- a/doc/source/devref/database.rst +++ b/doc/source/devref/database.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Database Programming Guide -========================== +The Database Layer +================== -The :mod:`api` Module +The :mod:`nova.db.api` Module --------------------- .. automodule:: nova.db.api @@ -27,33 +27,31 @@ The :mod:`api` Module :show-inheritance: -Drivers -------- - -Driver: Sqlalchemy -~~~~~~~~~~~~~~~~~~ +The Sqlalchemy Driver +--------------------- -The :mod:`sqlalchemy.api` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.db.sqlalchemy.api` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.api -The :mod:`sqlalchemy.models` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.db.sqlalchemy.models` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.models :members: :undoc-members: :show-inheritance: -The :mod:`sqlalchemy.session` Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The :mod:`nova.db.sqlalchemy.session` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.session :members: :undoc-members: :show-inheritance: + Tests ----- diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst new file mode 100644 index 000000000..34104c964 --- /dev/null +++ b/doc/source/devref/development.environment.rst @@ -0,0 +1,21 @@ +.. + 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. + +Setting up a development environment +==================================== + +.. todo:: write this diff --git a/doc/source/devref/fakes.rst b/doc/source/devref/fakes.rst index 61622754c..adba57969 100644 --- a/doc/source/devref/fakes.rst +++ b/doc/source/devref/fakes.rst @@ -15,13 +15,16 @@ License for the specific language governing permissions and limitations under the License. -Fakes Programming Guide -======================= +Fake Drivers +============ .. 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 @@ -29,8 +32,9 @@ The :mod:`virt.fake` Module :undoc-members: :show-inheritance: :noindex: - -The :mod:`fakeldap` Module + + +The :mod:`nova.auth.fakeldap` Module -------------------------- .. automodule:: nova.auth.fakeldap @@ -38,7 +42,8 @@ The :mod:`fakeldap` Module :undoc-members: :show-inheritance: -The :mod:`fakerabbit` Module + +The :mod:`nova.fakerabbit` Module ---------------------------- .. automodule:: nova.fakerabbit @@ -46,7 +51,8 @@ The :mod:`fakerabbit` Module :undoc-members: :show-inheritance: -The :class:`FakeAOEDriver` Class + +The :class:`nova.volume.driver.FakeAOEDriver` Class -------------------------------- .. autoclass:: nova.volume.driver.FakeAOEDriver @@ -54,7 +60,8 @@ The :class:`FakeAOEDriver` Class :undoc-members: :show-inheritance: -The :class:`service_unittest.FakeManager` Class + +The :class:`nova.tests.service_unittest.FakeManager` Class ----------------------------------------------- .. autoclass:: nova.tests.service_unittest.FakeManager @@ -62,7 +69,8 @@ The :class:`service_unittest.FakeManager` Class :undoc-members: :show-inheritance: -The :mod:`api.openstack.fakes` Module + +The :mod:`nova.tests.api.openstack.fakes` Module ------------------------------------------------ .. automodule:: nova.tests.api.openstack.fakes diff --git a/doc/source/devref/glance.rst b/doc/source/devref/glance.rst index 3d0f4ebec..8a9dd7d80 100644 --- a/doc/source/devref/glance.rst +++ b/doc/source/devref/glance.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations 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 diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 000000000..39d4c560e --- /dev/null +++ b/doc/source/devref/index.rst @@ -0,0 +1,61 @@ +.. + 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 Development Reference +========================== + +Nova is written in Python. + +Prerequisites +------------- + +.. toctree:: + :maxdepth: 1 + + ../concepts.and.introduction + architecture + development.environment + + +Contents +-------- + +.. toctree:: + :maxdepth: 3 + + services + database + volume + compute + network + auth + api + scheduler + fakes + nova + cloudpipe + objectstore + glance + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/devref/network.rst b/doc/source/devref/network.rst index 318286383..9b70b7830 100644 --- a/doc/source/devref/network.rst +++ b/doc/source/devref/network.rst @@ -15,24 +15,25 @@ License for the specific language governing permissions and limitations under the License. -Networking Programming Guide -============================ +Networking +========== .. todo:: * document hardware specific commands (maybe in admin guide?) (todd) * document a map between flags and managers/backends (todd) -The :mod:`Manager` module -------------------------- + +The :mod:`nova.network.manager` Module +-------------------------------------- .. automodule:: nova.network.manager :members: :undoc-members: :show-inheritance: -The :mod:`LinuxNet` driver --------------------------- +The :mod:`nova.network.linux_net` Driver +---------------------------------------- .. automodule:: nova.network.linux_net :members: @@ -51,7 +52,7 @@ The :mod:`network_unittest` Module :show-inheritance: -legacy docs +Legacy docs ----------- The nova networking components manage private networks, public IP addressing, VPN connectivity, and firewall rules. diff --git a/doc/source/devref/nova.rst b/doc/source/devref/nova.rst index 58125dc80..ff2b6ce9f 100644 --- a/doc/source/devref/nova.rst +++ b/doc/source/devref/nova.rst @@ -15,10 +15,14 @@ License for the specific language governing permissions and limitations 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 @@ -26,7 +30,8 @@ The :mod:`adminclient` Module :undoc-members: :show-inheritance: -The :mod:`context` Module + +The :mod:`nova.context` Module ------------------------- .. automodule:: nova.context @@ -34,7 +39,8 @@ The :mod:`context` Module :undoc-members: :show-inheritance: -The :mod:`exception` Module + +The :mod:`nova.exception` Module --------------------------- .. automodule:: nova.exception @@ -42,7 +48,8 @@ The :mod:`exception` Module :undoc-members: :show-inheritance: -The :mod:`flags` Module + +The :mod:`nova.flags` Module ----------------------- .. automodule:: nova.flags @@ -50,7 +57,8 @@ The :mod:`flags` Module :undoc-members: :show-inheritance: -The :mod:`process` Module + +The :mod:`nova.process` Module ------------------------- .. automodule:: nova.process @@ -58,7 +66,8 @@ The :mod:`process` Module :undoc-members: :show-inheritance: -The :mod:`rpc` Module + +The :mod:`nova.rpc` Module --------------------- .. automodule:: nova.rpc @@ -66,7 +75,8 @@ The :mod:`rpc` Module :undoc-members: :show-inheritance: -The :mod:`server` Module + +The :mod:`nova.server` Module ------------------------ .. automodule:: nova.server @@ -74,7 +84,8 @@ The :mod:`server` Module :undoc-members: :show-inheritance: -The :mod:`test` Module + +The :mod:`nova.test` Module ---------------------- .. automodule:: nova.test @@ -82,7 +93,8 @@ The :mod:`test` Module :undoc-members: :show-inheritance: -The :mod:`twistd` Module + +The :mod:`nova.twistd` Module ------------------------ .. automodule:: nova.twistd @@ -90,7 +102,8 @@ The :mod:`twistd` Module :undoc-members: :show-inheritance: -The :mod:`utils` Module + +The :mod:`nova.utils` Module ----------------------- .. automodule:: nova.utils @@ -98,7 +111,8 @@ The :mod:`utils` Module :undoc-members: :show-inheritance: -The :mod:`validate` Module + +The :mod:`nova.validate` Module -------------------------- .. automodule:: nova.validate @@ -106,7 +120,8 @@ The :mod:`validate` Module :undoc-members: :show-inheritance: -The :mod:`wsgi` Module + +The :mod:`nova.wsgi` Module ---------------------- .. automodule:: nova.wsgi @@ -114,6 +129,7 @@ The :mod:`wsgi` Module :undoc-members: :show-inheritance: + Tests ----- @@ -125,6 +141,7 @@ The :mod:`declare_flags` Module :undoc-members: :show-inheritance: + The :mod:`fake_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -133,6 +150,7 @@ The :mod:`fake_flags` Module :undoc-members: :show-inheritance: + The :mod:`flags_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,6 +159,7 @@ The :mod:`flags_unittest` Module :undoc-members: :show-inheritance: + The :mod:`process_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -149,6 +168,7 @@ The :mod:`process_unittest` Module :undoc-members: :show-inheritance: + The :mod:`real_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -157,6 +177,7 @@ The :mod:`real_flags` Module :undoc-members: :show-inheritance: + The :mod:`rpc_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,6 +186,7 @@ The :mod:`rpc_unittest` Module :undoc-members: :show-inheritance: + The :mod:`runtime_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -173,6 +195,7 @@ The :mod:`runtime_flags` Module :undoc-members: :show-inheritance: + The :mod:`twistd_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -181,6 +204,7 @@ The :mod:`twistd_unittest` Module :undoc-members: :show-inheritance: + The :mod:`validator_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/devref/objectstore.rst b/doc/source/devref/objectstore.rst index 4087b5dd0..473f32026 100644 --- a/doc/source/devref/objectstore.rst +++ b/doc/source/devref/objectstore.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Objectstore Programming Guide -============================= +Objectstore - File Storage Service +================================== -The :mod:`handler` Module +The :mod:`nova.objectstore.handler` Module ------------------------- .. automodule:: nova.objectstore.handler @@ -26,7 +26,8 @@ The :mod:`handler` Module :undoc-members: :show-inheritance: -The :mod:`bucket` Module + +The :mod:`nova.objectstore.bucket` Module ------------------------ .. automodule:: nova.objectstore.bucket @@ -34,7 +35,8 @@ The :mod:`bucket` Module :undoc-members: :show-inheritance: -The :mod:`stored` Module + +The :mod:`nova.objectstore.stored` Module ------------------------ .. automodule:: nova.objectstore.stored @@ -42,7 +44,8 @@ The :mod:`stored` Module :undoc-members: :show-inheritance: -The :mod:`image` Module + +The :mod:`nova.objecstore.image` Module ----------------------- .. automodule:: nova.objectstore.image @@ -50,6 +53,7 @@ The :mod:`image` Module :undoc-members: :show-inheritance: + Tests ----- diff --git a/doc/source/devref/scheduler.rst b/doc/source/devref/scheduler.rst index df820c2f2..d3a6132e5 100644 --- a/doc/source/devref/scheduler.rst +++ b/doc/source/devref/scheduler.rst @@ -15,10 +15,10 @@ License for the specific language governing permissions and limitations under the License. -Scheduler Programming Guide -=========================== +Scheduler +========= -The :mod:`manager` Module +The :mod:`nova.scheduler.manager` Module ------------------------- .. automodule:: nova.scheduler.manager @@ -26,7 +26,8 @@ The :mod:`manager` Module :undoc-members: :show-inheritance: -The :mod:`driver` Module + +The :mod:`nova.scheduler.driver` Module ------------------------ .. automodule:: nova.scheduler.driver @@ -34,7 +35,8 @@ The :mod:`driver` Module :undoc-members: :show-inheritance: -The :mod:`chance` Module + +The :mod:`nova.scheduler.chance` Driver ------------------------ .. automodule:: nova.scheduler.chance @@ -42,7 +44,8 @@ The :mod:`chance` Module :undoc-members: :show-inheritance: -The :mod:`simple` Module + +The :mod:`nova.scheduler.simple` Driver ------------------------ .. automodule:: nova.scheduler.simple @@ -50,6 +53,7 @@ The :mod:`simple` Module :undoc-members: :show-inheritance: + Tests ----- diff --git a/doc/source/devref/services.rst b/doc/source/devref/services.rst new file mode 100644 index 000000000..fe84e20d8 --- /dev/null +++ b/doc/source/devref/services.rst @@ -0,0 +1,53 @@ +.. + 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. + +.. _service_manager_driver: + +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. + +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. + + +The :mod:`nova.service` Module +------------------------------ + +.. automodule:: nova.service + :members: + :undoc-members: + :show-inheritance: + + +The :mod:`nova.manager` Module +------------------------------ + +.. automodule:: nova.manager + :members: + :undoc-members: + :show-inheritance: + + +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. + +Drivers should minimize touching the database, although it is currently acceptable for implementation specific data. This may be reconsidered at some point. + +It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/devref/volume.rst b/doc/source/devref/volume.rst index 19b750870..abec38ba8 100644 --- a/doc/source/devref/volume.rst +++ b/doc/source/devref/volume.rst @@ -15,8 +15,8 @@ License for the specific language governing permissions and limitations under the License. -Volume Programming Guide -========================= +Storage Volumes, Disks +====================== .. todo:: rework after iSCSI merge (see 'Old Docs') (todd or vish) @@ -41,6 +41,9 @@ The :mod:`nova.volume.driver` Module Tests ----- +The :mod:`volume_unittest` Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. automodule:: nova.tests.volume_unittest :members: :undoc-members: diff --git a/doc/source/index.rst b/doc/source/index.rst index 4ef75c432..f96d5ff80 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,7 +45,7 @@ Contents concepts.and.introduction adminguide/index - devguide/index + devref/index reaching.out Recommended System Configuration -- cgit From 7e8e4a74f425955a82f7c087956f3e31720cb0e3 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 14:56:17 -0500 Subject: File moves from "merge" of termie's branch. --- doc/source/Makefile | 102 ---------------------------------------------------- 1 file changed, 102 deletions(-) delete mode 100644 doc/source/Makefile (limited to 'doc/source') diff --git a/doc/source/Makefile b/doc/source/Makefile deleted file mode 100644 index f1391ea41..000000000 --- a/doc/source/Makefile +++ /dev/null @@ -1,102 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXSOURCE = source -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE) - -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest - -.DEFAULT_GOAL = html - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -rm -rf nova.sqlite - cat .autogenerated | xargs rm - rm .autogenerated - -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 - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: source/code.rst - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -pickle: source/code.rst - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: source/code.rst - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: source/code.rst - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: source/code.rst - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nova.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nova.qhc" - -latex: source/code.rst - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: source/code.rst - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: source/code.rst - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: source/code.rst - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." -- cgit From 913d078469720c514a19c01ffe97838c455132b7 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 14:58:02 -0500 Subject: quieter doc building (less warnings). --- doc/source/devref/cloudpipe.rst | 9 ++++++--- doc/source/devref/services.rst | 2 ++ 2 files changed, 8 insertions(+), 3 deletions(-) (limited to 'doc/source') diff --git a/doc/source/devref/cloudpipe.rst b/doc/source/devref/cloudpipe.rst index d6d456a6b..31bd85e81 100644 --- a/doc/source/devref/cloudpipe.rst +++ b/doc/source/devref/cloudpipe.rst @@ -65,27 +65,30 @@ If the use_project_ca flag is set (required to for cloudpipes to work securely), The :mod:`nova.cloudpipe.pipelib` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.cloudpipe.pipelib + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.api.cloudpipe` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.cloudpipe + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.crypto` Module -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.crypto + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/services.rst b/doc/source/devref/services.rst index fe84e20d8..f5bba5c12 100644 --- a/doc/source/devref/services.rst +++ b/doc/source/devref/services.rst @@ -29,6 +29,7 @@ The :mod:`nova.service` Module ------------------------------ .. automodule:: nova.service + :noindex: :members: :undoc-members: :show-inheritance: @@ -38,6 +39,7 @@ The :mod:`nova.manager` Module ------------------------------ .. automodule:: nova.manager + :noindex: :members: :undoc-members: :show-inheritance: -- cgit From 7a501be599e79b79c8a73a9969aa7ba14212bda0 Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 15:14:58 -0500 Subject: Cleanups to doc process. --- doc/source/devref/api.rst | 31 ++++++++++++++++++++++++++- doc/source/devref/auth.rst | 18 +++++++++++----- doc/source/devref/compute.rst | 26 ++++++++++++++++------ doc/source/devref/database.rst | 6 +++++- doc/source/devref/fakes.rst | 17 +++++++++------ doc/source/devref/glance.rst | 3 ++- doc/source/devref/network.rst | 3 +++ doc/source/devref/nova.rst | 45 ++++++++++++++++++++++++++++----------- doc/source/devref/objectstore.rst | 13 +++++++---- doc/source/devref/scheduler.rst | 13 +++++++---- doc/source/devref/volume.rst | 3 +++ 11 files changed, 137 insertions(+), 41 deletions(-) (limited to 'doc/source') diff --git a/doc/source/devref/api.rst b/doc/source/devref/api.rst index e9b79d8dd..14181529a 100644 --- a/doc/source/devref/api.rst +++ b/doc/source/devref/api.rst @@ -27,8 +27,8 @@ Common Components The :mod:`nova.api` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. automodule:: nova.api + :noindex: :members: :undoc-members: :show-inheritance: @@ -37,6 +37,7 @@ The :mod:`nova.api.cloud` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.cloud + :noindex: :members: :undoc-members: :show-inheritance: @@ -47,6 +48,7 @@ OpenStack API The :mod:`openstack` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack + :noindex: :members: :undoc-members: :show-inheritance: @@ -54,6 +56,7 @@ The :mod:`openstack` Module The :mod:`auth` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.auth + :noindex: :members: :undoc-members: :show-inheritance: @@ -61,6 +64,7 @@ The :mod:`auth` Module The :mod:`backup_schedules` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.backup_schedules + :noindex: :members: :undoc-members: :show-inheritance: @@ -68,6 +72,7 @@ The :mod:`backup_schedules` Module The :mod:`faults` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.faults + :noindex: :members: :undoc-members: :show-inheritance: @@ -75,6 +80,7 @@ The :mod:`faults` Module The :mod:`flavors` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.flavors + :noindex: :members: :undoc-members: :show-inheritance: @@ -82,6 +88,7 @@ The :mod:`flavors` Module The :mod:`images` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.images + :noindex: :members: :undoc-members: :show-inheritance: @@ -89,6 +96,7 @@ The :mod:`images` Module The :mod:`ratelimiting` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.ratelimiting + :noindex: :members: :undoc-members: :show-inheritance: @@ -96,6 +104,7 @@ The :mod:`ratelimiting` Module The :mod:`servers` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.servers + :noindex: :members: :undoc-members: :show-inheritance: @@ -103,6 +112,7 @@ The :mod:`servers` Module The :mod:`sharedipgroups` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.openstack.sharedipgroups + :noindex: :members: :undoc-members: :show-inheritance: @@ -114,6 +124,7 @@ The :mod:`nova.api.ec2` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.ec2 + :noindex: :members: :undoc-members: :show-inheritance: @@ -122,6 +133,7 @@ The :mod:`admin` Module ~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.ec2.admin + :noindex: :members: :undoc-members: :show-inheritance: @@ -130,6 +142,7 @@ The :mod:`apirequest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.ec2.apirequest + :noindex: :members: :undoc-members: :show-inheritance: @@ -138,6 +151,7 @@ The :mod:`cloud` Module ~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.ec2.cloud + :noindex: :members: :undoc-members: :show-inheritance: @@ -146,6 +160,7 @@ The :mod:`images` Module ~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.ec2.images + :noindex: :members: :undoc-members: :show-inheritance: @@ -154,6 +169,7 @@ The :mod:`metadatarequesthandler` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.api.ec2.metadatarequesthandler + :noindex: :members: :undoc-members: :show-inheritance: @@ -165,6 +181,7 @@ The :mod:`api_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -173,6 +190,7 @@ The :mod:`api_integration` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api_integration + :noindex: :members: :undoc-members: :show-inheritance: @@ -181,6 +199,7 @@ The :mod:`cloud_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.cloud_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -189,6 +208,7 @@ The :mod:`api.fakes` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.fakes + :noindex: :members: :undoc-members: :show-inheritance: @@ -197,6 +217,7 @@ The :mod:`api.test_wsgi` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.test_wsgi + :noindex: :members: :undoc-members: :show-inheritance: @@ -205,6 +226,7 @@ The :mod:`test_api` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_api + :noindex: :members: :undoc-members: :show-inheritance: @@ -213,6 +235,7 @@ The :mod:`test_auth` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_auth + :noindex: :members: :undoc-members: :show-inheritance: @@ -221,6 +244,7 @@ The :mod:`test_faults` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_faults + :noindex: :members: :undoc-members: :show-inheritance: @@ -229,6 +253,7 @@ The :mod:`test_flavors` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_flavors + :noindex: :members: :undoc-members: :show-inheritance: @@ -237,6 +262,7 @@ The :mod:`test_images` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_images + :noindex: :members: :undoc-members: :show-inheritance: @@ -245,6 +271,7 @@ The :mod:`test_ratelimiting` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_ratelimiting + :noindex: :members: :undoc-members: :show-inheritance: @@ -253,6 +280,7 @@ The :mod:`test_servers` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_servers + :noindex: :members: :undoc-members: :show-inheritance: @@ -261,6 +289,7 @@ The :mod:`test_sharedipgroups` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.api.openstack.test_sharedipgroups + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/auth.rst b/doc/source/devref/auth.rst index ee82df5ab..c3af3f945 100644 --- a/doc/source/devref/auth.rst +++ b/doc/source/devref/auth.rst @@ -21,18 +21,20 @@ Authentication and Authorization ================================ The :mod:`nova.quota` Module ------------------------ +---------------------------- .. automodule:: nova.quota + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.auth.signer` Module -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.signer + :noindex: :members: :undoc-members: :show-inheritance: @@ -42,26 +44,29 @@ Auth Manager ------------ The :mod:`nova.auth.manager` Module -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.manager + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.auth.ldapdriver` Driver -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.ldapdriver + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.auth.dbdriver` Driver -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.auth.dbdriver + :noindex: :members: :undoc-members: :show-inheritance: @@ -75,6 +80,7 @@ The :mod:`auth_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.auth_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -84,6 +90,7 @@ The :mod:`access_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.access_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -93,6 +100,7 @@ The :mod:`quota_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.quota_unittest + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/compute.rst b/doc/source/devref/compute.rst index 741ea6041..db9ef6f34 100644 --- a/doc/source/devref/compute.rst +++ b/doc/source/devref/compute.rst @@ -28,51 +28,57 @@ a specific virtualization backend, read Drivers_. The :mod:`nova.compute.manager` Module -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.manager + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.virt.connection` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.connection + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.compute.disk` Module -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.disk + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.virt.images` Module -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.images + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.compute.instance_types` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.instance_types + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.compute.power_state` Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.power_state + :noindex: :members: :undoc-members: :show-inheritance: @@ -86,6 +92,7 @@ The :mod:`nova.virt.libvirt_conn` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.libvirt_conn + :noindex: :members: :undoc-members: :show-inheritance: @@ -95,6 +102,7 @@ The :mod:`nova.virt.xenapi` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.xenapi + :noindex: :members: :undoc-members: :show-inheritance: @@ -104,6 +112,7 @@ The :mod:`nova.virt.fake` Driver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.virt.fake + :noindex: :members: :undoc-members: :show-inheritance: @@ -113,9 +122,10 @@ Monitoring ---------- The :mod:`nova.compute.monitor` Module -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.compute.monitor + :noindex: :members: :undoc-members: :show-inheritance: @@ -128,6 +138,7 @@ The :mod:`compute_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.compute_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -136,6 +147,7 @@ The :mod:`virt_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.virt_unittest + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/database.rst b/doc/source/devref/database.rst index 1b41990ab..14559aa8c 100644 --- a/doc/source/devref/database.rst +++ b/doc/source/devref/database.rst @@ -19,9 +19,10 @@ The Database Layer ================== The :mod:`nova.db.api` Module ---------------------- +----------------------------- .. automodule:: nova.db.api + :noindex: :members: :undoc-members: :show-inheritance: @@ -34,11 +35,13 @@ The :mod:`nova.db.sqlalchemy.api` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.api + :noindex: The :mod:`nova.db.sqlalchemy.models` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.models + :noindex: :members: :undoc-members: :show-inheritance: @@ -47,6 +50,7 @@ The :mod:`nova.db.sqlalchemy.session` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.db.sqlalchemy.session + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/fakes.rst b/doc/source/devref/fakes.rst index adba57969..0ba5d6ef2 100644 --- a/doc/source/devref/fakes.rst +++ b/doc/source/devref/fakes.rst @@ -25,46 +25,50 @@ fake implementations of various drivers let you get on with your day. The :mod:`nova.virt.fake` Module ---------------------------- +-------------------------------- .. automodule:: nova.virt.fake + :noindex: :members: :undoc-members: :show-inheritance: - :noindex: The :mod:`nova.auth.fakeldap` Module --------------------------- +------------------------------------ .. automodule:: nova.auth.fakeldap + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.fakerabbit` Module ----------------------------- +--------------------------------- .. automodule:: nova.fakerabbit + :noindex: :members: :undoc-members: :show-inheritance: The :class:`nova.volume.driver.FakeAOEDriver` Class --------------------------------- +--------------------------------------------------- .. autoclass:: nova.volume.driver.FakeAOEDriver + :noindex: :members: :undoc-members: :show-inheritance: The :class:`nova.tests.service_unittest.FakeManager` Class ------------------------------------------------ +---------------------------------------------------------- .. autoclass:: nova.tests.service_unittest.FakeManager + :noindex: :members: :undoc-members: :show-inheritance: @@ -74,6 +78,7 @@ The :mod:`nova.tests.api.openstack.fakes` Module ------------------------------------------------ .. automodule:: nova.tests.api.openstack.fakes + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/glance.rst b/doc/source/devref/glance.rst index 8a9dd7d80..d18f7fec6 100644 --- a/doc/source/devref/glance.rst +++ b/doc/source/devref/glance.rst @@ -19,9 +19,10 @@ Glance Integration - The Future of File Storage =============================================== The :mod:`nova.image.service` Module -------------------------------- +------------------------------------ .. automodule:: nova.image.service + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/network.rst b/doc/source/devref/network.rst index 9b70b7830..d9d091494 100644 --- a/doc/source/devref/network.rst +++ b/doc/source/devref/network.rst @@ -28,6 +28,7 @@ The :mod:`nova.network.manager` Module -------------------------------------- .. automodule:: nova.network.manager + :noindex: :members: :undoc-members: :show-inheritance: @@ -36,6 +37,7 @@ The :mod:`nova.network.linux_net` Driver ---------------------------------------- .. automodule:: nova.network.linux_net + :noindex: :members: :undoc-members: :show-inheritance: @@ -47,6 +49,7 @@ The :mod:`network_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.network_unittest + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/nova.rst b/doc/source/devref/nova.rst index ff2b6ce9f..53ce6f34f 100644 --- a/doc/source/devref/nova.rst +++ b/doc/source/devref/nova.rst @@ -23,108 +23,120 @@ very well yet. The :mod:`nova.adminclient` Module ------------------------------ +---------------------------------- .. automodule:: nova.adminclient + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.context` Module -------------------------- +------------------------------ .. automodule:: nova.context + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.exception` Module ---------------------------- +-------------------------------- .. automodule:: nova.exception + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.flags` Module ------------------------ +---------------------------- .. automodule:: nova.flags + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.process` Module -------------------------- +------------------------------ .. automodule:: nova.process + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.rpc` Module ---------------------- +-------------------------- .. automodule:: nova.rpc + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.server` Module ------------------------- +----------------------------- .. automodule:: nova.server + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.test` Module ----------------------- +--------------------------- .. automodule:: nova.test + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.twistd` Module ------------------------- +----------------------------- .. automodule:: nova.twistd + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.utils` Module ------------------------ +---------------------------- .. automodule:: nova.utils + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.validate` Module --------------------------- +------------------------------- .. automodule:: nova.validate + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.wsgi` Module ----------------------- +--------------------------- .. automodule:: nova.wsgi + :noindex: :members: :undoc-members: :show-inheritance: @@ -137,6 +149,7 @@ The :mod:`declare_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.declare_flags + :noindex: :members: :undoc-members: :show-inheritance: @@ -146,6 +159,7 @@ The :mod:`fake_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.fake_flags + :noindex: :members: :undoc-members: :show-inheritance: @@ -155,6 +169,7 @@ The :mod:`flags_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.flags_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -164,6 +179,7 @@ The :mod:`process_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.process_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -173,6 +189,7 @@ The :mod:`real_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.real_flags + :noindex: :members: :undoc-members: :show-inheritance: @@ -182,6 +199,7 @@ The :mod:`rpc_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.rpc_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -191,6 +209,7 @@ The :mod:`runtime_flags` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.runtime_flags + :noindex: :members: :undoc-members: :show-inheritance: @@ -200,6 +219,7 @@ The :mod:`twistd_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.twistd_unittest + :noindex: :members: :undoc-members: :show-inheritance: @@ -209,6 +229,7 @@ The :mod:`validator_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.validator_unittest + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/objectstore.rst b/doc/source/devref/objectstore.rst index 473f32026..3ccfc8566 100644 --- a/doc/source/devref/objectstore.rst +++ b/doc/source/devref/objectstore.rst @@ -19,36 +19,40 @@ Objectstore - File Storage Service ================================== The :mod:`nova.objectstore.handler` Module -------------------------- +------------------------------------------ .. automodule:: nova.objectstore.handler + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.objectstore.bucket` Module ------------------------- +----------------------------------------- .. automodule:: nova.objectstore.bucket + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.objectstore.stored` Module ------------------------- +----------------------------------------- .. automodule:: nova.objectstore.stored + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.objecstore.image` Module ------------------------ +---------------------------------------- .. automodule:: nova.objectstore.image + :noindex: :members: :undoc-members: :show-inheritance: @@ -61,6 +65,7 @@ The :mod:`objectstore_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.objectstore_unittest + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/scheduler.rst b/doc/source/devref/scheduler.rst index d3a6132e5..ab74b6ba8 100644 --- a/doc/source/devref/scheduler.rst +++ b/doc/source/devref/scheduler.rst @@ -19,36 +19,40 @@ Scheduler ========= The :mod:`nova.scheduler.manager` Module -------------------------- +---------------------------------------- .. automodule:: nova.scheduler.manager + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.scheduler.driver` Module ------------------------- +--------------------------------------- .. automodule:: nova.scheduler.driver + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.scheduler.chance` Driver ------------------------- +--------------------------------------- .. automodule:: nova.scheduler.chance + :noindex: :members: :undoc-members: :show-inheritance: The :mod:`nova.scheduler.simple` Driver ------------------------- +--------------------------------------- .. automodule:: nova.scheduler.simple + :noindex: :members: :undoc-members: :show-inheritance: @@ -61,6 +65,7 @@ The :mod:`scheduler_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.scheduler_unittest + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/devref/volume.rst b/doc/source/devref/volume.rst index abec38ba8..54a2d4f8b 100644 --- a/doc/source/devref/volume.rst +++ b/doc/source/devref/volume.rst @@ -25,6 +25,7 @@ The :mod:`nova.volume.manager` Module ------------------------------------- .. automodule:: nova.volume.manager + :noindex: :members: :undoc-members: :show-inheritance: @@ -33,6 +34,7 @@ The :mod:`nova.volume.driver` Module ------------------------------------- .. automodule:: nova.volume.driver + :noindex: :members: :undoc-members: :show-inheritance: @@ -45,6 +47,7 @@ The :mod:`volume_unittest` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: nova.tests.volume_unittest + :noindex: :members: :undoc-members: :show-inheritance: -- cgit From 75841f22d39d90859c1157315c326b4e8a4a3b9c Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 17:18:41 -0500 Subject: Fix include paths so setup.py build_sphinx works again. --- doc/source/conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc/source') diff --git a/doc/source/conf.py b/doc/source/conf.py index 177c6568e..f59a58cdc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -17,14 +17,15 @@ import sys, os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../../')) -sys.path.insert(0, '../') -sys.path.insert(0, './') +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) # -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'ext.nova_todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] +#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] todo_include_todos = True # Add any paths that contain templates here, relative to this directory. -- cgit From a3b6e0f358871dc41516c33d237a0a61735ff84c Mon Sep 17 00:00:00 2001 From: Todd Willey Date: Sun, 7 Nov 2010 17:53:39 -0500 Subject: Use the autodoc tools in the setup.py build_sphinx toolchain. --- doc/source/conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/source') diff --git a/doc/source/conf.py b/doc/source/conf.py index f59a58cdc..10a9b2317 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -24,8 +24,7 @@ sys.path.insert(0, os.path.abspath('./')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'ext.nova_todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] -#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'ext.nova_todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'ext.nova_autodoc'] todo_include_todos = True # Add any paths that contain templates here, relative to this directory. -- cgit From 0131600277f5a2e7183640e1f0d9886315933c1a Mon Sep 17 00:00:00 2001 From: root Date: Mon, 8 Nov 2010 18:39:51 -0800 Subject: add some info on authentication and keys --- doc/source/adminguide/index.rst | 52 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'doc/source') diff --git a/doc/source/adminguide/index.rst b/doc/source/adminguide/index.rst index ad1788b8b..428e3d454 100644 --- a/doc/source/adminguide/index.rst +++ b/doc/source/adminguide/index.rst @@ -20,6 +20,58 @@ Administration Guide How to deploy, monitor, and debug Nova. +Users and Access Keys +--------------------- + +Access to the ec2 api is controlled by an access and secret key. The user's access key needs to be included in the request, and the request must be signed with the secret key. Upon receipt of api requests, nova will verify the signature and execute commands on behalf of the user. + +In order to begin using nova, you will need a to create a user. This can be easily accomplished using the user create or user admin commands in nova-manage. `user create` will create a regular user, whereas `user admin` will create an admin user. The syntax of the command is nova-manage user create username [access] [secret]. For example:: + nova-manage user create john my-access-key a-super-secret-key + +If you do not specify an access or secret key, a random uuid will be created automatically. + +Projects +-------- + +Although the original ec2 api only supports users, nova adds the concept of projects. A user can specify which project he or she wishes to use by appending `:project_id` to his or her access key. If no project is specified in the api request, nova will attempt to use a project with the same id as the user. + +The api will return NotAuthorized if a normal user attempts to make requests for a project that he or she is not a member of. Note that admins or users with special admin roles skip this check and can make requests for any project. + +To create a project, use the `project create` command of nova-manage. The syntax is nova-manage project create projectname manager_id [description] You must specify a projectname and a manager_id. For example:: + nova-manage project create john_project john "This is a sample project" + +You can add and remove users from projects with `project add` and `project remove`. + +Roles +----- + +Roles control the api actions that a user is allowed to perform. For example, a user cannot allocate a public ip without the `netadmin` role. It is important to remember that a users de facto permissions in a project is the intersection of user (global) roles and project (local) roles. So for john to have netadmin permissions in his project, he needs to separate roles specified. You can add roles with `role add`. The syntax is nova-manage role add user_id role [project_id]. Let's give john the netadmin role for his project:: + nova-manage role add john netadmin + nova-manage role add john netadmin john_project + +Credentials +----------- + +Nova can generate a handy set of credentials for a user. These credentials include a CA for bundling images and a file for setting environment variables to be used by euca2ools. If you don't need to bundle images, just the environment script is required. You can export one with the `project environment` command. The syntax of the command is nova-manage project environment project_id user_id [filename]. If you don't specify a filename, it will be exported as novarc. After generating the file, you can simply source it in bash to add the variables to your environment:: + nova-manage project environment john_project john + . novarc + +If you do need to bundle images, you will need to get all of the credentials using `project zipfile`. Note that zipfile will give you an error message if networks haven't been created yet. Otherwise zipfile has the same syntax as environment, only the default file name is nova.zip. Example usage:: + nova-manage project zipfile john_project john + unzip nova.zip + . novarc + +Keypairs +-------- + +Images can be shared by many users, so it is dangerous to put passwords into the images. Nova therefore supports injecting ssh keys into instances before they are booted. This allows a user to login to the instances that he or she creates securely. Generally the first thing that a user does when using the system is create a keypair. Nova generates a public and private key pair, and sends the private key to the user. The public key is stored so that it can be injected into instances. + +Keypairs are created through the api. They can be created on the command line using the euca2ools script euca-add-keypair. Refer to the man page for the available options. Example usage:: + euca-add-keypair test > test.pem + chmod 600 test.pem + euca-run-instances -k test -t m1.tiny ami-tiny + # wait for boot + ssh -i test.pem root@ip.of.instance Contents -------- -- cgit