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) Open Platform for NFV Project, Inc. and its contributors
   4
   5 ========
   6 Abstract
   7 ========
   8
   9 This document describes how to install the Euphrates release of
  10 OPNFV when using Fuel as a deployment tool, covering its usage,
  11 limitations, dependencies and required system resources.
  12 This is an unified documentation for both x86_64 and aarch64
  13 architectures. All information is common for both architectures
  14 except when explicitly stated.
  15
  16 ============
  17 Introduction
  18 ============
  19
  20 This document provides guidelines on how to install and
  21 configure the Euphrates release of OPNFV when using Fuel as a
  22 deployment tool, including required software and hardware configurations.
  23
  24 Although the available installation options provide a high degree of
  25 freedom in how the system is set up, including architecture, services
  26 and features, etc., said permutations may not provide an OPNFV
  27 compliant reference architecture. This document provides a
  28 step-by-step guide that results in an OPNFV Euphrates compliant
  29 deployment.
  30
  31 The audience of this document is assumed to have good knowledge of
  32 networking and Unix/Linux administration.
  33
  34 =======
  35 Preface
  36 =======
  37
  38 Before starting the installation of the Euphrates release of
  39 OPNFV, using Fuel as a deployment tool, some planning must be
  40 done.
  41
  42 Preparations
  43 ============
  44
  45 Prior to installation, a number of deployment specific parameters must be collected, those are:
  46
  47 #.     Provider sub-net and gateway information
  48
  49 #.     Provider VLAN information
  50
  51 #.     Provider DNS addresses
  52
  53 #.     Provider NTP addresses
  54
  55 #.     Network overlay you plan to deploy (VLAN, VXLAN, FLAT)
  56
  57 #.     How many nodes and what roles you want to deploy (Controllers, Storage, Computes)
  58
  59 #.     Monitoring options you want to deploy (Ceilometer, Syslog, etc.).
  60
  61 #.     Other options not covered in the document are available in the links above
  62
  63
  64 This information will be needed for the configuration procedures
  65 provided in this document.
  66
  67 =========================================
  68 Hardware Requirements for Virtual Deploys
  69 =========================================
  70
  71 The following minimum hardware requirements must be met for the virtual
  72 installation of Euphrates using Fuel:
  73
  74 +----------------------------+--------------------------------------------------------+
  75 | **HW Aspect**              | **Requirement**                                        |
  76 |                            |                                                        |
  77 +============================+========================================================+
  78 | **1 Jumpserver**           | A physical node (also called Foundation Node) that     |
  79 |                            | will host a Salt Master VM and each of the VM nodes in |
  80 |                            | the virtual deploy                                     |
  81 +----------------------------+--------------------------------------------------------+
  82 | **CPU**                    | Minimum 1 socket with Virtualization support           |
  83 +----------------------------+--------------------------------------------------------+
  84 | **RAM**                    | Minimum 32GB/server (Depending on VNF work load)       |
  85 +----------------------------+--------------------------------------------------------+
  86 | **Disk**                   | Minimum 100GB (SSD or SCSI (15krpm) highly recommended |
  87 +----------------------------+--------------------------------------------------------+
  88
  89
  90 ===========================================
  91 Hardware Requirements for Baremetal Deploys
  92 ===========================================
  93
  94 The following minimum hardware requirements must be met for the baremetal
  95 installation of Euphrates using Fuel:
  96
  97 +-------------------------+------------------------------------------------------+
  98 | **HW Aspect**           | **Requirement**                                      |
  99 |                         |                                                      |
 100 +=========================+======================================================+
 101 | **# of nodes**          | Minimum 5                                            |
 102 |                         |                                                      |
 103 |                         | - 3 KVM servers which will run all the controller    |
 104 |                         |   services                                           |
 105 |                         |                                                      |
 106 |                         | - 2 Compute nodes                                    |
 107 |                         |                                                      |
 108 +-------------------------+------------------------------------------------------+
 109 | **CPU**                 | Minimum 1 socket with Virtualization support         |
 110 +-------------------------+------------------------------------------------------+
 111 | **RAM**                 | Minimum 16GB/server (Depending on VNF work load)     |
 112 +-------------------------+------------------------------------------------------+
 113 | **Disk**                | Minimum 256GB 10kRPM spinning disks                  |
 114 +-------------------------+------------------------------------------------------+
 115 | **Networks**            | 4 VLANs (PUBLIC, MGMT, STORAGE, PRIVATE) - can be    |
 116 |                         | a mix of tagged/native                               |
 117 |                         |                                                      |
 118 |                         | 1 Un-Tagged VLAN for PXE Boot - ADMIN Network        |
 119 |                         |                                                      |
 120 |                         | Note: These can be allocated to a single NIC -       |
 121 |                         | or spread out over multiple NICs                     |
 122 +-------------------------+------------------------------------------------------+
 123 | **1 Jumpserver**        | A physical node (also called Foundation Node) that   |
 124 |                         | hosts the Salt Master and MaaS VMs                   |
 125 +-------------------------+------------------------------------------------------+
 126 | **Power management**    | All targets need to have power management tools that |
 127 |                         | allow rebooting the hardware and setting the boot    |
 128 |                         | order (e.g. IPMI)                                    |
 129 +-------------------------+------------------------------------------------------+
 130
 131 **NOTE:** All nodes including the Jumpserver must have the same architecture (either x86_64 or aarch64).
 132
 133 **NOTE:** For aarch64 deployments an UEFI compatible firmware with PXE support is needed (e.g. EDK2).
 134
 135
 136 ===============================
 137 Help with Hardware Requirements
 138 ===============================
 139
 140 Calculate hardware requirements:
 141
 142 For information on compatible hardware types available for use, please see `Fuel OpenStack Hardware Compatibility List <https://www.mirantis.com/software/hardware-compatibility/>`_.
 143
 144 When choosing the hardware on which you will deploy your OpenStack
 145 environment, you should think about:
 146
 147 - CPU -- Consider the number of virtual machines that you plan to deploy in your cloud environment and the CPUs per virtual machine.
 148
 149 - Memory -- Depends on the amount of RAM assigned per virtual machine and the controller node.
 150
 151 - Storage -- Depends on the local drive space per virtual machine, remote volumes that can be attached to a virtual machine, and object storage.
 152
 153 - Networking -- Depends on the Choose Network Topology, the network bandwidth per virtual machine, and network storage.
 154
 155 ================================================
 156 Top of the Rack (TOR) Configuration Requirements
 157 ================================================
 158
 159 The switching infrastructure provides connectivity for the OPNFV
 160 infrastructure operations, tenant networks (East/West) and provider
 161 connectivity (North/South); it also provides needed connectivity for
 162 the Storage Area Network (SAN).
 163 To avoid traffic congestion, it is strongly suggested that three
 164 physically separated networks are used, that is: 1 physical network
 165 for administration and control, one physical network for tenant private
 166 and public networks, and one physical network for SAN.
 167 The switching connectivity can (but does not need to) be fully redundant,
 168 in such case it comprises a redundant 10GE switch pair for each of the
 169 three physically separated networks.
 170
 171 The physical TOR switches are **not** automatically configured from
 172 the Fuel OPNFV reference platform. All the networks involved in the OPNFV
 173 infrastructure as well as the provider networks and the private tenant
 174 VLANs needs to be manually configured.
 175
 176 Manual configuration of the Euphrates hardware platform should
 177 be carried out according to the `OPNFV Pharos Specification
 178 <https://wiki.opnfv.org/display/pharos/Pharos+Specification>`_.
 179
 180 ============================
 181 OPNFV Software Prerequisites
 182 ============================
 183
 184 The Jumpserver node should be pre-provisioned with an operating system,
 185 according to the Pharos specification. Relevant network bridges should
 186 also be pre-configured (e.g. admin, management, public).
 187
 188 Fuel@OPNFV has been validated by CI using the following distributions
 189 installed on the Jumpserver:
 190
 191    - CentOS 7 (recommended by Pharos specification);
 192    - Ubuntu Xenial;
 193
 194 ==========================================
 195 OPNFV Software Installation and Deployment
 196 ==========================================
 197
 198 This section describes the process of installing all the components needed to
 199 deploy the full OPNFV reference platform stack across a server cluster.
 200
 201 The installation is done with Mirantis Cloud Platform (MCP), which is based on
 202 a reclass model. This model provides the formula inputs to Salt, to make the deploy
 203 automatic based on deployment scenario.
 204 The reclass model covers:
 205
 206    - Infrastucture node definition: Salt Master node (cfg01) and MaaS node (mas01)
 207    - Openstack node defition: Controler nodes (ctl01, ctl02, ctl03) and Compute nodes (cmp001, cmp002)
 208    - Infrastructure components to install (software packages, services etc.)
 209    - Openstack components and services (rabbitmq, galera etc.), as well as all configuration for them
 210
 211
 212 Automatic Installation of a Virtual POD
 213 =======================================
 214
 215 For virtual deploys all the targets are VMs on the Jumpserver. The deploy script will:
 216
 217    - Create a Salt Master VM on the Jumpserver which will drive the installation
 218    - Create the bridges for networking with virsh (only if a real bridge does not already exists for a given network)
 219    - Install Openstack on the targets
 220       - Leverage Salt to install & configure Openstack services
 221
 222 .. figure:: img/fuel_virtual.png
 223    :align: center
 224    :alt: Fuel@OPNFV Virtual POD Network Layout Examples
 225
 226    Fuel@OPNFV Virtual POD Network Layout Examples
 227
 228
 229 Automatic Installation of a Baremetal POD
 230 =========================================
 231
 232 The baremetal installation process can be done by editing the information about
 233 hardware and enviroment in the reclass files, or by using a Pod Descriptor File (PDF).
 234 This file contains all the information about the hardware and network of the deployment
 235 the will be fed to the reclass model during deployment.
 236
 237 The installation is done automatically with the deploy script, which will:
 238
 239    - Create a Salt Master VM on the Jumpserver which will drive the installation
 240    - Create a MaaS Node VM on the Jumpserver which will provision the targets
 241    - Install Openstack on the targets
 242       - Leverage MaaS to provision baremetal nodes with the operating system
 243       - Leverage Salt to configure the operatign system on the baremetal nodes
 244       - Leverage Salt to install & configure Openstack services
 245
 246 .. figure:: img/fuel_baremetal.png
 247    :align: center
 248    :alt: Fuel@OPNFV Baremetal POD Network Layout Example
 249
 250    Fuel@OPNFV Baremetal POD Network Layout Example
 251
 252
 253 Steps to Start the Automatic Deploy
 254 ===================================
 255
 256 These steps are common both for virtual and baremetal deploys.
 257
 258 #. Clone the Fuel code from gerrit
 259
 260    For x86_64
 261
 262    .. code-block:: bash
 263
 264        $ git clone https://git.opnfv.org/fuel
 265        $ cd fuel
 266
 267    For aarch64
 268
 269    .. code-block:: bash
 270
 271        $ git clone https://git.opnfv.org/armband
 272        $ cd armband
 273
 274 #. Checkout the Euphrates release
 275
 276    .. code-block:: bash
 277
 278        $ git checkout opnfv-5.0.2
 279
 280 #. Start the deploy script
 281
 282    .. code-block:: bash
 283
 284        $ ci/deploy.sh -l <lab_name> \
 285                       -p <pod_name> \
 286                       -b <URI to configuration repo containing the PDF file> \
 287                       -s <scenario> \
 288                       -B <list of admin, management, private and public bridges>
 289
 290 Examples
 291 --------
 292 #. Virtual deploy
 293
 294    To start a virtual deployment, it is required to have the `virtual` keyword
 295    while specifying the pod name to the installer script.
 296
 297    It will create the required bridges and networks, configure Salt Master and
 298    install OpenStack.
 299
 300       .. code-block:: bash
 301
 302          $ ci/deploy.sh -b file:///home/jenkins/tmpdir/securedlab \
 303                         -l ericsson \
 304                         -p virtual_kvm \
 305                         -s os-nosdn-nofeature-noha
 306
 307    Once the deployment is complete, the OpenStack Dashboard, Horizon is
 308    available at http://<controller VIP>:8078, e.g. http://10.16.0.101:8078.
 309    The administrator credentials are **admin** / **opnfv_secret**.
 310
 311 #. Baremetal deploy
 312
 313    A x86 deploy on pod2 from Linux Foundation lab
 314
 315       .. code-block:: bash
 316
 317           $ ci/deploy.sh -b file:///home/jenkins/tmpdir/securedlab \
 318                          -l lf \
 319                          -p pod2 \
 320                          -s os-nosdn-nofeature-ha \
 321                          -B pxebr,br-ctl
 322
 323       .. figure:: img/lf_pod2.png
 324          :align: center
 325          :alt: Fuel@OPNFV LF POD2 Network Layout
 326
 327          Fuel@OPNFV LF POD2 Network Layout
 328
 329    An aarch64 deploy on pod5 from Arm lab
 330
 331       .. code-block:: bash
 332
 333          $ ci/deploy.sh -b file:///home/jenkins/tmpdir/securedlab \
 334                         -l arm \
 335                         -p pod5 \
 336                         -s os-nosdn-nofeature-ha \
 337                         -B admin7_br0,mgmt7_br0,,public7_br0
 338
 339       .. figure:: img/arm_pod5.png
 340          :align: center
 341          :alt: Fuel@OPNFV ARM POD5 Network Layout
 342
 343          Fuel@OPNFV ARM POD5 Network Layout
 344
 345
 346 =============
 347 Release Notes
 348 =============
 349
 350 Please refer to the :ref:`Release Notes <fuel-release-notes-label>` article.
 351
 352 ==========
 353 References
 354 ==========
 355
 356 OPNFV
 357
 358 1) `OPNFV Home Page <http://www.opnfv.org>`_
 359 2) `OPNFV documentation <http://docs.opnfv.org>`_
 360 3) `Software downloads <https://www.opnfv.org/software/download>`_
 361
 362 OpenStack
 363
 364 4) `OpenStack Ocata Release Artifacts <http://www.openstack.org/software/ocata>`_
 365 5) `OpenStack Documentation <http://docs.openstack.org>`_
 366
 367 OpenDaylight
 368
 369 6) `OpenDaylight Artifacts <http://www.opendaylight.org/software/downloads>`_
 370
 371 Fuel
 372
 373 7) `Mirantis Cloud Platform Documentation <https://docs.mirantis.com/mcp/latest>`_
 374
 375 Salt
 376
 377 8) `Saltstack Documentation <https://docs.saltstack.com/en/latest/topics>`_
 378 9) `Saltstack Formulas <http://salt-formulas.readthedocs.io/en/latest/develop/overview-reclass.html>`_
 379
 380 Reclass
 381
 382 10) `Reclass model <http://reclass.pantsfullofunix.net>`_