kolla-ansible/doc/source/contributor/vagrant-dev-env.rst
chenxing e471549e77 Upgrade the rst convention of the Contributor Guide
We upgrade the rst convention by following Documentation Contributor
Guide[1].

[1] https://docs.openstack.org/doc-contrib-guide/

Change-Id: I065ceb2f4d455412efeb502e7073e2cb7bc96996
Partially-Implements: blueprint optimize-the-documentation-format
2018-02-08 11:44:21 +00:00

277 lines
7.2 KiB
ReStructuredText

.. vagrant-dev-env:
====================================
Development Environment with Vagrant
====================================
This guide describes how to use `Vagrant <https://vagrantup.com>`__ to assist in
developing for Kolla.
Vagrant is a tool for building and managing virtual machine environments in
a single workflow. Vagrant takes care of setting up CentOS-based VMs for Kolla
development, each with proper hardware like memory amount and number of
network interfaces.
Getting Started
===============
The Vagrant script implements **all-in-one** or **multi-node** deployments.
**all-in-one** is the default.
In the case of **multi-node** deployment, the Vagrant setup builds a cluster
with the following nodes by default:
* 3 control nodes
* 1 compute node
* 1 storage node (Note: ceph requires at least 3 storage nodes)
* 1 network node
* 1 operator node
The cluster node count can be changed by editing the Vagrantfile.
Kolla runs from the operator node to deploy OpenStack.
All nodes are connected with each other on the secondary NIC. The primary NIC
is behind a NAT interface for connecting with the Internet. The third NIC is
connected without IP configuration to a public bridge interface. This may be
used for Neutron/Nova to connect to instances.
Start by downloading and installing the Vagrant package for the distro of
choice. Various downloads can be found at the `Vagrant downloads
<https://www.vagrantup.com/downloads.html>`__.
Install required dependencies as follows:
For CentOS 7 or later:
.. code-block:: console
sudo yum install ruby-devel libvirt-devel zlib-devel libpng-devel gcc \
qemu-kvm qemu-img libvirt libvirt-python libvirt-client virt-install \
bridge-utils git
.. end
For Ubuntu 16.04 or later:
.. code-block:: console
sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt \
libvirt-dev nfs-kernel-server zlib1g-dev libpng12-dev gcc git
.. end
.. note::
Many distros ship outdated versions of Vagrant by default. When in
doubt, always install the latest from the downloads page above.
Next install the hostmanager plugin so all hosts are recorded in ``/etc/hosts``
(inside each vm):
.. code-block:: console
vagrant plugin install vagrant-hostmanager
.. end
If you are going to use VirtualBox, then install vagrant-vbguest:
.. code-block:: console
vagrant plugin install vagrant-vbguest
.. end
Vagrant supports a wide range of virtualization technologies. If VirtualBox is
used, the vbguest plugin will be required to install the VirtualBox Guest
Additions in the virtual machine:
.. code-block:: console
vagrant plugin install vagrant-vbguest
.. end
This documentation focuses on libvirt specifics. To install vagrant-libvirt
plugin:
.. code-block:: console
vagrant plugin install --plugin-version ">= 0.0.31" vagrant-libvirt
.. end
Some Linux distributions offer vagrant-libvirt packages, but the version they
provide tends to be too old to run Kolla. A version of >= 0.0.31 is required.
To use libvirt from Vagrant with a low privileges user without being asked for
a password, add the user to the libvirt group:
.. code-block:: console
sudo gpasswd -a ${USER} libvirt
newgrp libvirt
.. end
Setup NFS to permit file sharing between host and VMs. Contrary to the rsync
method, NFS allows both way synchronization and offers much better performance
than VirtualBox shared folders. For CentOS:
#. Add the virtual interfaces to the internal zone:
.. code-block:: console
sudo firewall-cmd --zone=internal --add-interface=virbr0
sudo firewall-cmd --zone=internal --add-interface=virbr1
.. end
#. Enable nfs, rpc-bind and mountd services for firewalld:
.. code-block:: console
sudo firewall-cmd --permanent --zone=internal --add-service=nfs
sudo firewall-cmd --permanent --zone=internal --add-service=rpc-bind
sudo firewall-cmd --permanent --zone=internal --add-service=mountd
sudo firewall-cmd --permanent --zone=internal --add-port=2049/udp
sudo firewall-cmd --permanent --add-port=2049/tcp
sudo firewall-cmd --permanent --add-port=111/udp
sudo firewall-cmd --permanent --add-port=111/tcp
sudo firewall-cmd --reload
.. end
#. Start required services for NFS:
.. code-block:: console
sudo systemctl restart firewalld
sudo systemctl start nfs-server
sudo systemctl start rpcbind.service
.. end
Ensure your system has libvirt and associated software installed and setup
correctly. For CentOS:
.. code-block:: console
sudo systemctl start libvirtd
sudo systemctl enable libvirtd
.. end
Find a location in the system's home directory and checkout Kolla repos:
.. code-block:: console
git clone https://git.openstack.org/openstack/kolla-ansible
git clone https://git.openstack.org/openstack/kolla
.. end
Both repos must share the same parent directory so the bootstrap code can
locate them.
Developers can now tweak the Vagrantfile or bring up the default **all-in-one**
CentOS 7-based environment:
.. code-block:: console
cd kolla-ansible/contrib/dev/vagrant && vagrant up
.. end
The command ``vagrant status`` provides a quick overview of the VMs composing
the environment.
Vagrant Up
==========
Once Vagrant has completed deploying all nodes, the next step is to launch
Kolla. First, connect with the **operator** node:
.. code-block:: console
vagrant ssh operator
.. end
To speed things up, there is a local registry running on the operator. All
nodes are configured so they can use this insecure repo to pull from, and use
it as a mirror. Ansible may use this registry to pull images from.
All nodes have a local folder shared between the group and the hypervisor, and
a folder shared between **all** nodes and the hypervisor. This mapping is lost
after reboots, so make sure to use the command ``vagrant reload <node>`` when
reboots are required. Having this shared folder provides a method to supply
a different Docker binary to the cluster. The shared folder is also used to
store the docker-registry files, so they are save from destructive operations
like ``vagrant destroy``.
Building images
---------------
Once logged on the **operator** VM call the ``kolla-build`` utility:
.. code-block:: console
kolla-build
.. end
``kolla-build`` accept arguments as documented in `Building Container Images
<https://docs.openstack.org/kolla/latest/admin/image-building.html>`_.
It builds Docker images and pushes them to the local registry if the **push**
option is enabled (in Vagrant this is the default behaviour).
Deploying OpenStack with Kolla
------------------------------
To deploy **all-in-one**:
.. code-block:: console
sudo kolla-ansible deploy
.. end
To deploy multinode:
For Centos 7:
.. code-block:: console
sudo kolla-ansible deploy -i /usr/share/kolla-ansible/ansible/inventory/multinode
.. end
For Ubuntu 16.04 or later:
.. code-block:: console
sudo kolla-ansible deploy -i /usr/local/share/kolla-ansible/ansible/inventory/multinode
.. end
Validate OpenStack is operational:
.. code-block:: console
kolla-ansible post-deploy
. /etc/kolla/admin-openrc.sh
openstack user list
.. end
Or navigate to ``http://172.28.128.254/`` with a web browser.
Further Reading
===============
All Vagrant documentation can be found at
`Vagrant documentation <https://www.vagrantup.com/docs/>`_.