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". Once the jump server (Local Controller) is booted and
   5 the compute cluster-specific values are provided, the controller
   6 begins to inspect and provision the bare metal servers until the
   7 cluster is entirely configured. This document shows step-by-step how
   8 to configure the network and deployment architecture for the ICN
   9 blueprint.
  10
  11 # License
  12 Apache license v2.0
  13
  14 # Deployment Architecture
  15 The Local Controller is provisioned with the Cluster API controllers
  16 and the Metal3 infrastructure provider, which enable provisioning of
  17 bare metal servers. The controller has three network connections to
  18 the bare metal servers: network A connects bare metal servers, network
  19 B is a private network used for provisioning the bare metal servers
  20 and network C is the IPMI network, used for control during
  21 provisioning. In addition, the bare metal servers connect to the
  22 network D, the SRIOV network.
  23
  24 ![Figure 1](figure-1.png)*Figure 1: Deployment Architecture*
  25
  26 - Net A -- Bare metal network, lab networking for ssh. It is used as
  27   the control plane for K8s, used by OVN and Flannel for the overlay
  28   networking.
  29 - Net B (internal network) -- Provisioning network used by Ironic to
  30   do inspection.
  31 - Net C (internal network) -- IPMI LAN to do IPMI protocol for the OS
  32   provisioning. The NICs support IPMI. The IP address should be
  33   statically assigned via the IPMI tool or other means.
  34 - Net D (internal network) -- Data plane network for the Akraino
  35   application. Using the SR-IOV networking and fiber cables.  Intel
  36   25GB and 40GB FLV NICs.
  37
  38 In some deployment models, you can combine Net C and Net A to be the
  39 same networks, but the developer should take care of IP address
  40 management between Net A and IPMI address of the server.
  41
  42 Also note that the IPMI NIC may share the same RJ-45 jack with another
  43 one of the NICs.
  44
  45 # Pre-installation Requirements
  46 There are two main components in ICN Infra Local Controller - Local
  47 Controller and K8s compute cluster.
  48
  49 ### Local Controller
  50 The Local Controller will reside in the jump server to run the Cluster
  51 API controllers with the Kubeadm bootstrap provider and Metal3
  52 infrastructure provider.
  53
  54 ### K8s Compute Cluster
  55 The K8s compute cluster will actually run the workloads and is
  56 installed on bare metal servers.
  57
  58 ## Hardware Requirements
  59
  60 ### Minimum Hardware Requirement
  61 All-in-one VM based deployment requires servers with at least 32 GB
  62 RAM and 32 CPUs.
  63
  64 ### Recommended Hardware Requirements
  65 Recommended hardware requirements are servers with 64GB Memory, 32
  66 CPUs and SRIOV network cards.
  67
  68 ## Software Prerequisites
  69 The jump server is required to be pre-installed with Ubuntu 18.04.
  70
  71 ## Database Prerequisites
  72 No prerequisites for ICN blueprint.
  73
  74 ## Other Installation Requirements
  75
  76 ### Jump Server Requirements
  77
  78 #### Jump Server Hardware Requirements
  79 - Local Controller: at least three network interfaces.
  80 - Bare metal servers: four network interfaces, including one IPMI interface.
  81 - Four or more hubs, with cabling, to connect four networks.
  82
  83 (Tested as below)
  84 Hostname | CPU Model | Memory | Storage | 1GbE: NIC#, VLAN, (Connected extreme 480 switch) | 10GbE: NIC# VLAN, Network (Connected with IZ1 switch)
  85 ---------|-----------|--------|---------|--------------------------------------------------|------------------------------------------------------
  86 jump0 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 |
  87
  88 #### Jump Server Software Requirements
  89 ICN supports Ubuntu 18.04. The ICN blueprint installs all required
  90 software during `make jump_server`.
  91
  92 ### Network Requirements
  93 Please refer to figure 1 for all the network requirements of the ICN
  94 blueprint.
  95
  96 Please make sure you have 3 distinguished networks - Net A, Net B and
  97 Net C as mentioned in figure 1. Local Controller uses the Net B and
  98 Net C to provision the bare metal servers to do the OS provisioning.
  99
 100 ### Bare Metal Server Requirements
 101
 102 ### K8s Compute Cluster
 103
 104 #### Compute Server Hardware Requirements
 105 (Tested as below)
 106 Hostname | CPU Model | Memory | Storage | 1GbE: NIC#, VLAN, (Connected extreme 480 switch) | 10GbE: NIC# VLAN, Network (Connected with IZ1 switch)
 107 ---------|-----------|--------|---------|--------------------------------------------------|------------------------------------------------------
 108 node1 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 113
 109 node2 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 113
 110 node3 | Intel 2xE5-2699 | 64GB | 3TB (Sata)<br/>180 (SSD) | eth0: VLAN 110<br/>eno1: VLAN 110<br/>eno2: VLAN 111 | eno3: VLAN 113
 111
 112 #### Compute Server Software Requirements
 113 The Local Controller will install all the software in compute servers
 114 from the OS to the software required to bring up the K8s cluster.
 115
 116 ### Execution Requirements (Bare Metal Only)
 117 The ICN blueprint checks all the precondition and execution
 118 requirements for bare metal.
 119
 120 # Installation High-Level Overview
 121 Installation is two-step process:
 122 - Installation of the Local Controller.
 123 - Installation of a compute cluster.
 124
 125 ## Bare Metal Deployment Guide
 126
 127 ### Install Bare Metal Jump Server
 128
 129 #### Creating the Settings Files
 130
 131 ##### Local Controller Network Configuration Reference
 132 The user will find the network configuration file named as
 133 "user_config.sh" in the ICN parent directory.
 134
 135 `user_config.sh`
 136 ``` shell
 137 #!/bin/bash
 138
 139 #Ironic Metal3 settings for provisioning network (Net B)
 140 export IRONIC_INTERFACE="eno2"
 141
 142 #Ironic Metal3 setting for IPMI LAN Network (Net C)
 143 export IRONIC_IPMI_INTERFACE="eno1"
 144 ```
 145
 146 #### Running
 147 After configuring the network configuration file, please run `make
 148 jump_server` from the ICN parent directory as shown below:
 149
 150 ``` shell
 151 root@jump0:# git clone "https://gerrit.akraino.org/r/icn"
 152 Cloning into 'icn'...
 153 remote: Counting objects: 69, done
 154 remote: Finding sources: 100% (69/69)
 155 remote: Total 4248 (delta 13), reused 4221 (delta 13)
 156 Receiving objects: 100% (4248/4248), 7.74 MiB | 21.84 MiB/s, done.
 157 Resolving deltas: 100% (1078/1078), done.
 158 root@jump0:# cd icn/
 159 root@jump0:# make jump_server
 160 ```
 161
 162 The following steps occurs once the `make jump_server` command is
 163 given.
 164 1. All the software required to run the bootstrap cluster is
 165    downloaded and installed.
 166 2. K8s cluster to maintain the bootstrap cluster and all the servers
 167    in the edge location is installed.
 168 3. Metal3 specific network configuration such as local DHCP server
 169    networking for each edge location, Ironic networking for both
 170    provisioning network and IPMI LAN network are identified and
 171    created.
 172 4. The Cluster API controllers, bootstrap, and infrastructure
 173    providers and configured and installed.
 174 5. The Flux controllers are installed.
 175
 176 #### Creating a compute cluster
 177 A compute cluster is composed of installations of two types of Helm
 178 charts: machine and cluster. The specific installations of these Helm
 179 charts are defined in HelmRelease resources consumed by the Flux
 180 controllers in the jump server. The user is required to provide the
 181 machine and cluster specific values in the HelmRelease resources.
 182
 183 ##### Preconfiguration for the compute cluster in Jump Server
 184 The user is required to provide the IPMI information of the servers
 185 and the values of the compute cluster they connect to the Local
 186 Controller.
 187
 188 If the baremetal network provides a DHCP server with gateway and DNS
 189 server information, and each server has identical hardware then a
 190 cluster template can be used. Otherwise these values must also be
 191 provided with the values for each server. Refer to the machine chart
 192 in icn/deploy/machine for more details. In the example below, no DHCP
 193 server is present in the baremetal network.
 194
 195 > *NOTE:* To assist in the migration of R5 and earlier release's use
 196 > from `nodes.json` and the Provisioning resource to a site YAML, a
 197 > helper script is provided at `tools/migration/to_r6.sh`.
 198
 199 `site.yaml`
 200 ``` yaml
 201 apiVersion: v1
 202 kind: Namespace
 203 metadata:
 204     name: metal3
 205 ---
 206 apiVersion: source.toolkit.fluxcd.io/v1beta1
 207 kind: GitRepository
 208 metadata:
 209     name: icn
 210     namespace: metal3
 211 spec:
 212     gitImplementation: go-git
 213     interval: 1m0s
 214     ref:
 215         branch: master
 216     timeout: 20s
 217     url: https://gerrit.akraino.org/r/icn
 218 ---
 219 apiVersion: helm.toolkit.fluxcd.io/v2beta1
 220 kind: HelmRelease
 221 metadata:
 222     name: machine-node1
 223     namespace: metal3
 224 spec:
 225     interval: 5m
 226     chart:
 227         spec:
 228             chart: deploy/machine
 229             sourceRef:
 230                 kind: GitRepository
 231                 name: icn
 232             interval: 1m
 233     values:
 234         machineName: node1
 235         machineLabels:
 236             machine: node1
 237         bmcAddress: ipmi://10.10.110.11
 238         bmcUsername: admin
 239         bmcPassword: password
 240         networks:
 241             baremetal:
 242                 macAddress: 00:1e:67:fe:f4:19
 243                 type: ipv4
 244                 ipAddress: 10.10.110.21/24
 245                 gateway: 10.10.110.1
 246                 nameservers: ["8.8.8.8"]
 247             provisioning:
 248                 macAddress: 00:1e:67:fe:f4:1a
 249                 type: ipv4_dhcp
 250             sriov:
 251                 macAddress: 00:1e:67:f8:6a:41
 252                 type: ipv4
 253                 ipAddress: 10.10.113.3/24
 254 ---
 255 apiVersion: helm.toolkit.fluxcd.io/v2beta1
 256 kind: HelmRelease
 257 metadata:
 258     name: machine-node2
 259     namespace: metal3
 260 spec:
 261     interval: 5m
 262     chart:
 263         spec:
 264             chart: deploy/machine
 265             sourceRef:
 266                 kind: GitRepository
 267                 name: icn
 268             interval: 1m
 269     values:
 270         machineName: node2
 271         machineLabels:
 272             machine: node2
 273         bmcAddress: ipmi://10.10.110.12
 274         bmcUsername: admin
 275         bmcPassword: password
 276         networks:
 277             baremetal:
 278                 macAddress: 00:1e:67:f1:5b:90
 279                 type: ipv4
 280                 ipAddress: 10.10.110.22/24
 281                 gateway: 10.10.110.1
 282                 nameservers: ["8.8.8.8"]
 283             provisioning:
 284                 macAddress: 00:1e:67:f1:5b:91
 285                 type: ipv4_dhcp
 286             sriov:
 287                 macAddress: 00:1e:67:f8:69:81
 288                 type: ipv4
 289                 ipAddress: 10.10.113.4/24
 290 ---
 291 apiVersion: helm.toolkit.fluxcd.io/v2beta1
 292 kind: HelmRelease
 293 metadata:
 294     name: cluster-compute
 295     namespace: metal3
 296 spec:
 297     interval: 5m
 298     chart:
 299         spec:
 300             chart: deploy/cluster
 301             sourceRef:
 302                 kind: GitRepository
 303                 name: icn
 304             interval: 1m
 305     values:
 306         clusterName: compute
 307         controlPlaneEndpoint: 10.10.110.21
 308         controlPlaneHostSelector:
 309             matchLabels:
 310                 machine: node1
 311         workersHostSelector:
 312             matchLabels:
 313                 machine: node2
 314         userData:
 315             hashedPassword: $6$rounds=10000$PJLOBdyTv23pNp$9RpaAOcibbXUMvgJScKK2JRQioXW4XAVFMRKqgCB5jC4QmtAdbA70DU2jTcpAd6pRdEZIaWFjLCNQMBmiiL40.
 316             sshAuthorizedKey: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCrxu+fSrU51vgAO5zP5xWcTU8uLv4MkUZptE2m1BJE88JdQ80kz9DmUmq2AniMkVTy4pNeUW5PsmGJa+anN3MPM99CR9I37zRqy5i6rUDQgKjz8W12RauyeRMIBrbdy7AX1xasoTRnd6Ta47bP0egiFb+vUGnlTFhgfrbYfjbkJhVfVLCTgRw8Yj0NSK16YEyhYLbLXpix5udRpXSiFYIyAEWRCCsWJWljACr99P7EF82vCGI0UDGCCd/1upbUwZeTouD/FJBw9qppe6/1eaqRp7D36UYe3KzLpfHQNgm9AzwgYYZrD4tNN6QBMq/VUIuam0G1aLgG8IYRLs41HYkJ root@jump0
 317         flux:
 318             url: https://gerrit.akraino.org/r/icn
 319             branch: master
 320             path: ./deploy/site/cluster-icn
 321 ```
 322
 323 A brief overview of the values is below. Refer to the machine and
 324 cluster charts in deploy/machine and deploy/cluster respectively for
 325 more details.
 326
 327 - *machineName*: This will be the hostname for the machine, once it is
 328   provisioned by Metal3.
 329 - *bmcUsername*: BMC username required to be provided for Ironic.
 330 - *bmcPassword*: BMC password required to be provided for Ironic.
 331 - *bmcAddress*: BMC server IPMI LAN IP address.
 332 - *networks*: A dictionary of the networks used by ICN.  For more
 333   information, refer to the *networkData* field of the BareMetalHost
 334   resource definition.
 335   - *macAddress*: The MAC address of the interface.
 336   - *type*: The type of network, either dynamic ("ipv4_dhcp") or
 337     static ("ipv4").
 338   - *ipAddress*: Only valid for type "ipv4"; the IP address of the
 339     interface.
 340   - *gateway*: Only valid for type "ipv4"; the gateway of this
 341     network.
 342   - *nameservers*: Only valid for type "ipv4"; an array of DNS
 343      servers.
 344 - *clusterName*: The name of the cluster.
 345 - *controlPlaneEndpoint*: The K8s control plane endpoint. This works
 346   in cooperation with the *controlPlaneHostSelector* to ensure that it
 347   addresses the control plane node.
 348 - *controlPlaneHostSelector*: A K8s match expression against labels on
 349   the *BareMetalHost* machine resource (from the *machineLabels* value
 350   of the machine Helm chart).  This will be used by Cluster API to
 351   select machines for the control plane.
 352 - *workersHostSelector*: A K8s match expression selecting worker
 353   machines.
 354 - *userData*: User data values to be provisioned into each machine in
 355   the cluster.
 356   - *hashedPassword*: The hashed password of the default user on each
 357     machine.
 358   - *sshAuthorizedKey*: An authorized public key of the *root* user on
 359     each machine.
 360 - *flux*: An optional repository to continuously reconcile the created
 361   K8s cluster against.
 362
 363 #### Running
 364 After configuring the machine and cluster site values, the next steps
 365 are to encrypt the secrets contained in the file, commit the file to
 366 source control, and create the Flux resources on the jump server
 367 pointing to the committed files.
 368
 369 1. Create a key protect the secrets in the values if one does not
 370    already exist. The key created below will be named "site-secrets".
 371
 372 ``` shell
 373 root@jump0:# ./deploy/site/site.sh create-gpg-key site-secrets
 374 ```
 375
 376 2. Encrypt the secrets in the site values.
 377
 378 ``` shell
 379 root@jump0:# ./deploy/site/site.sh sops-encrypt-site site.yaml site-secrets
 380 ```
 381
 382 3. Commit the site.yaml and additional files (sops.pub.asc,
 383    .sops.yaml) created by sops-encrypt-site to a Git repository. For
 384    the purposes of the next step, site.yaml will be committed to a Git
 385    repository hosted at URL, on the specified BRANCH, and at location
 386    PATH inside the source tree.
 387
 388 4. Create the Flux resources to deploy the resources described by the
 389    repository in step 3. This creates a GitRepository resource
 390    containing the URL and BRANCH to synchronize, a Secret resource
 391    containing the private key used to decrypt the secrets in the site
 392    values, and a Kustomization resource with the PATH to the site.yaml
 393    file at the GitRepository.
 394
 395 ```shell
 396 root@jump0:# ./deploy/site/site.sh flux-create-site URL BRANCH PATH site-secrets
 397 ```
 398
 399 The progress of the deployment may be monitored in a number of ways:
 400
 401 ``` shell
 402 root@jump0:# kubectl -n metal3 get baremetalhost
 403 root@jump0:# kubectl -n metal3 get cluster compute
 404 root@jump0:# clusterctl -n metal3 describe cluster compute
 405 ```
 406
 407 When the control plane is ready, the kubeconfig can be obtained with
 408 clusterctl and used to access the compute cluster:
 409
 410 ``` shell
 411 root@jump0:# clusterctl -n metal3 get kubeconfig compute >compute-admin.conf
 412 root@jump0:# kubectl --kubeconfig=compute-admin.conf cluster-info
 413 ```
 414
 415 ## Virtual Deployment Guide
 416
 417 ### Standard Deployment Overview
 418 ![Figure 2](figure-2.png)*Figure 2: Virtual Deployment Architecture*
 419
 420 Virtual deployment is used for the development environment using
 421 Vagrant to create VMs with PXE boot. No setting is required from the
 422 user to deploy the virtual deployment.
 423
 424 ### Snapshot Deployment Overview
 425 No snapshot is implemented in ICN R6.
 426
 427 ### Special Requirements for Virtual Deployment
 428
 429 #### Install Jump Server
 430 Jump server is required to be installed with Ubuntu 18.04. This will
 431 install all the VMs and install the K8s clusters.
 432
 433 #### Verifying the Setup - VMs
 434 To verify the virtual deployment, execute the following commands:
 435 ``` shell
 436 $ vagrant up --no-parallel
 437 $ vagrant ssh jump
 438 vagrant@jump:~$ sudo su
 439 root@jump:/home/vagrant# cd /icn
 440 root@jump:/icn# make jump_server
 441 root@jump:/icn# make vm_cluster
 442 ```
 443 `vagrant up --no-parallel` creates three VMs: vm-jump, vm-machine-1,
 444 and vm-machine-2, each with 16GB RAM and 8 vCPUs. `make jump_server`
 445 installs the jump server components into vm-jump, and `make
 446 vm_cluster` installs a K8s cluster on the vm-machine VMs using Cluster
 447 API. The cluster is configured to use Flux to bring up the cluster
 448 with all addons and plugins.
 449
 450 # Verifying the Setup
 451 ICN blueprint checks all the setup in both bare metal and VM
 452 deployment. Verify script will first confirm that the cluster control
 453 plane is ready then run self tests of all addons and plugins.
 454
 455 **Bare Metal Verifier**: Run the `make bm_verifer`, it will verify the
 456 bare-metal deployment.
 457
 458 **Verifier**: Run the `make vm_verifier`, it will verify the virtual
 459 deployment.
 460
 461 # Developer Guide and Troubleshooting
 462 For development uses the virtual deployment, it take up to 10 mins to
 463 bring up the virtual BMC VMs with PXE boot.
 464
 465 ## Utilization of Images
 466 No images provided in this ICN release.
 467
 468 ## Post-deployment Configuration
 469 No post-deployment configuration required in this ICN release.
 470
 471 ## Debugging Failures
 472 * For first time installation enable KVM console in the trial or lab
 473   servers using Raritan console or use Intel web BMC console.
 474
 475   ![Figure 3](figure-3.png)
 476 * Deprovision state will result in Ironic agent sleeping before next
 477   heartbeat - it is not an error. It results in bare metal server
 478   without OS and installed with ramdisk.
 479 * Deprovision in Metal3 is not straight forward - Metal3 follows
 480   various stages from provisioned, deprovisioning and ready. ICN
 481   blueprint take care navigating the deprovisioning states and
 482   removing the BareMetalHost (BMH) custom resouce in case of cleaning.
 483 * Manual BMH cleaning of BMH or force cleaning of BMH resource result
 484   in hang state - use `make bmh_clean` to remove the BMH state.
 485 * Logs of Ironic, openstack baremetal command to see the state of the
 486   server.
 487 * Logs of baremetal operator gives failure related to images or images
 488   md5sum errors.
 489 * It is not possible to change the state from provision to deprovision
 490   or deprovision to provision without completing that state. All the
 491   issues are handled in ICN scripts.
 492
 493 ## Reporting a Bug
 494 Required Linux Foundation ID to launch bug in ICN:
 495 https://jira.akraino.org/projects/ICN/issues
 496
 497 # Uninstall Guide
 498
 499 ## Bare Metal deployment
 500 The command `make clean_all` uninstalls all the components installed by
 501 `make install`
 502 * It de-provision all the servers provisioned and removes them from
 503   Ironic database.
 504 * Baremetal operator is deleted followed by Ironic database and
 505   container.
 506 * Network configuration such internal DHCP server, provisioning
 507   interfaces and IPMI LAN interfaces are deleted.
 508 * It will reset the bootstrap cluster - K8s cluster is torn down in
 509   the jump server and all the associated docker images are removed.
 510 * All software packages installed by `make jump_server` are removed,
 511   such as Ironic, openstack utility tool, docker packages and basic
 512   prerequisite packages.
 513
 514 ## Virtual deployment
 515 The command `vagrant destroy -f` uninstalls all the components for the
 516 virtual deployments.
 517
 518 # Troubleshooting
 519
 520 ## Error Message Guide
 521 The error message is explicit, all messages are captured in log
 522 directory.
 523
 524 # Maintenance
 525
 526 ## Blueprint Package Maintenance
 527 No packages are maintained in ICN.
 528
 529 ## Software maintenance
 530 Not applicable.
 531
 532 ## Hardware maintenance
 533 Not applicable.
 534
 535 ## BluePrint Deployment Maintenance
 536 Not applicable.
 537
 538 # Frequently Asked Questions
 539 **How to setup IPMI?**
 540
 541 First, make sure the IPMI tool is installed in your servers, if not
 542 install them using `apt install ipmitool`. Then, check for the
 543 ipmitool information of each servers using the command `ipmitool lan
 544 print 1`. If the above command doesn't show the IPMI information, then
 545 setup the IPMI static IP address using the following instructions:
 546 - Mostl easy way to set up IPMI topology in your lab setup is by
 547   using IPMI tool.
 548 - Using IPMI tool -
 549   https://www.thomas-krenn.com/en/wiki/Configuring_IPMI_under_Linux_using_ipmitool
 550 - IPMI information can be considered during the BIOS setting as well.
 551
 552 **BMC web console URL is not working?**
 553
 554 It is hard to find issues or reason. Check the ipmitool bmc info to
 555 find the issues, if the URL is not available.
 556
 557 **No change in BMH state - provisioning state is for more than 40min?**
 558
 559 Generally, Metal3 provision for bare metal takes 20 - 30 mins. Look at
 560 the Ironic logs and baremetal operator to look at the state of
 561 servers. Openstack baremetal node shows all state of the server right
 562 from power, storage.
 563
 564 **Why provider network (baremetal network configuration) is required?**
 565
 566 Generally, provider network DHCP servers in a lab provide the router
 567 and DNS server details. In some labs, there is no DHCP server or the
 568 DHCP server does not provide this information.
 569
 570 # License
 571
 572 ```
 573 /*
 574 * Copyright 2019 Intel Corporation, Inc
 575 *
 576 * Licensed under the Apache License, Version 2.0 (the "License");
 577 * you may not use this file except in compliance with the License.
 578 * You may obtain a copy of the License at
 579 *
 580 * http://www.apache.org/licenses/LICENSE-2.0
 581 *
 582 * Unless required by applicable law or agreed to in writing, software
 583 * distributed under the License is distributed on an "AS IS" BASIS,
 584 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 585 * See the License for the specific language governing permissions and
 586 * limitations under the License.
 587 */
 588 ```
 589
 590 # References
 591
 592 # Definitions, acronyms and abbreviations