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