README.md

   1 # Introduction
   2 ICN strives to automate the process of installing the local cluster
   3 controller to the greatest degree possible – "zero touch
   4 installation". Most of the work is done simply by booting up the jump
   5 server (Local Controller). Once booted, the controller is fully
   6 provisioned and begins to inspect and provision the bare metal
   7 servers, until the cluster is entirely configured. This document shows
   8 step-by-step how to configure the network and deployment architecture
   9 for the ICN blueprint.
  10
  11 # License
  12 Apache license v2.0
  13
  14 # Deployment Architecture
  15 The Local Controller is provisioned with the Metal3 Baremetal Operator
  16 and Ironic, which enable provisioning of bare metal servers. The
  17 controller has three network connections to the bare metal servers:
  18 network A connects bare metal servers, network B is a private network
  19 used for provisioning the bare metal servers and network C is the IPMI
  20 network, used for control during provisioning. In addition, the
  21 bare metal servers connect to the network D, the SRIOV network.
  22
  23 ![Figure 1](figure-1.png)*Figure 1: Deployment Architecture*
  24
  25 - Net A -- Bare metal network, lab networking for ssh. It is used as
  26   the control plane for k8s, used by OVN and Flannel for the overlay
  27   networking.
  28 - Net B (internal network) -- Provisioning network used by Ironic to
  29   do inspection.
  30 - Net C (internal network) -- IPMI LAN to do IPMI protocol for the OS
  31   provisioning. The NICs support IPMI. The IP address should be
  32   statically assigned via the IPMI tool or other means.
  33 - Net D (internal network) -- Data plane network for the Akraino
  34   application. Using the SR-IOV networking and fiber cables.  Intel
  35   25GB and 40GB FLV NICs.
  36
  37 In some deployment models, you can combine Net C and Net A to be the
  38 same networks, but the developer should take care of IP address
  39 management between Net A and IPMI address of the server.
  40
  41 Also note that the IPMI NIC may share the same RJ-45 jack with another
  42 one of the NICs.
  43
  44 # Pre-installation Requirements
  45 There are two main components in ICN Infra Local Controller - Local
  46 Controller and k8s compute cluster.
  47
  48 ### Local Controller
  49 The Local Controller will reside in the jump server to run the Metal3
  50 operator, Binary Provisioning Agent (BPA) operator and BPA REST API
  51 controller.
  52
  53 ### k8s Compute Cluster
  54 The k8s compute cluster will actually run the workloads and is
  55 installed on bare metal servers.
  56
  57 ## Hardware Requirements
  58
  59 ### Minimum Hardware Requirement
  60 All-in-one VM based deployment requires servers with at least 32 GB
  61 RAM and 32 CPUs.
  62
  63 ### Recommended Hardware Requirements
  64 Recommended hardware requirements are servers with 64GB Memory, 32
  65 CPUs and SRIOV network cards.
  66
  67 ## Software Prerequisites
  68 The jump server is required to be pre-installed with Ubuntu 18.04.
  69
  70 ## Database Prerequisites
  71 No prerequisites for ICN blueprint.
  72
  73 ## Other Installation Requirements
  74
  75 ### Jump Server Requirements
  76
  77 #### Jump Server Hardware Requirements
  78 - Local Controller: at least three network interfaces.
  79 - Bare metal servers: four network interfaces, including one IPMI interface.
  80 - Four or more hubs, with cabling, to connect four networks.
  81
  82 (Tested as below)
  83 Hostname | CPU Model | Memory | Storage | 1GbE: NIC#, VLAN, (Connected extreme 480 switch) | 10GbE: NIC# VLAN, Network (Connected with IZ1 switch)
  84 ---------|-----------|--------|---------|--------------------------------------------------|------------------------------------------------------
  85 jump0 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 112
  86
  87 #### Jump Server Software Requirements
  88 ICN supports Ubuntu 18.04. The ICN blueprint installs all required
  89 software during `make install`.
  90
  91 ### Network Requirements
  92 Please refer to figure 1 for all the network requirements of the ICN
  93 blueprint.
  94
  95 Please make sure you have 3 distinguished networks - Net A, Net B and
  96 Net C as mentioned in figure 1. Local Controller uses the Net B and
  97 Net C to provision the bare metal servers to do the OS provisioning.
  98
  99 ### Bare Metal Server Requirements
 100
 101 ### k8s Compute Cluster
 102
 103 #### Compute Server Hardware Requirements
 104 (Tested as below)
 105 Hostname | CPU Model | Memory | Storage | 1GbE: NIC#, VLAN, (Connected extreme 480 switch) | 10GbE: NIC# VLAN, Network (Connected with IZ1 switch)
 106 ---------|-----------|--------|---------|--------------------------------------------------|------------------------------------------------------
 107 node1 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 112<br/>eno4: VLAN 113
 108 node2 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 112<br/>eno4: VLAN 113
 109 node3 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 112<br/>eno4: VLAN 113
 110
 111 #### Compute Server Software Requirements
 112 The Local Controller will install all the software in compute servers
 113 from the OS to the software required to bring up the k8s cluster.
 114
 115 ### Execution Requirements (Bare Metal Only)
 116 The ICN blueprint checks all the precondition and execution
 117 requirements for bare metal.
 118
 119 # Installation High-Level Overview
 120 Installation is two-step process and everything starts with one
 121 command `make install`.
 122 - Installation of the Local Controller.
 123 - Installation of compute cluster.
 124
 125 ## Bare Metal Deployment Guide
 126
 127 ### Install Bare Metal Jump Server
 128
 129 #### Creating a Node Inventory File
 130
 131 ##### Preconfiguration for the Local Controller in Jump Server
 132 The user is required to provide the IPMI information of the servers
 133 they connect to the Local Controller by editing node JSON sample file
 134 in the directory icn/deploy/metal3/scripts/nodes.json.sample as
 135 below. This example only shows 2 servers, statically configured on the
 136 baremetal network. If you want to increase servers, just add another
 137 array.  If the baremetal network provides a DHCP server with gateway
 138 and DNS server information, just change the baremetal type to "ipv4".
 139 ICN provides DHCP servers for the provisioning and bootstrap networks.
 140
 141 `node.json.sample`
 142 ``` json
 143 {
 144   "nodes": [{
 145     "name": "node1",
 146     "ipmi_driver_info": {
 147       "username": "admin",
 148       "password": "admin",
 149       "address": "10.10.10.11"
 150     },
 151     "os": {
 152       "image_name": "bionic-server-cloudimg-amd64.img",
 153       "username": "ubuntu",
 154       "password": "mypasswd"
 155     },
 156     "net": {
 157       "links": [
 158         {
 159           "id": "baremetal_nic",
 160           "ethernet_mac_address": "00:1e:67:fe:f4:19",
 161           "type": "phy"
 162         },
 163         {
 164           "id": "provisioning_nic",
 165           "ethernet_mac_address": "00:1e:67:fe:f4:1a",
 166           "type": "phy"
 167         },
 168         {
 169           "id": "bootstrap_nic",
 170           "ethernet_mac_address": "00:1e:67:f8:6a:40",
 171           "type": "phy"
 172         },
 173         {
 174           "id": "sriov_nic",
 175           "ethernet_mac_address": "00:1e:67:f8:6a:41",
 176           "type": "phy"
 177         }
 178       ],
 179       "networks": [
 180         {
 181           "id": "baremetal",
 182           "link": "baremetal_nic",
 183           "type": "ipv4",
 184           "ip_address": "10.10.110.21/24",
 185           "gateway": "10.10.110.1",
 186           "dns_nameservers": ["8.8.8.8"]
 187         },
 188         {
 189           "id": "provisioning",
 190           "link": "provisioning_nic",
 191           "type": "ipv4_dhcp"
 192         },
 193         {
 194           "id": "bootstrap",
 195           "link": "bootstrap_nic",
 196           "type": "ipv4_dhcp"
 197         },
 198         {
 199           "id": "sriov",
 200           "link": "sriov_nic",
 201           "type": "ipv4",
 202           "ip_address": "10.10.113.2/24"
 203         }
 204       ],
 205       "services": []
 206     }
 207   },
 208   {
 209     "name": "node2",
 210     "ipmi_driver_info": {
 211       "username": "admin",
 212       "password": "admin",
 213       "address": "10.10.10.12"
 214     },
 215     "os": {
 216       "image_name": "bionic-server-cloudimg-amd64.img",
 217       "username": "ubuntu",
 218       "password": "mypasswd"
 219     },
 220     "net": {
 221       "links": [
 222         {
 223           "id": "baremetal_nic",
 224           "ethernet_mac_address": "00:1e:67:f1:5b:90",
 225           "type": "phy"
 226         },
 227         {
 228           "id": "bootstrap_nic",
 229           "ethernet_mac_address": "00:1e:67:f8:69:80",
 230           "type": "phy"
 231         },
 232         {
 233           "id": "provisioning_nic",
 234           "ethernet_mac_address": "00:1e:67:f1:5b:91",
 235           "type": "phy"
 236         },
 237         {
 238           "id": "sriov_nic",
 239           "ethernet_mac_address": "00:1e:67:f8:69:81",
 240           "type": "phy"
 241         }
 242       ],
 243       "networks": [
 244         {
 245           "id": "baremetal",
 246           "link": "baremetal_nic",
 247           "type": "ipv4",
 248           "ip_address": "10.10.110.22/24",
 249           "gateway": "10.10.110.1",
 250           "dns_nameservers": ["8.8.8.8"]
 251         },
 252         {
 253           "id": "provisioning",
 254           "link": "provisioning_nic",
 255           "type": "ipv4_dhcp"
 256         },
 257         {
 258           "id": "bootstrap",
 259           "link": "bootstrap_nic",
 260           "type": "ipv4_dhcp"
 261         },
 262         {
 263           "id": "sriov",
 264           "link": "sriov_nic",
 265           "type": "ipv4",
 266           "ip_address": "10.10.113.3/24"
 267         }
 268       ],
 269       "services": []
 270     }
 271   }]
 272 }
 273 ```
 274
 275 ##### Local Controller Metal3 Configuration Reference
 276 - *node*: The array of nodes required to add to Local Controller.
 277 - *name*: This will be the hostname for the machine, once it is
 278   provisioned by Metal3.
 279 - *ipmi_driver_info*: IPMI driver info is a json field. It currently
 280   holds the IPMI information required for Ironic to send the IPMI tool
 281   command.
 282   - *username*: BMC username required to be provided for Ironic.
 283   - *password*: BMC password required to be provided for Ironic.
 284   - *address*: BMC server IPMI LAN IP address.
 285 - *os*: Bare metal machine OS information is a json field. It
 286   currently holds the image name to be provisioned, username and
 287   password for the login.
 288   - *image_name*: Images name should be in qcow2 format.
 289   - *username*: Login username for the OS provisioned.
 290   - *password*: Login password for the OS provisioned.
 291 - *net*: Bare metal network information is a json field.  It describes
 292   the interfaces and networks used by ICN.  For more information,
 293   refer to the *networkData* field of the BareMetalHost resource
 294   definition.
 295   - *links*: An array of interfaces.
 296         - *id*: The ID of the interface.  This is used in the network
 297       definitions to associate the interface with its network
 298       configuration.
 299     - *ethernet_mac_address*: The MAC address of the interface.
 300         - *type*: The type of interface.  Valid values are "phy".
 301   - *networks*: An array of networks.
 302     - *id*: The ID of the network.
 303     - *link*: The ID of the link this network definition applies to.
 304     - *type*: The type of network, either dynamic ("ipv4_dhcp") or
 305       static ("ipv4").
 306     - *ip_address*: Only valid for type "ipv4"; the IP address of the
 307       interface.
 308     - *gateway*: Only valid for type "ipv4"; the gateway of this
 309       network.
 310     - *dns_nameservers*: Only valid for type "ipv4"; an array of DNS
 311       servers.
 312
 313 #### Creating the Settings Files
 314
 315 ##### Local Controller Network Configuration Reference
 316 The user will find the network configuration file named as
 317 "user_config.sh" in the ICN parent directory.
 318
 319 `user_config.sh`
 320 ``` shell
 321 #!/bin/bash
 322
 323 #Local Controller - Bootstrap cluster DHCP connection
 324 #BS_DHCP_INTERFACE defines the interfaces, to which ICN DHCP deployment will bind
 325 export BS_DHCP_INTERFACE="eno3"
 326
 327 #BS_DHCP_INTERFACE_IP defines the IPAM for the ICN DHCP to be managed.
 328 export BS_DHCP_INTERFACE_IP="172.31.1.1/24"
 329
 330 #Edge Location Provider Network configuration
 331 #Net A - Provider Network
 332 #If provider having specific Gateway and DNS server details in the edge location,
 333 #supply those values in nodes.json.
 334
 335 #Ironic Metal3 settings for provisioning network
 336 #Interface to which Ironic provision network to be connected
 337 #Net B - Provisioning Network
 338 export IRONIC_INTERFACE="eno2"
 339
 340 #Ironic Metal3 setting for IPMI LAN Network
 341 #Interface to which Ironic IPMI LAN should bind
 342 #Net C - IPMI LAN Network
 343 export IRONIC_IPMI_INTERFACE="eno1"
 344
 345 #Interface IP for the IPMI LAN, ICN verfiy the LAN Connection is active or not
 346 #Net C - IPMI LAN Network
 347 export IRONIC_IPMI_INTERFACE_IP="10.10.10.10"
 348 ```
 349
 350 #### Running
 351 After configuring the node inventory file and network configuration
 352 files, please run `make install` from the ICN parent directory as
 353 shown below:
 354
 355 ``` shell
 356 root@pod11-jump:# git clone "https://gerrit.akraino.org/r/icn"
 357 Cloning into 'icn'...
 358 remote: Counting objects: 69, done
 359 remote: Finding sources: 100% (69/69)
 360 remote: Total 4248 (delta 13), reused 4221 (delta 13)
 361 Receiving objects: 100% (4248/4248), 7.74 MiB | 21.84 MiB/s, done.
 362 Resolving deltas: 100% (1078/1078), done.
 363 root@pod11-jump:# cd icn/
 364 root@pod11-jump:# vim Makefile
 365 root@pod11-jump:# make install
 366 ```
 367
 368 The following steps occurs once the `make install` command is given.
 369 1. All the software required to run the bootstrap cluster is
 370    downloaded and installed.
 371 2. k8s cluster to maintain the bootstrap cluster and all the servers
 372    in the edge location is installed.
 373 3. Metal3 specific network configuration such as local DHCP server
 374    networking for each edge location, Ironic networking for both
 375    provisioning network and IPMI LAN network are identified and
 376    created.
 377 4. Metal3 is launched with IPMI configuration as configured in
 378    "user_config.sh" and provisions the bare metal servers using IPMI
 379    LAN network. For more information refer to the [Debugging
 380    Failures](#debugging-failures) section.
 381 5. Metal3 launch verification runs with a timeout of 60 mins by
 382    checking the status of all the servers being provisioned or not.
 383    1. All servers are provisioned in parallel. For example, if your
 384       deployment is having 10 servers in the edge location, all the 10
 385       servers are provisioned at the same time.
 386    2. Metal3 launch verification takes care of checking all the
 387       servers are provisioned, the network interfaces are up and
 388       provisioned with a provider network gateway and DNS server.
 389    3. Metal3 launch verification checks the status of all servers
 390       given in user_config.sh to make sure all the servers are
 391       provisioned. For example, if 8 servers are provisioned and 2
 392       servers are not provisioned, launch verification makes sure all
 393       servers are provisioned before launch k8s clusters on those
 394       servers.
 395 6. BPA bare metal components are invoked with the MAC address of the
 396    servers provisioned by Metal3, BPA bare metal components decide the
 397    cluster size and also the number of clusters required in the edge
 398    location.
 399 7. BPA bare metal runs the containerized Kuberenetes Reference
 400    Deployment (KUD) as a job for each cluster. KUD installs the k8s
 401    cluster on the slice of servers and install ONAP4K8S and all other
 402    default plugins such as Multus, OVN, OVN4NFV, NFD, Virtlet and
 403    SRIOV.
 404 8. BPA REST API agent installed in the bootstrap cluster or jump
 405    server, and this install rest-api, rook/ceph, MinIO as the cloud
 406    storage. This provides a way for user to upload their own software,
 407    container images or OS image to jump server.
 408
 409 ## Virtual Deployment Guide
 410
 411 ### Standard Deployment Overview
 412 ![Figure 2](figure-2.png)*Figure 2: Virtual Deployment Architecture*
 413
 414 Virtual deployment is used for the development environment using
 415 Metal3 virtual deployment to create VM with PXE boot. VM Ansible
 416 scripts the node inventory file in /opt/ironic. No setting is required
 417 from the user to deploy the virtual deployment.
 418
 419 ### Snapshot Deployment Overview
 420 No snapshot is implemented in ICN R2.
 421
 422 ### Special Requirements for Virtual Deployment
 423
 424 #### Install Jump Server
 425 Jump server is required to be installed with Ubuntu 18.04. This will
 426 install all the VMs and install the k8s clusters. Same as bare metal
 427 deployment, use `make vm_install` to install virtual deployment.
 428
 429 #### Verifying the Setup - VMs
 430 `make verify_all` installs two VMs with name master-0 and worker-0
 431 with 8GB RAM and 8 vCPUs and installs k8s cluster on the VMs using the
 432 ICN BPA operator and install the ICN BPA REST API verifier. BPA
 433 operator installs the multi-cluster KUD to bring up k8s with all
 434 addons and plugins.
 435
 436 # Verifying the Setup
 437 ICN blueprint checks all the setup in both bare metal and VM
 438 deployment. Verify script will check that Metal3 provisioned the OS in
 439 each bare metal servers by checking with a timeout period of 60 sec
 440 and interval of 30. BPA operator verifier will check whether the KUD
 441 installation is complete by doing plain curl command to the k8s
 442 cluster installed in bare metal and VM setup.
 443
 444 **Bare Metal Verifier**: Run the `make bm_verifer`, it will verify the
 445 bare-metal deployment.
 446
 447 **Verifier**: Run the `make vm_verifier`, it will verify the virtual
 448 deployment.
 449
 450 # Developer Guide and Troubleshooting
 451 For development uses the virtual deployment, it take up to 10 mins to
 452 bring up the virtual BMC VMs with PXE boot.  Virtual deployment works
 453 well for the BPA operator development for Metal3 installation scripts.
 454
 455 ## Utilization of Images
 456 No images provided in this ICN release.
 457
 458 ## Post-deployment Configuration
 459 No post-deployment configuration required in this ICN release.
 460
 461 ## Debugging Failures
 462 * For first time installation enable KVM console in the trial or lab
 463   servers using Raritan console or use Intel web BMC console.
 464
 465   ![Figure 3](figure-3.png)
 466 * Deprovision state will result in Ironic agent sleeping before next
 467   heartbeat - it is not an error. It results in bare metal server
 468   without OS and installed with ramdisk.
 469 * Deprovision in Metal3 is not straight forward - Metal3 follows
 470   various stages from provisioned, deprovisioning and ready. ICN
 471   blueprint take care navigating the deprovisioning states and
 472   removing the BareMetalHost (BMH) custom resouce in case of cleaning.
 473 * Manual BMH cleaning of BMH or force cleaning of BMH resource result
 474   in hang state - use `make bmh_clean` to remove the BMH state.
 475 * Logs of Ironic, openstack baremetal command to see the state of the
 476   server.
 477 * Logs of baremetal operator gives failure related to images or images
 478   md5sum errors.
 479 * It is not possible to change the state from provision to deprovision
 480   or deprovision to provision without completing that state. All the
 481   issues are handled in ICN scripts.
 482 * k8s cluster failure can be debugged by KUD Pod logs.
 483
 484 ## Reporting a Bug
 485 Required Linux Foundation ID to launch bug in ICN:
 486 https://jira.akraino.org/projects/ICN/issues
 487
 488 # Uninstall Guide
 489
 490 ## Bare Metal deployment
 491 The command `make clean_all` uninstalls all the components installed by
 492 `make install`
 493 * It de-provision all the servers provisioned and removes them from
 494   Ironic database.
 495 * Baremetal operator is deleted followed by Ironic database and
 496   container.
 497 * Network configuration such internal DHCP server, provisioning
 498   interfaces and IPMI LAN interfaces are deleted.
 499 * docker images built during the `make install` are deleted, such as
 500   all Ironic, baremetal operator, BPA operator and KUD images.
 501 * KUD will reset the bootstrap cluster - k8s cluster is torn down in
 502   the jump server and all the associated docker images are removed.
 503 * All software packages installed by `make install_all` are removed,
 504   such as Ironic, openstack utility tool, docker packages and basic
 505   prerequisite packages.
 506
 507 ## Virtual deployment
 508 The command `make vm_clean_all` uninstalls all the components for the
 509 virtual deployments.
 510
 511 # Troubleshooting
 512
 513 ## Error Message Guide
 514 The error message is explicit, all messages are captured in log
 515 directory.
 516
 517 # Maintenance
 518
 519 ## Blueprint Package Maintenance
 520 No packages are maintained in ICN.
 521
 522 ## Software maintenance
 523 Not applicable.
 524
 525 ## Hardware maintenance
 526 Not applicable.
 527
 528 ## BluePrint Deployment Maintenance
 529 Not applicable.
 530
 531 # Frequently Asked Questions
 532 **How to setup IPMI?**
 533
 534 First, make sure the IPMI tool is installed in your servers, if not
 535 install them using `apt install ipmitool`. Then, check for the
 536 ipmitool information of each servers using the command `ipmitool lan
 537 print 1`. If the above command doesn't show the IPMI information, then
 538 setup the IPMI static IP address using the following instructions:
 539 - Mostl easy way to set up IPMI topology in your lab setup is by
 540   using IPMI tool.
 541 - Using IPMI tool -
 542   https://www.thomas-krenn.com/en/wiki/Configuring_IPMI_under_Linux_using_ipmitool
 543 - IPMI information can be considered during the BIOS setting as well.
 544
 545 **BMC web console URL is not working?**
 546
 547 It is hard to find issues or reason. Check the ipmitool bmc info to
 548 find the issues, if the URL is not available.
 549
 550 **No change in BMH state - provisioning state is for more than 40min?**
 551
 552 Generally, Metal3 provision for bare metal takes 20 - 30 mins. Look at
 553 the Ironic logs and baremetal operator to look at the state of
 554 servers. Openstack baremetal node shows all state of the server right
 555 from power, storage.
 556
 557 **Why provider network (baremetal network configuration) is required?**
 558
 559 Generally, provider network DHCP servers in a lab provide the router
 560 and DNS server details. In some labs, there is no DHCP server or the
 561 DHCP server does not provide this information.
 562
 563 # License
 564
 565 ```
 566 /*
 567 * Copyright 2019 Intel Corporation, Inc
 568 *
 569 * Licensed under the Apache License, Version 2.0 (the "License");
 570 * you may not use this file except in compliance with the License.
 571 * You may obtain a copy of the License at
 572 *
 573 * http://www.apache.org/licenses/LICENSE-2.0
 574 *
 575 * Unless required by applicable law or agreed to in writing, software
 576 * distributed under the License is distributed on an "AS IS" BASIS,
 577 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 578 * See the License for the specific language governing permissions and
 579 * limitations under the License.
 580 */
 581 ```
 582
 583 # References
 584
 585 # Definitions, acronyms and abbreviations