docs/release/installation/installation_baremetal.rst

   1 .. highlight:: bash
   2
   3
   4 Bare Metal Installation
   5 =======================
   6 Before proceeding, make sure that your hardware infrastructure satisfies the
   7 :ref:`setup-requirements`.
   8
   9
  10 Networking
  11 ----------
  12 Make sure you have at least two networks configured:
  13
  14 1.  *Admin* (management) network with gateway to access the Internet (for
  15     downloading installation resources).
  16 2.  A *public/floating* network to consume by tenants for floating IPs.
  17
  18 You may configure other networks, e.g. for data or storage, based on your
  19 network options for Openstack.
  20
  21
  22 .. _jumphost-install-os:
  23
  24 Jumphost installation and configuration
  25 ---------------------------------------
  26
  27 1.  Install Ubuntu 16.04 (Xenial) LTS server on Jumphost (one of the physical
  28     nodes).
  29
  30     .. tip::
  31         Use ``ubuntu`` as username as password, as this matches the MAAS
  32         credentials installed later.
  33
  34         During the OS installation, install the OpenSSH server package to
  35         allow SSH connections to the Jumphost.
  36
  37         If the data size of the image is too big or slow (e.g. when mounted
  38         through a slow virtual console), you can also use the Ubuntu mini ISO.
  39         Install packages: standard system utilities, basic Ubuntu server,
  40         OpenSSH server, Virtual Machine host.
  41
  42         If you have issues with blank console after booting, see
  43         `this SO answer <https://askubuntu.com/a/38782>`_ and set
  44         ``nomodeset``, (removing ``quiet splash`` can also be useful to see log
  45         during booting) either through console in recovery mode or via SSH (if
  46         installed).
  47
  48 2.  Install git and bridge-utils packages
  49
  50     ::
  51
  52        sudo apt install git bridge-utils
  53
  54 3.  Configure bridges for each network to be used.
  55
  56     Example ``/etc/network/interfaces`` file:
  57
  58     ::
  59
  60         source /etc/network/interfaces.d/*
  61
  62         # The loopback network interface (set by Ubuntu)
  63         auto lo
  64         iface lo inet loopback
  65
  66         # Admin network interface
  67         iface eth0 inet manual
  68         auto brAdmin
  69         iface brAdmin inet static
  70                 bridge_ports eth0
  71                 address 10.5.1.1
  72                 netmask 255.255.255.0
  73
  74         # Ext. network for floating IPs
  75         iface eth1 inet manual
  76         auto brExt
  77         iface brExt inet static
  78                 bridge_ports eth1
  79                 address 10.5.15.1
  80                 netmask 255.255.255.0
  81
  82     ..
  83
  84     .. note::
  85         If you choose to use the separate network for management, public, data
  86         and storage, then you need to create bridge for each interface. In case
  87         of VLAN tags, use the appropriate network on Jumphost depending on the
  88         VLAN ID on the interface.
  89
  90     .. note::
  91         Both of the networks need to have Internet connectivity. If only one
  92         of your interfaces has Internet access, you can setup IP forwarding.
  93         For an example how to accomplish that, see the script in Nokia pod 1
  94         deployment (``labconfig/nokia/pod1/setup_ip_forwarding.sh``).
  95
  96
  97 Configure JOID for your lab
  98 ---------------------------
  99
 100 All configuration for the JOID deployment is specified in a ``labconfig.yaml``
 101 file. Here you describe all your physical nodes, their roles in OpenStack,
 102 their network interfaces, IPMI parameters etc. It's also where you configure
 103 your OPNFV deployment and MAAS networks/spaces.
 104 You can find example configuration files from already existing nodes in the
 105 `repository <https://gerrit.opnfv.org/gerrit/gitweb?p=joid.git;a=tree;f=labconfig>`_.
 106
 107 First of all, download JOID to your Jumphost. We recommend doing this in your
 108 home directory.
 109
 110 ::
 111
 112       git clone https://gerrit.opnfv.org/gerrit/p/joid.git
 113
 114 .. tip::
 115     You can select the stable version of your choice by specifying the git
 116     branch, for example:
 117
 118     ::
 119
 120         git clone -b stable/fraser https://gerrit.opnfv.org/gerrit/p/joid.git
 121
 122 Create a directory in ``joid/labconfig/<company_name>/<pod_number>/`` and
 123 create or copy a ``labconfig.yaml`` configuration file to that directory.
 124 For example:
 125
 126 ::
 127
 128     # All JOID actions are done from the joid/ci directory
 129     cd joid/ci
 130     mkdir -p ../labconfig/your_company/pod1
 131     cp ../labconfig/nokia/pod1/labconfig.yaml ../labconfig/your_company/pod1/
 132
 133 Example ``labconfig.yaml`` configuration file:
 134
 135 ::
 136
 137     lab:
 138       location: your_company
 139       racks:
 140       - rack: pod1
 141         nodes:
 142         - name: rack-1-m1
 143           architecture: x86_64
 144           roles: [network,control]
 145           nics:
 146           - ifname: eth0
 147             spaces: [admin]
 148             mac: ["12:34:56:78:9a:bc"]
 149           - ifname: eth1
 150             spaces: [floating]
 151             mac: ["12:34:56:78:9a:bd"]
 152           power:
 153             type: ipmi
 154             address: 192.168.10.101
 155             user: admin
 156             pass: admin
 157         - name: rack-1-m2
 158           architecture: x86_64
 159           roles: [compute,control,storage]
 160           nics:
 161           - ifname: eth0
 162             spaces: [admin]
 163             mac: ["23:45:67:89:ab:cd"]
 164           - ifname: eth1
 165             spaces: [floating]
 166             mac: ["23:45:67:89:ab:ce"]
 167           power:
 168             type: ipmi
 169             address: 192.168.10.102
 170             user: admin
 171             pass: admin
 172         - name: rack-1-m3
 173           architecture: x86_64
 174           roles: [compute,control,storage]
 175           nics:
 176           - ifname: eth0
 177             spaces: [admin]
 178             mac: ["34:56:78:9a:bc:de"]
 179           - ifname: eth1
 180             spaces: [floating]
 181             mac: ["34:56:78:9a:bc:df"]
 182           power:
 183             type: ipmi
 184             address: 192.168.10.103
 185             user: admin
 186             pass: admin
 187         - name: rack-1-m4
 188           architecture: x86_64
 189           roles: [compute,storage]
 190           nics:
 191           - ifname: eth0
 192             spaces: [admin]
 193             mac: ["45:67:89:ab:cd:ef"]
 194           - ifname: eth1
 195             spaces: [floating]
 196             mac: ["45:67:89:ab:ce:f0"]
 197           power:
 198             type: ipmi
 199             address: 192.168.10.104
 200             user: admin
 201             pass: admin
 202         - name: rack-1-m5
 203           architecture: x86_64
 204           roles: [compute,storage]
 205           nics:
 206           - ifname: eth0
 207             spaces: [admin]
 208             mac: ["56:78:9a:bc:de:f0"]
 209           - ifname: eth1
 210             spaces: [floating]
 211             mac: ["56:78:9a:bc:df:f1"]
 212           power:
 213             type: ipmi
 214             address: 192.168.10.105
 215             user: admin
 216             pass: admin
 217         floating-ip-range: 10.5.15.6,10.5.15.250,10.5.15.254,10.5.15.0/24
 218         ext-port: "eth1"
 219         dns: 8.8.8.8
 220     opnfv:
 221         release: d
 222         distro: xenial
 223         type: noha
 224         openstack: pike
 225         sdncontroller:
 226         - type: nosdn
 227         storage:
 228         - type: ceph
 229           disk: /dev/sdb
 230         feature: odl_l2
 231         spaces:
 232         - type: admin
 233           bridge: brAdmin
 234           cidr: 10.5.1.0/24
 235           gateway:
 236           vlan:
 237         - type: floating
 238           bridge: brExt
 239           cidr: 10.5.15.0/24
 240           gateway: 10.5.15.1
 241           vlan:
 242
 243 .. TODO: Details about the labconfig.yaml file
 244
 245 Once you have prepared the configuration file, you may begin with the automatic
 246 MAAS deployment.
 247
 248 MAAS Install
 249 ------------
 250
 251 This section will guide you through the MAAS deployment. This is the first of
 252 two JOID deployment steps.
 253
 254 .. note::
 255     For all the commands in this document, please do not use a ``root`` user
 256     account to run but instead use a non-root user account. We recommend using
 257     the ``ubuntu`` user as described above.
 258
 259     If you have already enabled maas for your environment and installed it then
 260     there is no need to enabled it again or install it. If you have patches
 261     from previous MAAS install, then you can apply them here.
 262
 263     Pre-installed MAAS without using the ``03-maasdeploy.sh`` script is not
 264     supported. We strongly suggest to use ``03-maasdeploy.sh`` script to deploy
 265     the MAAS and JuJu environment.
 266
 267 With the ``labconfig.yaml`` configuration file ready, you can start the MAAS
 268 deployment. In the joid/ci directory, run the following command:
 269
 270 ::
 271
 272     # in joid/ci directory
 273     ./03-maasdeploy.sh custom <absolute path of config>/labconfig.yaml
 274
 275 ..
 276
 277 If you prefer, you can also host your ``labconfig.yaml`` file remotely and JOID
 278 will download it from there. Just run
 279
 280 ::
 281
 282     # in joid/ci directory
 283     ./03-maasdeploy.sh custom http://<web_site_location>/labconfig.yaml
 284
 285 ..
 286
 287 This step will take approximately 30 minutes to a couple of hours depending on
 288 your environment.
 289 This script will do the following:
 290
 291 *   If this is your first time running this script, it will download all the
 292     required packages.
 293 *   Install MAAS on the Jumphost.
 294 *   Configure MAAS to enlist and commission a VM for Juju bootstrap node.
 295 *   Configure MAAS to enlist and commission bare metal servers.
 296 *   Download and load Ubuntu server images to be used by MAAS.
 297
 298 Already during deployment, once MAAS is installed, configured and launched,
 299 you can visit the MAAS Web UI and observe the progress of the deployment.
 300 Simply open the IP of your jumphost in a web browser and navigate to the
 301 ``/MAAS`` directory (e.g. ``http://10.5.1.1/MAAS`` in our example). You can
 302 login with username ``ubuntu`` and password ``ubuntu``. In the *Nodes* page,
 303 you can see the bootstrap node and the bare metal servers and their status.
 304
 305 .. hint::
 306     If you need to re-run this step, first undo the performed actions by
 307     running
 308
 309     ::
 310
 311         # in joid/ci
 312         ./cleanvm.sh
 313         ./cleanmaas.sh
 314         # now you can run the ./03-maasdeploy.sh script again
 315
 316     ..
 317
 318
 319 Juju Install
 320 ------------
 321
 322 This section will guide you through the Juju an OPNFV deployment. This is the
 323 second of two JOID deployment steps.
 324
 325 JOID allows you to deploy different combinations of OpenStack and SDN solutions
 326 in HA or no-HA mode. For OpenStack, it supports Pike and Ocata. For SDN, it
 327 supports Open vSwitch, OpenContrail, OpenDaylight and ONOS (Open Network
 328 Operating System). In addition to HA or no-HA mode, it also supports deploying
 329 the latest from the development tree (tip).
 330
 331 To deploy OPNFV on the previously deployed MAAS system, use the ``deploy.sh``
 332 script. For example:
 333
 334 ::
 335
 336     # in joid/ci directory
 337     ./deploy.sh -d xenial -m openstack -o pike -s nosdn -f none -t noha -l custom
 338
 339 The above command starts an OPNFV deployment with Ubuntu Xenial (16.04) distro,
 340 OpenStack model, Pike version of OpenStack, Open vSwitch (and no other SDN),
 341 no special features, no-HA OpenStack mode and with custom labconfig. I.e. this
 342 corresponds to the ``os-nosdn-nofeature-noha`` OPNFV deployment scenario.
 343
 344 .. note::
 345     You can see the usage info of the script by running
 346
 347     ::
 348
 349         ./deploy.sh --help
 350
 351     Possible script arguments are as follows.
 352
 353     **Ubuntu distro to deploy**
 354     ::
 355
 356         [-d <trusty|xenial>]
 357
 358     -   ``trusty``: Ubuntu 16.04.
 359     -   ``xenial``: Ubuntu 17.04.
 360
 361     **Model to deploy**
 362     ::
 363
 364         [-m <openstack|kubernetes>]
 365
 366     JOID introduces two various models to deploy.
 367
 368     -   ``openstack``:  Openstack, which will be used for KVM/LXD
 369         container-based workloads.
 370     -   ``kubernetes``: Kubernetes model will be used for docker-based
 371         workloads.
 372
 373     **Version of Openstack deployed**
 374     ::
 375
 376         [-o <pike|ocata>]
 377
 378     -   ``pike``: Pike version of OpenStack.
 379     -   ``ocata``:  Ocata version of OpenStack.
 380
 381     **SDN controller**
 382     ::
 383
 384         [-s <nosdn|odl|opencontrail|onos|canal>]
 385
 386     -   ``nosdn``:        Open vSwitch only and no other SDN.
 387     -   ``odl``:          OpenDayLight Boron version.
 388     -   ``opencontrail``: OpenContrail SDN.
 389     -   ``onos``:         ONOS framework as SDN.
 390     -   ``cana;``:        canal CNI plugin for kubernetes.
 391
 392     **Feature to deploy** (comma separated list)
 393     ::
 394
 395         [-f <lxd|dvr|sfc|dpdk|ipv6|none>]
 396
 397     -   ``none``: No special feature will be enabled.
 398     -   ``ipv6``: IPv6 will be enabled for tenant in OpenStack.
 399     -   ``lxd``:  With this feature hypervisor will be LXD rather than KVM.
 400     -   ``dvr``:  Will enable distributed virtual routing.
 401     -   ``dpdk``: Will enable DPDK feature.
 402     -   ``sfc``:  Will enable sfc feature only supported with ONOS deployment.
 403     -   ``lb``:   Load balancing in case of Kubernetes will be enabled.
 404     -   ``ceph``: Ceph storage  Kubernetes will be enabled.
 405
 406     **Mode of Openstack deployed**
 407     ::
 408
 409         [-t <noha|ha|tip>]
 410
 411     -   ``noha``: No High Availability.
 412     -   ``ha``:   High Availability.
 413     -   ``tip``:  The latest from the development tree.
 414
 415     **Where to deploy**
 416     ::
 417
 418         [-l <custom|default|...>]
 419
 420     -   ``custom``: For bare metal deployment where labconfig.yaml was provided
 421         externally and not part of JOID package.
 422     -   ``default``: For virtual deployment where installation will be done on
 423         KVM created using ``03-maasdeploy.sh``.
 424
 425     **Architecture**
 426     ::
 427
 428         [-a <amd64|ppc64el|aarch64>]
 429
 430     -   ``amd64``: Only x86 architecture will be used. Future version will
 431         support arm64 as well.
 432
 433 This step may take up to a couple of hours, depending on your configuration,
 434 internet connectivity etc. You can check the status of the deployment by
 435 running this command in another terminal:
 436
 437 ::
 438
 439     watch juju status --format tabular
 440
 441
 442 .. hint::
 443     If you need to re-run this step, first undo the performed actions by
 444     running
 445     ::
 446
 447         # in joid/ci
 448         ./clean.sh
 449         # now you can run the ./deploy.sh script again
 450
 451     ..
 452
 453
 454 OPNFV Scenarios in JOID
 455 -----------------------
 456 Following OPNFV scenarios can be deployed using JOID. Separate yaml bundle will
 457 be created to deploy the individual scenario.
 458
 459 ======================= ======= ===============================================
 460 Scenario                Owner   Known Issues
 461 ======================= ======= ===============================================
 462 os-nosdn-nofeature-ha   Joid
 463 os-nosdn-nofeature-noha Joid
 464 os-odl_l2-nofeature-ha  Joid    Floating ips are not working on this deployment.
 465 os-nosdn-lxd-ha         Joid    Yardstick team is working to support.
 466 os-nosdn-lxd-noha       Joid    Yardstick team is working to support.
 467 os-onos-nofeature-ha    ONOSFW
 468 os-onos-sfc-ha          ONOSFW
 469 k8-nosdn-nofeature-noha Joid    No support from Functest and Yardstick
 470 k8-nosdn-lb-noha        Joid    No support from Functest and Yardstick
 471 ======================= ======= ===============================================
 472
 473
 474 .. _troubleshooting:
 475
 476 Troubleshoot
 477 ------------
 478 By default debug is enabled in script and error messages will be printed on ssh
 479 terminal where you are running the scripts.
 480
 481 Logs are indispensable when it comes time to troubleshoot. If you want to see
 482 all the service unit deployment logs, you can run ``juju debug-log`` in another
 483 terminal. The debug-log command shows the consolidated logs of all Juju agents
 484 (machine and unit logs) running in the environment.
 485
 486 To view a single service unit deployment log, use ``juju ssh`` to access to the
 487 deployed unit. For example to login into ``nova-compute`` unit and look for
 488 ``/var/log/juju/unit-nova-compute-0.log`` for more info:
 489
 490 ::
 491
 492   ubuntu@R4N4B1:~$ juju ssh nova-compute/0
 493   Warning: Permanently added '172.16.50.60' (ECDSA) to the list of known hosts.
 494   Warning: Permanently added '3-r4n3b1-compute.maas' (ECDSA) to the list of known hosts.
 495   Welcome to Ubuntu 16.04.1 LTS (GNU/Linux 3.13.0-77-generic x86_64)
 496
 497   * Documentation:  https://help.ubuntu.com/
 498   <skipped>
 499   Last login: Tue Feb  2 21:23:56 2016 from bootstrap.maas
 500   ubuntu@3-R4N3B1-compute:~$ sudo -i
 501   root@3-R4N3B1-compute:~# cd /var/log/juju/
 502   root@3-R4N3B1-compute:/var/log/juju# ls
 503   machine-2.log  unit-ceilometer-agent-0.log  unit-ceph-osd-0.log  unit-neutron-contrail-0.log  unit-nodes-compute-0.log  unit-nova-compute-0.log  unit-ntp-0.log
 504   root@3-R4N3B1-compute:/var/log/juju#
 505
 506 .. note::
 507     By default Juju will add the Ubuntu user keys for authentication into the
 508     deployed server and only ssh access will be available.
 509
 510 Once you resolve the error, go back to the jump host to rerun the charm hook
 511 with
 512
 513 ::
 514
 515   $ juju resolved --retry <unit>
 516
 517 If you would like to start over, run
 518 ``juju destroy-environment <environment name>`` to release the resources, then
 519 you can run ``deploy.sh`` again.
 520
 521 To access of any of the nodes or containers, use
 522
 523 ::
 524
 525     juju ssh <service name>/<instance id>
 526
 527 For example:
 528
 529 ::
 530
 531     juju ssh openstack-dashboard/0
 532     juju ssh nova-compute/0
 533     juju ssh neutron-gateway/0
 534
 535 You can see the available nodes and containers by running
 536
 537 ::
 538
 539     juju status
 540
 541 All charm log files are available under ``/var/log/juju``.
 542
 543 -----
 544
 545 If you have questions, you can join the JOID channel ``#opnfv-joid`` on
 546 `Freenode <https://webchat.freenode.net/>`_.
 547
 548
 549 Common Issues
 550 -------------
 551
 552 The following are the common issues we have collected from the community:
 553
 554 -   The right variables are not passed as part of the deployment procedure.
 555
 556     ::
 557
 558         ./deploy.sh -o pike -s nosdn -t ha -l custom -f none
 559
 560 -   If you have not setup MAAS with ``03-maasdeploy.sh`` then the
 561     ``./clean.sh`` command could hang, the ``juju status`` command may hang
 562     because the correct MAAS API keys are not mentioned in cloud listing for
 563     MAAS.
 564
 565     _Solution_: Please make sure you have an MAAS cloud listed using juju
 566     clouds and the correct MAAS API key has been added.
 567 -   Deployment times out: use the command ``juju status`` and make sure all
 568     service containers receive an IP address and they are executing code.
 569     Ensure there is no service in the error state.
 570 -   In case the cleanup process hangs,run the juju destroy-model command
 571     manually.
 572
 573 **Direct console access** via the OpenStack GUI can be quite helpful if you
 574 need to login to a VM but cannot get to it over the network.
 575 It can be enabled by setting the ``console-access-protocol`` in the
 576 ``nova-cloud-controller`` to ``vnc``. One option is to directly edit the
 577 ``juju-deployer`` bundle and set it there prior to deploying OpenStack.
 578
 579 ::
 580
 581     nova-cloud-controller:
 582       options:
 583         console-access-protocol: vnc
 584
 585 To access the console, just click on the instance in the OpenStack GUI and
 586 select the Console tab.
 587
 588
 589
 590 .. Links:
 591 .. _`Ubuntu download`: https://www.ubuntu.com/download/server