DOC: Added draft for layer documentation

Signed-off-by: Mihai Prica <prica.mihai@gmail.com>

1 files changed, 96 insertions, 0 deletions

diff --git a/meta-openstack/DOC b/meta-openstack/DOC
new file mode 100644
index 0000000..f00ae86
--- /dev/null
+++ b/meta-openstack/DOC
@@ -0,0 +1,96 @@
+Meta-OpenStack
+==============
+
+Description
+-----------
+The meta-openstack layer provides support for building the OpenStack packages.
+It contains recipes for the nova, glance, keystone, cinder, quantum, swift and
+horizon components and their dependencies.
+
+Components
+----------
+* All the openstack packages are python packages so they can be found in the
+recipes-devtools/python folder. Each component has been split into multiple
+packages similar to the ones used by other Linux distributions.
+
+* The configuration files for each package can be found in the folder with the
+package name. The debug and verbose options have been enabled for capturing
+meaningful information in the logs. The configurations have been done using
+devstack as a model. Each package has to initialize the database before it is
+used for the first time. This is done using a postinstall script that is run
+the first time the image is booted. Due to this, the image boot time is longer
+the first time.
+
+* System-V initscripts are also provided that start the services at boot time.
+
+* The postgresql package is used for the database backend. The layer contains
+an initscript that starts the DB server at boot time. Tests were also done
+using sqlite3 and MySQL and there were no errors.
+
+* The RabbitMQ server is used for the AMQP message queues.  The server is
+started at boot time with the default configuration.
+
+* The dashboard(horizon) component is still under development.
+
+* Three new packagegroups have been defined:
+** packagegroup-cloud-controller - required packages for building a controller
+node. This provides all functionality except the hosting of the virtual
+machines or providing network services. This includes the postgresql-server,
+rabbitmq-server and all the openstack services except the nova-compute
+component.
+** packagegroup-cloud-compute - packages for a processing  node. This node runs
+the compute service as well as the network service agent (in our case, the
+Open vSwitch plugin agent). This server also manages the KVM  hypervisor.
+** packagegroup-cloud-network: this provides networking services like DHCP,
+layer 2 switching, layer 3 routing and metadata connectivity.
+
+* Multiple packagegroups can be used in the same image to get a image that can
+be used both as a controller and compute node.
+
+Dependencies
+------------
+* This layers depends on components from the poky, meta-virtualization and
+meta-openembedded layers. You can find the exact URIs of the repos and the
+necessary revisions in the README file.
+
+Building an image
+-----------------
+* There are two new target images: nova-image-compute and nova-image-controller
+that contain the packagegroups with the same name, that have been describe
+above.
+
+* Once a buildir has been initialized you have to append the necessary layers
+to the bblayers.conf file:
+    /meta-virtualization \
+    /meta-openstack \
+    /meta-openembedded/meta-oe \
+    /meta-openembedded/meta-networking \
+
+Package configurations
+----------------------
+The identity.sh script creates the necessary users, services and endpoints
+for the Keystone identity system. If you want to customize the usernames,
+passwords you have to change this information in the configuration
+files for the services as well.
+
+Running an image
+----------------
+* Controller node *
+To test the image, you can run it using the runqemu script. After the image
+has booted, to use the command line clients some environmental variables
+required by the openstack services to connect to the identity service have to
+be set. These can be found in /root/.bashrc. If you start a new bash session
+they are automatically loaded. All the nova(except compute), keystone, glance,
+cinder, quantum, swift services should be running after a successful boot.
+
+* Compute node *
+The configuration files for the nova package are for a controller node so some
+options have to be changed for the compute service to properly work. You have
+to replace localhost to the controller node IP in the following files:
+    /etc/nova/nova.conf:        sql_connection; rabbit_host;
+    /etc/nova/api-paste.ini:    auth_host;
+    /root/.bashrc:              SERVICE_ENDPOINT, OS_AUTH_URL;
+Once the changes are done you have to restart the nova-compute service.
+!! Hint !!
+When using a multi-node setup is recommended that each host have a different
+hostname and that every host knows the other hosts.