.. Copyright (C) 2022 Nippon Telegraph and Telephone Corporation 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. Devstack Installation with Vagrant ================================== This documentation is for introducing a deployment tool for Tacker. You can find a :doc:`basic installation ` for deploying OpenStack environment using ``devstack`` as a part of :doc:`Tacker Installation Guide`. This guide expects you have already setup your VMs and installed all packages required to run OpenStack. However, it's something annoying for beginners, or developers frequently cleanup their environment. You may want to use a tool to shortcut such a tasks. This tool enables you to deploy several usecases with minimal effort. How to Use ---------- Install Required Tools ~~~~~~~~~~~~~~~~~~~~~~ This installer consists of ``vagrant`` and ``ansible``. Please follow instructions on official sites for installation. * `vagrant `_ * `ansible `_ .. note:: In this documentation, it's supposed you use `VirtualBox `_, but you can use any other hypervisor supported by ``vagrant``. .. figure:: ../_images/vagrant-devstack.svg :scale: 55 You should install plugin ``vagrant-disksize`` before launching your VMs to enable to expand size of volume of VMs. It is because the default size of box is fixed and not enough for deploying Tacker. .. code-block:: console $ vagrant plugin install vagrant-disksize Setup Configuration File ~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: Create your ssh key before running this tool to enable to direct login with auto-generated ssh config although you can still do two step login starts from ``vagrant ssh``. You can login to ``controller`` host with auto-generated config ``ssh_config`` as below. .. code-block:: console $ ssh -F /path/to/tacker/vagrant/devstack/ssh_config controller Setup ``machines.yml`` which is a config file defines parameters of each VM you deploy. You can find some templates of ``machines.yml`` in ``samples`` directory. This config file should be placed at ``/path/to/tacker/vagrant/devstack`` while running ``vagrant up``, or failed to run the command. .. code-block:: console $ cd /path/to/tacker/vagrant/devstack $ cp samples/machines.yml ./ $ YOUR_FAVORITE_EDITOR machines.yml As named as ``machines.yml``, it defines parameters of each VMs. There are two top sections in the file, ``global`` and ``machines``. The former one defines common parameters among the VMs, and later one is for each VM. .. note:: ``global`` is optional currently and only one parameter under the section is ``ssh_pub_key`` for specifying its location explicitly. You don't need to use it if your public key is ``$HOME/.ssh/id_rsa.pub``. Here is an example of ``machine.yml``. It's is for single node usecase and ``machines`` has only one entry. .. literalinclude:: ../../../vagrant/devstack/samples/machines.yml :language: yaml There are several parameters for each VM supported in this tool. .. list-table:: :widths: 30 125 :header-rows: 1 * - Attribute - Description * - hostname - Any hostname for convenience, such as ``controller`` or ``compute``. * - provider - Vagrant box provider. * - box - Name of the box. * - nof_cpus - The number of CPUs assigned to the VM. * - mem_size - The size of memory assigned to the VM. * - disk_size - The size of disk assigned to the VM. * - private_ips - Series of private IPs. * - public_ips - Series of public IPs. * - fwd_port_list - Series of combination of ``guest`` and ``host`` ports for port forwarding. You also update entries of IP addresses in the inventory file ``hosts`` as you defined each ``private_ips`` in ``machines.yml``. Now, you are ready to fire up the VMs and deploying OpenStack with ``ansible``. Deploy OpenStack with Devstack ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Run ``vagrant up`` so that launches VMs and create ``stack`` user on them. .. code-block:: console $ vagrant up If ``vagrant up`` is completed successfully, you can login to the VMs as ``stack`` user with your ssh public key. This tool provides ``ansible`` playbooks for setting up ``devstack`` installation. You don't need to modify the playbooks usually, but configurable in ``group_vars/all.yml``. See :ref:`optional_config` describing how you configure the file. .. code-block:: console $ ansible-playbook -i hosts site.yaml After finished all tasks, you can login to the launched VMs. So, login to controller node and run ``stack.sh`` for installing OpenStack. You will find out that ``local.conf`` is already prepared for your environment. See instruction how to configure ``local.conf`` described in `DevStack Quick Start `_ if you customize it furthermore by yourself. .. code-block:: console $ ssh stack@192.168.56.11 $ cd devstack $ YOUR_FAVORITE_EDITOR local.conf $ ./stack.sh .. _optional_config: Options Configuration ~~~~~~~~~~~~~~~~~~~~~ There some parameters in ``group_vars/all.yml`` such as password on devstack or optional configurations. You don't need to update it usually. .. literalinclude:: ../../../vagrant/devstack/group_vars/all.yml :language: yaml Developer Tools --------------- In the playbools, installation of vim and some extra packages is included for developers. If you exclude such a developer tools, modify ``group_vars/all.yml`` before running ``ansible-playbook`` command. .. list-table:: :widths: 30 125 :header-rows: 1 * - Parameter - Description * - use_vim_latest - (Only for ubuntu) ``true`` or ``false`` for using the latest vim. * - use_vim_extra_plugins - ``true`` or ``false`` for installing vim packages including language servers for python and bash. * - use_extra_tools - | ``true`` or ``false`` for using extra packages bellow. | - jq | - htop (Ubuntu only) | - lnav (Ubuntu only)