X-Git-Url: https://gerrit.akraino.org/r/gitweb?a=blobdiff_plain;f=docs%2Frelease%2Finstallation%2Finstallation.instruction.rst;fp=docs%2Frelease%2Finstallation%2Finstallation.instruction.rst;h=706d5903adad1a22f1145dd7777c9076f61f6f09;hb=b55251f4f820cccee84a13fe919473d6d022d151;hp=01341e951db43e27c6ce9050b99210096660e97d;hpb=16f5e89dd4b251c8a11444aa5514318a262e7c5e;p=iec.git diff --git a/docs/release/installation/installation.instruction.rst b/docs/release/installation/installation.instruction.rst index 01341e9..706d590 100644 --- a/docs/release/installation/installation.instruction.rst +++ b/docs/release/installation/installation.instruction.rst @@ -10,51 +10,167 @@ Akraino IEC Installation Instruction Introduction ============ -License -======= +This document provides guidelines on how to install the Akraino IEC Release 1, +including required software and hardware configurations. + +The audience of this document is assumed to have good knowledge of +networking and Unix/Linux administration. + +Currently, the chosen operating system (OS) is Ubuntu 16.04 and/or 18.04. +The infrastructure orchestration of IEC is based on Kubernetes, which is a +production-grade container orchestration with a rich running eco-system. +The current container network interface (CNI) solution chosen for Kubernetes is +project Calico, which is a high performance, scalable, policy enabled and +widely used container networking solution with rather easy installation and +arm64 support. How to use this document ======================== +The following sections describe the prerequisites for planning an IEC +deployment. Once these are met, installation steps provided should be followed +in order to obtain an IEC compliant Kubernetes cluster. + Deployment Architecture ======================= +The reference cluster platform consists of 3 nodes, baremetal or virtual +machines: + +- the first node will have the role of Kubernetes Master; +- all other nodes will have the role of Kubernetes Slave; +- Calico will be used as container network interface (CNI); + +One additional management/orchestration node (which will be referred to as +``jumpserver`` or ``orchestration node``) is necessary for running the +installation steps. + +If all nodes are virtual machines on the same machine which is also used as the +``jumpserver``, the deployment type will be referred to as ``virtual`` - useful +mostly for development and/or testing and not production grade. + +.. NOTE:: + + The default number of Kubernetes slaves is 2; although less or more slaves + can be used as well. + +.. WARNING:: + + Currently, we assume all the cluster nodes have the same architecture + (``aarch64`` or ``x86_64``). + +All machines (including the ``jumpserver``) should be part of at least one +common network segment. + Pre-Installation Requirements ============================= Hardware Requirements --------------------- +.. NOTE:: + + Hardware requirements depend on the deployment type. + If more cluster nodes are used, the requirements for a single node can + be lowered, provided that the sum of available resources is enough. + + Depending on the intended usecase(s), more memory/storage might be + required for running/storing the containers. + Minimum Hardware Requirements ````````````````````````````` ++------------------+------------------------------------------------------+ +| **HW Aspect** | **Requirement** | +| | | ++==================+======================================================+ +| **1 Jumpserver** | A physical or virtualized machine that has direct | +| | network connectivity to the cluster nodes. | +| | | +| | .. NOTE:: | +| | | +| | For ``virtual`` deployments, CPU/RAM/disk | +| | requirements of cluster nodes should be | +| | satisfiable as virtual machine resources | +| | when using the ``jumpserver`` as a hypervisor. | ++------------------+------------------------------------------------------+ +| **CPU** | Minimum 1 socket (each cluster node) | ++------------------+------------------------------------------------------+ +| **RAM** | Minimum 2GB/server (Depending on usecase work load) | ++------------------+------------------------------------------------------+ +| **Disk** | Minimum 20GB (each cluster node) | ++------------------+------------------------------------------------------+ +| **Networks** | Mininum 1 | ++------------------+------------------------------------------------------+ + Recommended Hardware Requirements ````````````````````````````````` ++------------------+------------------------------------------------------+ +| **HW Aspect** | **Requirement** | +| | | ++==================+======================================================+ +| **1 Jumpserver** | A physical or virtualized machine that has direct | +| | network connectivity to the cluster nodes. | +| | | +| | .. NOTE:: | +| | | +| | For ``virtual`` deployments, CPU/RAM/disk | +| | requirements of cluster nodes should be | +| | satisfiable as virtual machine resources | +| | when using the ``jumpserver`` as a hypervisor. | ++------------------+------------------------------------------------------+ +| **CPU** | 1 socket (each cluster node) | ++------------------+------------------------------------------------------+ +| **RAM** | 16GB/server (Depending on usecase work load) | ++------------------+------------------------------------------------------+ +| **Disk** | 100GB (each cluster node) | ++------------------+------------------------------------------------------+ +| **Networks** | 2/3 (management and public, optionally separate PXE) | ++------------------+------------------------------------------------------+ + Software Prerequisites ---------------------- +- Ubuntu 16.04/18.04 is installed on each node; +- SSH server running on each node, allowing password-based logins; +- a user (by default named ``iec``, but can be customized via config later) + is present on each node; +- ``iec`` user has passwordless sudo rights; +- ``iec`` user is allowed password-based SSH login; + Database Prerequisites ---------------------- Schema scripts `````````````` +N/A + Other Installation Requirements ------------------------------- Jump Host Requirements `````````````````````` +N/A + Network Requirements ```````````````````` +- at least one common network segment across all nodes; +- internet connectivity; + Bare Metal Node Requirements ```````````````````````````` +N/A + Execution Requirements (Bare Metal Only) ```````````````````````````````````````` +N/A + Installation High-Level Overview ================================ @@ -64,98 +180,227 @@ Bare Metal Deployment Guide Install Bare Metal Jump Host ```````````````````````````` +The jump host (``jumpserver``) operating system should be preprovisioned. +No special software requirements apply apart from package prerequisites: + +- git +- sshpass + Creating a Node Inventory File `````````````````````````````` +N/A + Creating the Settings Files ``````````````````````````` +Clone the IEC git repo and edit the configuration file by setting: + +- user name for SSH-ing into cluster nodes (default: ``iec``); +- user password for SSH-ing into cluster nodes; +- Kubernetes master node IP address (should be reachable from ``jumpserver`` + and accept SSH connections); +- Kubernetes slave node(s) IP address(es) and passwords for SSH access; + +.. code-block:: console + + jenkins@jumpserver:~$ git clone https://gerrit.akraino.org/r/iec.git + jenkins@jumpserver:~$ cd iec/src/foundation/scripts + jenkins@jumpserver:~/iec/src/foundation/scripts$ vim config.sh + Running ``````` +Simply start the installation script in the same directory: + +.. code-block:: console + + jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh + Virtual Deployment Guide ------------------------ Standard Deployment Overview ```````````````````````````` +From the installer script's perspective, virtual deployments are identical to +baremetal ones. +Preprovision some virtual machines on the ``jumpserver`` node as hypervisor, +using Ubuntu 16.04/18.04, then continue the installation similar to the +baremetal deployment process described above. + Snapshot Deployment Overview ```````````````````````````` +N/A + Special Requirements for Virtual Deployments ```````````````````````````````````````````` +N/A + Install Jump Host ''''''''''''''''' +Similar to baremetal deployments. Additionally, one hypervisor solution should +be available for creating the cluster nodes virtual machines (e.g. KVM). + Verifying the Setup - VMs ''''''''''''''''''''''''' +N/A + Upstream Deployment Guide ------------------------- +N/A + Upstream Deployment Key Features ```````````````````````````````` +N/A + Special Requirements for Upstream Deployments ````````````````````````````````````````````` +N/A + Scenarios and Deploy Settings for Upstream Deployments `````````````````````````````````````````````````````` +N/A + Including Upstream Patches with Deployment `````````````````````````````````````````` +N/A + Running ``````` +Similar to virtual deployments, edit the configuration file, then launch the +installation script: + +.. code-block:: console + + jenkins@jumpserver:~$ git clone https://gerrit.akraino.org/r/iec.git + jenkins@jumpserver:~$ cd iec/src/foundation/scripts + jenkins@jumpserver:~/iec/src/foundation/scripts$ vim config.sh + jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh + Interacting with Containerized Overcloud ```````````````````````````````````````` +N/A + Verifying the Setup =================== +IEC installation automatically performs one simple test of the Kubernetes +cluster installation by spawning an ``nginx`` container and fetching a sample +file via HTTP. + +`Akraino Blueprint Validation`_ integration will later offer a complete e2e +(end to end) validation of the Kubernetes installation by running the complete +e2e test suite of `Sonobuoy`_ diagnostics suite. +Meanwhile, `Sonobuoy`_ can be used manually by following the instructions in +its README file. + OpenStack Verification ====================== +N/A + Developer Guide and Troubleshooting =================================== Utilization of Images --------------------- +N/A + Post-deployment Configuration ----------------------------- +N/A + OpenDaylight Integration ------------------------ +N/A + Debugging Failures ------------------ +N/A + Reporting a Bug --------------- +All issues should be reported via `IEC JIRA`_ page. +When submitting reports, please provide as much relevant information as possible, e.g.: + +- output logs; +- IEC git repository commit used; +- jumpserver info (operating system, versions of involved software components et al.); +- command history (when relevant); + Uninstall Guide =============== +N/A + Troubleshooting =============== Error Message Guide ------------------- +N/A + Maintenance =========== +N/A + Frequently Asked Questions ========================== +N/A + License ======= +`Apache License 2.0`_: + +| Any software developed by the "Akraino IEC" Project is licenced under the +| Apache License, Version 2.0 (the "License"); +| you may not use the content of this software bundle except in compliance with the License. +| You may obtain a copy of the License at +| +| 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. + References ========== +For more information on the Akraino Release 1, please see: + +#. `Akraino Home Page`_ +#. `IEC Wiki`_ + Definitions, acronyms and abbreviations ======================================= + +N/A + +.. All links go below this line +.. _`Apache License 2.0`: https://www.apache.org/licenses/LICENSE-2.0 +.. _`Akraino Home Page`: https://wiki.akraino.org/pages/viewpage.action?pageId=327703 +.. _`IEC Wiki`: https://wiki.akraino.org/display/AK/Integrated+Edge+Cloud+%28IEC%29+Blueprint+Family +.. _`IEC JIRA`: https://jira.akraino.org/projects/IEC/issues/ +.. _`Akraino Blueprint Validation`: https://wiki.akraino.org/display/AK/Akraino+Blueprint+Validation+Framework +.. _`Sonobuoy`: https://github.com/heptio/sonobuoy