docs/kud_architecture.rst

   1 .. Copyright 2018 Intel Corporation.
   2    Licensed under the Apache License, Version 2.0 (the "License");
   3    you may not use this file except in compliance with the License.
   4    You may obtain a copy of the License at
   5         http://www.apache.org/licenses/LICENSE-2.0
   6    Unless required by applicable law or agreed to in writing, software
   7    distributed under the License is distributed on an "AS IS" BASIS,
   8    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   9    See the License for the specific language governing permissions and
  10    limitations under the License.
  11
  12 ****************
  13 KUD Architecture
  14 ****************
  15
  16 This document explains the different components of the Kubernetes
  17 Reference Deployment project and how they can be configured to modify
  18 its default behaviour.
  19
  20 Vagrantfile
  21 ###########
  22
  23 This file describes how the Virtual Machines are going to be
  24 configured and the scripts and arguments used during their
  25 provisioning process. This file uses *elastic/ubuntu-16.04-x86_64*
  26 vagrant box for VirtualBox and Libvirt providers.
  27
  28 config/
  29 #######
  30
  31 This folder contains the POD Descriptor File (PDF) which is used
  32 by Vagrant during the provisioning process. The *samples* folder
  33 contains examples for some setups (All-in-One, Mini, NoHA, HA, etc.)
  34 that can be used.
  35
  36 This list contains the valid entries used by Vagrant to define the virtual
  37 resources used by Vagrant during the creation of the Virtual Machines:
  38
  39     * ip - The static IP address assigned to the VM. (String value)
  40     * memory - The amount of memory RAM. (KB - Integer value)
  41     * cpus - Number of CPUs. (Integer value)
  42     * volumes - List of volumes to be formatted and mounted to the VM.
  43
  44 config/default.yml
  45 ******************
  46
  47 If there is no *pdf.yml* file present in *config* folder, Vagrant will
  48 use the information specified in the **config/default.yml**. The following
  49 diagram displays how the services are installed in the nodes using the
  50 default configuration.
  51
  52 .. image:: ./img/default_pdf.png
  53
  54 docs/
  55 #####
  56
  57 This folder contains documentation files using reStructuredText
  58 (RST) syntax. It's possible to generate documentation in  *html*
  59 format using `python tox module <https://tox.readthedocs.io/en/latest/>`_
  60 . Once this is installed, it's possible to build html files using
  61 this following command:
  62
  63 .. code-block:: bash
  64
  65     tox -e docs
  66
  67 After its execution, the **docs/build** subfolder will contain
  68 subfolders and html files that can be opened from any web browser.
  69
  70 galaxy-requirements.yml
  71 #######################
  72
  73 This file contains third party Ansible roles. Only those tasks which
  74 are not related with the main installation process have been placed in
  75 this file.
  76
  77 installer.sh
  78 ############
  79
  80 Main bash script that installs dependencies and executes ansible
  81 playbooks for provisioning KUD components on external nodes.
  82
  83 inventory/
  84 ##########
  85
  86 This folder contains the Ansible host inventory file. The
  87 **inventory/host.ini** file, which is used during the execution of
  88 Ansible playbooks, is created by Vagrant using the values specified
  89 in the *config/pdf.yml* file (or *config/default.yml*).
  90
  91 inventory/group_vars/k8s-cluster.yml
  92 ************************************
  93
  94 A preferred practice in Ansible is to not store variables in the
  95 main inventory file. The configuration variables required for
  96 `Kubespray <https://github.com/kubernetes-incubator/kubespray>`_ are
  97 stored in this file.
  98
  99 node.sh
 100 #######
 101
 102 This bash script is executed in every node after this has been
 103 provisioned. The script provides the possibility to partition and
 104 mount external volumes.
 105
 106 playbooks/
 107 ##########
 108
 109 This folder contains a set of Ansible playbooks which perform the
 110 tasks required for configuring services like Multus, Virtlet and/or
 111 OVN.
 112
 113 playbooks/configure-kud.yml
 114 ***************************
 115
 116 This ansible playbook collects the common actions among all the
 117 Kubernetes AddOns offered by the KUD.
 118
 119 playbooks/kud-vars.yml
 120 ************************
 121
 122 This file centralizes the version numbers and source URLs used for
 123 different components offered by the KUD. Bumping a version requires
 124 extensive testing to ensure compatibility.
 125
 126 setup.sh
 127 ########
 128
 129 This bash script is used for the installation and configuration of
 130 dependencies required for the usage of the KUD via Virtual Machines.
 131 Some of this dependencies are:
 132
 133   - `Vagrant <https://www.vagrantup.com/>`_,
 134   - `Libvirt <https://libvirt.org/>`_ or `VirtualBox <https://www.virtualbox.org/>`_
 135
 136 The *-p* argument determines the Virtualization provider to be used
 137 and installed in the host machine.
 138
 139 .. code-block:: bash
 140
 141     sudo ./setup.sh -p libvirt
 142
 143 Vagrant uses VirtualBox as default Virtualization provider. It's
 144 possible to modify this behavior using the global enviroment variable
 145 named **VAGRANT_DEFAULT_PROVIDER**.
 146
 147 .. note::  The execution of this script is recommended only during the initial setup.
 148
 149 tests/
 150 ######
 151
 152 This folder contains the health check scripts that guarantee the
 153 proper installation/configuration of Kubernetes AddOns. Its
 154 execution is disabled by default. In order to enable it, it's
 155 necessary to export KUD_ENABLE_TESTS=true environment variable before calling the **installer.sh** bash
 156 script, usually through changing the arguments in the *Vagrantfile*.