Check the Manifest information after create
[iec.git] / 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