From 32bba0e639eaca254e18b5e4d36969f21f9e3d0e Mon Sep 17 00:00:00 2001 From: Cristina Pauna Date: Thu, 1 Feb 2018 15:30:01 +0200 Subject: [docs] Remove redundant information Armband and fuel documentation have been the same for E release. Instead of duplicating everyhting, make references to Fuel from armband docs. I removed the scenario folder as it should not have been here in the first place, otherwise the folder structure is kept as is. JIRA: ARMBAND-357 Change-Id: I060f22aee60713cabfd09ccf2fc0201e68a03c2a Signed-off-by: Cristina Pauna --- docs/release/installation/img/README.rst | 12 - docs/release/installation/img/arm_pod5.png | Bin 168862 -> 0 bytes docs/release/installation/img/fuel_baremetal.png | Bin 245916 -> 0 bytes docs/release/installation/img/fuel_virtual.png | Bin 216442 -> 0 bytes docs/release/installation/img/lf_pod2.png | Bin 167832 -> 0 bytes docs/release/installation/index.rst | 4 +- .../installation/installation.instruction.rst | 552 +-------------------- 7 files changed, 11 insertions(+), 557 deletions(-) delete mode 100644 docs/release/installation/img/README.rst delete mode 100644 docs/release/installation/img/arm_pod5.png delete mode 100644 docs/release/installation/img/fuel_baremetal.png delete mode 100644 docs/release/installation/img/fuel_virtual.png delete mode 100644 docs/release/installation/img/lf_pod2.png (limited to 'docs/release/installation') diff --git a/docs/release/installation/img/README.rst b/docs/release/installation/img/README.rst deleted file mode 100644 index bc8d9bed..00000000 --- a/docs/release/installation/img/README.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. SPDX-License-Identifier: CC-BY-4.0 -.. (c) 2017 Ericsson AB, Mirantis Inc., Enea AB and others. - -Image Editor -============ -All files in this directory have been created using `draw.io `_. - -Image Sources -============= -Image sources are embedded in each `png` file. -To edit an image, import the `png` file using `draw.io `_. diff --git a/docs/release/installation/img/arm_pod5.png b/docs/release/installation/img/arm_pod5.png deleted file mode 100644 index b35b661a..00000000 Binary files a/docs/release/installation/img/arm_pod5.png and /dev/null differ diff --git a/docs/release/installation/img/fuel_baremetal.png b/docs/release/installation/img/fuel_baremetal.png deleted file mode 100644 index aee42ac3..00000000 Binary files a/docs/release/installation/img/fuel_baremetal.png and /dev/null differ diff --git a/docs/release/installation/img/fuel_virtual.png b/docs/release/installation/img/fuel_virtual.png deleted file mode 100644 index d7664865..00000000 Binary files a/docs/release/installation/img/fuel_virtual.png and /dev/null differ diff --git a/docs/release/installation/img/lf_pod2.png b/docs/release/installation/img/lf_pod2.png deleted file mode 100644 index b6c9b8e3..00000000 Binary files a/docs/release/installation/img/lf_pod2.png and /dev/null differ diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst index 784eec25..93bbc408 100644 --- a/docs/release/installation/index.rst +++ b/docs/release/installation/index.rst @@ -1,10 +1,8 @@ -.. _fuel-installation: - .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. (c) Open Platform for NFV Project, Inc. and its contributors -.. _fuel-release-installation-label: +.. _armband-release-installation-label: **************************************** Installation instruction for Fuel\@OPNFV diff --git a/docs/release/installation/installation.instruction.rst b/docs/release/installation/installation.instruction.rst index cad1b107..52a5b35e 100644 --- a/docs/release/installation/installation.instruction.rst +++ b/docs/release/installation/installation.instruction.rst @@ -6,545 +6,13 @@ Abstract ======== -This document describes how to install the Euphrates release of -OPNFV when using Fuel as a deployment tool, covering its usage, -limitations, dependencies and required system resources. -This is an unified documentation for both x86_64 and aarch64 -architectures. All information is common for both architectures -except when explicitly stated. - -============ -Introduction -============ - -This document provides guidelines on how to install and -configure the Euphrates release of OPNFV when using Fuel as a -deployment tool, including required software and hardware configurations. - -Although the available installation options provide a high degree of -freedom in how the system is set up, including architecture, services -and features, etc., said permutations may not provide an OPNFV -compliant reference architecture. This document provides a -step-by-step guide that results in an OPNFV Euphrates compliant -deployment. - -The audience of this document is assumed to have good knowledge of -networking and Unix/Linux administration. - -======= -Preface -======= - -Before starting the installation of the Euphrates release of -OPNFV, using Fuel as a deployment tool, some planning must be -done. - -Preparations -============ - -Prior to installation, a number of deployment specific parameters must be collected, those are: - -#. Provider sub-net and gateway information - -#. Provider VLAN information - -#. Provider DNS addresses - -#. Provider NTP addresses - -#. Network overlay you plan to deploy (VLAN, VXLAN, FLAT) - -#. How many nodes and what roles you want to deploy (Controllers, Storage, Computes) - -#. Monitoring options you want to deploy (Ceilometer, Syslog, etc.). - -#. Other options not covered in the document are available in the links above - - -This information will be needed for the configuration procedures -provided in this document. - -========================================= -Hardware Requirements for Virtual Deploys -========================================= - -The following minimum hardware requirements must be met for the virtual -installation of Euphrates using Fuel: - -+----------------------------+--------------------------------------------------------+ -| **HW Aspect** | **Requirement** | -| | | -+============================+========================================================+ -| **1 Jumpserver** | A physical node (also called Foundation Node) that | -| | will host a Salt Master VM and each of the VM nodes in | -| | the virtual deploy | -+----------------------------+--------------------------------------------------------+ -| **CPU** | Minimum 1 socket with Virtualization support | -+----------------------------+--------------------------------------------------------+ -| **RAM** | Minimum 32GB/server (Depending on VNF work load) | -+----------------------------+--------------------------------------------------------+ -| **Disk** | Minimum 100GB (SSD or SCSI (15krpm) highly recommended | -+----------------------------+--------------------------------------------------------+ - - -=========================================== -Hardware Requirements for Baremetal Deploys -=========================================== - -The following minimum hardware requirements must be met for the baremetal -installation of Euphrates using Fuel: - -+-------------------------+------------------------------------------------------+ -| **HW Aspect** | **Requirement** | -| | | -+=========================+======================================================+ -| **# of nodes** | Minimum 5 | -| | | -| | - 3 KVM servers which will run all the controller | -| | services | -| | | -| | - 2 Compute nodes | -| | | -+-------------------------+------------------------------------------------------+ -| **CPU** | Minimum 1 socket with Virtualization support | -+-------------------------+------------------------------------------------------+ -| **RAM** | Minimum 16GB/server (Depending on VNF work load) | -+-------------------------+------------------------------------------------------+ -| **Disk** | Minimum 256GB 10kRPM spinning disks | -+-------------------------+------------------------------------------------------+ -| **Networks** | 4 VLANs (PUBLIC, MGMT, STORAGE, PRIVATE) - can be | -| | a mix of tagged/native | -| | | -| | 1 Un-Tagged VLAN for PXE Boot - ADMIN Network | -| | | -| | Note: These can be allocated to a single NIC - | -| | or spread out over multiple NICs | -+-------------------------+------------------------------------------------------+ -| **1 Jumpserver** | A physical node (also called Foundation Node) that | -| | hosts the Salt Master and MaaS VMs | -+-------------------------+------------------------------------------------------+ -| **Power management** | All targets need to have power management tools that | -| | allow rebooting the hardware and setting the boot | -| | order (e.g. IPMI) | -+-------------------------+------------------------------------------------------+ - -**NOTE:** All nodes including the Jumpserver must have the same architecture (either x86_64 or aarch64). - -**NOTE:** For aarch64 deployments an UEFI compatible firmware with PXE support is needed (e.g. EDK2). - -=============================== -Help with Hardware Requirements -=============================== - -Calculate hardware requirements: - -For information on compatible hardware types available for use, -please see `Fuel OpenStack Hardware Compatibility List `_ - -When choosing the hardware on which you will deploy your OpenStack -environment, you should think about: - -- CPU -- Consider the number of virtual machines that you plan to deploy in your cloud environment and the CPUs per virtual machine. - -- Memory -- Depends on the amount of RAM assigned per virtual machine and the controller node. - -- Storage -- Depends on the local drive space per virtual machine, remote volumes that can be attached to a virtual machine, and object storage. - -- Networking -- Depends on the Choose Network Topology, the network bandwidth per virtual machine, and network storage. - -================================================ -Top of the Rack (TOR) Configuration Requirements -================================================ - -The switching infrastructure provides connectivity for the OPNFV -infrastructure operations, tenant networks (East/West) and provider -connectivity (North/South); it also provides needed connectivity for -the Storage Area Network (SAN). -To avoid traffic congestion, it is strongly suggested that three -physically separated networks are used, that is: 1 physical network -for administration and control, one physical network for tenant private -and public networks, and one physical network for SAN. -The switching connectivity can (but does not need to) be fully redundant, -in such case it comprises a redundant 10GE switch pair for each of the -three physically separated networks. - -The physical TOR switches are **not** automatically configured from -the Fuel OPNFV reference platform. All the networks involved in the OPNFV -infrastructure as well as the provider networks and the private tenant -VLANs needs to be manually configured. - -Manual configuration of the Euphrates hardware platform should -be carried out according to the `OPNFV Pharos Specification -`_. - -============================ -OPNFV Software Prerequisites -============================ - -The Jumpserver node should be pre-provisioned with an operating system, -according to the Pharos specification. Relevant network bridges should -also be pre-configured (e.g. admin_br, mgmt_br, public_br). - - - The admin bridge (admin_br) is mandatory for the baremetal nodes PXE booting during fuel installation. - - The management bridge (mgmt_br) is required for testing suites (e.g. functest/yardstick), it is - suggested to pre-configure it for debugging purposes. - - The public bridge (public_br) is also nice to have for debugging purposes, but not mandatory. - -The user running the deploy script on the Jumpserver should belong to "sudo" and "libvirt" groups, -and have passwordless sudo access. - -The following example adds the groups to the user "jenkins" - -.. code-block:: bash - - $ sudo usermod -aG sudo jenkins - $ sudo usermod -aG libvirt jenkins - $ reboot - $ groups - jenkins sudo libvirt - - $ sudo visudo - ... - %jenkins ALL=(ALL) NOPASSWD:ALL - -For an AArch64 Jumpserver, the "libvirt" minimum required version is 3.x, 3.5 or newer highly recommended. -While not mandatory, upgrading the kernel and QEMU on the Jumpserver is also highly recommended -(especially on AArch64 Jumpservers). - -For CentOS 7.4 (AArch64), distro provided packages are already new enough. -For Ubuntu 16.04 (arm64), distro packages are too old and 3rd party repositories should be used. -For convenience, Armband provides a DEB repository holding all the required packages. - -To add and enable the Armband repository on an Ubuntu 16.04 system, -create a new sources list file `/apt/sources.list.d/armband.list` with the following contents: - -.. code-block:: bash - - $ cat /etc/apt/sources.list.d/armband.list - //for OpenStack Pike release - deb http://linux.enea.com/mcp-repos/pike/xenial pike-armband main - - $ apt-get update - -Fuel@OPNFV has been validated by CI using the following distributions -installed on the Jumpserver: - - - CentOS 7 (recommended by Pharos specification); - - Ubuntu Xenial; - -**NOTE**: The install script expects 'libvirt' to be already running on the Jumpserver.In case libvirt -packages are missing, the script will install them; but depending on the OS distribution, the user -might have to start the 'libvirtd' service manually, then run the deploy script again. Therefore, it -is recommened to install libvirt-bin explicitly on the Jumpserver before the deployment. - -**NOTE**: It is also recommened to install the newer kernel on the Jumpserver before the deployment. - -**NOTE**: The install script will automatically install the rest of required distro package -dependencies on the Jumpserver, unless explicitly asked not to (via -P deploy arg). This includes -Python, QEMU, libvirt etc. - -.. code-block:: bash - - $ apt-get install linux-image-generic-hwe-16.04-edge libvirt-bin - - -========================================== -OPNFV Software Installation and Deployment -========================================== - -This section describes the process of installing all the components needed to -deploy the full OPNFV reference platform stack across a server cluster. - -The installation is done with Mirantis Cloud Platform (MCP), which is based on -a reclass model. This model provides the formula inputs to Salt, to make the deploy -automatic based on deployment scenario. -The reclass model covers: - - - Infrastucture node definition: Salt Master node (cfg01) and MaaS node (mas01) - - OpenStack node definition: Controller nodes (ctl01, ctl02, ctl03) and Compute nodes (cmp001, cmp002) - - Infrastructure components to install (software packages, services etc.) - - OpenStack components and services (rabbitmq, galera etc.), as well as all configuration for them - - -Automatic Installation of a Virtual POD -======================================= - -For virtual deploys all the targets are VMs on the Jumpserver. The deploy script will: - - - Create a Salt Master VM on the Jumpserver which will drive the installation - - Create the bridges for networking with virsh (only if a real bridge does not already exist for a given network) - - Install OpenStack on the targets - - Leverage Salt to install & configure OpenStack services - -.. figure:: img/fuel_virtual.png - :align: center - :alt: Fuel@OPNFV Virtual POD Network Layout Examples - - Fuel@OPNFV Virtual POD Network Layout Examples - - +-----------------------+------------------------------------------------------------------------+ - | cfg01 | Salt Master VM | - +-----------------------+------------------------------------------------------------------------+ - | ctl01 | Controller VM | - +-----------------------+------------------------------------------------------------------------+ - | cmp01/cmp02 | Compute VMs | - +-----------------------+------------------------------------------------------------------------+ - | gtw01 | Gateway VM with neutron services (dhcp agent, L3 agent, metadata, etc) | - +-----------------------+------------------------------------------------------------------------+ - | odl01 | VM on which ODL runs (for scenarios deployed with ODL) | - +-----------------------+------------------------------------------------------------------------+ - - -In this figure there are examples of two virtual deploys: - - Jumphost 1 has only virsh bridges, created by the deploy script - - Jumphost 2 has a mix of Linux and virsh bridges; When Linux bridge exists for a specified network, - the deploy script will skip creating a virsh bridge for it - -**Note**: A virtual network "mcpcontrol" is always created. For virtual deploys, "mcpcontrol" is also - used for Admin, leaving the PXE/Admin bridge unused. - - -Automatic Installation of a Baremetal POD -========================================= - -The baremetal installation process can be done by editing the information about -hardware and environment in the reclass files, or by using a Pod Descriptor File (PDF). -This file contains all the information about the hardware and network of the deployment -the will be fed to the reclass model during deployment. - -The installation is done automatically with the deploy script, which will: - - - Create a Salt Master VM on the Jumpserver which will drive the installation - - Create a MaaS Node VM on the Jumpserver which will provision the targets - - Install OpenStack on the targets - - Leverage MaaS to provision baremetal nodes with the operating system - - Leverage Salt to configure the operating system on the baremetal nodes - - Leverage Salt to install & configure OpenStack services - -.. figure:: img/fuel_baremetal.png - :align: center - :alt: Fuel@OPNFV Baremetal POD Network Layout Example - - Fuel@OPNFV Baremetal POD Network Layout Example - - +-----------------------+---------------------------------------------------------+ - | cfg01 | Salt Master VM | - +-----------------------+---------------------------------------------------------+ - | mas01 | MaaS Node VM | - +-----------------------+---------------------------------------------------------+ - | kvm01..03 | Baremetals which hold the VMs with controller functions | - +-----------------------+---------------------------------------------------------+ - | cmp001/cmp002 | Baremetal compute nodes | - +-----------------------+---------------------------------------------------------+ - | prx01/prx02 | Proxy VMs for Nginx | - +-----------------------+---------------------------------------------------------+ - | msg01..03 | RabbitMQ Service VMs | - +-----------------------+---------------------------------------------------------+ - | dbs01..03 | MySQL service VMs | - +-----------------------+---------------------------------------------------------+ - | mdb01..03 | Telemetry VMs | - +-----------------------+---------------------------------------------------------+ - | odl01 | VM on which ODL runs (for scenarios deployed with ODL) | - +-----------------------+---------------------------------------------------------+ - | Tenant VM | VM running in the cloud | - +-----------------------+---------------------------------------------------------+ - -In the baremetal deploy all bridges but "mcpcontrol" are Linux bridges. For the Jumpserver, it is -required to pre-configure at least the admin_br bridge for the PXE/Admin. -For the targets, the bridges are created by the deploy script. - -**Note**: A virtual network "mcpcontrol" is always created. For baremetal deploys, PXE bridge is used -for baremetal node provisioning, while "mcpcontrol" is used to provision the infrastructure VMs only. - - -Steps to Start the Automatic Deploy -=================================== - -These steps are common both for virtual and baremetal deploys. - -#. Clone the Fuel code from gerrit - - For x86_64 - - .. code-block:: bash - - $ git clone https://git.opnfv.org/fuel - $ cd fuel - - For aarch64 - - .. code-block:: bash - - $ git clone https://git.opnfv.org/armband - $ cd armband - -#. Checkout the Euphrates release - - .. code-block:: bash - - $ git checkout opnfv-5.0.2 - -#. Start the deploy script - - Besides the basic options, there are other recommended deploy arguments: - - - use **-D** option to enable the debug info - - use **-S** option to point to a tmp dir where the disk images are saved. The images will be - re-used between deploys - - use **|& tee** to save the deploy log to a file - - .. code-block:: bash - - $ ci/deploy.sh -l \ - -p \ - -b \ - -s \ - -B \ - -D \ - -S |& tee deploy.log - -Examples --------- -#. Virtual deploy - - To start a virtual deployment, it is required to have the `virtual` keyword - while specifying the pod name to the installer script. - - It will create the required bridges and networks, configure Salt Master and - install OpenStack. - - .. code-block:: bash - - $ ci/deploy.sh -b file:///home/jenkins/tmpdir/securedlab \ - -l ericsson \ - -p virtual_kvm \ - -s os-nosdn-nofeature-noha \ - -D \ - -S /home/jenkins/tmpdir |& tee deploy.log - - Once the deployment is complete, the OpenStack Dashboard, Horizon is - available at http://:8078, e.g. http://10.16.0.101:8078. - The administrator credentials are **admin** / **opnfv_secret**. - -#. Baremetal deploy - - A x86 deploy on pod2 from Linux Foundation lab - - .. code-block:: bash - - $ ci/deploy.sh -b file:///home/jenkins/tmpdir/securedlab \ - -l lf \ - -p pod2 \ - -s os-nosdn-nofeature-ha \ - -B pxebr,br-ctl - -D \ - -S /home/jenkins/tmpdir |& tee deploy.log - - .. figure:: img/lf_pod2.png - :align: center - :alt: Fuel@OPNFV LF POD2 Network Layout - - Fuel@OPNFV LF POD2 Network Layout - - Once the deployment is complete, the SaltStack Deployment Documentation is - available at http://:8090, e.g. http://172.30.10.103:8090. - - An aarch64 deploy on pod5 from Arm lab - - .. code-block:: bash - - $ ci/deploy.sh -b file:///home/jenkins/tmpdir/securedlab \ - -l arm \ - -p pod5 \ - -s os-nosdn-nofeature-ha \ - -D \ - -S /home/jenkins/tmpdir |& tee deploy.log - - .. figure:: img/arm_pod5.png - :align: center - :alt: Fuel@OPNFV ARM POD5 Network Layout - - Fuel@OPNFV ARM POD5 Network Layout - -Pod Descriptor Files -==================== - -Descriptor files provide the installer with an abstraction of the target pod -with all its hardware characteristics and required parameters. This information -is split into two different files: -Pod Descriptor File (PDF) and Installer Descriptor File (IDF). - - -The Pod Descriptor File is a hardware and network description of the pod -infrastructure. The information is modeled under a yaml structure. -A reference file with the expected yaml structure is available at -*mcp/config/labs/local/pod1.yaml* - -A common network section describes all the internal and provider networks -assigned to the pod. Each network is expected to have a vlan tag, IP subnet and -attached interface on the boards. Untagged vlans shall be defined as "native". - -The hardware description is arranged into a main "jumphost" node and a "nodes" -set for all target boards. For each node the following characteristics -are defined: - -- Node parameters including CPU features and total memory. -- A list of available disks. -- Remote management parameters. -- Network interfaces list including mac address, speed and advanced features. -- IP list of fixed IPs for the node - -**Note**: the fixed IPs are ignored by the MCP installer script and it will instead -assign based on the network ranges defined under the pod network configuration. - - -The Installer Descriptor File extends the PDF with pod related parameters -required by the installer. This information may differ per each installer type -and it is not considered part of the pod infrastructure. Fuel installer relies -on the IDF model to map the networks to the bridges on the foundation node and -to setup all node NICs by defining the expected OS device name and bus address. - - -The file follows a yaml structure and a "fuel" section is expected. Contents and -references must be aligned with the PDF file. The IDF file must be named after -the PDF with the prefix "idf-". A reference file with the expected structure -is available at *mcp/config/labs/local/idf-pod1.yaml* - - -============= -Release Notes -============= - -Please refer to the :ref:`Release Notes ` article. - -========== -References -========== - -OPNFV - -1) `OPNFV Home Page `_ -2) `OPNFV documentation `_ -3) `Software downloads `_ - -OpenStack - -4) `OpenStack Ocata Release Artifacts `_ -5) `OpenStack Documentation `_ - -OpenDaylight - -6) `OpenDaylight Artifacts `_ - -Fuel - -7) `Mirantis Cloud Platform Documentation `_ - -Salt - -8) `Saltstack Documentation `_ -9) `Saltstack Formulas `_ - -Reclass - -10) `Reclass model `_ +Armband project aims to integrate and test all aspects of OPNFV releases +on ARM-based servers. The goal is to replicate all OPNFV software build, +continuous integration, lab provisioning, and testing processes of each +standard release OPNFV, such that the release can be available on both +Intel Architecture-based and ARM Architecture-based servers. + +The armband repo contains the patches necessary for Fuel installer to run on +aarch64 hardware. For more information on how to install the Euphrates release +of OPNFV when using Fuel as a deployment tool check +:ref:`fuel-release-installation-label` -- cgit 1.2.3-korg