From 1c2952255367066411fbc39e7cac09390aaeb277 Mon Sep 17 00:00:00 2001 From: Ryan Hallisey Date: Mon, 2 May 2016 18:28:35 -0400 Subject: [PATCH] Doc rework for quickstart, multinode, and image-building Our quickstart guide is way too complex. We need to simplify the quickstart guide by pulling out the overwhelming amount of information and splitting it into other docs. Change-Id: Iec175ee7f60bfd11ce06b22c861e51e180c188a9 Partially-implements: blueprint documentation-rework --- doc/image-building.rst | 18 ++++ doc/index.rst | 2 +- doc/multinode.rst | 128 +++++++++++++++++++++++ doc/quickstart.rst | 227 +++++++++++++++++------------------------ 4 files changed, 239 insertions(+), 136 deletions(-) create mode 100644 doc/multinode.rst diff --git a/doc/image-building.rst b/doc/image-building.rst index 677383c5e9..798c7cab05 100644 --- a/doc/image-building.rst +++ b/doc/image-building.rst @@ -4,6 +4,24 @@ Building Container Images The ``tools/build.py`` script in this repository is responsible for building docker images. +Generating kolla-build.conf +--------------------------- + +Install tox and generate the build configuration. The build +configuration is designed to hold advanced customizations when building +containers. + +Create kolla-build.conf using the following steps. +:: + + pip install tox + tox -e genconfig + +The location of the generated configuration file is ``etc/kolla/kolla-build.conf``, +You can also copy it to ``/etc/kolla``. The default location is one of +``/etc/kolla/kolla-build.conf`` or ``etc/kolla/kolla-build.conf``. + + Guide ----- diff --git a/doc/index.rst b/doc/index.rst index edae0fd53c..93b9aeeb76 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,6 +35,7 @@ Kolla Overview CONTRIBUTING deployment-philosophy quickstart + multinode heat-dev-env vagrant-dev-env image-building @@ -43,7 +44,6 @@ Kolla Overview selinux liberty-deployment-warning - Kolla Services ============== diff --git a/doc/multinode.rst b/doc/multinode.rst new file mode 100644 index 0000000000..2d6e984c18 --- /dev/null +++ b/doc/multinode.rst @@ -0,0 +1,128 @@ +Multinode Deployment of Kolla +============================= + +Deploy a registry (required for multinode) +------------------------------------------ + +A Docker registry is a locally hosted registry that replaces the need +to pull from the Docker Hub to get images. Kolla can function with +or without a local registry, however for a multinode deployment a registry +is required. + +The Docker registry prior to version 2.3 has extremely bad performance +because all container data is pushed for every image rather than taking +advantage of Docker layering to optimize push operations. For more +information reference +`pokey registry `__. + + +The Kolla community recommends using registry 2.3 or later. To deploy +registry 2.3 do the following: + +:: + + docker run -d -p 4000:5000 --restart=always --name registry registry:2 + +Note: Kolla looks for the Docker registry to use port 4000. (Docker default +is port 5000) + +After starting the registry, it is necessary to instruct Docker that it will +be communicating with an insecure registry. To enable insecure registry +communication on CentOS, modify the "/etc/sysconfig/docker" file to contain +the following where 192.168.1.100 is the IP address of the machine where the +registry is currently running: + +:: + + # CentOS + other_args="--insecure-registry 192.168.1.100:4000" + +For Ubuntu, edit /etc/default/docker and add: + +:: + + # Ubuntu + DOCKER_OPTS="--insecure-registry 192.168.1.100:4000" + +Docker Inc's packaged version of docker-engine for CentOS is defective and +does not read the other_args configuration options from +"/etc/sysconfig/docker". To rectify this problem, ensure the +following lines appear in the drop-in unit file at +"/etc/systemd/system/docker.service.d/kolla.conf": + +:: + + # CentOS + [Service] + EnvironmentFile=/etc/sysconfig/docker + # It's necessary to clear ExecStart before attempting to override it + # or systemd will complain that it is defined more than once. + ExecStart=/usr/bin/docker daemon -H fd:// $other_args + +And restart docker by executing the following commands: + +:: + + # CentOS + systemctl daemon-reload + systemctl stop docker + systemctl start docker + + # Ubuntu + sudo service docker restart + +Edit the Inventory File +----------------------- + +The ansible inventory file contains all the information needed to determine +what services will land on which hosts. Edit the inventory file in the kolla +directory ansible/inventory/multinode or if kolla was installed with pip, it +can be found in /usr/share/kolla. + +Add the ip addresses or hostnames to a group and the services associated with +that group will land on that host: + +:: + + # These initial groups are the only groups required to be modified. The + # additional groups are for more control of the environment. + [control] + # These hostname must be resolvable from your deployment host + control01 + 192.168.122.24 + + +For more advanced roles, the operator can edit which services will be associated +in with each group. Keep in mind that some services have to be grouped together +and changing these around can break your deployment: + +:: + + [kibana:children] + control + + [elasticsearch:children] + control + + [haproxy:children] + network + +Deploying Kolla +--------------- + +First, check that the deployment targets are in a state where Kolla may deploy +to them: + +:: + + kolla-ansible prechecks -i + +For additional environment setup see the `quickstart guide`_. + +Run the deployment: + +:: + + kolla-ansible deploy -i + +.. _quickstart guide: ./quickstart.rst#deploying-kolla diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 521c5663bb..78757f74e5 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -1,35 +1,6 @@ Deployment of Kolla on Bare Metal or Virtual Machine ==================================================== -Evaluation and Developer Environments -------------------------------------- - -Two virtualized development environment options are available for Kolla. -These options permit the development of Kolla without disrupting the host -operating system. - -If developing Kolla on an OpenStack cloud environment that supports Heat, -follow the :doc:`Heat developer environment guide `. - -If developing Kolla on a system that provides VirtualBox or Libvirt in -addition to Vagrant, use the Vagrant virtual environment documented in -:doc:`Vagrant developer environment guide `. - -Currently the Heat development environment is entirely non-functional. -The Kolla core reviewers have debated removing it from the repository -but have resisted to provide an opportunity for contributors to make Heat -usable for Kolla development. THe Kolla core reviewers believe Heat -would offer a great way to develop Kolla in addition to Vagrant, -bare metal, or a manually setup virtual machine. - -For more information refer to -`_bug 1562334 `__. - -If evaluating Kolla, the community strongly recommends using bare metal or a -virtual machine during the evaluation period. Follow the instructions in this -document to get started with deploying OpenStack on bare metal or a virtual -machine with Kolla. - Host machine requirements ------------------------- @@ -41,7 +12,18 @@ The recommended deployment target requirements: .. NOTE:: Some commands below may require root permissions (e.g. pip, apt-get). -Installing Dependencies +Recommended Environment +----------------------- + +If developing or evaluating Kolla, the community strongly recommends using bare +metal or a virtual machine. Follow the instructions in this document to get +started with deploying OpenStack on bare metal or a virtual machine with Kolla. + +.. NOTE:: There are other deployment environments referenced below in +`Additional Environments`_. + + +Install Dependencies ----------------------- Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container @@ -87,6 +69,7 @@ Make sure the "pip" package manager is installed before proceeding: # Ubuntu 14.04 LTS apt-get install python-pip + Since Docker is required to build images as well as be present on all deployed targets, the Kolla community recommends installing the official Docker, Inc. packaged version of Docker for maximum stability and compatibility with the @@ -144,57 +127,6 @@ easy to install a newer version: pip install -U docker-py -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. Before installing the OpenStack python client, the -following requirements are needed to build the client code: - -:: - - # Ubuntu - apt-get install -y python-dev libffi-dev libssl-dev gcc git - - # CentOS 7 - yum -y install python-devel libffi-devel openssl-devel gcc git - -To install these clients use: - -:: - - pip install -U python-openstackclient - -To clone the Kolla repo: - -:: - - git clone https://git.openstack.org/openstack/kolla - -To install Kolla tools and Python dependencies use: - -:: - - pip install kolla/ - -Copy Kolla configuration to /etc: - -:: - - cd kolla - cp -r etc/kolla /etc/ - -Optionally, you can install tox and generate the build configuration using -following steps. - -:: - - pip install tox - tox -e genconfig - -The location of the generated configuration file is ``etc/kolla/kolla-build.conf``, -You can also copy it to ``/etc/kolla``. The default location is one of -``/etc/kolla/kolla-build.conf`` or ``etc/kolla/kolla-build.conf``. - OpenStack, RabbitMQ, and Ceph require all hosts to have matching times to ensure proper message delivery. In the case of Ceph, it will complain if the hosts differ by more than 0.05 seconds. Some OpenStack services have timers as low as @@ -246,6 +178,7 @@ the libvirt profile. sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.libvirtd + Kolla deploys OpenStack using `Ansible `__. Install Ansible from distribution packaging if the distro packaging has recommended version available. @@ -266,18 +199,6 @@ On CentOS or RHEL systems, this can be done using: Many DEB based systems do not meet Kolla's Ansible version requirements. It is recommended to use pip to install Ansible 1.9.4. - -Some ansible dependencies, like pycrypto, may need gcc installed on the build -system. Install it using system packaging tools if it's not installed already: - -:: - - # CentOS 7 - yum -y install gcc - - # Ubuntu - apt-get install gcc - Finally Ansible 1.9.4 may be installed using: :: @@ -292,63 +213,90 @@ version requirements it can be installed by: apt-get install ansible -Deploy a registry (required for multinode) ------------------------------------------- +Install Kolla +------------- -A Docker registry is a locally hosted registry that replaces the need -to pull from the Docker Hub to get images. Kolla can function with -or without a local registry, however for a multinode deployment a registry -is required. - -The Docker registry prior to version 2.3 has extremely bad performance -because all container data is pushed for every image rather than taking -advantage of Docker layering to optimize push operations. For more -information reference -`pokey registry `__. - -The Kolla community recommends using registry 2.3 or later. To deploy -registry 2.3 do the following: +To clone the Kolla repo: :: - docker run -d -p 4000:5000 --restart=always --name registry registry:2 + git clone https://git.openstack.org/openstack/kolla -Note: Kolla looks for the Docker registry to use port 4000. (Docker default -is port 5000) - -After enabling the registry, it is necessary to instruct Docker that it will -be communicating with an insecure registry. To enable insecure registry -communication on CentOS, modify the "/etc/sysconfig/docker" file to contain -the following where 192.168.1.100 is the IP address of the machine where the -registry is currently running: +To install Kolla tools and Python dependencies use: :: - other_args="--insecure-registry 192.168.1.100:4000" + pip install kolla/ -Docker Inc's packaged version of docker-engine for CentOS is defective and -does not read the other_args configuration options from -"/etc/sysconfig/docker". To rectify this problem, ensure the -following lines appear in the drop-in unit file at -"/etc/systemd/system/docker.service.d/kolla.conf": +Kolla holds configurations files in etc/kolla. Copy the configuration files +to /etc: :: - [Service] - EnvironmentFile=/etc/sysconfig/docker - # It's necessary to clear ExecStart before attempting to override it - # or systemd will complain that it is defined more than once. - ExecStart= - ExecStart=/usr/bin/docker daemon -H fd:// $other_args + cd kolla + cp -r etc/kolla /etc/ -And restart docker by executing the following commands: + +Install Python Clients +---------------------- + +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. The following requirements are needed to build the +client code: :: - # CentOS - systemctl daemon-reload - systemctl stop docker - systemctl start docker + # Ubuntu + apt-get install -y python-dev libffi-dev libssl-dev gcc + + # CentOS 7 + yum -y install python-devel libffi-devel openssl-devel gcc + + +To install the clients use: + +:: + yum install -y python-openstackclient python-neutronclient + + or + + pip install -U python-openstackclient python-neutronclient + +Local Registry +-------------- + +A local registry is not required for an all-in-one installation. Check out the +`multinode doc`_ for more information on using a local registry. Otherwise, the +`dockerhub image registry https://hub.docker.com/u/kollaglue/`__ contains all images from each of Kolla's major releases. The latest release tag is +2.0.0 for Mitaka. + + +Additional Environments +----------------------- + +Two virtualized development environment options are available for Kolla. +These options permit the development of Kolla without disrupting the host +operating system. + +If developing Kolla on an OpenStack cloud environment that supports Heat, +follow the `Heat developer environment guide `__. + +If developing Kolla on a system that provides VirtualBox or Libvirt in +addition to Vagrant, use the Vagrant virtual environment documented in +`Vagrant developer environment guide `__. + +Currently the Heat development environment is entirely non-functional. +The Kolla core reviewers have debated removing it from the repository +but have resisted to provide an opportunity for contributors to make Heat +usable for Kolla development. THe Kolla core reviewers believe Heat +would offer a great way to develop Kolla in addition to Vagrant, +bare metal, or a manually setup virtual machine. + +For more information refer to +`_bug 1562334 `__. + Building Container Images ------------------------- @@ -361,6 +309,8 @@ using the Docker Hub registry with the 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. +Checkout the `image-building doc`_ for more advanced build configuration. + Before running the below instructions, ensure the docker daemon is running or the build process will fail. To build images using default parameters run: @@ -407,6 +357,7 @@ In order to see all available parameters, run: kolla-build -h + Deploying Kolla --------------- @@ -415,7 +366,8 @@ deploy: *all-in-one* and *multinode*. The "all-in-one" deploy is similar to `devstack `__ deploy which installs all OpenStack services on a single host. In the "multinode" deploy, OpenStack services can be run on specific hosts. This documentation only -describes deploying *all-in-one* method as most simple one. +describes deploying *all-in-one* method as most simple one. To setup multinode +see the `multinode doc`_. Each method is represented as an Ansible inventory file. More information on the Ansible inventory file can be found in the Ansible `inventory introduction @@ -665,3 +617,8 @@ Note: When you log in to Kibana web interface for the first time, you are prompted to create an index. Please create an index using the name ``log-*``. This step is necessary until the default Kibana dashboard is implemented in Kolla. + +.. _Additional Environments: ./quickstart.rst#additional-environments +.. _multinode doc: ./multinode.rst +.. _dockerhub image: https://hub.docker.com/u/kollaglue/ +.. _image-building doc: ./image-building.rst