summaryrefslogtreecommitdiffstats
path: root/docs/kud_architecture.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/kud_architecture.rst')
-rw-r--r--docs/kud_architecture.rst156
1 files changed, 156 insertions, 0 deletions
diff --git a/docs/kud_architecture.rst b/docs/kud_architecture.rst
new file mode 100644
index 00000000..f56b72a5
--- /dev/null
+++ b/docs/kud_architecture.rst
@@ -0,0 +1,156 @@
+.. Copyright 2018 Intel Corporation.
+ 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.
+
+****************
+KUD Architecture
+****************
+
+This document explains the different components of the Kubernetes
+Reference Deployment project and how they can be configured to modify
+its default behaviour.
+
+Vagranfile
+##########
+
+This file describes how the Virtual Machines are going to be
+configured and the scripts and arguments used during their
+provisioning process. This file uses *elastic/ubuntu-16.04-x86_64*
+vagrant box for VirtualBox and Libvirt providers.
+
+config/
+#######
+
+This folder contains the POD Descriptor File (PDF) which is used
+by Vagrant during the provisioning process. The *samples* folder
+contains examples for some setups (All-in-One, Mini, NoHA, HA, etc.)
+that can be used.
+
+This list contains the valid entries used by Vagrant to define the virtual
+resources used by Vagrant during the creation of the Virtual Machines:
+
+ * ip - The static IP address assigned to the VM. (String value)
+ * memory - The amount of memory RAM. (KB - Integer value)
+ * cpus - Number of CPUs. (Integer value)
+ * volumes - List of volumes to be formatted and mounted to the VM.
+
+config/default.yml
+******************
+
+If there is no *pdf.yml* file present in *config* folder, Vagrant will
+use the information specified in the **config/default.yml**. The following
+diagram displays how the services are installed in the nodes using the
+default configuration.
+
+.. image:: ./img/default_pdf.png
+
+docs/
+#####
+
+This folder contains documentation files using reStructuredText
+(RST) syntax. It's possible to generate documentation in *html*
+format using `python tox module <https://tox.readthedocs.io/en/latest/>`_
+. Once this is installed, it's possible to build html files using
+this following command:
+
+.. code-block:: bash
+
+ tox -e docs
+
+After its execution, the **docs/build** subfolder will contain
+subfolders and html files that can be opened from any web browser.
+
+galaxy-requirements.yml
+#######################
+
+This file contains third party Ansible roles. Only those tasks which
+are not related with the main installation process have been placed in
+this file.
+
+installer.sh
+############
+
+Main bash script that installs dependencies and executes ansible
+playbooks for provisioning KUD components on external nodes.
+
+inventory/
+##########
+
+This folder contains the Ansible host inventory file. The
+**inventory/host.ini** file, which is used during the execution of
+Ansible playbooks, is created by Vagrant using the values specified
+in the *config/pdf.yml* file (or *config/default.yml*).
+
+inventory/group_vars/k8s-cluster.yml
+************************************
+
+A preferred practice in Ansible is to not store variables in the
+main inventory file. The configuration variables required for
+`Kubespray <https://github.com/kubernetes-incubator/kubespray>`_ are
+stored in this file.
+
+node.sh
+#######
+
+This bash script is executed in every node after this has been
+provisioned. The script provides the possibility to partition and
+mount external volumes.
+
+playbooks/
+##########
+
+This folder contains a set of Ansible playbooks which perform the
+tasks required for configuring services like Multus, Virtlet and/or
+OVN.
+
+playbooks/configure-kud.yml
+***************************
+
+This ansible playbook collects the common actions among all the
+Kubernetes AddOns offered by the KUD.
+
+playbooks/kud-vars.yml
+************************
+
+This file centralizes the version numbers and source URLs used for
+different components offered by the KUD. Bumping a version requires
+extensive testing to ensure compatibility.
+
+setup.sh
+########
+
+This bash script is used for the installation and configuration of
+dependencies required for the usage of the KRD via Virtual Machines.
+Some of this dependencies are:
+
+ - `Vagrant <https://www.vagrantup.com/>`_,
+ - `Libvirt <https://libvirt.org/>`_ or `VirtualBox <https://www.virtualbox.org/>`_
+
+The *-p* argument determines the Virtualization provider to be used
+and installed in the host machine.
+
+.. code-block:: bash
+
+ ./setup.sh -p libvirt
+
+Vagrant uses VirtualBox as default Virtualization provider. It's
+possible to modify this behavior using the global enviroment variable
+named **VAGRANT_DEFAULT_PROVIDER**.
+
+.. note:: The execution of this script is recommended only during the initial setup.
+
+tests/
+######
+
+This folder contains the health check scripts that guarantee the
+proper installation/configuration of Kubernetes AddOns. Its
+execution is disabled by default. In order to enable it, it's
+necessary to export KUD_ENABLE_TESTS=true environment variable before calling the **installer.sh** bash
+script, usually through changing the arguments in the *Vagrantfile*.