docs/release/installation/baremetal.rst

   1 Installation High-Level Overview - Bare Metal Deployment
   2 ========================================================
   3
   4 The setup presumes that you have 6 or more bare metal servers already setup
   5 with network connectivity on at least 1 or more network interfaces for all
   6 servers via a TOR switch or other network implementation.
   7
   8 The physical TOR switches are **not** automatically configured from the OPNFV
   9 reference platform.  All the networks involved in the OPNFV infrastructure as
  10 well as the provider networks and the private tenant VLANs needs to be manually
  11 configured.
  12
  13 The Jump Host can be installed using the bootable ISO or by using the
  14 (``opnfv-apex*.rpm``) RPMs and their dependencies.  The Jump Host should then
  15 be configured with an IP gateway on its admin or public interface and
  16 configured with a working DNS server.  The Jump Host should also have routable
  17 access to the lights out network for the overcloud nodes.
  18
  19 ``opnfv-deploy`` is then executed in order to deploy the undercloud VM and to
  20 provision the overcloud nodes.  ``opnfv-deploy`` uses three configuration files
  21 in order to know how to install and provision the OPNFV target system.
  22 The information gathered under section
  23 `Execution Requirements (Bare Metal Only)`_ is put into the YAML file
  24 ``/etc/opnfv-apex/inventory.yaml`` configuration file.  Deployment options are
  25 put into the YAML file ``/etc/opnfv-apex/deploy_settings.yaml``.  Alternatively
  26 there are pre-baked deploy_settings files available in ``/etc/opnfv-apex/``.
  27 These files are named with the naming convention
  28 os-sdn_controller-enabled_feature-[no]ha.yaml. These files can be used in place
  29 of the ``/etc/opnfv-apex/deploy_settings.yaml`` file if one suites your
  30 deployment needs.  Networking definitions gathered under section
  31 `Network Requirements`_ are put into the YAML file
  32 ``/etc/opnfv-apex/network_settings.yaml``.  ``opnfv-deploy`` will boot the
  33 undercloud VM and load the target deployment configuration into the
  34 provisioning toolchain.  This information includes MAC address, IPMI,
  35 Networking Environment and OPNFV deployment options.
  36
  37 Once configuration is loaded and the undercloud is configured it will then
  38 reboot the overcloud nodes via IPMI.  The nodes should already be set to PXE
  39 boot first off the admin interface.  The nodes will first PXE off of the
  40 undercloud PXE server and go through a discovery/introspection process.
  41
  42 Introspection boots off of custom introspection PXE images. These images are
  43 designed to look at the properties of the hardware that is being booted
  44 and report the properties of it back to the undercloud node.
  45
  46 After introspection the undercloud will execute a Heat Stack Deployment to
  47 continue node provisioning and configuration.  The nodes will reboot and PXE
  48 from the undercloud PXE server again to provision each node using Glance disk
  49 images provided by the undercloud.  These disk images include all the necessary
  50 packages and configuration for an OPNFV deployment to execute.  Once the disk
  51 images have been written to node's disks the nodes will boot locally and
  52 execute cloud-init which will execute the final node configuration. This
  53 configuration is largely completed by executing a puppet apply on each node.
  54
  55 Installation Guide - Bare Metal Deployment
  56 ==========================================
  57
  58 This section goes step-by-step on how to correctly install and provision the
  59 OPNFV target system to bare metal nodes.
  60
  61 Install Bare Metal Jump Host
  62 ----------------------------
  63
  64 1a. If your Jump Host does not have CentOS 7 already on it, or you would like
  65     to do a fresh install, then download the Apex bootable ISO from the OPNFV
  66     artifacts site <http://artifacts.opnfv.org/apex.html>.  There have been
  67     isolated reports of problems with the ISO having trouble completing
  68     installation successfully. In the unexpected event the ISO does not work
  69     please workaround this by downloading the CentOS 7 DVD and performing a
  70     "Virtualization Host" install.  If you perform a "Minimal Install" or
  71     install type other than "Virtualization Host" simply run
  72     ``sudo yum -y groupinstall "Virtualization Host"``
  73     ``chkconfig libvirtd on && reboot``
  74     to install virtualization support and enable libvirt on boot. If you use
  75     the CentOS 7 DVD proceed to step 1b once the CentOS 7 with
  76     "Virtualization Host" support is completed.
  77
  78 1b. Boot the ISO off of a USB or other installation media and walk through
  79     installing OPNFV CentOS 7.  The ISO comes prepared to be written directly
  80     to a USB drive with dd as such:
  81
  82     ``dd if=opnfv-apex.iso of=/dev/sdX bs=4M``
  83
  84     Replace /dev/sdX with the device assigned to your usb drive. Then select
  85     the USB device as the boot media on your Jump Host
  86
  87 2a. When not using the OPNFV Apex ISO, install these repos:
  88
  89     ``sudo yum install https://repos.fedorapeople.org/repos/openstack/openstack-pike/rdo-release-pike-1.noarch.rpm``
  90     ``sudo yum install epel-release``
  91     ``sudo curl -o /etc/yum.repos.d/opnfv-apex.repo http://artifacts.opnfv.org/apex/euphrates/opnfv-apex.repo``
  92
  93     The RDO Project release repository is needed to install OpenVSwitch, which
  94     is a dependency of opnfv-apex. If you do not have external connectivity to
  95     use this repository you need to download the OpenVSwitch RPM from the RDO
  96     Project repositories and install it with the opnfv-apex RPM.  The
  97     opnfv-apex repo hosts all of the Apex dependencies which will automatically
  98     be installed when installing RPMs, but will be pre-installed with the ISO.
  99
 100 2b. If you chose not to use the Apex ISO, then you must download and install
 101     the Apex RPMs to the Jump Host. Download the first 3 Apex RPMs from the
 102     OPNFV downloads page, under the TripleO RPMs
 103     ``https://www.opnfv.org/software/downloads``.
 104     The following RPMs are available for installation:
 105
 106     - opnfv-apex                 - OpenDaylight, OVN, and nosdn support
 107     - opnfv-apex-undercloud      - (reqed) Undercloud Image
 108     - python34-opnfv-apex        - (reqed) OPNFV Apex Python package
 109     - python34-markupsafe        - (reqed) Dependency of python34-opnfv-apex **
 110     - python34-jinja2            - (reqed) Dependency of python34-opnfv-apex **
 111     - python3-ipmi               - (reqed) Dependency of python34-opnfv-apex **
 112     - python34-pbr               - (reqed) Dependency of python34-opnfv-apex **
 113     - python34-virtualbmc        - (reqed) Dependency of python34-opnfv-apex **
 114     - python34-iptables          - (reqed) Dependency of python34-opnfv-apex **
 115     - python34-cryptography      - (reqed) Dependency of python34-opnfv-apex **
 116     - python34-libvirt           - (reqed) Dependency of python34-opnfv-apex **
 117
 118     ** These RPMs are not yet distributed by CentOS or EPEL.
 119     Apex has built these for distribution with Apex while CentOS and EPEL do
 120     not distribute them. Once they are carried in an upstream channel Apex will
 121     no longer carry them and they will not need special handling for
 122     installation.  You do not need to explicitly install these as they will be
 123     automatically installed by installing python34-opnfv-apex when the
 124     opnfv-apex.repo has been previously downloaded to ``/etc/yum.repos.d/``.
 125
 126     Install the three required RPMs (replace <rpm> with the actual downloaded
 127     artifact):
 128     ``yum -y install <opnfv-apex.rpm> <opnfv-apex-undercloud> <python34-opnfv-apex>``
 129
 130 3.  After the operating system and the opnfv-apex RPMs are installed, login to
 131     your Jump Host as root.
 132
 133 4.  Configure IP addresses on the interfaces that you have selected as your
 134     networks.
 135
 136 5.  Configure the IP gateway to the Internet either, preferably on the public
 137     interface.
 138
 139 6.  Configure your ``/etc/resolv.conf`` to point to a DNS server
 140     (8.8.8.8 is provided by Google).
 141
 142 Creating a Node Inventory File
 143 ------------------------------
 144
 145 IPMI configuration information gathered in section
 146 `Execution Requirements (Bare Metal Only)`_ needs to be added to the
 147 ``inventory.yaml`` file.
 148
 149 1.  Copy ``/usr/share/doc/opnfv/inventory.yaml.example`` as your inventory file
 150     template to ``/etc/opnfv-apex/inventory.yaml``.
 151
 152 2.  The nodes dictionary contains a definition block for each baremetal host
 153     that will be deployed.  1 or more compute nodes and 3 controller nodes are
 154     required.  (The example file contains blocks for each of these already).
 155     It is optional at this point to add more compute nodes into the node list.
 156
 157 3.  Edit the following values for each node:
 158
 159     - ``mac_address``: MAC of the interface that will PXE boot from undercloud
 160     - ``ipmi_ip``: IPMI IP Address
 161     - ``ipmi_user``: IPMI username
 162     - ``ipmi_password``: IPMI password
 163     - ``pm_type``: Power Management driver to use for the node
 164         values: pxe_ipmitool (tested) or pxe_wol (untested) or pxe_amt (untested)
 165     - ``cpus``: (Introspected*) CPU cores available
 166     - ``memory``: (Introspected*) Memory available in Mib
 167     - ``disk``: (Introspected*) Disk space available in Gb
 168     - ``disk_device``: (Opt***) Root disk device to use for installation
 169     - ``arch``: (Introspected*) System architecture
 170     - ``capabilities``: (Opt**) Node's role in deployment
 171         values: profile:control or profile:compute
 172
 173     \* Introspection looks up the overcloud node's resources and overrides these
 174     value. You can leave default values and Apex will get the correct values when
 175     it runs introspection on the nodes.
 176
 177     ** If capabilities profile is not specified then Apex will select node's roles
 178     in the OPNFV cluster in a non-deterministic fashion.
 179
 180     \*** disk_device declares which hard disk to use as the root device for
 181     installation.  The format is a comma delimited list of devices, such as
 182     "sda,sdb,sdc".  The disk chosen will be the first device in the list which
 183     is found by introspection to exist on the system.  Currently, only a single
 184     definition is allowed for all nodes.  Therefore if multiple disk_device
 185     definitions occur within the inventory, only the last definition on a node
 186     will be used for all nodes.
 187
 188 Creating the Settings Files
 189 ---------------------------
 190
 191 Edit the 2 settings files in /etc/opnfv-apex/. These files have comments to
 192 help you customize them.
 193
 194 1. deploy_settings.yaml
 195    This file includes basic configuration options deployment, and also documents
 196    all available options.
 197    Alternatively, there are pre-built deploy_settings files available in
 198    (``/etc/opnfv-apex/``). These files are named with the naming convention
 199    os-sdn_controller-enabled_feature-[no]ha.yaml. These files can be used in
 200    place of the (``/etc/opnfv-apex/deploy_settings.yaml``) file if one suites
 201    your deployment needs. If a pre-built deploy_settings file is chosen there
 202    is no need to customize (``/etc/opnfv-apex/deploy_settings.yaml``). The
 203    pre-built file can be used in place of the
 204    (``/etc/opnfv-apex/deploy_settings.yaml``) file.
 205
 206 2. network_settings.yaml
 207    This file provides Apex with the networking information that satisfies the
 208    prerequisite `Network Requirements`_. These are specific to your
 209    environment.
 210
 211 Running ``opnfv-deploy``
 212 ------------------------
 213
 214 You are now ready to deploy OPNFV using Apex!
 215 ``opnfv-deploy`` will use the inventory and settings files to deploy OPNFV.
 216
 217 Follow the steps below to execute:
 218
 219 1.  Execute opnfv-deploy
 220     ``sudo opnfv-deploy -n network_settings.yaml
 221     -i inventory.yaml -d deploy_settings.yaml``
 222     If you need more information about the options that can be passed to
 223     opnfv-deploy use ``opnfv-deploy --help``.  -n
 224     network_settings.yaml allows you to customize your networking topology.
 225     Note it can also be useful to run the command with the ``--debug``
 226     argument which will enable a root login on the overcloud nodes with
 227     password: 'opnfvapex'.  It is also useful in some cases to surround the
 228     deploy command with ``nohup``.  For example:
 229     ``nohup <deploy command> &``, will allow a deployment to continue even if
 230     ssh access to the Jump Host is lost during deployment.
 231
 232 2.  Wait while deployment is executed.
 233     If something goes wrong during this part of the process, start by reviewing
 234     your network or the information in your configuration files. It's not
 235     uncommon for something small to be overlooked or mis-typed.
 236     You will also notice outputs in your shell as the deployment progresses.
 237
 238 3.  When the deployment is complete the undercloud IP and overcloud dashboard
 239     url will be printed. OPNFV has now been deployed using Apex.
 240
 241 .. _`Execution Requirements (Bare Metal Only)`: requirements.html#execution-requirements-bare-metal-only
 242 .. _`Network Requirements`: requirements.html#network-requirements