From 233864ff32af10a2c927cdbca3475b537c8e6808 Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Wed, 2 Sep 2015 22:33:01 -0700 Subject: Rename docs dir to doc for publishing The publishing docs expect the documentation to be present in the /doc directory not the /docs directory. If the documentation is in the /docs directory, according to fungi the docs won't be published properly. Change-Id: I718fec7e69d298a5cb2376ca4e2455e12169566e Partially-Implements: blueprint kola-tox-doc --- README.rst | 8 +- doc/ansible-deployment.rst | 117 ++++++++++++++++++++++++++ doc/cinder-guide.rst | 77 +++++++++++++++++ doc/conf.py | 71 ++++++++++++++++ doc/dev-quickstart.rst | 198 ++++++++++++++++++++++++++++++++++++++++++++ doc/devenv-heat.rst | 195 +++++++++++++++++++++++++++++++++++++++++++ doc/devenv-vagrant.rst | 96 +++++++++++++++++++++ doc/image-building.rst | 86 +++++++++++++++++++ doc/index.rst | 44 ++++++++++ doc/kollanet.png | Bin 0 -> 26014 bytes doc/swift-readme.rst | 130 +++++++++++++++++++++++++++++ docs/ansible-deployment.rst | 117 -------------------------- docs/cinder-guide.rst | 77 ----------------- docs/conf.py | 71 ---------------- docs/dev-quickstart.rst | 198 -------------------------------------------- docs/devenv-heat.rst | 195 ------------------------------------------- docs/devenv-vagrant.rst | 96 --------------------- docs/image-building.rst | 86 ------------------- docs/index.rst | 44 ---------- docs/kollanet.png | Bin 26014 -> 0 bytes docs/swift-readme.rst | 130 ----------------------------- setup.cfg | 6 +- 22 files changed, 1021 insertions(+), 1021 deletions(-) create mode 100644 doc/ansible-deployment.rst create mode 100644 doc/cinder-guide.rst create mode 100644 doc/conf.py create mode 100644 doc/dev-quickstart.rst create mode 100644 doc/devenv-heat.rst create mode 100644 doc/devenv-vagrant.rst create mode 100644 doc/image-building.rst create mode 100644 doc/index.rst create mode 100644 doc/kollanet.png create mode 100644 doc/swift-readme.rst delete mode 100644 docs/ansible-deployment.rst delete mode 100644 docs/cinder-guide.rst delete mode 100644 docs/conf.py delete mode 100644 docs/dev-quickstart.rst delete mode 100644 docs/devenv-heat.rst delete mode 100644 docs/devenv-vagrant.rst delete mode 100644 docs/image-building.rst delete mode 100644 docs/index.rst delete mode 100644 docs/kollanet.png delete mode 100644 docs/swift-readme.rst diff --git a/README.rst b/README.rst index 7bcc693c8..a6051221f 100644 --- a/README.rst +++ b/README.rst @@ -21,9 +21,9 @@ Getting Started =============== Please get started by reading the `Developer -Quickstart `__ +Quickstart `__ followed by the `Ansible Deployment -Guide `__. +Guide `__. Docker Images ------------- @@ -31,7 +31,7 @@ Docker Images The `Docker images `__ are built by the Kolla project maintainers. A detailed process for contributing to the images can be found in the `image building -guide `__. +guide `__. Images reside in the Docker Hub `Kollaglue repo `__. @@ -71,7 +71,7 @@ Directories Ansible. - demos - Contains a few demos to use with Kolla. - devenv - Contains an OpenStack-Heat based development environment. -- docs - Contains documentation. +- doc - Contains documentation. - etc - Contains a reference etc directory structure which requires configuration of a small number of configuration variables to achieve a working All-in-One (AIO) deployment. diff --git a/doc/ansible-deployment.rst b/doc/ansible-deployment.rst new file mode 100644 index 000000000..37a08a98a --- /dev/null +++ b/doc/ansible-deployment.rst @@ -0,0 +1,117 @@ +Kolla with Ansible! +=================== + +Kolla supports deploying Openstack using +`Ansible `__. + +Getting Started +--------------- + +To run the Ansible playbooks, an inventory file which tracks all of the +available nodes in the environment must be specified. With this +inventory file Ansible will log into each node via ssh (configurable) +and run tasks. Ansible does not require password-less logins via ssh, +however it is highly recommended to setup ssh-keys. + +Two sample inventory files are provided, *all-in-one*, and *multinode*. +The "all-in-one" inventory defaults to use the Ansible "local" +connection type, which removes the need to setup ssh keys in order to +get started quickly. + +More information on the Ansible inventory file can be found in the Ansible +`inventory introduction `__. + +Prerequisites +------------- + +On the deployment host you must have Ansible>=1.8.4 installed. That is +the only requirement for deploying. To build the images locally you must +also have the Python library docker-py>=1.2.0 installed. + +On the target nodes you must have docker>=1.6.0 and docker-py>=1.2.0 +installed. + +Deploying +--------- + +Add the etc/kolla directory to /etc/kolla on the deployment host. Inside +of this directory are two files and a minimum number of parameters which +are listed below. + +All variables for the environment can be specified in the files: +"/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml" + +The kolla\_\*\_address variables can both be the same. Please specify +an unused IP address in your network to act as a VIP for +kolla\_internal\_address. The VIP will be used with keepalived and +added to your "api\_interface" as specified in the globals.yml + +:: + + kolla_external_address: "openstack.example.com" + kolla_internal_address: "10.10.10.254" + +The "network\_interface" variable is the interface that we bind all our +services to. For example, when starting up Mariadb it will bind to the +IP on the interface list in the "network\_interface" variable. + +:: + + network_interface: "eth0" + +The "neutron\_external\_interface" variable is the interface that will +be used for your external bridge in Neutron. Without this bridge your +instance traffic will be unable to access the rest of the Internet. In +the case of a single interface on a machine, you may use a veth pair +where one end of the veth pair is listed here and the other end is in a +bridge on your system. + +:: + + neutron_external_interface: "eth1" + +The docker\_pull\_policy specifies whether Docker should always pull +images from the repository it is configured for, or only in the case +where the image isn't present locally. If you are building your own +images locally without pushing them to the Docker Registry, or a local +registry, you must set this value to "missing" or when you run the +playbooks docker will attempt to fetch the latest image upstream. + +:: + + docker_pull_policy: "always" + +For All-In-One deploys, the following commands can be run. These will +setup all of the containers on the localhost. These commands will be +wrapped in the kolla-script in the future. + +:: + + cd ./kolla/ansible + ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml + +To run the playbooks for only a particular service, Ansible tags can be +used. Multiple tags may be specified, and order is still determined by +the playbooks. + +:: + + cd ./kolla/ansible + ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq + ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq,mariadb + +Finally, you can view ./kolla/tools/openrc-example for an example of an +openrc you can use with your environment. If you wish you may also run +the following command to initiate your environment with an glance image +and neutron networks. + +:: + + cd ./kolla/tools + ./init-runonce + +Further Reading +--------------- + +Ansible playbook documentation can be found in the Ansible +`playbook documentation `__. diff --git a/doc/cinder-guide.rst b/doc/cinder-guide.rst new file mode 100644 index 000000000..7247cc02a --- /dev/null +++ b/doc/cinder-guide.rst @@ -0,0 +1,77 @@ +Cinder in Kolla +=============== + +Overview +-------- +Currently Kolla can deploy the cinder services: + +- cinder-api +- cinder-scheduler +- cinder-backup +- cinder-volume + +The cinder implementation defaults to using LVM storage. The default +implementation requires a volume group be set up. This can either be +a real physical volume or a loopback mounted file for development. + +Create a Volume Group +--------------------- +Use pvcreate and vgcreate to create the volume group. For example with +the devices /dev/sdb and /dev/sdc: + +:: + + + + pvcreate /dev/sdb /dev/sdc + vgcreate cinder-volumes /dev/sdb /dev/sdc + +During development, it may be desireable to use file backed block storage. It +is possible to use a file and mount it as a block device via the loopback +system. + +:: + + mknod /dev/loop2 b 7 2 + dd if=/dev/zero of=/var/lib/cinder_data.img bs=1g count=20 + losetup /dev/loop2 /var/lib/cinder_data.img + pvcreate /dev/loop2 + vgcreate cinder-volumes /dev/loop2 + +Validation +---------- + +Create a volume as follows: + +:: + + $ openstack volume create --size 1 steak_volume + + +Verify it is available. If it says "error" here something went wrong during +LVM creation of the volume. + +:: + + $ openstack volume list + +--------------------------------------+--------------+-----------+------+-------------+ + | ID | Display Name | Status | Size | Attached to | + +--------------------------------------+--------------+-----------+------+-------------+ + | 0069c17e-8a60-445a-b7f0-383a8b89f87e | steak_volume | available | 1 | | + +--------------------------------------+--------------+-----------+------+-------------+ + +Attach the volume to a server using: + +:: + + openstack server add volume steak_server 0069c17e-8a60-445a-b7f0-383a8b89f87e + +Check the console log added the disk: + +:: + + opoenstack console log show steak_server + +A /dev/vdb should appear in the console log, atleast when booting cirros. +If the disk stays in the available state, something went wrong during the +iSCSI mounting of the volume to the guest VM. diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..a0d74bd97 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,71 @@ +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'oslosphinx' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'kolla' +copyright = u'2013, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] diff --git a/doc/dev-quickstart.rst b/doc/dev-quickstart.rst new file mode 100644 index 000000000..e334a3ce5 --- /dev/null +++ b/doc/dev-quickstart.rst @@ -0,0 +1,198 @@ +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 +`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 +----------------------- + +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 dameon. + +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. + +The deployment targt nodes require the installation of docker>=1.7.0 and +docker-py>=1.2.0. + +To install Kolla Python depenedencies use: + +:: + + git clone http://github.com/stackforge/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 compatiblity 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 + sudo apt-get install -y python-dev python-pip libffi-dev libssl-dev + + # Fedora + sudo yum install -y python-devel python-pip libffi-devel openssl-devel + + # Centos + sudo easy_install pip + sudo yum install -y python-devel libffi-devel openssl-devel + +To install these clients use: + +:: + + sudo pip install -U python-openstackclient + +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 + +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. + +Before running the below intructions, make sure docker dameon is running, +or the build process would fail: + +:: + + 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 Guide `__ documentation. + +Finally, run the deploy operation: + +:: + + $ sudo ./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 new file mode 100644 index 000000000..019fe7ebd --- /dev/null +++ b/doc/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/doc/devenv-vagrant.rst b/doc/devenv-vagrant.rst new file mode 100644 index 000000000..f3fe559aa --- /dev/null +++ b/doc/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/doc/image-building.rst b/doc/image-building.rst new file mode 100644 index 000000000..c118fef99 --- /dev/null +++ b/doc/image-building.rst @@ -0,0 +1,86 @@ +Image building +============== + +The ``tools/build.py`` script in this repository is +responsible for building docker images. + +Guide +----- + +In general, you will build images like this: + +:: + + $ tools/build.py + +By default, the above command would build all images based on centos image. + +If you want to change the base distro image, add ``-b``: + +:: + + $ tools/build.py -b ubuntu + +There are following distros available for building images: + +- fedora +- centos +- oraclelinux +- ubuntu + +To push the image after building, add ``--push``: + +:: + + $ tools/build.py --push + + +If you want to build only keystone image, use the following command: + +:: + + $ tools/build.py keystone + + +If you want to build multiple images e.g. keystone and nova, use the following command: + +:: + + $ tools/build.py keystone nova + + +``tools/build.py`` use ``kollaglue`` as default namespace. If you +want to push images to your dockerhub, change the namespace like: + +:: + + $ tools/build.py -n yourusername --push + + +Build Openstack from Source +--------------------------- + +When building images, there are two methods of the Openstack install. +One is ``binary``. Another is ``source``. +The ``binary`` means that Openstack will be installed from apt/yum. +And the ``source`` means that Openstack will be installed from source code. +The default method of the Openstack install is ``binary``. +You can change it to ``source`` using the following command: + +:: + + tools/build.py -t source + +The locations of Opentack source code are written in ``build.ini``. +Now the source type support ``url`` and ``git``. The ``build.ini`` looks like: + +:: + + [glance-base] + type = url + location = http://tarballs.openstack.org/glance/glance-master.tar.gz + + [keystone] + type = git + location = https://github.com/openstack/keystone + reference = stable/kilo diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..258c6180a --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,44 @@ +.. + Copyright 2014-2015 OpenStack Foundation + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Welcome to Kolla's Documentation! +================================= + +Kolla provides Docker containers and Ansible playbooks to meet Kolla's mission. +Kolla is highly opinionated out of the box, but allows for complete +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. + +Developer Info +============== + +.. toctree:: + :maxdepth: 1 + + dev-quickstart + ansible-deployment + devenv-vagrant + devenv-heat + +Services in Kolla +================= + +.. toctree:: + :maxdepth: 1 + + cinder-guide + swift-readme diff --git a/doc/kollanet.png b/doc/kollanet.png new file mode 100644 index 000000000..cfb0c6014 Binary files /dev/null and b/doc/kollanet.png differ diff --git a/doc/swift-readme.rst b/doc/swift-readme.rst new file mode 100644 index 000000000..9f8e19ecd --- /dev/null +++ b/doc/swift-readme.rst @@ -0,0 +1,130 @@ +Swift in Kolla +============== + +Overview +-------- +Currently Kolla can deploy the "core" services required for a working Swift, in either an AIO or +multi node setup: + +- swift-proxy +- swift-account +- swift-container +- swift-object + +There are a variety of other services such the replicator, expirer, rsyncd, etc. which actually make +Swift useful, which are in progress and hope to be finished in liberty-rc1. + +Prerequisites +------------- +Before running Swift we need to generate "rings", which are binary compressed files that at a high +level let the various Swift services know where data is in the cluster. Again, we hope to be able to +generate these automatically for liberty-rc1. + +Swift also expects block devices to be available and partitioned on the host, which Swift uses in +combination with the rings to store data. Swift demos commonly just use directories created under +/srv/node to simulate these devices. In order to ease "out of the box" testing of Kolla, we offer a +similar setup with a data container. *Note*, data containers are very inefficient for this purpose. +In production setups operators will want to provision disks according to the Swift operator guide, +which can then be added the rings and used in Kolla. + +For an AIO setup, the following commands can be used, locally, to generate rings containing the data +container directories: + +:: + + export KOLLA_INTERNAL_ADDRESS=1.2.3.4 + + # Object ring + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base \ + swift-ring-builder /etc/kolla/config/swift/object.builder create 10 3 1 + + for partition in sdb1 sdb2 sdb3; do + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base swift-ring-builder \ + /etc/kolla/config/swift/object.builder add z1-${KOLLA_INTERNAL_ADDRESS}:6000/${partition} 1 + done + + # Account ring + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base \ + swift-ring-builder /etc/kolla/config/swift/account.builder create 10 3 1 + + for partition in sdb1 sdb2 sdb3; do + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base swift-ring-builder \ + /etc/kolla/config/swift/account.builder add z1-${KOLLA_INTERNAL_ADDRESS}:6001/${partition} 1 + done + + # Container ring + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base \ + swift-ring-builder /etc/kolla/config/swift/container.builder create 10 3 1 + + for partition in sdb1 sdb2 sdb3; do + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base swift-ring-builder \ + /etc/kolla/config/swift/container.builder add z1-${KOLLA_INTERNAL_ADDRESS}:6002/${partition} 1 + done + + for ring in object account container; do + docker run \ + -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ + kollaglue/centos-binary-swift-base swift-ring-builder \ + /etc/kolla/config/swift/${ring}.builder rebalance + done + +Similar commands can be used for multinode, you will just need to run the the 'add' step for each IP +in the cluster. + +For more info, see +http://docs.openstack.org/kilo/install-guide/install/apt/content/swift-initial-rings.html + +Deploying +--------- +Once the rings are in place, deploying Swift is the same as any other Kolla Ansible service. Below +is the minimal command to bring up Swift AIO, and it's dependencies: + +:: + + ansible-playbook \ + -i ansible/inventory/all-in-one \ + -e @/etc/kolla/globals.yml \ + -e @etc/kolla/passwords.yml \ + ansible/site.yml \ + --tags=rabbitmq,mariadb,keystone,swift + +Validation +---------- +A very basic smoke test: + +:: + + $ swift stat + Account: AUTH_4c19d363b9cf432a80e34f06b1fa5749 + Containers: 1 + Objects: 0 + Bytes: 0 + Containers in policy "policy-0": 1 + Objects in policy "policy-0": 0 + Bytes in policy "policy-0": 0 + X-Account-Project-Domain-Id: default + X-Timestamp: 1440168098.28319 + X-Trans-Id: txf5a62b7d7fc541f087703-0055d73be7 + Content-Type: text/plain; charset=utf-8 + Accept-Ranges: bytes + + $ swift upload mycontainer README.rst + README.md + + $ swift list + mycontainer + + $ swift download mycontainer README.md + README.md [auth 0.248s, headers 0.939s, total 0.939s, 0.006 MB/s] diff --git a/docs/ansible-deployment.rst b/docs/ansible-deployment.rst deleted file mode 100644 index 37a08a98a..000000000 --- a/docs/ansible-deployment.rst +++ /dev/null @@ -1,117 +0,0 @@ -Kolla with Ansible! -=================== - -Kolla supports deploying Openstack using -`Ansible `__. - -Getting Started ---------------- - -To run the Ansible playbooks, an inventory file which tracks all of the -available nodes in the environment must be specified. With this -inventory file Ansible will log into each node via ssh (configurable) -and run tasks. Ansible does not require password-less logins via ssh, -however it is highly recommended to setup ssh-keys. - -Two sample inventory files are provided, *all-in-one*, and *multinode*. -The "all-in-one" inventory defaults to use the Ansible "local" -connection type, which removes the need to setup ssh keys in order to -get started quickly. - -More information on the Ansible inventory file can be found in the Ansible -`inventory introduction `__. - -Prerequisites -------------- - -On the deployment host you must have Ansible>=1.8.4 installed. That is -the only requirement for deploying. To build the images locally you must -also have the Python library docker-py>=1.2.0 installed. - -On the target nodes you must have docker>=1.6.0 and docker-py>=1.2.0 -installed. - -Deploying ---------- - -Add the etc/kolla directory to /etc/kolla on the deployment host. Inside -of this directory are two files and a minimum number of parameters which -are listed below. - -All variables for the environment can be specified in the files: -"/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml" - -The kolla\_\*\_address variables can both be the same. Please specify -an unused IP address in your network to act as a VIP for -kolla\_internal\_address. The VIP will be used with keepalived and -added to your "api\_interface" as specified in the globals.yml - -:: - - kolla_external_address: "openstack.example.com" - kolla_internal_address: "10.10.10.254" - -The "network\_interface" variable is the interface that we bind all our -services to. For example, when starting up Mariadb it will bind to the -IP on the interface list in the "network\_interface" variable. - -:: - - network_interface: "eth0" - -The "neutron\_external\_interface" variable is the interface that will -be used for your external bridge in Neutron. Without this bridge your -instance traffic will be unable to access the rest of the Internet. In -the case of a single interface on a machine, you may use a veth pair -where one end of the veth pair is listed here and the other end is in a -bridge on your system. - -:: - - neutron_external_interface: "eth1" - -The docker\_pull\_policy specifies whether Docker should always pull -images from the repository it is configured for, or only in the case -where the image isn't present locally. If you are building your own -images locally without pushing them to the Docker Registry, or a local -registry, you must set this value to "missing" or when you run the -playbooks docker will attempt to fetch the latest image upstream. - -:: - - docker_pull_policy: "always" - -For All-In-One deploys, the following commands can be run. These will -setup all of the containers on the localhost. These commands will be -wrapped in the kolla-script in the future. - -:: - - cd ./kolla/ansible - ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml - -To run the playbooks for only a particular service, Ansible tags can be -used. Multiple tags may be specified, and order is still determined by -the playbooks. - -:: - - cd ./kolla/ansible - ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq - ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq,mariadb - -Finally, you can view ./kolla/tools/openrc-example for an example of an -openrc you can use with your environment. If you wish you may also run -the following command to initiate your environment with an glance image -and neutron networks. - -:: - - cd ./kolla/tools - ./init-runonce - -Further Reading ---------------- - -Ansible playbook documentation can be found in the Ansible -`playbook documentation `__. diff --git a/docs/cinder-guide.rst b/docs/cinder-guide.rst deleted file mode 100644 index 7247cc02a..000000000 --- a/docs/cinder-guide.rst +++ /dev/null @@ -1,77 +0,0 @@ -Cinder in Kolla -=============== - -Overview --------- -Currently Kolla can deploy the cinder services: - -- cinder-api -- cinder-scheduler -- cinder-backup -- cinder-volume - -The cinder implementation defaults to using LVM storage. The default -implementation requires a volume group be set up. This can either be -a real physical volume or a loopback mounted file for development. - -Create a Volume Group ---------------------- -Use pvcreate and vgcreate to create the volume group. For example with -the devices /dev/sdb and /dev/sdc: - -:: - - - - pvcreate /dev/sdb /dev/sdc - vgcreate cinder-volumes /dev/sdb /dev/sdc - -During development, it may be desireable to use file backed block storage. It -is possible to use a file and mount it as a block device via the loopback -system. - -:: - - mknod /dev/loop2 b 7 2 - dd if=/dev/zero of=/var/lib/cinder_data.img bs=1g count=20 - losetup /dev/loop2 /var/lib/cinder_data.img - pvcreate /dev/loop2 - vgcreate cinder-volumes /dev/loop2 - -Validation ----------- - -Create a volume as follows: - -:: - - $ openstack volume create --size 1 steak_volume - - -Verify it is available. If it says "error" here something went wrong during -LVM creation of the volume. - -:: - - $ openstack volume list - +--------------------------------------+--------------+-----------+------+-------------+ - | ID | Display Name | Status | Size | Attached to | - +--------------------------------------+--------------+-----------+------+-------------+ - | 0069c17e-8a60-445a-b7f0-383a8b89f87e | steak_volume | available | 1 | | - +--------------------------------------+--------------+-----------+------+-------------+ - -Attach the volume to a server using: - -:: - - openstack server add volume steak_server 0069c17e-8a60-445a-b7f0-383a8b89f87e - -Check the console log added the disk: - -:: - - opoenstack console log show steak_server - -A /dev/vdb should appear in the console log, atleast when booting cirros. -If the disk stays in the available state, something went wrong during the -iSCSI mounting of the volume to the guest VM. diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index a0d74bd97..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,71 +0,0 @@ -# -*- coding: utf-8 -*- -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -# implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import os -import sys - -sys.path.insert(0, os.path.abspath('../..')) -# -- General configuration ---------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - 'sphinx.ext.autodoc', - 'oslosphinx' -] - -# autodoc generation is a bit aggressive and a nuisance when doing heavy -# text edit cycles. -# execute "export SPHINX_DEBUG=1" in your terminal to disable - -# The suffix of source filenames. -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'kolla' -copyright = u'2013, OpenStack Foundation' - -# If true, '()' will be appended to :func: etc. cross-reference text. -add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -add_module_names = True - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# -- Options for HTML output -------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -# html_theme_path = ["."] -# html_theme = '_theme' -# html_static_path = ['static'] - -# Output file base name for HTML help builder. -htmlhelp_basename = '%sdoc' % project - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto/manual]). -latex_documents = [ - ('index', - '%s.tex' % project, - u'%s Documentation' % project, - u'OpenStack Foundation', 'manual'), -] diff --git a/docs/dev-quickstart.rst b/docs/dev-quickstart.rst deleted file mode 100644 index e334a3ce5..000000000 --- a/docs/dev-quickstart.rst +++ /dev/null @@ -1,198 +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 -`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 ------------------------ - -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 dameon. - -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. - -The deployment targt nodes require the installation of docker>=1.7.0 and -docker-py>=1.2.0. - -To install Kolla Python depenedencies use: - -:: - - git clone http://github.com/stackforge/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 compatiblity 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 - sudo apt-get install -y python-dev python-pip libffi-dev libssl-dev - - # Fedora - sudo yum install -y python-devel python-pip libffi-devel openssl-devel - - # Centos - sudo easy_install pip - sudo yum install -y python-devel libffi-devel openssl-devel - -To install these clients use: - -:: - - sudo pip install -U python-openstackclient - -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 - -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. - -Before running the below intructions, make sure docker dameon is running, -or the build process would fail: - -:: - - 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 Guide `__ documentation. - -Finally, run the deploy operation: - -:: - - $ sudo ./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/docs/devenv-heat.rst b/docs/devenv-heat.rst deleted file mode 100644 index 019fe7ebd..000000000 --- a/docs/devenv-heat.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/docs/devenv-vagrant.rst b/docs/devenv-vagrant.rst deleted file mode 100644 index f3fe559aa..000000000 --- a/docs/devenv-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 `__. diff --git a/docs/image-building.rst b/docs/image-building.rst deleted file mode 100644 index c118fef99..000000000 --- a/docs/image-building.rst +++ /dev/null @@ -1,86 +0,0 @@ -Image building -============== - -The ``tools/build.py`` script in this repository is -responsible for building docker images. - -Guide ------ - -In general, you will build images like this: - -:: - - $ tools/build.py - -By default, the above command would build all images based on centos image. - -If you want to change the base distro image, add ``-b``: - -:: - - $ tools/build.py -b ubuntu - -There are following distros available for building images: - -- fedora -- centos -- oraclelinux -- ubuntu - -To push the image after building, add ``--push``: - -:: - - $ tools/build.py --push - - -If you want to build only keystone image, use the following command: - -:: - - $ tools/build.py keystone - - -If you want to build multiple images e.g. keystone and nova, use the following command: - -:: - - $ tools/build.py keystone nova - - -``tools/build.py`` use ``kollaglue`` as default namespace. If you -want to push images to your dockerhub, change the namespace like: - -:: - - $ tools/build.py -n yourusername --push - - -Build Openstack from Source ---------------------------- - -When building images, there are two methods of the Openstack install. -One is ``binary``. Another is ``source``. -The ``binary`` means that Openstack will be installed from apt/yum. -And the ``source`` means that Openstack will be installed from source code. -The default method of the Openstack install is ``binary``. -You can change it to ``source`` using the following command: - -:: - - tools/build.py -t source - -The locations of Opentack source code are written in ``build.ini``. -Now the source type support ``url`` and ``git``. The ``build.ini`` looks like: - -:: - - [glance-base] - type = url - location = http://tarballs.openstack.org/glance/glance-master.tar.gz - - [keystone] - type = git - location = https://github.com/openstack/keystone - reference = stable/kilo diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 258c6180a..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. - Copyright 2014-2015 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Welcome to Kolla's Documentation! -================================= - -Kolla provides Docker containers and Ansible playbooks to meet Kolla's mission. -Kolla is highly opinionated out of the box, but allows for complete -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. - -Developer Info -============== - -.. toctree:: - :maxdepth: 1 - - dev-quickstart - ansible-deployment - devenv-vagrant - devenv-heat - -Services in Kolla -================= - -.. toctree:: - :maxdepth: 1 - - cinder-guide - swift-readme diff --git a/docs/kollanet.png b/docs/kollanet.png deleted file mode 100644 index cfb0c6014..000000000 Binary files a/docs/kollanet.png and /dev/null differ diff --git a/docs/swift-readme.rst b/docs/swift-readme.rst deleted file mode 100644 index 9f8e19ecd..000000000 --- a/docs/swift-readme.rst +++ /dev/null @@ -1,130 +0,0 @@ -Swift in Kolla -============== - -Overview --------- -Currently Kolla can deploy the "core" services required for a working Swift, in either an AIO or -multi node setup: - -- swift-proxy -- swift-account -- swift-container -- swift-object - -There are a variety of other services such the replicator, expirer, rsyncd, etc. which actually make -Swift useful, which are in progress and hope to be finished in liberty-rc1. - -Prerequisites -------------- -Before running Swift we need to generate "rings", which are binary compressed files that at a high -level let the various Swift services know where data is in the cluster. Again, we hope to be able to -generate these automatically for liberty-rc1. - -Swift also expects block devices to be available and partitioned on the host, which Swift uses in -combination with the rings to store data. Swift demos commonly just use directories created under -/srv/node to simulate these devices. In order to ease "out of the box" testing of Kolla, we offer a -similar setup with a data container. *Note*, data containers are very inefficient for this purpose. -In production setups operators will want to provision disks according to the Swift operator guide, -which can then be added the rings and used in Kolla. - -For an AIO setup, the following commands can be used, locally, to generate rings containing the data -container directories: - -:: - - export KOLLA_INTERNAL_ADDRESS=1.2.3.4 - - # Object ring - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base \ - swift-ring-builder /etc/kolla/config/swift/object.builder create 10 3 1 - - for partition in sdb1 sdb2 sdb3; do - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base swift-ring-builder \ - /etc/kolla/config/swift/object.builder add z1-${KOLLA_INTERNAL_ADDRESS}:6000/${partition} 1 - done - - # Account ring - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base \ - swift-ring-builder /etc/kolla/config/swift/account.builder create 10 3 1 - - for partition in sdb1 sdb2 sdb3; do - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base swift-ring-builder \ - /etc/kolla/config/swift/account.builder add z1-${KOLLA_INTERNAL_ADDRESS}:6001/${partition} 1 - done - - # Container ring - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base \ - swift-ring-builder /etc/kolla/config/swift/container.builder create 10 3 1 - - for partition in sdb1 sdb2 sdb3; do - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base swift-ring-builder \ - /etc/kolla/config/swift/container.builder add z1-${KOLLA_INTERNAL_ADDRESS}:6002/${partition} 1 - done - - for ring in object account container; do - docker run \ - -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \ - kollaglue/centos-binary-swift-base swift-ring-builder \ - /etc/kolla/config/swift/${ring}.builder rebalance - done - -Similar commands can be used for multinode, you will just need to run the the 'add' step for each IP -in the cluster. - -For more info, see -http://docs.openstack.org/kilo/install-guide/install/apt/content/swift-initial-rings.html - -Deploying ---------- -Once the rings are in place, deploying Swift is the same as any other Kolla Ansible service. Below -is the minimal command to bring up Swift AIO, and it's dependencies: - -:: - - ansible-playbook \ - -i ansible/inventory/all-in-one \ - -e @/etc/kolla/globals.yml \ - -e @etc/kolla/passwords.yml \ - ansible/site.yml \ - --tags=rabbitmq,mariadb,keystone,swift - -Validation ----------- -A very basic smoke test: - -:: - - $ swift stat - Account: AUTH_4c19d363b9cf432a80e34f06b1fa5749 - Containers: 1 - Objects: 0 - Bytes: 0 - Containers in policy "policy-0": 1 - Objects in policy "policy-0": 0 - Bytes in policy "policy-0": 0 - X-Account-Project-Domain-Id: default - X-Timestamp: 1440168098.28319 - X-Trans-Id: txf5a62b7d7fc541f087703-0055d73be7 - Content-Type: text/plain; charset=utf-8 - Accept-Ranges: bytes - - $ swift upload mycontainer README.rst - README.md - - $ swift list - mycontainer - - $ swift download mycontainer README.md - README.md [auth 0.248s, headers 0.939s, total 0.939s, 0.006 MB/s] diff --git a/setup.cfg b/setup.cfg index 678776679..86514738f 100644 --- a/setup.cfg +++ b/setup.cfg @@ -24,7 +24,7 @@ data_files = share/kolla/ansible = ansible/* share/kolla/devenv = devenv/* share/kolla/docker = docker/* - share/kolla/docs = docs/* + share/kolla/doc = doc/* share/kolla/etc_examples = etc/* share/kolla/vagrant = vagrant/* share/kolla = tools/init-runonce @@ -45,5 +45,5 @@ setup-hooks = [build_sphinx] all_files = 1 -build-dir = docs/build -source-dir = docs/ +build-dir = doc/build +source-dir = doc/ -- cgit v1.2.3