Documentation/training-labs

About Training Labs
Openstack Training Labs is a collection of scripts that install a working OpenStack cluster on your computer almost at the push of a button. It is an automated, fast, reliable and reproducible way of following OpenStack install guides to create a cluster using VirtualBox/KVM Virtual Machines (VM) and should run on most common hardware (Desktops/Laptops) out of the box.

Supported Platforms
The scripts support GNU/Linux, MacOS, and Windows as host Operating Systems (OS). They currently install the Newton or Ocata release of OpenStack on Ubuntu 16.04 Long Term Support (LTS).

Any reasonably modern laptop or desktop Personal Computer (PC) should be able to run the training labs. The most likely bottleneck is main memory - on a 8 GB PC, close major memory consumers like browsers before starting a cluster. Less than 10GB of disk space will be consumed by the VMs that make up the cluster and the CD-ROM image required to install them.

Dependencies
VirtualBox on any supported platform or KVM/Quick Emulator (QEMU) on GNU/Linux.

If you just want to deploy the given OpenStack release, the easiest method is to download the tarball or zip file for your platform and get rocking with OpenStack. Follow training-labs page here: Get training labs here

Alternatively, you can use git to download the training labs development repository, for example (recommended only for advanced users and developers):

git clone git://git.openstack.org/openstack/training-labs.git

Additional notes for Windows users
The zip files available for download contain everything you need to build an OpenStack cluster (except for VirtualBox). If you want to use ssh to communicate with your cluster nodes instead of using the VirtualBox console windows, you need an ssh client such as the free Putty.

The development repository does not contain the Windows batch scripts, you need a POSIX environment (GNU/Linux, OS X, UNIX, Cygwin, ...) to create them (instructions below).

Proxy
If your network need to set proxy to access Internet, set VM_PROXY in "training-labs/labs/config/localrc"  as follows:

VM_PROXY="http://your_proxy_host:port"

Building the cluster
On all platforms, log files are written to the training-labs/labs/log directory while the cluster is building.

The cluster is built in three phases
 * 1) Download the OS image. This phase is skipped if the image exists already in the training-labs/labs/img directory.
 * 2) Build a base disk, about 30 to 40 minutes. This phase is skipped if the base disk exists already.
 * 3) Build the node VMs based on the base disk, about 25 to 30 minutes.

Extra step when using KVM
By default, the cluster is built on Virtualbox VMs. To use KVM/QEMU, set the environment variable PROVIDER to kvm.

cd training-labs/labs sed -i.bak 's/${PROVIDER:=virtualbox}/${PROVIDER:=kvm}/' config/localrc

GNU/Linux and MacOS
cd training-labs/labs ./st.py -b cluster

The command builds a base disk which contains the OS and the software needed for the OpenStack cluster. After the base disk, the command builds two node VMs (controller, compute).

If you execute the same command again, the existing node VMs are deleted and recreated based on the existing base disk. If you want to rebuild the base disk, too, either delete the disk file in the labs/img directory, or use this command:

./st.py -b basedisk

Get Windows batch files
The easiest and recommended way to get everything you need besides VirtualBox is to download a zip file for Windows from the Training Labs page. The zip files include pre-generated Windows batch files. If you have the content of the zip file on your Windows machine, you can skip straight to the next step, "Creating the cluster under Windows".

If you prefer to generate the batch files that create the cluster yourself, you need a POSIX environment that contains bash - a GNU/Linux or UNIX installation is fine, but Cygwin may also work.

In a POSIX environment: cd training-labs/labs ./st.py -w cluster

The Windows batch files are created in a new directory named wbatch. Copy the training-labs/labs directory to Windows.

Creating the cluster under Windows
Run the following three scripts in this order. The first two scripts are only needed once:


 * create_hostnet.bat
 * Creates the host-only networks used by the node VMs to communicate. The script asks for elevated privileges which are needed for that task. You only need to run this script once, the network configuration is saved by VirtualBox. You can verify the configured networks in the VirtualBox GUI: File->Preferences->Network->Host-only Networks.


 * create_base.bat
 * Creates the base disk. You only need to run this script once (and every time you want to update the base disk). This script downloads the OS image needed to build the base disk to training-labs\labs\img, if it doesn't exist, and asks the user to hit a key to proceed after downloading.


 * create_ubuntu_cluster_node.bat
 * Creates the node VMs based on the base disk.

Note: The Windows batch scripts still have some limitations. For instance, if they find an existing node VM of the same name, they print an error and exit. Do not start a batch script if another one is still running.

VirtualBox
By default, the cluster is built in headless mode. In that case, the way to access the cluster nodes is via secure shell (ssh). The localhost's TCP ports 2230 and 2232 are forwarded to the nodes.

To get shell prompts on the cluster nodes:

ssh -p 2230 osbash@localhost  # controller (note the network node is incorporated here since OpenStack Liberty) ssh -p 2232 osbash@localhost  # compute node The password is osbash. To become root, use sudo.

The Putty client allows you to set the port number on the settings->session page before making the connection.

Console windows for the VirtualBox VMs can be displayed by stopping the VMs and starting them again from the VirtualBox Graphical User Interface (GUI). Alternatively, in order to have the console always on, even during the build, add the "-g gui" option to the st.py commands. For instance:

./st.py -g gui -b cluster ./st.py -g gui -b basedisk ./st.py -g gui -w cluster   # generate DOS batch files which will always display console windows

Horizon is also accessed via a forwarded port. Use this URL to access the GUI: http://127.0.0.1:8888/horizon

Two accounts are configured: admin/admin_user_secret and demo/demo_user_pass. The default domain required for login is "default". These and other passwords are configured in config/credentials.

KVM/QEMU
Like with VirtualBox, by default, the cluster is built in headless mode. In that case, the way to access the cluster nodes is via secure shell (ssh). However unlike VirtualBox there is no redirection to special ports to access node shells. It is therefore necessary to ssh to the nodes via the public network "virbr0" Internet Protocol (IP) addresses.

The IP addresses are logged in log/node_ip.db. For instance: 52:54:00:ac:37:da 192.168.122.215 controller 52:54:00:06:6a:b7 192.168.122.3 compute1

The IP addresses can also be acquired by getting the node Medium Access Control (MAC) addresses associated with "virbr0" and using it to parse the Address Resolution Protocol (ARP) table for the IP address. For example to get the MAC address of the Controller node:

virsh -c 'qemu:///system' domiflist controller | grep virbr0 | awk '{print $5}' 52:54:00:ee:b0:e4

Now using the MAC Address extract the IP address for the node using ARP.

arp -e | grep 52:54:00:ee:b0:e4 | awk '{print $1}' 192.168.122.82

To simplify the process here is a simple script that extracts the IP address of the "controller" and "compute" nodes:

cat get_ip.sh CONTROLLER_MAC=`virsh -c qemu:///system domiflist controller | grep virbr0 | awk '{print $5}'` COMPUTE1_MAC=`virsh -c qemu:///system domiflist compute1 | grep virbr0 | awk '{print $5}'` CONTROLLER_IP=`arp -e | grep $CONTROLLER_MAC | awk '{print $1}'` COMPUTE1_IP=`arp -e | grep $COMPUTE1_MAC | awk '{print $1}'` echo "Controller IP: $CONTROLLER_IP" echo "Compute1 IP: $COMPUTE1_IP"
 * 1) !/bin/bash

Here is an example of the script in operation:

./get_ip.sh Controller IP: 192.168.122.82 Compute1 IP: 192.168.122.139

To get shell prompts on the cluster nodes:

ssh osbash@192.168.122.82   # controller, note the network node is incorporated here since OpenStack Liberty) ssh osbash@192.168.122.139   # compute node The password is osbash. To become root, use sudo.

Console windows for the KVM/QEMU VMs can be displayed by stopping the VMs and starting them again from the Virtual Machine Manager (VMM).

Horizon is accessed via the IP address 10.0.0.11 on the "virbr1" Management Network: http://10.0.0.11/horizon

Two accounts are configured: admin/admin_user_secret and demo/demo_user_pass. The default domain required for login is "default". These and other passwords are configured in config/credentials.

Third-party documentation

 * OpenStack Laboratory Guide v5.0.1. Detailed instructions for training-labs by Diarmuid O'Briain of the netLabs!UG OpenStack user group. (2017-10-02)

Managing and Maintaining our Project
Just a starting point for the core developers. It is easier for us to share our knowledge on various important but not feature related boilerplate work for the project. In case of the original author for a given task is not available, this should enable the team to function and not miss important aspects of the project like releases, backports etc.

Please follow the well written and maintained [Project Driver's Guide](http://docs.openstack.org/infra/manual/drivers.html) for more information. The above given document may cover some regions of the project which may require you to be in the **core team**. But majority of the tasks should not require the same.

Quick Links

 * Training-Labs Webpage: http://docs.openstack.org/training_labs/
 * Slides from our presentation at the OpenStack Summit 2015 in Tokyo: https://docs.google.com/presentation/d/1PYe1SQnAL8DxOXcnGI8O-1YAW-Z45P2IXj4NMb3VTNo/
 * training-labs repo: http://git.openstack.org/cgit/openstack/training-labs/
 * Launchpad bug tracker https://launchpad.net/labs
 * Review queue: https://review.openstack.org/#/q/status:open+project:openstack/training-labs,n,z
 * Old labs section in Training guides: http://git.openstack.org/cgit/openstack/training-guides/tree/labs
 * Spec: http://specs.openstack.org/openstack/docs-specs/specs/liberty/training-labs.html
 * Developers Guide: http://docs.openstack.org/infra/manual/developers.html

Meeting Information

 * For more information please follow this link: Training Labs Team Meeting

Team Members

 * Pranav Salunke, IRC: dguitarbite
 * Roger Luethi, IRC: rluethi
 * Julen Larrucea, IRC: julen
 * Name, IRC: Nick, role/interests.