Merge lp:~annegentle/nova/docs into lp:~hudson-openstack/nova/trunk

[Anne Gentle]

Updated docs for db sync requirements; merged with Vish's similar doc updates

[Jay Pipes (jaypipes)]

Hi!

Need two newlines (you have one newline) after sys.exit(1) here to avoid pep8 fault:

21 + exit(1)

Other than that, looks good :)

-jay

review: Needs Fixing

[Jay Pipes (jaypipes)]

Also, unless I'm mistaken, exit(1) should be sys.exit(1), and please ensure that you have done:

import sys

in that file :)

-jay

[Anne Gentle (annegentle)]

Thanks for reviewing, Jay - though I think maybe I should exclude any changes to bin/nova-manage that I got from merging from here:

https://code.launchpad.net/~vishvananda/nova/friendly-db/+merge/46797

Eric Day thought there was a better approach so I don't want code changes, I just want this proposal to be for doc changes... hm. So, how do I remove bin/nova-manage? Just replace the file with the one from trunk, commit, push to this branch?

[Jay Pipes (jaypipes)]

Ah, I see.

OK, do this then on your laptop:

# I assume below your local branch of trunk is called "trunk"...
bzr branch trunk new-docs
cd new-docs
bzr merge -r revno:593:../docs

That should do the trick I think :)

bzr diff | less

and check the diff only include the doc fixes, then if it all looks good:

bzr commit -m "Merge doc changes for db sync"
bzr push --overwrite lp:~annegentle/nova/docs

-jay

[lp:~annegentle/nova/docs]

593. By Anne Gentle on 2011-01-21

Merge doc changes affected by db sync

[Anne Gentle (annegentle)]

Thanks Jay! That did what I hoped - only the RST files are changed now. Please re-review when you get a mo.

[Jay Pipes (jaypipes)]

w00tness.

review: Approve

=== modified file 'doc/source/adminguide/distros/ubuntu.10.04.rst'
--- doc/source/adminguide/distros/ubuntu.10.04.rst	2011-01-03 09:08:32 +0000
+++ doc/source/adminguide/distros/ubuntu.10.04.rst	2011-01-21 16:50:35 +0000
@@ -31,7 +31,7 @@
 
 ::
 
-    sudo add-get install python-software-properties
+    sudo apt-get install python-software-properties
     sudo add-apt-repository ppa:nova-core/trunk
     sudo apt-get update
     sudo apt-get install python-twisted python-gflags

=== modified file 'doc/source/adminguide/index.rst'
--- doc/source/adminguide/index.rst	2011-01-04 22:58:08 +0000
+++ doc/source/adminguide/index.rst	2011-01-21 16:50:35 +0000
@@ -60,12 +60,13 @@
 Deployment
 ----------
 
-.. todo:: talk about deployment scenarios
+For a starting multi-node architecture, you would start with two nodes - a cloud controller node and a compute node. The cloud controller node contains the nova- services plus the Nova database. The compute node installs all the nova-services but then refers to the database installation, which is hosted by the cloud controller node. Ensure that the nova.conf file is identical on each node. If you find performance issues not related to database reads or writes, but due to the messaging queue backing up, you could add additional messaging services (rabbitmq).
 
 .. toctree::
    :maxdepth: 1
 
    multi.node.install
+   dbsync
 
 
 Networking

=== modified file 'doc/source/adminguide/multi.node.install.rst'
--- doc/source/adminguide/multi.node.install.rst	2011-01-07 16:56:41 +0000
+++ doc/source/adminguide/multi.node.install.rst	2011-01-21 16:50:35 +0000
@@ -1,20 +1,3 @@
-..
-      Copyright 2010-2011 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.
 
 Installing Nova on Multiple Servers
 ===================================
@@ -26,13 +9,14 @@
  
 You can install multiple nodes to increase performance and availability of the OpenStack Compute installation.
  
-This setup is based on an Ubuntu Lucid 10.04 installation with the latest updates. Most of this works around issues that need to be resolved in the installation and configuration scripts as of October 18th 2010. It also needs to eventually be generalized, but the intent here is to get the multi-node configuration bootstrapped so folks can move forward.
- 
- 
+This setup is based on an Ubuntu Lucid 10.04 installation with the latest updates. Most of this works around issues that need to be resolved either in packaging or bug-fixing. It also needs to eventually be generalized, but the intent here is to get the multi-node configuration bootstrapped so folks can move forward.
+
+For a starting architecture, these instructions describing installing a cloud controller node and a compute node. The cloud controller node contains the nova- services plus the database. The compute node installs all the nova-services but then refers to the database installation, which is hosted by the cloud controller node.
+
 Requirements for a multi-node installation
 ------------------------------------------
  
-* You need a real database, compatible with SQLAlchemy (mysql, postgresql) There's not a specific reason to choose one over another, it basically depends what you know. MySQL is easier to do High Availability (HA) with, but people may already know Postgres. We should document both configurations, though.
+* You need a real database, compatible with SQLAlchemy (mysql, postgresql) There's not a specific reason to choose one over another, it basically depends what you know. MySQL is easier to do High Availability (HA) with, but people may already know PostgreSQL. We should document both configurations, though.
 * For a recommended HA setup, consider a MySQL master/slave replication, with as many slaves as you like, and probably a heartbeat to kick one of the slaves into being a master if it dies.
 * For performance optimization, split reads and writes to the database. MySQL proxy is the easiest way to make this work if running MySQL.
  
@@ -41,7 +25,45 @@
  
 * Networking is configured between/through the physical machines on a single subnet.
 * Installation and execution are both performed by ROOT user.
-  
+
+Scripted Installation
+---------------------
+A script available to get your OpenStack cloud running quickly. You can copy the file to the server where you want to install OpenStack Compute services - typically you would install a compute node and a cloud controller node. 
+
+You must run these scripts with root permissions. 
+
+From a server you intend to use as a cloud controller node, use this command to get the cloud controller script. This script is a work-in-progress and the maintainer plans to keep it up, but it is offered "as-is." Feel free to collaborate on it in GitHub - https://github.com/dubsquared/OpenStack-NOVA-Installer-Script/.
+
+::
+    
+    wget --no-check-certificate https://github.com/dubsquared/OpenStack-NOVA-Installer-Script/raw/master/Nova_CC_Installer_v0.1
+
+Ensure you can execute the script by modifying the permissions on the script file.
+
+::
+    
+    sudo chmod 755 Nova_CC_Installer_v0.1
+
+
+::
+    
+    sudo ./Nova_CC_Installer_v0.1
+
+Next, from a server you intend to use as a compute node (doesn't contain the database), install the nova services. Copy the nova.conf from the cloud controller node to the compute node. 
+
+Restart related services::
+ 
+    libvirtd restart; service nova-network restart; service nova-compute restart; service nova-api restart; service nova-objectstore restart; service nova-scheduler restart
+
+You can go to the `Configuration section`_ for next steps.
+
+Manual Installation - Step-by-Step
+----------------------------------
+The following sections show you how to install Nova manually with a cloud controller node and a separate compute node. The cloud controller node contains the database plus all nova- services, and the compute node runs nova- services only. 
+
+Cloud Controller Installation
+`````````````````````````````
+On the cloud controller node, you install nova services and the related helper applications, and then configure with the nova.conf file. You will then copy the nova.conf file to the compute node, which you install as a second node in the `Compute Installation`_.
  
 Step 1 - Use apt-get to get the latest code
 -------------------------------------------
@@ -59,19 +81,18 @@
     
     sudo apt-get update
 
-3. Install nova-pkgs (dependencies should be automatically installed).
+3. Install python required packages, nova-packages, and helper apps.
 
 ::
 
-    sudo apt-get install python-greenlet
-    sudo apt-get install nova-common nova-doc python-nova nova-api nova-network nova-objectstore nova-scheduler
+    sudo apt-get install python-greenlet python-mysqldb python-nova nova-common nova-doc nova-api nova-network nova-objectstore nova-scheduler nova-compute euca2ools unzip
 
 It is highly likely that there will be errors when the nova services come up since they are not yet configured. Don't worry, you're only at step 1!
 
-Step 2 Setup configuration file (installed in /etc/nova)
---------------------------------------------------------
+Step 2 Set up configuration file (installed in /etc/nova)
+---------------------------------------------------------
 
-1.  Nova development has consolidated all config files to nova.conf as of November 2010.   There is a default set of options that are already configured in nova.conf:
+1.  Nova development has consolidated all config files to nova.conf as of November 2010. There is a default set of options that are already configured in nova.conf:
  
 ::
  
@@ -81,7 +102,7 @@
 --logdir=/var/log/nova
 --state_path=/var/lib/nova
  
-The following items ALSO need to be defined in /etc/nova/nova.conf.  I’ve added some explanation of the variables, as comments CANNOT be in nova.conf.  There seems to be an issue with nova-manage not processing the comments/whitespace correctly:
+The following items ALSO need to be defined in /etc/nova/nova.conf.  I’ve added some explanation of the variables, as comments CANNOT be in nova.conf. There seems to be an issue with nova-manage not processing the comments/whitespace correctly:
 
 --sql_connection ###  Location of Nova SQL DB
 
@@ -130,7 +151,7 @@
 The Nova config file should have its owner set to root:nova, and mode set to 0644, since they contain your MySQL server's root password. ::
 
     chown -R root:nova /etc/nova
-    chmod 644 /etc/nova/nova.conf
+    chmod 644 /etc/nova/nova.conf 
  
 Step 3 - Setup the SQL DB (MySQL for this setup)
 ------------------------------------------------
@@ -153,10 +174,30 @@
 
     sed -i 's/127.0.0.1/0.0.0.0/g' /etc/mysql/my.cnf
     service mysql restart
- 
-3.  Network Configuration
- 
-If you use FlatManager (as opposed to VlanManager that we set) as your network manager, there are some additional networking changes you’ll have to make to ensure connectivity between your nodes and VMs.  If you chose VlanManager or FlatDHCP, you may skip this section, as it’s set up for you automatically.
+
+4. MySQL DB configuration:
+ 
+Create NOVA database::
+
+    mysql -uroot -p$MYSQL_PASS -e 'CREATE DATABASE nova;'
+ 
+Update the DB to include user 'root'@'%' with super user privileges::
+
+    mysql -uroot -p$MYSQL_PASS -e "GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;"
+ 
+Set mySQL root password::
+
+    mysql -uroot -p$MYSQL_PASS -e "SET PASSWORD FOR 'root'@'%' = PASSWORD('$MYSQL_PASS');" 
+ 
+Compute Node Installation
+`````````````````````````
+ 
+Repeat steps 1 and 2 from the Cloud Controller Installation section above, then configure the network for your Compute instances on the Compute node. Copy the nova.conf file from the Cloud Controller node to this node.
+ 
+Network Configuration
+---------------------
+
+If you use FlatManager as your network manager (as opposed to VlanManager that is shown in the nova.conf example above), there are some additional networking changes you’ll have to make to ensure connectivity between your nodes and VMs.  If you chose VlanManager or FlatDHCP, you may skip this section, as it’s set up for you automatically.
  
 Nova defaults to a bridge device named 'br100'. This needs to be created and somehow integrated into YOUR network. To keep things as simple as possible, have all the VM guests on the same network as the VM hosts (the compute nodes). To do so, set the compute node's external IP address to be on the bridge and add eth0 to that bridge. To do this, edit your network interfaces config to look like the following::
 
@@ -179,31 +220,24 @@
  
     sudo /etc/init.d/networking restart
 
-4. MySQL DB configuration:
- 
-Create NOVA database::
-
-    mysql -uroot -p$MYSQL_PASS -e 'CREATE DATABASE nova;'
- 
-Update the DB to include user 'root'@'%' with super user privileges::
-
-    mysql -uroot -p$MYSQL_PASS -e "GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;"
- 
-Set mySQL root password::
-
-    mysql -uroot -p$MYSQL_PASS -e "SET PASSWORD FOR 'root'@'%' = PASSWORD('$MYSQL_PASS');"
- 
-Step 4 - Setup Nova environment
--------------------------------
-
-These are the commands you run to set up a user and project::
-
+Configuration
+`````````````
+
+On the Compute node, you should continue with these configuration steps.
+
+Step 1 - Set up the Nova environment
+------------------------------------
+
+These are the commands you run to update the database if needed, and then set up a user and project::
+
+    /usr/bin/python /usr/bin/nova-manage db sync
     /usr/bin/python /usr/bin/nova-manage user admin <user_name>
     /usr/bin/python /usr/bin/nova-manage project create <project_name> <user_name>
     /usr/bin/python /usr/bin/nova-manage network create <project-network> <number-of-networks-in-project> <IPs in project>
  
 Here is an example of what this looks like with real data::
 
+    /usr/bin/python /usr/bin/nova-manage db sync
     /usr/bin/python /usr/bin/nova-manage user admin dub
     /usr/bin/python /usr/bin/nova-manage project create dubproject dub
     /usr/bin/python /usr/bin/nova-manage network create 192.168.0.0/24 1 255
@@ -215,7 +249,7 @@
 On running this command, entries are made in the 'networks' and 'fixed_ips' table. However, one of the networks listed in the 'networks' table needs to be marked as bridge in order for the code to know that a bridge exists. The Network is marked as bridged automatically based on the type of network manager selected.  This is ONLY necessary if you chose FlatManager as your network type.  More information can be found at the end of this document discussing setting up the bridge device.
  
  
-Step 5 - Create Nova certifications
+Step 2 - Create Nova certifications
 -----------------------------------
  
 1.  Generate the certs as a zip file.  These are the certs you will use to launch instances, bundle images, and all the other assorted api functions. 
@@ -229,18 +263,18 @@
 
 ::
 
-    unzip /root/creds/novacreds.zip -d /root/creds/ 
+    unzip /root/creds/novacreds.zip -d /root/creds/
     cat /root/creds/novarc >> ~/.bashrc
     source ~/.bashrc
 
-Step 6 - Restart all relevant services
+Step 3 - Restart all relevant services
 --------------------------------------
 
 Restart all six services in total, just to cover the entire spectrum::
  
     libvirtd restart; service nova-network restart; service nova-compute restart; service nova-api restart; service nova-objectstore restart; service nova-scheduler restart
 
-Step 7 - Closing steps, and cleaning up
+Step 4 - Closing steps, and cleaning up
 ---------------------------------------
 
 One of the most commonly missed configuration areas is not allowing the proper access to VMs. Use the 'euca-authorize' command to enable access.  Below, you will find the commands to allow 'ping' and 'ssh' to your VMs::
@@ -253,8 +287,8 @@
     killall dnsmasq
     service nova-network restart
 
-Step 8 – Testing the installation
----------------------------------
+Testing the Installation
+````````````````````````
 
 You can then use `euca2ools` to test some items::
 
@@ -267,13 +301,15 @@
  
 If you don’t get any immediate errors, you’re successfully making calls to your cloud!
 
-Step 9 - Spinning up a VM for testing 
--------------------------------------
+Spinning up a VM for Testing 
+````````````````````````````
 
 (This excerpt is from Thierry Carrez's blog, with reference to http://wiki.openstack.org/GettingImages.) 
 
 The image that you will use here will be a ttylinux image, so this is a limited function server. You will be able to ping and SSH to this instance, but it is in no way a full production VM.  
 
+UPDATE: Due to `bug 661159 <https://bugs.launchpad.net/nova/+bug/661159>`_, we can’t use images without ramdisks yet, so we can’t use the classic Ubuntu cloud images from http://uec-images.ubuntu.com/releases/ yet. For the sake of this tutorial, we’ll use the `ttylinux images from Scott Moser instead <http://smoser.brickies.net/ubuntu/ttylinux-uec/>`_.
+
 Download the image, and publish to your bucket:
 
 ::
@@ -324,5 +360,4 @@
 
 For more information in creating you own custom (production ready) instance images, please visit http://wiki.openstack.org/GettingImages for more information!
 
-Enjoy your new private cloud, and play responsibly!
-
+Enjoy your new private cloud, and play responsibly!
\ No newline at end of file

=== modified file 'doc/source/adminguide/single.node.install.rst'
--- doc/source/adminguide/single.node.install.rst	2010-12-07 22:48:42 +0000
+++ doc/source/adminguide/single.node.install.rst	2011-01-21 16:50:35 +0000
@@ -159,7 +159,7 @@
     Resolving cblah2.cdn.cloudfiles.rackspacecloud.com... 208.111.196.6, 208.111.196.7
     Connecting to cblah2.cdn.cloudfiles.rackspacecloud.com|208.111.196.6|:80... connected.
     HTTP request sent, awaiting response... 200 OK
-    Length: 58520278 (56M) [appication/x-gzip]
+    Length: 58520278 (56M) [application/x-gzip]
     Saving to: `images.tgz'
 
     100%[======================================>] 58,520,278  14.1M/s   in 3.9s

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2011-01-04 22:58:08 +0000
+++ doc/source/index.rst	2011-01-21 16:50:35 +0000
@@ -20,7 +20,7 @@
 
 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.
+computing systems. Nova originated as a project out of NASA Ames Research Laboratory.
 
 Nova is written with the following design guidelines in mind:
 
@@ -32,7 +32,7 @@
 * **API Compatibility**: Nova strives to provide API-compatible with popular systems like Amazon EC2
 
 This documentation is generated by the Sphinx toolkit and lives in the source
-tree.  Additional documentation on Nova and other components of OpenStack can
+tree. Additional documentation on Nova and other components of OpenStack can
 be found on the `OpenStack wiki`_.  Also see the :doc:`community` page for
 other ways to interact with the community.