From 426e63772496769ba37538bfc2d3cd472a7a1ab8 Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Mon, 2 Nov 2015 07:07:47 -0700 Subject: Implement Mitaka ODS Documentation structure From this etherpad: https://etherpad.openstack.org/p/kolla-mitaka-documentation Lay groundwork for structure of new documentation layout. Further work will finish the job on this doc work. Note in a later change I793244c47ffbe0ba304e79bacf708494e59d99c4 ansible-deployment, deploy-all-in-one-node, and quickstart.rst will be merged into one document. Change-Id: I42b576ffab796da6e27adc9dbf55b2ceed641c16 --- doc/advanced-configuration.rst | 10 ++ doc/customize-deployment.rst | 70 -------------- doc/deployment-philosophy.rst | 70 ++++++++++++++ doc/dev-quickstart.rst | 215 ----------------------------------------- doc/devenv-heat.rst | 194 ------------------------------------- doc/devenv-vagrant.rst | 138 -------------------------- doc/heat-dev-env.rst | 194 +++++++++++++++++++++++++++++++++++++ doc/index.rst | 16 +-- doc/operating-kolla.rst | 22 +++++ doc/quickstart.rst | 215 +++++++++++++++++++++++++++++++++++++++++ doc/vagrant-dev-env.rst | 138 ++++++++++++++++++++++++++ 11 files changed, 657 insertions(+), 625 deletions(-) create mode 100644 doc/advanced-configuration.rst delete mode 100644 doc/customize-deployment.rst create mode 100644 doc/deployment-philosophy.rst delete mode 100644 doc/dev-quickstart.rst delete mode 100644 doc/devenv-heat.rst delete mode 100644 doc/devenv-vagrant.rst create mode 100644 doc/heat-dev-env.rst create mode 100644 doc/operating-kolla.rst create mode 100644 doc/quickstart.rst create mode 100644 doc/vagrant-dev-env.rst (limited to 'doc') diff --git a/doc/advanced-configuration.rst b/doc/advanced-configuration.rst new file mode 100644 index 000000000..fda524ce8 --- /dev/null +++ b/doc/advanced-configuration.rst @@ -0,0 +1,10 @@ +Advanced Configuration +====================== + +Deployment Configuration +------------------------ +TODO(all) fill this section out + +OpenStack Service Configuration in Kolla +---------------------------------------- +TODO(all) fill this section out diff --git a/doc/customize-deployment.rst b/doc/customize-deployment.rst deleted file mode 100644 index 9359f3934..000000000 --- a/doc/customize-deployment.rst +++ /dev/null @@ -1,70 +0,0 @@ -Customize an OpenStack Deployment -================================= - -Kolla's Philosphy on Deployment -------------------------------- - -Kolla has an objective to replace the inflexible, painful, resource intensive -deployment process of OpenStack with a flexible, painless, inexpensive -deployment process. Often to deploy OpenStack at one-hundred node scale that -a small business may require means building a team of OpenStack professionals -to maintain and manage the OpenStack deployment. Finding people experienced -in OpenStack deployment is very difficult and expensive, resulting in a big -barrier for OpenStack adoption. Kolla seeks to remedy this set of problems by -simplifying the deployment process but enabling flexible deployment models. - -Kolla is a highly opinionated deployment tool out of the box. This permits -Kolla to be deployable with configuration of three key/value pairs. As an -operator's experience with OpenStack grows and the desire to customize -OpenStack services increases, Kolla offers full capability to override every -OpenStack service configuration option in the deployment. - -The Kolla upstream community does not want to place key/value pairs in the -Ansible playbook configuration options that are not essential to obtaining -a functional deployment. If the Kolla upstream starts down the path of -templating configuration options, the Ansible configuration could conceivably -grow to hundreds of configuration key/value pairs which is unmanageable. -Further, as new versions of Kolla are released, there would be independent -customization available for different versions creating an unsupportable and -difficult to document environment. Finally, adding key/value pairs for -configuration options creates a situation in which a development and release -cycle is required in order to successfully add a new customization. -Essentially templating in configuration options is not a scalable solution -and would result in an inability of the project to execute its mission. - - -Kolla's Solution to Customization ---------------------------------- - -Rather then deal with the customization madness of templating configuration -options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies -of existing deployment tools through a tidy simple design. - -During deployment of an OpenStack service, a basic set of default configuration -options are merged with and overridden by custom ini configuration sections. -Kolla deployment customization is that simple! This does create a situation -in which the Operator references the upstream documentation if a customization -is desired in the OpenStack deployment. Fortunately the configuration options -documentation is extremely mature and well-formulated. - -As an example, consider running Kolla in a virtual machine. In order to -launch virtual machines from Nova in a virtual environment, it is necessary -to use the QEMU hypervisor, rather than the KVM hypervisor. To achieve this -result, simply modify the file `/etc/kolla/config/nova/nova-compute.conf` and -add the contents:: - - [libvirt] - virt_type=qemu - -After this change Kolla will use an emulated hypervisor with lower performance. -Kolla could have templated this commonly modified configuration option. If -Kolla starts down this path, the Kolla project could end with hundreds of -config options all of which would have to be subjectively evaluated for -inclusion or exclusion in the source tree. - -Kolla's approach yields a solution which enables complete customization without -any upstream maintenance burden. Operators don't have to rely on a subjective -approval process for configuration options nor rely on a -development/test/release cycle to obtain a desired customization. Instead -operators have ultimate freedom to make desired deployment choices immediately -without the approval of a third party. diff --git a/doc/deployment-philosophy.rst b/doc/deployment-philosophy.rst new file mode 100644 index 000000000..9359f3934 --- /dev/null +++ b/doc/deployment-philosophy.rst @@ -0,0 +1,70 @@ +Customize an OpenStack Deployment +================================= + +Kolla's Philosphy on Deployment +------------------------------- + +Kolla has an objective to replace the inflexible, painful, resource intensive +deployment process of OpenStack with a flexible, painless, inexpensive +deployment process. Often to deploy OpenStack at one-hundred node scale that +a small business may require means building a team of OpenStack professionals +to maintain and manage the OpenStack deployment. Finding people experienced +in OpenStack deployment is very difficult and expensive, resulting in a big +barrier for OpenStack adoption. Kolla seeks to remedy this set of problems by +simplifying the deployment process but enabling flexible deployment models. + +Kolla is a highly opinionated deployment tool out of the box. This permits +Kolla to be deployable with configuration of three key/value pairs. As an +operator's experience with OpenStack grows and the desire to customize +OpenStack services increases, Kolla offers full capability to override every +OpenStack service configuration option in the deployment. + +The Kolla upstream community does not want to place key/value pairs in the +Ansible playbook configuration options that are not essential to obtaining +a functional deployment. If the Kolla upstream starts down the path of +templating configuration options, the Ansible configuration could conceivably +grow to hundreds of configuration key/value pairs which is unmanageable. +Further, as new versions of Kolla are released, there would be independent +customization available for different versions creating an unsupportable and +difficult to document environment. Finally, adding key/value pairs for +configuration options creates a situation in which a development and release +cycle is required in order to successfully add a new customization. +Essentially templating in configuration options is not a scalable solution +and would result in an inability of the project to execute its mission. + + +Kolla's Solution to Customization +--------------------------------- + +Rather then deal with the customization madness of templating configuration +options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies +of existing deployment tools through a tidy simple design. + +During deployment of an OpenStack service, a basic set of default configuration +options are merged with and overridden by custom ini configuration sections. +Kolla deployment customization is that simple! This does create a situation +in which the Operator references the upstream documentation if a customization +is desired in the OpenStack deployment. Fortunately the configuration options +documentation is extremely mature and well-formulated. + +As an example, consider running Kolla in a virtual machine. In order to +launch virtual machines from Nova in a virtual environment, it is necessary +to use the QEMU hypervisor, rather than the KVM hypervisor. To achieve this +result, simply modify the file `/etc/kolla/config/nova/nova-compute.conf` and +add the contents:: + + [libvirt] + virt_type=qemu + +After this change Kolla will use an emulated hypervisor with lower performance. +Kolla could have templated this commonly modified configuration option. If +Kolla starts down this path, the Kolla project could end with hundreds of +config options all of which would have to be subjectively evaluated for +inclusion or exclusion in the source tree. + +Kolla's approach yields a solution which enables complete customization without +any upstream maintenance burden. Operators don't have to rely on a subjective +approval process for configuration options nor rely on a +development/test/release cycle to obtain a desired customization. Instead +operators have ultimate freedom to make desired deployment choices immediately +without the approval of a third party. diff --git a/doc/dev-quickstart.rst b/doc/dev-quickstart.rst deleted file mode 100644 index 068c95dec..000000000 --- a/doc/dev-quickstart.rst +++ /dev/null @@ -1,215 +0,0 @@ -Quickstart to Deploying OpenStack using Ansible -=============================================== - -Evaluation and Developer Environments -------------------------------------- - -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 :doc:`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 :doc:`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 ------------------------ - -Kolla is tested on Fedora/Ubuntu/CentOS. It should work with other OS -distributions, but some need further testing. If other OS distributions can -be verified, update this doc accordingly. For Fedora/Ubuntu, follow below -recommendations: - -Fedora: 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. - -Ubuntu: For Ubuntu based systems where Docker is used, do not use AUFS when -starting Docker daemon unless you are running the Ubuntu with 3.19 kernel or -above. AUFS requires CONFIG\_AUFS\_XATTR=y set when building the kernel. On -Ubuntu, versions 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 when running Docker daemon. - -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 dependencies docker>=1.7.0 and the Python libraries -docker-py>=1.2.0 and Jinja2>=2.6 must be installed. - -The deployment target nodes require the installation of docker>=1.7.0 and -docker-py>=1.2.0. - -To install Kolla Python dependencies use: - -:: - - git clone https://git.openstack.org/openstack/kolla - cd kolla - sudo pip install -r requirements.txt - -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 compatibility with the following -command: - -:: - - curl -sSL https://get.docker.io | bash - -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, there are -the following requirements needed by your system: - -:: - - # Ubuntu - apt-get install -y python-dev python-pip libffi-dev libssl-dev - - # Fedora - yum install -y python-devel python-pip libffi-devel openssl-devel - - # Centos - easy_install pip - yum install -y python-devel libffi-devel openssl-devel - -To install these clients use: - -:: - - pip install -U python-openstackclient - -OpenStack uses healthcheck timers which run off wall-clock time rather then -starting a timer and expring the timer, encoding the expiration in the message -contents. In some cases, this timer interval can be on the order of 60 -seconds. For OpenStack to Operate correctly with these tight health-check -timer intervals, the Kolla community highly recommends running the ntpd -service on all deployment targets. To install, start, and enable ntp on -CentOS execute the following: - -:: - - yum -y install ntp - chkconfig ntpd enable - service ntpd start - -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 - -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 - -Building 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. - -Before running the below instructions, ensure the docker daemon is running -or the build process would fail: - -:: - - tools/build.py - -A docker build of all containers on Xeon hardware with SSDs and 100mbit network -takes roughly 30 minutes. The CentOS mirrors are flakey and the RDO delorean -repository is not mirrored at all. As a result occasionally some containers -fail to build. To rectify this, the build tool will automatically attempt three -retries of a build operation if the first one fails. - -It is also possible to build individual containers. If for some reason the glance -containers failed to build, all glance related containers can be rebuilt as follows: - -:: - - tools/build.py glance - -Starting Kolla --------------- - -Configure Ansible by reading the -:doc:`Kolla Ansible configuration Guide ` documentation. - -Finally, run the deploy operation: - -:: - - ./tools/kolla-ansible deploy - -A bare metal system takes three minutes to deploy AIO. A virtual machine -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 ---------------- - -The container's status can be determined on the deployment targets by -executing: - -:: - - 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. - - the logs can be examined by executing: - -:: - - 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/doc/devenv-heat.rst b/doc/devenv-heat.rst deleted file mode 100644 index 17de5393c..000000000 --- a/doc/devenv-heat.rst +++ /dev/null @@ -1,194 +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: - -.. image:: kollanet.png - :alt: Kolla networking - -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 separate 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 -binary, 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/doc/devenv-vagrant.rst b/doc/devenv-vagrant.rst deleted file mode 100644 index 6ba11131e..000000000 --- a/doc/devenv-vagrant.rst +++ /dev/null @@ -1,138 +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. Vagrant -takes care of setting up CentOS-based VMs for Kolla development, each with -proper hardware like memory amount and number of network interfaces. - -Getting Started ---------------- - -The Vagrant script implements All-in-One (AIO) or multi-node deployments. AIO -is the default. - -In the case of multi-node deployment, the Vagrant setup builds a cluster with -the following nodes by default: - -- 3 control nodes -- 1 compute node -- 1 storage node (Note: ceph requires at least 3 storage nodes) -- 1 network node -- 1 operator node - -The cluster node count can be changed by editing the Vagrantfile. - -Kolla runs from the operator node to deploy OpenStack. - -All nodes are connected with each other on the secondary NIC. The -primary NIC is behind a NAT interface for connecting with the Internet. -The third NIC is connected without IP configuration to a public bridge -interface. This may be used for Neutron/Nova to connect to instances. - -Start by downloading and installing the Vagrant package for the distro of -choice. Various downloads can be found at the `Vagrant downloads -`__. - -On Fedora 22 it is as easy as:: - - sudo dnf install vagrant ruby-devel libvirt-devel - -**Note:** Many distros ship outdated versions of Vagrant by default. When in -doubt, always install the latest from the downloads page above. - -Next 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. This -documentation describes libvirt. To install vagrant-libvirt plugin:: - - vagrant plugin install --plugin-version ">= 0.0.31" vagrant-libvirt - -Some Linux distributions offer vagrant-libvirt packages, but the version they -provide tends to be too old to run Kolla. A version of >= 0.0.31 is required. - -Setup NFS to permit file sharing between host and VMs. Contrary to the rsync -method, NFS allows both way synchronization and offers much better performance -than VirtualBox shared folders. On Fedora 22:: - - sudo systemctl start nfs-server - firewall-cmd --permanent --add-port=2049/udp - firewall-cmd --permanent --add-port=2049/tcp - firewall-cmd --permanent --add-port=111/udp - firewall-cmd --permanent --add-port=111/tcp - -Find a location in the system's home directory and checkout the Kolla repo:: - - git clone https://github.com/openstack/kolla.git - -Developers can now tweak the Vagrantfile or bring up the default AIO -Centos7-based environment:: - - cd kolla/dev/vagrant && vagrant up - -The command ``vagrant status`` provides a quick overview of the VMs composing -the environment. - -Vagrant Up ----------- - -Once Vagrant has completed deploying all nodes, the next step is to launch -Kolla. First, connect with the *operator* node:: - - vagrant ssh operator - -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 use -it as a 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 to use the command ``vagrant reload `` when -reboots are required. Having this shared folder provides 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``. - - -Building images -^^^^^^^^^^^^^^^ - -Once logged on the *operator* VM call the ``kolla-build`` utility:: - - kolla-build - -``kolla-build`` accept arguments as documented in :doc:`image-building`. It -builds Docker images and pushes them to the local registry if the *push* -option is enabled (in Vagrant this is the default behaviour). - - - -Deploying OpenStack with Kolla -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Deploy AIO with:: - - sudo kolla-ansible deploy - -Deploy multinode with:: - - sudo kolla-ansible deploy -i /usr/share/kolla/ansible/inventory/multinode - -Validate OpenStack is operational:: - - source ~/openrc - openstack user list - -Or navigate to http://10.10.10.254/ with a web browser. - - -Further Reading ---------------- - -All Vagrant documentation can be found at -`docs.vagrantup.com `__. diff --git a/doc/heat-dev-env.rst b/doc/heat-dev-env.rst new file mode 100644 index 000000000..17de5393c --- /dev/null +++ b/doc/heat-dev-env.rst @@ -0,0 +1,194 @@ +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: + +.. image:: kollanet.png + :alt: Kolla networking + +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 separate 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 +binary, 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/doc/index.rst b/doc/index.rst index 1a14ba4c1..41eef16eb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -23,19 +23,19 @@ customization. This permits operators with little experience to deploy OpenStack quickly and as experience grows modify the OpenStack configuration to suit the operator's exact requirements. -Deployment Information -====================== - .. toctree:: :maxdepth: 1 - dev-quickstart + deployment-philosophy + quckstart ansible-deployment - devenv-vagrant - devenv-heat - image-building deploy-all-in-one-node - customize-deployment + heat-dev-env + vagrant-dev-env + image-building + advanced-configuration + operating-kolla + Services in Kolla ================= diff --git a/doc/operating-kolla.rst b/doc/operating-kolla.rst new file mode 100644 index 000000000..fda01e768 --- /dev/null +++ b/doc/operating-kolla.rst @@ -0,0 +1,22 @@ +Operating Kolla +=============== + +Upgrading +--------- +TODO(all) fill this section out + +Diagnostics +----------- +TODO(all) fill this section out + +Failure Recovery +---------------- +TODO(all) fill this section out + +Reconfiguration of an existing environment +------------------------------------------ +TODO(all) fill this section out + +Tips and Tricks +--------------- +TODO(all) fill this section out diff --git a/doc/quickstart.rst b/doc/quickstart.rst new file mode 100644 index 000000000..068c95dec --- /dev/null +++ b/doc/quickstart.rst @@ -0,0 +1,215 @@ +Quickstart to Deploying OpenStack using Ansible +=============================================== + +Evaluation and Developer Environments +------------------------------------- + +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 :doc:`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 :doc:`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 +----------------------- + +Kolla is tested on Fedora/Ubuntu/CentOS. It should work with other OS +distributions, but some need further testing. If other OS distributions can +be verified, update this doc accordingly. For Fedora/Ubuntu, follow below +recommendations: + +Fedora: 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. + +Ubuntu: For Ubuntu based systems where Docker is used, do not use AUFS when +starting Docker daemon unless you are running the Ubuntu with 3.19 kernel or +above. AUFS requires CONFIG\_AUFS\_XATTR=y set when building the kernel. On +Ubuntu, versions 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 when running Docker daemon. + +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 dependencies docker>=1.7.0 and the Python libraries +docker-py>=1.2.0 and Jinja2>=2.6 must be installed. + +The deployment target nodes require the installation of docker>=1.7.0 and +docker-py>=1.2.0. + +To install Kolla Python dependencies use: + +:: + + git clone https://git.openstack.org/openstack/kolla + cd kolla + sudo pip install -r requirements.txt + +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 compatibility with the following +command: + +:: + + curl -sSL https://get.docker.io | bash + +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, there are +the following requirements needed by your system: + +:: + + # Ubuntu + apt-get install -y python-dev python-pip libffi-dev libssl-dev + + # Fedora + yum install -y python-devel python-pip libffi-devel openssl-devel + + # Centos + easy_install pip + yum install -y python-devel libffi-devel openssl-devel + +To install these clients use: + +:: + + pip install -U python-openstackclient + +OpenStack uses healthcheck timers which run off wall-clock time rather then +starting a timer and expring the timer, encoding the expiration in the message +contents. In some cases, this timer interval can be on the order of 60 +seconds. For OpenStack to Operate correctly with these tight health-check +timer intervals, the Kolla community highly recommends running the ntpd +service on all deployment targets. To install, start, and enable ntp on +CentOS execute the following: + +:: + + yum -y install ntp + chkconfig ntpd enable + service ntpd start + +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 + +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 + +Building 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. + +Before running the below instructions, ensure the docker daemon is running +or the build process would fail: + +:: + + tools/build.py + +A docker build of all containers on Xeon hardware with SSDs and 100mbit network +takes roughly 30 minutes. The CentOS mirrors are flakey and the RDO delorean +repository is not mirrored at all. As a result occasionally some containers +fail to build. To rectify this, the build tool will automatically attempt three +retries of a build operation if the first one fails. + +It is also possible to build individual containers. If for some reason the glance +containers failed to build, all glance related containers can be rebuilt as follows: + +:: + + tools/build.py glance + +Starting Kolla +-------------- + +Configure Ansible by reading the +:doc:`Kolla Ansible configuration Guide ` documentation. + +Finally, run the deploy operation: + +:: + + ./tools/kolla-ansible deploy + +A bare metal system takes three minutes to deploy AIO. A virtual machine +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 +--------------- + +The container's status can be determined on the deployment targets by +executing: + +:: + + 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. + + the logs can be examined by executing: + +:: + + 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/doc/vagrant-dev-env.rst b/doc/vagrant-dev-env.rst new file mode 100644 index 000000000..6ba11131e --- /dev/null +++ b/doc/vagrant-dev-env.rst @@ -0,0 +1,138 @@ +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. Vagrant +takes care of setting up CentOS-based VMs for Kolla development, each with +proper hardware like memory amount and number of network interfaces. + +Getting Started +--------------- + +The Vagrant script implements All-in-One (AIO) or multi-node deployments. AIO +is the default. + +In the case of multi-node deployment, the Vagrant setup builds a cluster with +the following nodes by default: + +- 3 control nodes +- 1 compute node +- 1 storage node (Note: ceph requires at least 3 storage nodes) +- 1 network node +- 1 operator node + +The cluster node count can be changed by editing the Vagrantfile. + +Kolla runs from the operator node to deploy OpenStack. + +All nodes are connected with each other on the secondary NIC. The +primary NIC is behind a NAT interface for connecting with the Internet. +The third NIC is connected without IP configuration to a public bridge +interface. This may be used for Neutron/Nova to connect to instances. + +Start by downloading and installing the Vagrant package for the distro of +choice. Various downloads can be found at the `Vagrant downloads +`__. + +On Fedora 22 it is as easy as:: + + sudo dnf install vagrant ruby-devel libvirt-devel + +**Note:** Many distros ship outdated versions of Vagrant by default. When in +doubt, always install the latest from the downloads page above. + +Next 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. This +documentation describes libvirt. To install vagrant-libvirt plugin:: + + vagrant plugin install --plugin-version ">= 0.0.31" vagrant-libvirt + +Some Linux distributions offer vagrant-libvirt packages, but the version they +provide tends to be too old to run Kolla. A version of >= 0.0.31 is required. + +Setup NFS to permit file sharing between host and VMs. Contrary to the rsync +method, NFS allows both way synchronization and offers much better performance +than VirtualBox shared folders. On Fedora 22:: + + sudo systemctl start nfs-server + firewall-cmd --permanent --add-port=2049/udp + firewall-cmd --permanent --add-port=2049/tcp + firewall-cmd --permanent --add-port=111/udp + firewall-cmd --permanent --add-port=111/tcp + +Find a location in the system's home directory and checkout the Kolla repo:: + + git clone https://github.com/openstack/kolla.git + +Developers can now tweak the Vagrantfile or bring up the default AIO +Centos7-based environment:: + + cd kolla/dev/vagrant && vagrant up + +The command ``vagrant status`` provides a quick overview of the VMs composing +the environment. + +Vagrant Up +---------- + +Once Vagrant has completed deploying all nodes, the next step is to launch +Kolla. First, connect with the *operator* node:: + + vagrant ssh operator + +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 use +it as a 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 to use the command ``vagrant reload `` when +reboots are required. Having this shared folder provides 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``. + + +Building images +^^^^^^^^^^^^^^^ + +Once logged on the *operator* VM call the ``kolla-build`` utility:: + + kolla-build + +``kolla-build`` accept arguments as documented in :doc:`image-building`. It +builds Docker images and pushes them to the local registry if the *push* +option is enabled (in Vagrant this is the default behaviour). + + + +Deploying OpenStack with Kolla +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Deploy AIO with:: + + sudo kolla-ansible deploy + +Deploy multinode with:: + + sudo kolla-ansible deploy -i /usr/share/kolla/ansible/inventory/multinode + +Validate OpenStack is operational:: + + source ~/openrc + openstack user list + +Or navigate to http://10.10.10.254/ with a web browser. + + +Further Reading +--------------- + +All Vagrant documentation can be found at +`docs.vagrantup.com `__. -- cgit v1.2.3