openstack/nova
Code Issues Proposed changes

working on novadoc structure

Browse Source
This commit is contained in:
root 2010-11-08 18:40:21 -08:00
parent d24c709044
commit 2a81e25f89
21 changed files with 539 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
doc/source/adminguide/euca2ools.rst Normal file
View File

@ -0,0 +1,49 @@
Euca2ools
=========
Nova is compatible with most of the euca2ools command line utilities. Both Administrators and Users will find these tools helpful for day-to-day administration.
* euca-add-group
* euca-delete-bundle
* euca-describe-instances
* euca-register
* euca-add-keypair
* euca-delete-group
* euca-describe-keypairs
* euca-release-address
* euca-allocate-address
* euca-delete-keypair
* euca-describe-regions
* euca-reset-image-attribute
* euca-associate-address
* euca-delete-snapshot
* euca-describe-snapshots
* euca-revoke
* euca-attach-volume
* euca-delete-volume
* euca-describe-volumes
* euca-run-instances
* euca-authorize
* euca-deregister
* euca-detach-volume
* euca-terminate-instances
* euca-bundle-image
* euca-describe-addresses
* euca-disassociate-address
* euca-unbundle
* euca-bundle-vol
* euca-describe-availability-zones
* euca-download-bundle
* euca-upload-bundle
* euca-confirm-product-instance
* euca-describe-groups
* euca-get-console-output
* euca-version
* euca-create-snapshot
* euca-describe-image-attribute
* euca-modify-image-attribute
* euca-create-volume
* euca-describe-images
* euca-reboot-instances

2
doc/source/adminguide/getting.started.rst
View File

@ -19,7 +19,7 @@ Getting Started with Nova
=========================
This code base is continually changing, so dependencies also change. If you
encounter any problems, see the :doc:`../reaching.out` page.
encounter any problems, see the :doc:`../community` page.
The `contrib/nova.sh` script should be kept up to date, and may be a good
resource to review when debugging.

43
doc/source/adminguide/index.rst
View File

@ -18,19 +18,48 @@
Administration Guide
====================
How to deploy, monitor, and debug Nova.
This guide describes the basics of installing and managing Nova. If you havn't yet, you should do the :doc:`../quickstart` before proceeding.
Authentication
--------------
Contents
--------
.. todo:: Explain authentication
Administration Utilities
------------------------
There are two main tools that a system administrator will find useful to manage their Nova cloud:
.. toctree::
:maxdepth: 1
quickstart
getting.started
binaries
multi.node.install
euca2ools
nova.manage
User and Resource Management
----------------------------
nova-manage and euca2ools provide the basic interface to perform a broad range of administration functions. In this section, you can read more about how to accomplish specific administration tasks.
.. toctree::
:maxdepth: 1
managing.users
managing.projects
managing.instances
managing.images
managing.volumes
managing.networks
Advanced Topics
---------------
.. toctree::
:maxdepth: 1
multi.node.install
binaries
flags
monitoring

21
doc/source/adminguide/managing.images.rst Normal file
View File

@ -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.
Managing Images
===============
.. todo:: Put info on managing images here!

45
doc/source/adminguide/managing.instances.rst Normal file
View File

@ -0,0 +1,45 @@
..
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.
Managing Instances
==================
.. todo: cleanup
Instance management can be accomplished with euca commands:
To run an instance:
::
euca-run-instances
To terminate an instance:
::
euca-terminate-instances
To reboot an instance:
::
euca-reboot-instances
See the euca2ools documentation for more information

49
doc/source/adminguide/managing.networks.rst Normal file
View File

@ -0,0 +1,49 @@
..
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.
Managing Networks
=================
VPN Management
~~~~~~~~~~~~~~
* vpn list: Print a listing of the VPNs for all projects.
* arguments: none
* vpn run: Start the VPN for a given project.
* arguments: project
* vpn spawn: Run all VPNs.
* arguments: none
Floating IP Management
~~~~~~~~~~~~~~~~~~~~~~
* floating create: Creates floating ips for host by range
* arguments: host ip_range
* floating delete: Deletes floating ips by range
* arguments: range
* floating list: Prints a listing of all floating ips
* arguments: none
Network Management
~~~~~~~~~~~~~~~~~~
* network create: Creates fixed ips for host by range
* arguments: [fixed_range=FLAG], [num_networks=FLAG],
[network_size=FLAG], [vlan_start=FLAG],
[vpn_start=FLAG]

57
doc/source/adminguide/managing.projects.rst Normal file
View File

@ -0,0 +1,57 @@
..
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.
Managing Projects
=================
Projects are isolated resource containers forming the principal organizational structure within Nova. They consist of a separate vlan, volumes, instances, images, keys, and users.
Basic Commands
--------------
Admins and Project Managers can use the 'nova-manage project' command to manage project resources:
* project add: Adds user to project
* arguments: project user
* project create: Creates a new project
* arguments: name project_manager [description]
* project delete: Deletes an existing project
* arguments: project_id
* project environment: Exports environment variables to an sourcable file
* arguments: project_id user_id [filename='novarc]
* project list: lists all projects
* arguments: none
* project remove: Removes user from project
* arguments: project user
* project scrub: Deletes data associated with project
* arguments: project
* project zipfile: Exports credentials for project to a zip file
* arguments: project_id user_id [filename='nova.zip]
Setting Quotas
--------------
Nova utilizes a quota system at the project level to control resource consumption across available hardware resources. Current quota controls are available to limit the:
* Number of volumes which may be created
* Total size of all volumes within a project as measured in GB
* Number of instances which may be launched
* Number of processor cores which may be allocated
* Publicly accessible IP addresses
Use the following command to set quotas for a project
* project quota: Set or display quotas for project
* arguments: project_id [key] [value]

63
doc/source/adminguide/managing.users.rst Normal file
View File

@ -0,0 +1,63 @@
Managing Users
==============
.. todo:: is itsec a valid nova user role?
.. todo:: need samples of adding/removing user roles
Role-based access control (RBAC) is an approach to restricting system access to authorized users based on an individual’s role within an organization. Various employee functions require certain levels of system access in order to be successful. These functions are mapped to defined roles and individuals are categorized accordingly. Since users are not assigned permissions directly, but only acquire them through their role (or roles), management of individual user rights becomes a matter of assigning appropriate roles to the user. This simplifies common operations, such as adding a user, or changing a user's department.
Nova’s rights management system employs the RBAC model and currently supports the following five roles:
* **Cloud Administrator.** (admin) Users of this class enjoy complete system access.
* **IT Security.** (itsec) This role is limited to IT security personnel. It permits role holders to quarantine instances.
* **Project Manager.** (projectmanager)The default for project owners, this role affords users the ability to add other users to a project, interact with project images, and launch and terminate instances.
* **Network Administrator.** (netadmin) Users with this role are permitted to allocate and assign publicly accessible IP addresses as well as create and modify firewall rules.
* **Developer.** This is a general purpose role that is assigned to users by default.
RBAC management is exposed through the dashboard for simplified user management.
Nova Administrators
-------------------
Personnel tasked with user and project administration have access to an additional suite of administrative tools that enable:
* Adding and Removing Users
* Managing user roles
* Adding and Removing Projects
* Controlling project VPNs
* Sending user credentials, including VPN certifications, configuration, and a file useful for command line API access. [#f92]_
User Maintenance
~~~~~~~~~~~~~~~~
Users, including admins, are created through the ``user`` commands.
* user admin: creates a new admin and prints exports
* arguments: name [access] [secret]
* user create: creates a new user and prints exports
* arguments: name [access] [secret]
* user delete: deletes an existing user
* arguments: name
* user exports: prints access and secrets for user in export format
* arguments: name
* user list: lists all users
* arguments: none
* user modify: update a users keys & admin flag
* arguments: accesskey secretkey admin
* leave any field blank to ignore it, admin should be 'T', 'F', or blank
User Role Management
~~~~~~~~~~~~~~~~~~~~
* role add: adds role to user
* if project is specified, adds project specific role
* arguments: user, role [project]
* role has: checks to see if user has role
* if project is specified, returns True if user has
the global role and the project role
* arguments: user, role [project]
* role remove: removes role from user
* if project is specified, removes project specific role
* arguments: user, role [project]

4
doc/source/adminguide/multi.node.install.rst
View File

@ -15,8 +15,8 @@
License for the specific language governing permissions and limitations
under the License.
Multi-Node Nova
===============
Running Nova on Multiple Nodes
==============================
When you move beyond evaluating the technology and into building an actual
production environemnt, you will need to know how to configure your datacenter

88
doc/source/adminguide/nova.manage.rst
View File

@ -16,8 +16,8 @@
under the License.
nova-manage
===========
The nova-manage command
=======================
Introduction
~~~~~~~~~~~~
@ -43,61 +43,6 @@ category:
``nova-manage user``
User Maintenance
~~~~~~~~~~~~~~~~
Users, including admins, are created through the ``user`` commands.
* user admin: creates a new admin and prints exports
* arguments: name [access] [secret]
* user create: creates a new user and prints exports
* arguments: name [access] [secret]
* user delete: deletes an existing user
* arguments: name
* user exports: prints access and secrets for user in export format
* arguments: name
* user list: lists all users
* arguments: none
* user modify: update a users keys & admin flag
* arguments: accesskey secretkey admin
* leave any field blank to ignore it, admin should be 'T', 'F', or blank
Project Maintenance
~~~~~~~~~~~~~~~~~~~
* project add: Adds user to project
* arguments: project user
* project create: Creates a new project
* arguments: name project_manager [description]
* project delete: Deletes an existing project
* arguments: project_id
* project environment: Exports environment variables to an sourcable file
* arguments: project_id user_id [filename='novarc]
* project list: lists all projects
* arguments: none
* project quota: Set or display quotas for project
* arguments: project_id [key] [value]
* project remove: Removes user from project
* arguments: project user
* project scrub: Deletes data associated with project
* arguments: project
* project zipfile: Exports credentials for project to a zip file
* arguments: project_id user_id [filename='nova.zip]
User Role Management
~~~~~~~~~~~~~~~~~~~~
* role add: adds role to user
* if project is specified, adds project specific role
* arguments: user, role [project]
* role has: checks to see if user has role
* if project is specified, returns True if user has
the global role and the project role
* arguments: user, role [project]
* role remove: removes role from user
* if project is specified, removes project specific role
* arguments: user, role [project]
Nova Shell
~~~~~~~~~~
@ -113,35 +58,6 @@ Nova Shell
* shell script: Runs the script from the specifed path with flags set properly.
* arguments: path
VPN Management
~~~~~~~~~~~~~~
* vpn list: Print a listing of the VPNs for all projects.
* arguments: none
* vpn run: Start the VPN for a given project.
* arguments: project
* vpn spawn: Run all VPNs.
* arguments: none
Floating IP Management
~~~~~~~~~~~~~~~~~~~~~~
* floating create: Creates floating ips for host by range
* arguments: host ip_range
* floating delete: Deletes floating ips by range
* arguments: range
* floating list: Prints a listing of all floating ips
* arguments: none
Network Management
~~~~~~~~~~~~~~~~~~
* network create: Creates fixed ips for host by range
* arguments: [fixed_range=FLAG], [num_networks=FLAG],
[network_size=FLAG], [vlan_start=FLAG],
[vpn_start=FLAG]
Concept: Flags
--------------

10
doc/source/adminguide/single.node.install.rst Normal file
View File

@ -0,0 +1,10 @@
Single Node Installation
========================
.. todo:: need extended notes on running a single machine
Nova can be run on a single machine, and it is recommended that new users practice managing this type of installation before graduating to multi node systems.
The fastest way to get a test cloud running is through our :doc:`../quickstart`.

21
doc/source/cloud101.rst Normal file
View File

@ -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.
Cloud Computing 101
===================
.. todo:: add in a brief tour of cloud computing concepts

9
doc/source/reaching.out.rst → doc/source/community.rst
View File

@ -15,10 +15,12 @@
License for the specific language governing permissions and limitations
under the License.
Reaching Out
============
Getting Involved
================
The OpenStack community is a very friendly place. Feel free to ask questions.
.. todo:: Talk about contributing code back to the project
The Nova community is a very friendly place. Feel free to ask questions.
This document points you to some of the places you may want to communicate
with people at.
@ -62,3 +64,4 @@ Twitter
-------
Because all the cool kids do it: `@openstack <http://twitter.com/openstack>`_.

2
doc/source/conf.py
View File

@ -24,7 +24,7 @@ sys.path.insert(0, './')
# 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', 'ext.nova_todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig','sphinx.ext.graphviz']
todo_include_todos = True
# Add any paths that contain templates here, relative to this directory.

21
doc/source/devguide/index.rst
View File

@ -15,23 +15,18 @@
License for the specific language governing permissions and limitations
under the License.
Nova Development Guide
======================
Developer Guide
===============
Nova is written in python.
In this section you will find information on Nova's lower level programming APIs.
Prerequisites
-------------
.. toctree::
:maxdepth: 1
Programming HowTos and Tutorials
--------------------------------
../concepts.and.introduction
architecture
development.environment
.. todo:: Add some programming howtos and tuts
Contents
--------
Module Reference
----------------
.. toctree::
:maxdepth: 1

19
doc/source/devguide/modules.rst Normal file
View File

@ -0,0 +1,19 @@
Module Reference
================
.. toctree::
:maxdepth: 1
services
database
volume
compute
network
auth
api
scheduler
fakes
nova
cloudpipe
objectstore
glance

BIN
doc/source/images/fabric.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 123 KiB

35
doc/source/index.rst
View File

@ -18,7 +18,9 @@
Welcome to Nova's documentation!
================================
Nova is a cloud computing fabric controller, the main part of an IaaS system. Individuals and organizations can use it to host and manage their own cloud computing systems. Nova originated as a project out of NASA Ames Research Laboratory.
Nova is a cloud computing fabric controller, the main part of an IaaS system.
Individuals and organizations can use Nova to host and manage their own cloud
computing systems. Nova originated as a project out of NASA Ames Research Laboratory.
Nova is written with the following design guidelines in mind:
@ -31,35 +33,30 @@ Nova is written with the following design guidelines in mind:
This documentation is generated by the Sphinx toolkit and lives in the source
tree. Additional documentation on Nova and other components of OpenStack can
be found on the `OpenStack wiki`_. Also see the :doc:`reaching.out` page for
be found on the `OpenStack wiki`_. Also see the :doc:`community` page for
other ways to interact with the community.
.. _`OpenStack wiki`: http://wiki.openstack.org
Key Concepts
============
.. toctree::
:maxdepth: 1
Contents
========
cloud101
service.architecture
object.model
Using Nova
==========
.. toctree::
:maxdepth: 1
concepts.and.introduction
quickstart
adminguide/index
devguide/index
reaching.out
Recommended System Configuration
================================
Although Nova can be run on a variety of system architectures, for most users the following will be simplest:
* Ubuntu Lucid
* 10GB Hard Disk Space
* 512MB RAM
For development, Nova can run from within a VM.
.. include:: adminguide/quickstart.rst
community
Outstanding Documentation Tasks

53
doc/source/object.model.rst Normal file
View File

@ -0,0 +1,53 @@
Object Model
============
.. todo:: Add brief description for core models
.. graphviz::
digraph foo {
graph [rankdir="LR"]; node [fontsize=9 shape=box];
Instances -> "Public IPs" [arrowhead=crow];
Instances -> "Security Groups" [arrowhead=crow];
Users -> Projects [arrowhead=crow arrowtail=crow dir=both];
Users -> Keys [arrowhead=crow];
Instances -> Volumes [arrowhead=crow];
Projects -> "Public IPs" [arrowhead=crow];
Projects -> Instances [arrowhead=crow];
Projects -> Volumes [arrowhead=crow];
Projects -> Images [arrowhead=crow];
Images -> Instances [arrowhead=crow];
Projects -> "Security Groups" [arrowhead=crow];
"Security Groups" -> Rules [arrowhead=crow];
}
Projects
--------
Instances
---------
Volumes
-------
Users
-----
Images
------
Security Groups
---------------
VLANs
-----
IP Addresses
------------

20
doc/source/adminguide/quickstart.rst → doc/source/quickstart.rst
View File

@ -24,6 +24,26 @@ Nova Quickstart
mysql, etc) (todd)
* Document env vars that can change things (USE_MYSQL, HOST_IP) (todd)
Recommended System Configuration
--------------------------------
Although Nova can be run on a variety of system architectures, for most users the following will be simplest:
* Ubuntu Lucid
* 10GB Hard Disk Space
* 512MB RAM
For development, Nova can run from within a VM.
Getting the Code
----------------
Nova is hosted on launchpad. You can get the code with the following command
::
bzr clone lp:nova
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

60
doc/source/service.architecture.rst Normal file
View File

@ -0,0 +1,60 @@
Service Architecture
====================
Nova’s Cloud Fabric is composed of the following major components:
* API Server
* Message Queue
* Compute Worker
* Network Controller
* Volume Worker
* Scheduler
* Image Store
.. image:: /images/fabric.png
:width: 790
API Server
--------------------------------------------------
At the heart of the cloud framework is an API Server. This API Server makes command and control [#f80]_ of the hypervisor, storage, and networking programmatically available to users in realization of the definition of cloud computing.
The API endpoints are basic http web services which handle authentication, authorization, and basic command and control functions using various API interfaces under the Amazon, Rackspace, and related models. This enables API compatibility with multiple existing tool sets created for interaction with offerings from other vendors. This broad compatibility prevents vendor lock-in.
Message Queue
--------------------------------------------------
A messaging queue brokers the interaction between compute nodes (processing), volumes (block storage), the networking controllers (software which controls network infrastructure), API endpoints, the scheduler (determines which physical hardware to allocate to a virtual resource), and similar components. Communication to and from the cloud controller is by HTTP requests through multiple API endpoints.
A typical message passing event begins with the API server receiving a request from a user. The API server authenticates the user and ensures that the user is permitted to issue the subject command. Availability of objects implicated in the request is evaluated and, if available, the request is routed to the queuing engine for the relevant workers. Workers continually listen to the queue based on their role, and occasionally their type hostname. When such listening produces a work request, the worker takes assignment of the task and begins its execution. Upon completion, a response is dispatched to the queue which is received by the API server and relayed to the originating user. Database entries are queried, added, or removed as necessary throughout the process.
Compute Worker
--------------------------------------------------
Compute workers manage computing instances on host machines. Through the API, commands are dispatched to compute workers to:
* Run instances
* Terminate instances
* Reboot instances
* Attach volumes
* Detach volumes
* Get console output
Network Controller
--------------------------------------------------
The Network Controller manages the networking resources on host machines. The API server dispatches commands through the message queue, which are subsequently processed by Network Controllers. Specific operations include:
* Allocate Fixed IP Addresses
* Configuring VLANs for projects
* Configuring networks for compute nodes
Volume Workers
--------------------------------------------------
Volume Workers interact with iSCSI storage to manage LVM-based [#f89]_ instance volumes. Specific functions include:
* Create Volumes
* Delete Volumes
* Establish Compute volumes
Volumes may easily be transferred between instances, but may be attached to only a single instance at a time.
.. todo:: image store description