diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dev-quickstart.rst | 157 | ||||
| -rw-r--r-- | docs/devenv-heat.rst | 195 | ||||
| -rw-r--r-- | docs/devenv-vagrant.rst (renamed from docs/vagrant.rst) | 0 | ||||
| -rw-r--r-- | docs/kollanet.png | bin | 0 -> 26014 bytes |
4 files changed, 315 insertions, 37 deletions
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 <https://github.com/stackforge/kolla/blob/master/devenv/README.md>`__. -Another option available on systems with VirutalBox is the use of -`Vagrant <https://github.com/stackforge/kolla/blob/master/docs/vagrant.md>`__. +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 <https://github.com/stackforge/kolla/blob/master/docs/devenv-heat.rst>`__. + +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 <https://github.com/stackforge/kolla/blob/master/docs/devenv-vagrant.rst>`__. + +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 <https://ansible.com>`__. 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 <https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md>`__ documentation. +Configure Ansible by reading the +`Kolla Ansible configuration Guide <https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md>`__ 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 <container-name> + $ docker logs <container-name> + +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_/_<service_> 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 <https://wiki.openstack.org/wiki/Heat>`__ templates will +deploy an *N*-node `Kolla <https://launchpad.net/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 <https://review.openstack.org/#/c/153798/>`__. 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 <http://sdake.io/2015/01/28/an-atomic-upgrade-process-for-openstack-compute-nodes/>`__ +concept. + +The Kolla cluster is based on Fedora 21, requires the minimum Docker +version of 1.7.0 +`binary <https://docs.docker.com/installation/binaries/>`__. + +These templates are designed to work with the Icehouse or Juno versions +of Heat. If using Icehouse Heat, this +`patch <https://review.openstack.org/#/c/121139/>`__ 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 <osp-service-container> 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 <containerid> + +:: + + $ curl http://<NODE_IP>: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/vagrant.rst b/docs/devenv-vagrant.rst index f3fe559aa..f3fe559aa 100644 --- a/docs/vagrant.rst +++ b/docs/devenv-vagrant.rst diff --git a/docs/kollanet.png b/docs/kollanet.png Binary files differnew file mode 100644 index 000000000..cfb0c6014 --- /dev/null +++ b/docs/kollanet.png |
