From 2806e453b6f00797d673ac031de6cf5a05fe773e Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Fri, 21 Aug 2015 02:05:23 -0700 Subject: Rework documentaton to actually get people rolling Individuals are beginning to evaluate Kolla and our quickstart documentation is in terrible terrible shape. Pleae just approve this change but do leave feedback. I will address changes in an iterative process in future patches rather then having a perfect documentation patch in one bang. Since this isn't code, there is not a high cost to refactoring or risk of regressions. Change-Id: I222cf15f4c5d748fb2daf3638094b4e7b35f8844 --- devenv/README.rst | 195 ------------------------------------------------ devenv/kollanet.png | Bin 26014 -> 0 bytes docs/dev-quickstart.rst | 157 +++++++++++++++++++++++++++++--------- docs/devenv-heat.rst | 195 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/devenv-vagrant.rst | 96 ++++++++++++++++++++++++ docs/kollanet.png | Bin 0 -> 26014 bytes docs/vagrant.rst | 96 ------------------------ 7 files changed, 411 insertions(+), 328 deletions(-) delete mode 100644 devenv/README.rst delete mode 100644 devenv/kollanet.png create mode 100644 docs/devenv-heat.rst create mode 100644 docs/devenv-vagrant.rst create mode 100644 docs/kollanet.png delete mode 100644 docs/vagrant.rst diff --git a/devenv/README.rst b/devenv/README.rst deleted file mode 100644 index 4436f4660..000000000 --- a/devenv/README.rst +++ /dev/null @@ -1,195 +0,0 @@ -A Kolla Cluster with Heat -========================= - -These `Heat `__ templates will -deploy an *N*-node `Kolla `__ cluster, -where *N* is the value of the ``number_of_nodes`` parameter you specify -when creating the stack. - -Kolla has recently undergone a considerable design change. The details -of the design change is addressed in this -`spec `__. As part of the -design change, containers share pid and networking namespaces with the -Docker host. Therefore, containers no longer connect to a docker0 bridge -and have separate networking from the host. As a result, Kolla -networking has a configuration similar to: - -.. figure:: https://raw.githubusercontent.com/stackforge/kolla/master/devenv/kollanet.png - :alt: Image - - Image -Sharing pid and networking namespaces is detailed in the `super -privileged -containers `__ -concept. - -The Kolla cluster is based on Fedora 21, requires the minimum Docker -version of 1.7.0 -`binary `__. - -These templates are designed to work with the Icehouse or Juno versions -of Heat. If using Icehouse Heat, this -`patch `__ is required to -correct a bug with template validation when using the "Fn::Join" -function). - -Create the Glance Image -======================= - -After cloning the project, run the get-image.sh script from the -project's devenv directory: - -:: - - $ ./get-image.sh - -The script will create a Fedora 21 image with the required -modifications. - -Add the image to your Glance image store: - -:: - - $ glance image-create --name "fedora-21-x86_64" \ - --file /var/lib/libvirt/images/fedora-21-x86_64 \ - --disk-format qcow2 --container-format bare \ - --is-public True --progress - -Create the Stack -================ - -Copy local.yaml.example to local.yaml and edit the contents to match -your deployment environment. Here is an example of a customized -local.yaml: - -:: - - parameters: - ssh_key_name: admin-key - external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d - container_external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d - container_external_subnet_id: 575770dd-6828-1101-34dd-0c62b06fjf8s - dns_nameserver: 192.168.200.1 - -The external\_network\_id is used by Heat to automatically assign -floating IP's to your Kolla nodes. You can then access your Kolla nodes -directly using the floating IP. The network ID is derived from the -``neutron net-list`` command. - -The container\_external\_network\_id is used by the nova-network -container within the Kolla node as the FLAT\_INTERFACE. The -FLAT\_INTERFACE tells Nova what device to use (i.e. eth1) to pass -network traffic between Nova instances across Kolla nodes. This network -should be seperate from the external\_network\_id above and is derived -from the 'neutron net-list' command. - -The container\_external\_subnet\_id: is the subnet equivalent to -container\_external\_network\_id - -Review the parameters section of kollacluster.yaml for a full list of -configuration options. **Note:** You must provide values for: - -- ``ssh_key_name`` -- ``external_network_id`` -- ``container_external_network_id`` -- ``container_external_subnet_id`` - -And then create the stack, referencing that environment file: - -:: - - $ heat stack-create -f kollacluster.yaml -e local.yaml kolla-cluster - -Access the Kolla Nodes -====================== - -You can get the ip address of the Kolla nodes using the -``heat output-show`` command: - -:: - - $ heat output-show kolla-cluster kolla_node_external_ip - "192.168.200.86" - -You can ssh into that server as the ``fedora`` user: - -:: - - $ ssh fedora@192.168.200.86 - -Once logged into your Kolla node, setup your environment. The basic -starting environment will be created using ``docker-compose``. This -environment will start up the openstack services listed in the compose -directory. - -To start, setup your environment variables. - -:: - - $ cd kolla - $ ./tools/genenv - -The ``genenv`` script will create a compose/openstack.env file and an -openrc file in your current directory. The openstack.env file contains -all of your initialized environment variables, which you can edit for a -different setup. - -Next, run the start script. - -:: - - $ ./tools/kolla-compose start - -The ``start`` script is responsible for starting the containers using -``docker-compose -f up -d``. - -If you want to start a container set by hand use this template - -:: - - $ docker-compose -f glance-api-registry.yml up -d - -Debugging -========= - -All Docker commands should be run from the directory of the Docker -binaray, by default this is ``/``. - -A few commands for debugging the system. - -:: - - $ sudo ./docker images - -Lists all images that have been pulled from the upstream kollaglue -repository thus far. This can be run on the node during the ``./start`` -operation to check on the download progress. - -:: - - $ sudo ./docker ps -a - -This will show all processes that docker has started. Removing the -``-a`` will show only active processes. This can be run on the node -during the ``./start`` operation to check that the containers are -orchestrated. - -:: - - $ sudo ./docker logs - -:: - - $ curl http://:3306 - -You can use curl to test connectivity to a container. This example -demonstrates the Mariadb service is running on the node. Output should -appear as follows - -:: - - $ curl http://10.0.0.4:3306 - Trying 10.0.0.4... - Connected to 10.0.0.4. - Escape character is '^]'. - diff --git a/devenv/kollanet.png b/devenv/kollanet.png deleted file mode 100644 index cfb0c6014..000000000 Binary files a/devenv/kollanet.png and /dev/null differ diff --git a/docs/dev-quickstart.rst b/docs/dev-quickstart.rst index e5cecf53d..57e38a700 100644 --- a/docs/dev-quickstart.rst +++ b/docs/dev-quickstart.rst @@ -1,24 +1,42 @@ -Developer Environment -===================== +Quickstart to Deploying OpenStack using Ansible +=============================================== -If you are developing Kolla on an existing OpenStack cloud that supports -Heat, then follow the Heat template -`README `__. -Another option available on systems with VirutalBox is the use of -`Vagrant `__. +Evaluation and Developer Environments +------------------------------------- -The best experience is available with bare metal deployment by following -the instructions below to manually create your Kolla deployment. +Two virtualized evaluation and development environment options are +available. These options permit the evaluation of Kolla without +disrupting the host operating system. + +If developing or evaluating Kolla on an OpenStack cloud environment that +supports Heat, follow the +`Heat evaluation and developer environment guide `__. + +If developing or evaluating Kolla on a system that provides VirtualBox, +Vagrant may be used and is documented in the +`Vagrant evaluation and developer environment guide `__. + +If evaluating or deploying OpenStack on bare-metal with Kolla, follow the +instructions in this document to get started. Installing Dependencies ----------------------- -NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses -kernel modules with the .xz compressed format. The guestfs system cannot -read these images because a dependent package supermin in CentOS needs -to be updated to add .xz compressed format support. +Kolla will not run on Fedora 22 or later currently. Fedora 22 compresses +kernel modules with the .xz compressed format. The guestfs system in the +CentOS family of containers cannot read these images because a dependent +package supermin in CentOS needs to be updated to add .xz compressed format +support. + +On the deployment host Ansible>=1.8.4 must be installed and is the only +requirement for deploying OpenStack. To build the Docker container images +locally the dependnencies docker>=1.7.0 and the Python libraries +docker-py>=1.2.0 and Jinja2>=2.6 must be installed. -To install Kolla depenedencies use: +The deployment targt nodes require the installation of docker>=1.7.0 and +docker-py>=1.2.0. + +To install Kolla Python depenedencies use: :: @@ -26,67 +44,132 @@ To install Kolla depenedencies use: cd kolla sudo pip install -r requirements.txt -In order to run Kolla, it is mandatory to run a version of ``docker`` -that is 1.7.0 or later. - -For most systems you can install the latest stable version of Docker -with the following command: +Since Docker is required to build images as well as be present on all deployed +targets, the Kolla community recommends installing the Docker Inc. packaged +version of Docker for maximum stability and compatiblity with the following +command: :: curl -sSL https://get.docker.io | bash -For Ubuntu based systems, do not use AUFS when starting Docker daemon -unless you are running the Utopic (3.19) kernel. AUFS requires +For Ubuntu based systems where Docker is used, do not use AUFS when starting +Docker daemon unless you are running the Utopic (3.19) kernel. AUFS requires CONFIG\_AUFS\_XATTR=y set when building the kernel. On Ubuntu, versions -prior to 3.19 did not set that flag. If you are unable to upgrade your -kernel, you should use a different storage backend such as btrfs. +prior to 3.19 did not set this flag to be compatible with Docker. If unable +to upgrade the kernel, the Kolla community recommends using a different storage +backend such as btrfs. -Next, install the OpenStack python clients if they are not installed: +On the system where the OpenStack CLI/Python code is run, the Kolla community +recommends installing the OpenStack python clients if they are not installed. +This could be a completely different machine then the deployment host or +deployment targets. To install these clients use: :: sudo pip install -U python-openstackclient -Finally stop libvirt on the host machine. Only one copy of libvirt may +Libvirt is started by default on many operating systems. Please disable libvirt +on any machines that will be deployment targets. Only one copy of libvirt may be running at a time. :: + service libvirtd disable service libvirtd stop -The basic starting environment will be created using ``ansible``. This -environment will start up the OpenStack services listed in the inventory -file. +Kolla deploys OpenStack using +`Ansible `__. Install Ansible from distribution +packaging if the distro packaging has 1.8.4 or greater available. Currently +Ubuntu's version of Ansible is too old to use from packaging. On RPM +based systems install from packaging using: + +:: + + yum -y install ansible + +On DEB based systems this can be done using: + +:: + + apt-get install ansible + +If the distro packaged version of Ansible is too old, install Ansible using +pip: + +:: + + pip install -U ansible + +Buildling Container Images +-------------------------- + +The Kolla community does not currently generate new images for each commit +to the repository. The push time for a full image build to the docker registry +is about 5 hours on 100mbit Internet, so there are technical limitations to +using the Docker Hub registry with our current OpenStack CI/CD systems. + +The Kolla community builds and pushes tested images for each tagged release of +Kolla, but if running from master, it is recommended to build images locally. +All Docker images can be built as follows: + +:: + + tools/build.py -T 1000 + +The -T option specifies how many threads to run concurrently. A docker build +of all containers on Xeon hardware with SSDs and 100mbit network takes roughly +15 minutes. The CentOS mirrors are flakey and the RDO delorean repository is +not mirrored at all. As a result occasionally some containers will fail to +build. If something important fails to bulid, repeat the entire build process +again. The Kolla community recognizes this is not ideal and the Kolla +community is adding an individual container build option to solve this +particular problem. Starting Kolla -------------- -Configure Ansible by reading the Kolla -`Ansible configuration `__ documentation. +Configure Ansible by reading the +`Kolla Ansible configuration Guide `__ documentation. -Next, run the start command: +Finally, run the deploy operation: :: $ sudo ./tools/kolla-ansible deploy A bare metal system takes three minutes to deploy AIO. A virtual machine -takes five minutes to deploy AIO. These are estimates; your hardware may -be faster or slower but should near these results. +deployment takes five minutes to deploy AIO. These are estimates; different +hardware may be faster or slower but should be near these results. Debugging Kolla --------------- -You can determine a container's status by executing: +The container's status can be determined on the deployment targets by +executing: :: - $ sudo docker ps -a + $ docker ps -a + +If any of the containers exited, this indicates a bug in the container. Please +seek help by filing a bug or contacting the developers via IRC. -If any of the containers exited you can check the logs by executing: + the logs can be examined by executing: :: - $ sudo docker logs + $ docker logs + +Note some of the containers don't log to stdout at present so the above +command will provide no information. Instead they log to files +in _/var_/log_/_ inside the container. The Kolla community is +working to improve auditing and make things more consistent. The Kolla +community expects this work to complete by Liberty rc1. An example of +reading the logs for nova-api: + +:: + $ docker exec -t nova_api more /var/log/nova/nova-api.log +Note reading the logs via an exec operation can only be done if the +container is running. diff --git a/docs/devenv-heat.rst b/docs/devenv-heat.rst new file mode 100644 index 000000000..4436f4660 --- /dev/null +++ b/docs/devenv-heat.rst @@ -0,0 +1,195 @@ +A Kolla Cluster with Heat +========================= + +These `Heat `__ templates will +deploy an *N*-node `Kolla `__ cluster, +where *N* is the value of the ``number_of_nodes`` parameter you specify +when creating the stack. + +Kolla has recently undergone a considerable design change. The details +of the design change is addressed in this +`spec `__. As part of the +design change, containers share pid and networking namespaces with the +Docker host. Therefore, containers no longer connect to a docker0 bridge +and have separate networking from the host. As a result, Kolla +networking has a configuration similar to: + +.. figure:: https://raw.githubusercontent.com/stackforge/kolla/master/devenv/kollanet.png + :alt: Image + + Image +Sharing pid and networking namespaces is detailed in the `super +privileged +containers `__ +concept. + +The Kolla cluster is based on Fedora 21, requires the minimum Docker +version of 1.7.0 +`binary `__. + +These templates are designed to work with the Icehouse or Juno versions +of Heat. If using Icehouse Heat, this +`patch `__ is required to +correct a bug with template validation when using the "Fn::Join" +function). + +Create the Glance Image +======================= + +After cloning the project, run the get-image.sh script from the +project's devenv directory: + +:: + + $ ./get-image.sh + +The script will create a Fedora 21 image with the required +modifications. + +Add the image to your Glance image store: + +:: + + $ glance image-create --name "fedora-21-x86_64" \ + --file /var/lib/libvirt/images/fedora-21-x86_64 \ + --disk-format qcow2 --container-format bare \ + --is-public True --progress + +Create the Stack +================ + +Copy local.yaml.example to local.yaml and edit the contents to match +your deployment environment. Here is an example of a customized +local.yaml: + +:: + + parameters: + ssh_key_name: admin-key + external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d + container_external_network_id: 028d70dd-67b8-4901-8bdd-0c62b06cce2d + container_external_subnet_id: 575770dd-6828-1101-34dd-0c62b06fjf8s + dns_nameserver: 192.168.200.1 + +The external\_network\_id is used by Heat to automatically assign +floating IP's to your Kolla nodes. You can then access your Kolla nodes +directly using the floating IP. The network ID is derived from the +``neutron net-list`` command. + +The container\_external\_network\_id is used by the nova-network +container within the Kolla node as the FLAT\_INTERFACE. The +FLAT\_INTERFACE tells Nova what device to use (i.e. eth1) to pass +network traffic between Nova instances across Kolla nodes. This network +should be seperate from the external\_network\_id above and is derived +from the 'neutron net-list' command. + +The container\_external\_subnet\_id: is the subnet equivalent to +container\_external\_network\_id + +Review the parameters section of kollacluster.yaml for a full list of +configuration options. **Note:** You must provide values for: + +- ``ssh_key_name`` +- ``external_network_id`` +- ``container_external_network_id`` +- ``container_external_subnet_id`` + +And then create the stack, referencing that environment file: + +:: + + $ heat stack-create -f kollacluster.yaml -e local.yaml kolla-cluster + +Access the Kolla Nodes +====================== + +You can get the ip address of the Kolla nodes using the +``heat output-show`` command: + +:: + + $ heat output-show kolla-cluster kolla_node_external_ip + "192.168.200.86" + +You can ssh into that server as the ``fedora`` user: + +:: + + $ ssh fedora@192.168.200.86 + +Once logged into your Kolla node, setup your environment. The basic +starting environment will be created using ``docker-compose``. This +environment will start up the openstack services listed in the compose +directory. + +To start, setup your environment variables. + +:: + + $ cd kolla + $ ./tools/genenv + +The ``genenv`` script will create a compose/openstack.env file and an +openrc file in your current directory. The openstack.env file contains +all of your initialized environment variables, which you can edit for a +different setup. + +Next, run the start script. + +:: + + $ ./tools/kolla-compose start + +The ``start`` script is responsible for starting the containers using +``docker-compose -f up -d``. + +If you want to start a container set by hand use this template + +:: + + $ docker-compose -f glance-api-registry.yml up -d + +Debugging +========= + +All Docker commands should be run from the directory of the Docker +binaray, by default this is ``/``. + +A few commands for debugging the system. + +:: + + $ sudo ./docker images + +Lists all images that have been pulled from the upstream kollaglue +repository thus far. This can be run on the node during the ``./start`` +operation to check on the download progress. + +:: + + $ sudo ./docker ps -a + +This will show all processes that docker has started. Removing the +``-a`` will show only active processes. This can be run on the node +during the ``./start`` operation to check that the containers are +orchestrated. + +:: + + $ sudo ./docker logs + +:: + + $ curl http://:3306 + +You can use curl to test connectivity to a container. This example +demonstrates the Mariadb service is running on the node. Output should +appear as follows + +:: + + $ curl http://10.0.0.4:3306 + Trying 10.0.0.4... + Connected to 10.0.0.4. + Escape character is '^]'. + diff --git a/docs/devenv-vagrant.rst b/docs/devenv-vagrant.rst new file mode 100644 index 000000000..f3fe559aa --- /dev/null +++ b/docs/devenv-vagrant.rst @@ -0,0 +1,96 @@ +Vagrant up! +=========== + +This guide describes how to use `Vagrant `__ to +assist in developing for Kolla. + +Vagrant is a tool to assist in scripted creation of virtual machines, it +will take care of setting up a CentOS-based cluster of virtual machines, +each with proper hardware like memory amount and number of network +interfaces. + +Getting Started +--------------- + +The vagrant setup will build a cluster with the following nodes: + +- 3 control nodes +- 1 compute node +- 1 operator node + +Kolla runs from the operator node to deploy OpenStack on the other +nodes. + +All nodes are connected with each other on the secondary nic, the +primary nic is behind a NAT interface for connecting with the internet. +A third nic is connected without IP configuration to a public bridge +interface. This may be used for Neutron/Nova to connect to instances. + +Start with downloading and installing the Vagrant package for your +distro of choice. Various downloads can be found +at the `Vagrant downloads `__. +After we will install the hostmanager plugin so all hosts are recorded in +/etc/hosts (inside each vm): + +:: + + vagrant plugin install vagrant-hostmanager + +Vagrant supports a wide range of virtualization technologies, of which +we will use VirtualBox for now. + +Find some place in your homedir and checkout the Kolla repo: + +:: + + git clone https://github.com/stackforge/kolla.git ~/dev/kolla + +You can now tweak the Vagrantfile or start a CentOS7-based cluster right +away: + +:: + + cd ~/dev/kolla/vagrant && vagrant up + +The command ``vagrant up`` will build your cluster, ``vagrant status`` +will give you a quick overview once done. + +Vagrant Up +---------- + +Once vagrant has completed deploying all nodes, we can focus on +launching Kolla. First, connect with the *operator* node: + +:: + + vagrant ssh operator + +Once connected you can run a simple Ansible-style ping to verify if the +cluster is operable: + +:: + + ansible -i kolla/ansible/inventory/multinode all -m ping -e ansible_ssh_user=root + +Congratulations, your cluster is usable and you can start deploying +OpenStack using Ansible! + +To speed things up, there is a local registry running on the operator. +All nodes are configured so they can use this insecure repo to pull +from, and they will use it as mirror. Ansible may use this registry to +pull images from. + +All nodes have a local folder shared between the group and the +hypervisor, and a folder shared between *all* nodes and the hypervisor. +This mapping is lost after reboots, so make sure you use the command +``vagrant reload `` when reboots are required. Having this shared +folder you have a method to supply a different docker binary to the +cluster. The shared folder is also used to store the docker-registry +files, so they are save from destructive operations like +``vagrant destroy``. + +Further Reading +--------------- + +All Vagrant documentation can be found at +`docs.vagrantup.com `__. diff --git a/docs/kollanet.png b/docs/kollanet.png new file mode 100644 index 000000000..cfb0c6014 Binary files /dev/null and b/docs/kollanet.png differ diff --git a/docs/vagrant.rst b/docs/vagrant.rst deleted file mode 100644 index f3fe559aa..000000000 --- a/docs/vagrant.rst +++ /dev/null @@ -1,96 +0,0 @@ -Vagrant up! -=========== - -This guide describes how to use `Vagrant `__ to -assist in developing for Kolla. - -Vagrant is a tool to assist in scripted creation of virtual machines, it -will take care of setting up a CentOS-based cluster of virtual machines, -each with proper hardware like memory amount and number of network -interfaces. - -Getting Started ---------------- - -The vagrant setup will build a cluster with the following nodes: - -- 3 control nodes -- 1 compute node -- 1 operator node - -Kolla runs from the operator node to deploy OpenStack on the other -nodes. - -All nodes are connected with each other on the secondary nic, the -primary nic is behind a NAT interface for connecting with the internet. -A third nic is connected without IP configuration to a public bridge -interface. This may be used for Neutron/Nova to connect to instances. - -Start with downloading and installing the Vagrant package for your -distro of choice. Various downloads can be found -at the `Vagrant downloads `__. -After we will install the hostmanager plugin so all hosts are recorded in -/etc/hosts (inside each vm): - -:: - - vagrant plugin install vagrant-hostmanager - -Vagrant supports a wide range of virtualization technologies, of which -we will use VirtualBox for now. - -Find some place in your homedir and checkout the Kolla repo: - -:: - - git clone https://github.com/stackforge/kolla.git ~/dev/kolla - -You can now tweak the Vagrantfile or start a CentOS7-based cluster right -away: - -:: - - cd ~/dev/kolla/vagrant && vagrant up - -The command ``vagrant up`` will build your cluster, ``vagrant status`` -will give you a quick overview once done. - -Vagrant Up ----------- - -Once vagrant has completed deploying all nodes, we can focus on -launching Kolla. First, connect with the *operator* node: - -:: - - vagrant ssh operator - -Once connected you can run a simple Ansible-style ping to verify if the -cluster is operable: - -:: - - ansible -i kolla/ansible/inventory/multinode all -m ping -e ansible_ssh_user=root - -Congratulations, your cluster is usable and you can start deploying -OpenStack using Ansible! - -To speed things up, there is a local registry running on the operator. -All nodes are configured so they can use this insecure repo to pull -from, and they will use it as mirror. Ansible may use this registry to -pull images from. - -All nodes have a local folder shared between the group and the -hypervisor, and a folder shared between *all* nodes and the hypervisor. -This mapping is lost after reboots, so make sure you use the command -``vagrant reload `` when reboots are required. Having this shared -folder you have a method to supply a different docker binary to the -cluster. The shared folder is also used to store the docker-registry -files, so they are save from destructive operations like -``vagrant destroy``. - -Further Reading ---------------- - -All Vagrant documentation can be found at -`docs.vagrantup.com `__. -- cgit v1.2.3