diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ansible-deployment.rst | 117 | ||||
| -rw-r--r-- | docs/dev-quickstart.rst | 82 | ||||
| -rw-r--r-- | docs/image-building.rst | 76 | ||||
| -rw-r--r-- | docs/vagrant.rst | 103 |
4 files changed, 224 insertions, 154 deletions
diff --git a/docs/ansible-deployment.rst b/docs/ansible-deployment.rst index 9f277c2ab..37a08a98a 100644 --- a/docs/ansible-deployment.rst +++ b/docs/ansible-deployment.rst @@ -1,95 +1,111 @@ Kolla with Ansible! -============================ - -Kolla supports deploying Openstack using [Ansible][]. - -[Ansible]: https://docs.ansible.com +=================== +Kolla supports deploying Openstack using +`Ansible <https://docs.ansible.com>`__. Getting Started --------------- To run the Ansible playbooks, an inventory file which tracks all of the -available nodes in the environment must be speficied. 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. +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. -More information on the Ansible inventory file can be found [here][]. +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. -[here]: https://docs.ansible.com/intro_inventory.html +More information on the Ansible inventory file can be found in the Ansible +`inventory introduction <https://docs.ansible.com/intro_inventory.html>`__. 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 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. +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. +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 +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. +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. +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. +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. +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. +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. +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 @@ -97,6 +113,5 @@ command to initiate your environment with an glance image and neutron networks. Further Reading --------------- -Ansible playbook documentation can be found [here][]. - -[here]: http://docs.ansible.com/playbooks.html +Ansible playbook documentation can be found in the Ansible +`playbook documentation <http://docs.ansible.com/playbooks.html>`__. diff --git a/docs/dev-quickstart.rst b/docs/dev-quickstart.rst index 2b79097e4..e5cecf53d 100644 --- a/docs/dev-quickstart.rst +++ b/docs/dev-quickstart.rst @@ -1,76 +1,92 @@ -# Developer Environment +Developer Environment +===================== If you are developing Kolla on an existing OpenStack cloud that supports -Heat, then follow the Heat template [README][]. Another option available -on systems with VirutalBox is the use of [Vagrant][]. +Heat, then follow the Heat template +`README <https://github.com/stackforge/kolla/blob/master/devenv/README.md>`__. +Another option available on systems with VirutalBox is the use of +`Vagrant <https://github.com/stackforge/kolla/blob/master/docs/vagrant.md>`__. The best experience is available with bare metal deployment by following the instructions below to manually create your Kolla deployment. -[README]: https://github.com/stackforge/kolla/blob/master/devenv/README.md -[Vagrant]: https://github.com/stackforge/kolla/blob/master/docs/vagrant.md +Installing Dependencies +----------------------- -## Installing Dependencies - -NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses kernel -modules with the .xz compressed format. The guestfs system cannot read -these images because a dependent package supermin in CentOS needs to be -updated to add .xz compressed format support. +NB: Kolla will not run on Fedora 22 or later. Fedora 22 compresses +kernel modules with the .xz compressed format. The guestfs system cannot +read these images because a dependent package supermin in CentOS needs +to be updated to add .xz compressed format support. To install Kolla depenedencies use: +:: + git clone http://github.com/stackforge/kolla cd kolla sudo pip install -r requirements.txt -In order to run Kolla, it is mandatory to run a version of `docker` that is -1.7.0 or later. +In order to run Kolla, it is mandatory to run a version of ``docker`` +that is 1.7.0 or later. + +For most systems you can install the latest stable version of Docker +with the following command: -For most systems you can install the latest stable version of Docker with the -following command: +:: curl -sSL https://get.docker.io | bash -For Ubuntu based systems, do not use AUFS when starting Docker daemon unless -you are running the Utopic (3.19) kernel. AUFS requires CONFIG_AUFS_XATTR=y -set when building the kernel. On Ubuntu, versions prior to 3.19 did not set that -flag. If you are unable to upgrade your kernel, you should use a different -storage backend such as btrfs. +For Ubuntu based systems, do not use AUFS when starting Docker daemon +unless you are running the Utopic (3.19) kernel. AUFS requires +CONFIG\_AUFS\_XATTR=y set when building the kernel. On Ubuntu, versions +prior to 3.19 did not set that flag. If you are unable to upgrade your +kernel, you should use a different storage backend such as btrfs. Next, install the OpenStack python clients if they are not installed: +:: + sudo pip install -U python-openstackclient -Finally stop libvirt on the host machine. Only one copy of libvirt may be -running at a time. +Finally stop libvirt on the host machine. Only one copy of libvirt may +be running at a time. - service libvirtd stop +:: -The basic starting environment will be created using `ansible`. -This environment will start up the OpenStack services listed in the -inventory file. + service libvirtd stop -## Starting Kolla +The basic starting environment will be created using ``ansible``. This +environment will start up the OpenStack services listed in the inventory +file. -Configure Ansible by reading the Kolla Ansible configuration documentation -[DEPLOY][]. +Starting Kolla +-------------- -[DEPLOY]: https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md +Configure Ansible by reading the Kolla +`Ansible configuration <https://github.com/stackforge/kolla/blob/master/docs/ansible-deployment.md>`__ documentation. Next, run the start command: +:: + $ sudo ./tools/kolla-ansible deploy -A bare metal system takes three minutes to deploy AIO. A virtual machine -takes five minutes to deploy AIO. These are estimates; your hardware may +A bare metal system takes three minutes to deploy AIO. A virtual machine +takes five minutes to deploy AIO. These are estimates; your hardware may be faster or slower but should near these results. -## Debugging Kolla +Debugging Kolla +--------------- You can determine a container's status by executing: +:: + $ sudo docker ps -a If any of the containers exited you can check the logs by executing: +:: + $ sudo docker logs <container-name> + diff --git a/docs/image-building.rst b/docs/image-building.rst index a67f3da08..48b3ce2f2 100644 --- a/docs/image-building.rst +++ b/docs/image-building.rst @@ -1,77 +1,101 @@ -# Image building +Image building +============== -The `tools/build-docker-image` script in this repository is -responsible for building docker images. It is symlinked as `./build` +The ``tools/build-docker-image`` script in this repository is +responsible for building docker images. It is symlinked as ``./build`` inside each Docker image directory. When creating new image directories, you can run the -`tools/update-build-links` scripts to install the `build` symlink +``tools/update-build-links`` scripts to install the ``build`` symlink (this script will install the symlink anywhere it find a file named -`Dockerfile`). +``Dockerfile``). -## Workflow +Workflow +-------- In general, you will build images like this: +:: + $ cd docker/keystone $ ./build By default, the above command would build -`kollaglue/centos-rdo-keystone:CID`, where `CID` is the current short -commit ID. That is, given: +``kollaglue/centos-rdo-keystone:CID``, where ``CID`` is the current +short commit ID. That is, given: + +:: $ git rev-parse HEAD 76a16029006a2f5d3b79f1198d81acb6653110e9 The above command would generate -`kollaglue/centos-rdo-keystone:76a1602`. This tagging is meant to +``kollaglue/centos-rdo-keystone:76a1602``. This tagging is meant to prevent developers from stepping on each other or on release images during the development process. -To push the image after building, add `--push`: +To push the image after building, add ``--push``: + +:: $ ./build --push -To use these images, you must specify the tag in your `docker run` +To use these images, you must specify the tag in your ``docker run`` commands: +:: + $ docker run kollaglue/centos-rdo-keystone:76a1602 -## Building releases +Building releases +----------------- + +To build into the ``latest`` tag, add ``--release``: -To build into the `latest` tag, add `--release`: +:: $ ./build --release Or to build and push: +:: + $ ./build --push --release -## Build all images at once +Build all images at once +------------------------ + +The ``build-all-docker-images`` script in the tools directory is a +wrapper for the ``build-docker-image`` that builds all images, as the +name suggests, in the correct order. It responds to the same options as +``build-docker-image`` with the additional ``--from`` and ``--to`` +options that allows building only images that have changed between the +specified git revisions. -The `build-all-docker-images` script in the tools directory is a wrapper for -the `build-docker-image` that builds all images, as the name suggests, in the -correct order. It responds to the same options as `build-docker-image` with the -additional `--from` and `--to` options that allows building only images that -have changed between the specified git revisions. +For example, to build all images contained in docker directory and push +new release: -For example, to build all images contained in docker directory and push new release: +:: $ tools/build-all-docker-images --release --push To build only images modified in test-branch along with their children: +:: + $ tools/build-all-docker-images --from master --to test-branch -## Configuration +Configuration +------------- -The `build-docker-image` script will look for a file named `.buildconf` -in the image directory and in the top level of the repository. You -can use this to set defaults, such as: +The ``build-docker-image`` script will look for a file named +``.buildconf`` in the image directory and in the top level of the +repository. You can use this to set defaults, such as: + +:: NAMESPACE=larsks PREFIX=fedora-rdo- -This setting would cause images to be tagged into the `larsks/` +This setting would cause images to be tagged into the ``larsks/`` namespace and use Fedora as base image instead of the default CentOS. - diff --git a/docs/vagrant.rst b/docs/vagrant.rst index b6f47f179..f3fe559aa 100644 --- a/docs/vagrant.rst +++ b/docs/vagrant.rst @@ -1,81 +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. - -[Vagrant]: http://vagrantup.com +This guide describes how to use `Vagrant <http://vagrantup.com>`__ 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 +- 3 control nodes +- 1 compute node +- 1 operator node + +Kolla runs from the operator node to deploy OpenStack on the other +nodes. -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. -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 <https://www.vagrantup.com/downloads.html>`__. +After we will install the hostmanager plugin so all hosts are recorded in +/etc/hosts (inside each vm): -Start with downloading and installing the Vagrant package for your distro of -choice. Various downloads can be found [here][]. 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. +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 +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: +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. + cd ~/dev/kolla/vagrant && vagrant up -[here]: https://www.vagrantup.com/downloads.html +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: -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: +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! +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. +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 <node>` 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`. +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 <node>`` 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 on their [website][]. - -[website]: http://docs.vagrantup.com +All Vagrant documentation can be found at +`docs.vagrantup.com <http://docs.vagrantup.com>`__. |