docs/release/installation/installation.instruction.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) Akraino Project, Inc. and its contributors
   4
   5 ************************************
   6 Akraino IEC Installation Instruction
   7 ************************************
   8
   9
  10 Introduction
  11 ============
  12
  13 This document provides guidelines on how to install the Akraino IEC Release 1,
  14 including required software and hardware configurations.
  15
  16 The audience of this document is assumed to have good knowledge of
  17 networking and Unix/Linux administration.
  18
  19 Currently, the chosen operating system (OS) is Ubuntu 16.04 and/or 18.04.
  20 The infrastructure orchestration of IEC is based on Kubernetes, which is a
  21 production-grade container orchestration with a rich running eco-system.
  22 The current container network interface (CNI) solution chosen for Kubernetes is
  23 project Calico, which is a high performance, scalable, policy enabled and
  24 widely used container networking solution with rather easy installation and
  25 arm64 support.
  26
  27 How to use this document
  28 ========================
  29
  30 The following sections describe the prerequisites for planning an IEC
  31 deployment. Once these are met, installation steps provided should be followed
  32 in order to obtain an IEC compliant Kubernetes cluster.
  33
  34 Deployment Architecture
  35 =======================
  36
  37 The reference cluster platform consists of 3 nodes, baremetal or virtual
  38 machines:
  39
  40 - the first node will have the role of Kubernetes Master;
  41 - all other nodes will have the role of Kubernetes Slave;
  42 - Calico will be used as container network interface (CNI);
  43
  44 One additional management/orchestration node (which will be referred to as
  45 ``jumpserver`` or ``orchestration node``) is necessary for running the
  46 installation steps.
  47
  48 If all nodes are virtual machines on the same machine which is also used as the
  49 ``jumpserver``, the deployment type will be referred to as ``virtual`` - useful
  50 mostly for development and/or testing and not production grade.
  51
  52 .. NOTE::
  53
  54     The default number of Kubernetes slaves is 2; although less or more slaves
  55     can be used as well.
  56
  57 .. WARNING::
  58
  59     Currently, we assume all the cluster nodes have the same architecture
  60     (``aarch64`` or ``x86_64``).
  61
  62 All machines (including the ``jumpserver``) should be part of at least one
  63 common network segment.
  64
  65 Pre-Installation Requirements
  66 =============================
  67
  68 Hardware Requirements
  69 ---------------------
  70
  71 .. NOTE::
  72
  73     Hardware requirements depend on the deployment type.
  74     If more cluster nodes are used, the requirements for a single node can
  75     be lowered, provided that the sum of available resources is enough.
  76
  77     Depending on the intended usecase(s), more memory/storage might be
  78     required for running/storing the containers.
  79
  80 Minimum Hardware Requirements
  81 `````````````````````````````
  82
  83 +------------------+------------------------------------------------------+
  84 | **HW Aspect**    | **Requirement**                                      |
  85 |                  |                                                      |
  86 +==================+======================================================+
  87 | **1 Jumpserver** | A physical or virtualized machine that has direct    |
  88 |                  | network connectivity to the cluster nodes.           |
  89 |                  |                                                      |
  90 |                  | .. NOTE::                                            |
  91 |                  |                                                      |
  92 |                  |     For ``virtual`` deployments, CPU/RAM/disk        |
  93 |                  |     requirements of cluster nodes should be          |
  94 |                  |     satisfiable as virtual machine resources         |
  95 |                  |     when using the ``jumpserver`` as a hypervisor.   |
  96 +------------------+------------------------------------------------------+
  97 | **CPU**          | Minimum 1 socket (each cluster node)                 |
  98 +------------------+------------------------------------------------------+
  99 | **RAM**          | Minimum 2GB/server (Depending on usecase work load)  |
 100 +------------------+------------------------------------------------------+
 101 | **Disk**         | Minimum 20GB (each cluster node)                     |
 102 +------------------+------------------------------------------------------+
 103 | **Networks**     | Mininum 1                                            |
 104 +------------------+------------------------------------------------------+
 105
 106 Recommended Hardware Requirements
 107 `````````````````````````````````
 108
 109 +------------------+------------------------------------------------------+
 110 | **HW Aspect**    | **Requirement**                                      |
 111 |                  |                                                      |
 112 +==================+======================================================+
 113 | **1 Jumpserver** | A physical or virtualized machine that has direct    |
 114 |                  | network connectivity to the cluster nodes.           |
 115 |                  |                                                      |
 116 |                  | .. NOTE::                                            |
 117 |                  |                                                      |
 118 |                  |     For ``virtual`` deployments, CPU/RAM/disk        |
 119 |                  |     requirements of cluster nodes should be          |
 120 |                  |     satisfiable as virtual machine resources         |
 121 |                  |     when using the ``jumpserver`` as a hypervisor.   |
 122 +------------------+------------------------------------------------------+
 123 | **CPU**          | 1 socket (each cluster node)                         |
 124 +------------------+------------------------------------------------------+
 125 | **RAM**          | 16GB/server (Depending on usecase work load)         |
 126 +------------------+------------------------------------------------------+
 127 | **Disk**         | 100GB (each cluster node)                            |
 128 +------------------+------------------------------------------------------+
 129 | **Networks**     | 2/3 (management and public, optionally separate PXE) |
 130 +------------------+------------------------------------------------------+
 131
 132 Software Prerequisites
 133 ----------------------
 134
 135 - Ubuntu 16.04/18.04 is installed on each node;
 136 - SSH server running on each node, allowing password-based logins;
 137 - a user (by default named ``iec``, but can be customized via config later)
 138   is present on each node;
 139 - ``iec`` user has passwordless sudo rights;
 140 - ``iec`` user is allowed password-based SSH login;
 141
 142 Database Prerequisites
 143 ----------------------
 144
 145 Schema scripts
 146 ``````````````
 147
 148 N/A
 149
 150 Other Installation Requirements
 151 -------------------------------
 152
 153 Jump Host Requirements
 154 ``````````````````````
 155
 156 N/A
 157
 158 Network Requirements
 159 ````````````````````
 160
 161 - at least one common network segment across all nodes;
 162 - internet connectivity;
 163
 164 Bare Metal Node Requirements
 165 ````````````````````````````
 166
 167 N/A
 168
 169 Execution Requirements (Bare Metal Only)
 170 ````````````````````````````````````````
 171
 172 N/A
 173
 174 Installation High-Level Overview
 175 ================================
 176
 177 Bare Metal Deployment Guide
 178 ---------------------------
 179
 180 Install Bare Metal Jump Host
 181 ````````````````````````````
 182
 183 The jump host (``jumpserver``) operating system should be preprovisioned.
 184 No special software requirements apply apart from package prerequisites:
 185
 186 - git
 187 - sshpass
 188
 189 Creating a Node Inventory File
 190 ``````````````````````````````
 191
 192 N/A
 193
 194 Creating the Settings Files
 195 ```````````````````````````
 196
 197 Clone the IEC git repo and edit the configuration file by setting:
 198
 199 - user name for SSH-ing into cluster nodes (default: ``iec``);
 200 - user password for SSH-ing into cluster nodes;
 201 - Kubernetes master node IP address (should be reachable from ``jumpserver``
 202   and accept SSH connections);
 203 - Kubernetes slave node(s) IP address(es) and passwords for SSH access;
 204
 205 .. code-block:: console
 206
 207     jenkins@jumpserver:~$ git clone https://gerrit.akraino.org/r/iec.git
 208     jenkins@jumpserver:~$ cd iec/src/foundation/scripts
 209     jenkins@jumpserver:~/iec/src/foundation/scripts$ vim config.sh
 210
 211 Running
 212 ```````
 213
 214 Simply start the installation script in the same directory:
 215
 216 .. code-block:: console
 217
 218     jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh
 219
 220 Virtual Deployment Guide
 221 ------------------------
 222
 223 Standard Deployment Overview
 224 ````````````````````````````
 225
 226 From the installer script's perspective, virtual deployments are identical to
 227 baremetal ones.
 228 Preprovision some virtual machines on the ``jumpserver`` node as hypervisor,
 229 using Ubuntu 16.04/18.04, then continue the installation similar to the
 230 baremetal deployment process described above.
 231
 232 Snapshot Deployment Overview
 233 ````````````````````````````
 234
 235 N/A
 236
 237 Special Requirements for Virtual Deployments
 238 ````````````````````````````````````````````
 239
 240 N/A
 241
 242 Install Jump Host
 243 '''''''''''''''''
 244
 245 Similar to baremetal deployments. Additionally, one hypervisor solution should
 246 be available for creating the cluster nodes virtual machines (e.g. KVM).
 247
 248 Verifying the Setup - VMs
 249 '''''''''''''''''''''''''
 250
 251 N/A
 252
 253 Upstream Deployment Guide
 254 -------------------------
 255
 256 N/A
 257
 258 Upstream Deployment Key Features
 259 ````````````````````````````````
 260
 261 N/A
 262
 263 Special Requirements for Upstream Deployments
 264 `````````````````````````````````````````````
 265
 266 N/A
 267
 268 Scenarios and Deploy Settings for Upstream Deployments
 269 ``````````````````````````````````````````````````````
 270
 271 N/A
 272
 273 Including Upstream Patches with Deployment
 274 ``````````````````````````````````````````
 275
 276 N/A
 277
 278 Running
 279 ```````
 280
 281 Similar to virtual deployments, edit the configuration file, then launch the
 282 installation script:
 283
 284 .. code-block:: console
 285
 286     jenkins@jumpserver:~$ git clone https://gerrit.akraino.org/r/iec.git
 287     jenkins@jumpserver:~$ cd iec/src/foundation/scripts
 288     jenkins@jumpserver:~/iec/src/foundation/scripts$ vim config.sh
 289     jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh
 290
 291 Interacting with Containerized Overcloud
 292 ````````````````````````````````````````
 293
 294 N/A
 295
 296 Verifying the Setup
 297 ===================
 298
 299 IEC installation automatically performs one simple test of the Kubernetes
 300 cluster installation by spawning an ``nginx`` container and fetching a sample
 301 file via HTTP.
 302
 303 `Akraino Blueprint Validation`_ integration will later offer a complete e2e
 304 (end to end) validation of the Kubernetes installation by running the complete
 305 e2e test suite of `Sonobuoy`_ diagnostics suite.
 306 Meanwhile, `Sonobuoy`_ can be used manually by following the instructions in
 307 its README file.
 308
 309 OpenStack Verification
 310 ======================
 311
 312 N/A
 313
 314 Developer Guide and Troubleshooting
 315 ===================================
 316
 317 Utilization of Images
 318 ---------------------
 319
 320 N/A
 321
 322 Post-deployment Configuration
 323 -----------------------------
 324
 325 N/A
 326
 327 OpenDaylight Integration
 328 ------------------------
 329
 330 N/A
 331
 332 Debugging Failures
 333 ------------------
 334
 335 N/A
 336
 337 Reporting a Bug
 338 ---------------
 339
 340 All issues should be reported via `IEC JIRA`_ page.
 341 When submitting reports, please provide as much relevant information as possible, e.g.:
 342
 343 - output logs;
 344 - IEC git repository commit used;
 345 - jumpserver info (operating system, versions of involved software components et al.);
 346 - command history (when relevant);
 347
 348 Uninstall Guide
 349 ===============
 350
 351 N/A
 352
 353 Troubleshooting
 354 ===============
 355
 356 Error Message Guide
 357 -------------------
 358
 359 N/A
 360
 361 Maintenance
 362 ===========
 363
 364 N/A
 365
 366 Frequently Asked Questions
 367 ==========================
 368
 369 N/A
 370
 371 License
 372 =======
 373
 374 `Apache License 2.0`_:
 375
 376 | Any software developed by the "Akraino IEC" Project is licenced under the
 377 | Apache License, Version 2.0 (the "License");
 378 | you may not use the content of this software bundle except in compliance with the License.
 379 | You may obtain a copy of the License at <https://www.apache.org/licenses/LICENSE-2.0>
 380 |
 381 | Unless required by applicable law or agreed to in writing, software
 382 | distributed under the License is distributed on an "AS IS" BASIS,
 383 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 384 | See the License for the specific language governing permissions and
 385 | limitations under the License.
 386
 387 References
 388 ==========
 389
 390 For more information on the Akraino Release 1, please see:
 391
 392 #. `Akraino Home Page`_
 393 #. `IEC Wiki`_
 394
 395 Definitions, acronyms and abbreviations
 396 =======================================
 397
 398 N/A
 399
 400 .. All links go below this line
 401 .. _`Apache License 2.0`: https://www.apache.org/licenses/LICENSE-2.0
 402 .. _`Akraino Home Page`: https://wiki.akraino.org/pages/viewpage.action?pageId=327703
 403 .. _`IEC Wiki`: https://wiki.akraino.org/display/AK/Integrated+Edge+Cloud+%28IEC%29+Blueprint+Family
 404 .. _`IEC JIRA`: https://jira.akraino.org/projects/IEC/issues/
 405 .. _`Akraino Blueprint Validation`: https://wiki.akraino.org/display/AK/Akraino+Blueprint+Validation+Framework
 406 .. _`Sonobuoy`: https://github.com/heptio/sonobuoy