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 --- 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 +++++++++++++++++++++++++++++ 10 files changed, 1014 insertions(+) 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 (limited to 'doc') 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] -- cgit v1.2.3