From 0bfd22fabb43a4b13a56eb89e00a2d1ce37581db Mon Sep 17 00:00:00 2001 From: Samuli Silvius Date: Thu, 30 May 2019 19:16:27 +0300 Subject: Documentation update for aio.sh CI change Update documentation accordingly. Issue-ID: MULTICLOUD-629 Change-Id: I36b65dd270a25d63884d161163cfa8e7a813d241 Signed-off-by: Samuli Silvius --- docs/bare_metal_provisioning.rst | 45 ++++------- docs/index.rst | 6 +- docs/krd_architecture.rst | 162 --------------------------------------- docs/kud_architecture.rst | 156 +++++++++++++++++++++++++++++++++++++ 4 files changed, 175 insertions(+), 194 deletions(-) delete mode 100644 docs/krd_architecture.rst create mode 100644 docs/kud_architecture.rst (limited to 'docs') diff --git a/docs/bare_metal_provisioning.rst b/docs/bare_metal_provisioning.rst index 2cb74afe..934cea82 100644 --- a/docs/bare_metal_provisioning.rst +++ b/docs/bare_metal_provisioning.rst @@ -13,11 +13,11 @@ Bare-Metal Provisioning *********************** -The Kubernetes Reference Deployment, aka KRD, has been designed to be consumed -by Virtual Machines as well as Bare-Metal servers. The *vagrant/aio.sh* +The Kubernetes Deployment, aka KUD, has been designed to be consumed +by Virtual Machines as well as Bare-Metal servers. The *baremetal/aio.sh* script contains the bash instructions for provisioning an All-in-One Kubernetes deployment in a Bare-Metal server. This document lists the Hardware & Software -requirements and walkthrough the instructions that *vagrant/aio.sh* contains. +requirements and walkthrough the instructions that *baremetal/aio.sh* contains. Hardware Requirements ##################### @@ -37,8 +37,8 @@ Software Requirements - Ubuntu Server 16.04 LTS -vagrant/aio.sh -############## +baremetal/aio.sh +################ This bash script provides an automated process for deploying an All-in-One Kubernetes cluster. Given that the ansible inventory file created by this @@ -50,23 +50,17 @@ The following two instructions start the provisioning process. .. code-block:: bash $ sudo su - # wget -O - https://git.onap.org/multicloud/k8s/plain/vagrant/aio.sh | bash + # git clone https://git.onap.org/multicloud/k8s/ + # cd k8s/kud/hosting_providers/baremetal/ + # ./aio.sh In overall, this script can be summarized in three general phases: -1. Cloning and configuring the KRD project. +1. Generating Inventory. 2. Enabiling Nested-Virtualization. -3. Deploying KRD services. +3. Deploying KUD services. -**Cloning and configuring the KRD project** - -KRD requires multiple files(bash scripts and ansible playbooks) to operate. -Therefore, it's necessary to clone the *ONAP multicloud/k8s* project to get -access to the *vagrant* folder. - -.. code-block:: bash - - git clone https://git.onap.org/multicloud/k8s/ +**Inventory** Ansible works agains multiple systems, the way for selecting them is through the usage of the inventory. The inventory file is a static source for determining the @@ -102,17 +96,10 @@ an inventory file for addressing those tasks to localhost. kube-master EOL -KRD consumes kubespray_ for provisioning a Kubernetes base deployment. As part -of the deployment process, this tool downloads and configures *kubectl* binary. -This action conflicts with *andrewrothstein.kubectl* ansible role. Therefore is -necessary to remove those instructions from all the ansible playbooks. +KUD consumes kubespray_ for provisioning a Kubernetes base deployment. .. _kubespray: https://github.com/kubernetes-incubator/kubespray -.. code-block:: bash - - # sed -i '/andrewrothstein.kubectl/d' playbooks/configure-*.yml - Ansible uses SSH protocol for executing remote instructions. The following instructions create and register ssh keys which avoid the usage of passwords. @@ -124,7 +111,7 @@ instructions create and register ssh keys which avoid the usage of passwords. **Enabling Nested-Virtualization** -KRD installs Virtlet_ Kubernetes CRI for running Virtual Machine workloads. +KUD installs Virtlet_ Kubernetes CRI for running Virtual Machine workloads. Nested-virtualization gives the ability of running a Virtual Machine within another. The *node.sh* bash script contains the instructions for enabling Nested-Virtualization. @@ -135,14 +122,14 @@ Nested-Virtualization. # ./node.sh -**Deploying KRD services** +**Deploying KUD services** Finally, the KRD provisioning process can be started through the use of *installer.sh* bash script. The output of this script is collected in the -*krd_installer.log* file for future reference. +*kud_installer.log* file for future reference. .. code-block:: bash - # ./installer.sh | tee krd_installer.log + # ./installer.sh | tee kud_installer.log .. image:: ./img/installer_workflow.png diff --git a/docs/index.rst b/docs/index.rst index 173076b4..7a49b6d1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ over cloud regions that support Kubernetes as the orchestrator. Kubernetes Reference Deployment =============================== -The Kubernetes Reference Deployment(KRD) provides an +The Kubernetes Reference Deployment(KUD) provides an automated mechanism to install and configure the Kubernetes services required for the MultiCloud Kubernetes plugin. @@ -18,6 +18,6 @@ Table of contents .. toctree:: :maxdepth: 3 - KRD Project Architecture - Bare Metal All-in-One KRD deployment + KUD Project Architecture + Bare Metal All-in-One KUD deployment Kubernetes MultiCloud API sample ommands diff --git a/docs/krd_architecture.rst b/docs/krd_architecture.rst deleted file mode 100644 index f188135e..00000000 --- a/docs/krd_architecture.rst +++ /dev/null @@ -1,162 +0,0 @@ -.. 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. - -**************** -KRD 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 `_ -. 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 KRD components on external nodes. This -script uses some arguments for the additional installation of -components. For more information about its usage: - -.. code-block:: bash - - ./installer.sh -h - -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 `_ 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-krd.yml -*************************** - -This ansible playbook collects the common actions among all the -Kubernetes AddOns offered by the KRD. - -playbooks/krd-vars.yml -************************ - -This file centralizes the version numbers and source URLs used for -different components offered by the KRD. 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 `_, - - `Libvirt `_ or `VirtualBox `_ - -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 pass the *-t* argument to the **installer.sh** bash -script, usually through changing the arguments in the *Vagrantfile*. 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 `_ +. 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 `_ 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 `_, + - `Libvirt `_ or `VirtualBox `_ + +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*. -- cgit 1.2.3-korg