resources/tools/testbed-setup/README.rst

   1 Testbed Setup
   2 =============
   3
   4 Introduction
   5 ------------
   6
   7 This directory contains the *high-level* process to set up a hardware machine
   8 as a CSIT testbed, either for use as a physical performance testbed host or as
   9 a vpp_device host.
  10
  11 Code in this directory is NOT executed as part of a regular CSIT test case
  12 but is stored here for ad-hoc installation of HW, archiving and documentation
  13 purposes.
  14
  15 Setting up a hardware host
  16 --------------------------
  17
  18 Documentation below is step by step tutorial and assumes an understanding of PXE
  19 boot and Ansible and managing physical hardware via CIMC or IPMI.
  20
  21 This process is not specific for LF lab, but associated files and code, is based
  22 on the assumption that it runs in LF environment. If run elsewhere, changes
  23 will be required in following files:
  24
  25 #. Inventory directory: `ansible/inventories/sample_inventory/`
  26 #. Inventory files: `ansible/inventories/sample_inventory/hosts`
  27 #. Kickseed file: `pxe/ks.cfg`
  28 #. DHCPD file: `pxe/dhcpd.conf`
  29 #. Bootscreen file: `boot-screens_txt.cfg`
  30
  31 The process below assumes that there is a host used for bootstrapping (referred
  32 to as "PXE bootstrap server" below).
  33
  34 Prepare the PXE bootstrap server when there is no http server AMD64
  35 ```````````````````````````````````````````````````````````````````
  36
  37 #. Clone the csit repo:
  38
  39    .. code-block:: bash
  40
  41       git clone https://gerrit.fd.io/r/csit
  42       cd csit/resources/tools/testbed-setup/pxe
  43
  44 #. Setup prerequisities (isc-dhcp-server tftpd-hpa nginx-light ansible):
  45
  46    .. code-block:: bash
  47
  48       sudo apt-get install isc-dhcp-server tftpd-hpa nginx-light ansible
  49
  50 #. Edit dhcpd.cfg:
  51
  52    .. code-block:: bash
  53
  54       sudo cp dhcpd.cfg /etc/dhcp/
  55       sudo service isc-dhcp-server restart
  56       sudo mkdir /mnt/cdrom
  57
  58 #. Download Ubuntu 18.04 LTS - X86_64:
  59
  60    .. code-block:: bash
  61
  62       wget http://cdimage.ubuntu.com/ubuntu/releases/18.04/release/ubuntu-18.04-server-amd64.iso
  63       sudo mount -o loop ubuntu-18.04-server-amd64.iso /mnt/cdrom/
  64       sudo cp -r /mnt/cdrom/install/netboot/* /var/lib/tftpboot/
  65
  66       # Figure out root folder for NGINX webserver. The configuration is in one
  67       # of the files in /etc/nginx/conf.d/, /etc/nginx/sites-enabled/ or in
  68       # /etc/nginx/nginx.conf under section server/root. Save the path to
  69       # variable WWW_ROOT.
  70       sudo mkdir -p ${WWW_ROOT}/download/ubuntu
  71       sudo cp -r /mnt/cdrom/* ${WWW_ROOT}/download/ubuntu/
  72       sudo cp /mnt/cdrom/ubuntu/isolinux/ldlinux.c32 /var/lib/tftpboot
  73       sudo cp /mnt/cdrom/ubuntu/isolinux/libcom32.c32 /var/lib/tftpboot
  74       sudo cp /mnt/cdrom/ubuntu/isolinux/libutil.c32 /var/lib/tftpboot
  75       sudo cp /mnt/cdrom/ubuntu/isolinux/chain.c32 /var/lib/tftpboot
  76       sudo umount /mnt/cdrom
  77
  78 #. Edit ks.cfg and replace IP address of PXE bootstrap server and subdir in
  79    `/var/www` (in this case `/var/www/download`):
  80
  81    .. code-block:: bash
  82
  83       sudo cp ks.cfg ${WWW_ROOT}/download/ks.cfg
  84
  85 #. Edit boot-screens_txt.cfg and replace IP address of PXE bootstrap server and
  86    subdir in `/var/www` (in this case `/var/www/download`):
  87
  88    .. code-block:: bash
  89
  90       sudo cp boot-screens_txt.cfg /var/lib/tftpboot/ubuntu-installer/amd64/boot-screens/txt.cfg
  91       sudo cp syslinux.cfg /var/lib/tftpboot/ubuntu-installer/amd64/boot-screens/syslinux.cfg
  92
  93 New testbed host - manual preparation
  94 `````````````````````````````````````
  95
  96 Set CIMC/IPMI address, username, password and hostname an BIOS.
  97
  98 Bootstrap the host
  99 ``````````````````
 100
 101 Convenient way to re-stage host via script:
 102
 103 .. code-block:: bash
 104
 105    sudo ./bootstrap_setup_testbed.sh <linux_ip> <mgmt_ip> <username> <pass>
 106
 107 Optional: CIMC - From PXE boostrap server
 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 109
 110 #. Initialize args.ip: Power-Off, reset BIOS defaults, Enable console redir, get
 111    LOM MAC addr:
 112
 113    .. code-block:: bash
 114
 115      ./cimc.py -u admin -p Cisco1234 $CIMC_ADDRESS -d -i
 116
 117 #. Adjust BIOS settings:
 118
 119    .. code-block:: bash
 120
 121       ./cimc.py -u admin -p Cisco1234 $CIMC_ADDRESS -d -s '<biosVfIntelHyperThreadingTech rn="Intel-HyperThreading-Tech" vpIntelHyperThreadingTech="disabled" />' -s '<biosVfEnhancedIntelSpeedStepTech rn="Enhanced-Intel-SpeedStep-Tech" vpEnhancedIntelSpeedStepTech="disabled" />' -s '<biosVfIntelTurboBoostTech rn="Intel-Turbo-Boost-Tech" vpIntelTurboBoostTech="disabled" />'
 122
 123 #. If RAID is not created in CIMC. Create RAID array. Reboot:
 124
 125    .. code-block:: bash
 126
 127       ./cimc.py -u admin -p Cisco1234 $CIMC_ADDRESS -d --wipe
 128       ./cimc.py -u admin -p Cisco1234 $CIMC_ADDRESS -d -r -rl 1 -rs <disk size> -rd '[1,2]'
 129
 130 #. Reboot server with boot from PXE (restart immediately):
 131
 132    .. code-block:: bash
 133
 134       ./cimc.py -u admin -p Cisco1234 $CIMC_ADDRESS -d -pxe
 135
 136 #. Set the next boot from HDD (without restart). Execute while Ubuntu install
 137    is running:
 138
 139    .. code-block:: bash
 140
 141       ./cimc.py -u admin -p Cisco1234 $CIMC_ADDRESS -d -hdd
 142
 143 Optional: IPMI - From PXE boostrap server
 144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 145
 146 #. Get MAC address of LAN0:
 147
 148    .. code-block:: bash
 149
 150       ipmitool -U ADMIN -H $HOST_ADDRESS raw 0x30 0x21 | tail -c 18
 151
 152 #. Reboot into PXE for next boot only:
 153
 154    .. code-block:: bash
 155
 156       ipmitool -I lanplus -H $HOST_ADDRESS -U ADMIN chassis bootdev pxe
 157       ipmitool -I lanplus -H $HOST_ADDRESS -U ADMIN power reset
 158
 159 #. For live watching SOL (Serial-over-LAN console):
 160
 161    .. code-block:: bash
 162
 163       ipmitool -I lanplus -H $HOST_ADDRESS -U ADMIN sol activate
 164       ipmitool -I lanplus -H $HOST_ADDRESS -U ADMIN sol deactivate
 165
 166 Ansible machine
 167 ~~~~~~~~~~~~~~~
 168
 169 Prerequisities for running Ansible
 170 ..................................
 171
 172 - Ansible can run on any machine that has direct SSH connectivity to target
 173   machines that will be provisioned (does not need to be PXE server).
 174 - User `testuser` with password `Csit1234` is created with home folder
 175   initialized on all target machines that will be provisioned.
 176 - SSH keys for no pass access are copied to all target machines that will be
 177   provisioned: `ssh-copy-id x.x.x.x`.
 178 - Inventory directory is created with same or similar content as
 179   `inventories/lf_inventory` in `inventories/` directory (`sample_inventory`
 180   can be used).
 181 - Group variables in `ansible/inventories/<inventory>/group_vars/all.yaml` are
 182   adjusted per environment. Special attention to `proxy_env` variable.
 183 - Host variables in `ansible/inventories/<inventory>/host_vars/x.x.x.x.yaml` are
 184   defined.
 185
 186 Ansible structure
 187 .................
 188
 189 Ansible is defining roles `TG` (Traffic Generator), `SUT` (System Under Test),
 190 `VPP_DEVICE` (vpp_device host for functional testing).
 191
 192 Each Host has corresponding Ansible role mapped and is applied only if Host
 193 with that role is present in inventory file. As a part of optimization the role
 194 `common` contains Ansible tasks applied for all Hosts.
 195
 196 .. note::
 197
 198    You may see `[WARNING]: Could not match supplied host pattern, ignoring:
 199    <role>` in case you have not define hosts for that particular role.
 200
 201 Ansible structure is described below:
 202
 203 .. code-block:: bash
 204
 205    .
 206    ├── inventories                     # Contains all inventories.
 207    │   ├── sample_inventory            # Sample, free for edits outside of LF.
 208    │   │   ├── group_vars              # Variables applied for all hosts.
 209    │   │   │   └── all.yaml
 210    │   │   ├── hosts                   # Inventory list with sample hosts.
 211    │   │   └── host_vars               # Variables applied for single host only.
 212    │   │       └── 1.1.1.1.yaml        # Sample host with IP 1.1.1.1
 213    │   └── lf_inventory                # Linux Foundation inventory.
 214    │       ├── group_vars
 215    │       │   └── all.yaml
 216    │       ├── hosts
 217    │       └── host_vars
 218    ├── roles                           # CSIT roles.
 219    │   ├── common                      # Role applied for all hosts.
 220    │   ├── sut                         # Role applied for all SUTs only.
 221    │   ├── tg                          # Role applied for all TGs only.
 222    │   ├── tg_sut                      # Role applied for TGs and SUTs only.
 223    │   └── vpp_device                  # Role applied for vpp_device only.
 224    ├── site.yaml                       # Main playbook.
 225    ├── sut.yaml                        # SUT playbook.
 226    ├── tg.yaml                         # TG playbook.
 227    ├── vault_pass                      # Main password for vualt.
 228    ├── vault.yml                       # Ansible vualt storage.
 229    └── vpp_device.yaml                 # vpp_device playbook.
 230
 231 Running Ansible
 232 ...............
 233
 234 #. Go to ansible directory: `cd csit/resources/tools/testbed-setup/ansible`
 235 #. Run ansible on selected hosts:
 236    `ansible-playbook --vault-id vault_pass --extra-vars '@vault.yml' --inventory <inventory_file> site.yaml --limit x.x.x.x`
 237
 238 .. note::
 239
 240    In case you want to provision only particular role. You can use tags: `tg`,
 241    `sut`, `vpp_device`.
 242
 243 Reboot hosts
 244 ------------
 245
 246 Manually reboot hosts after Ansible provisioning succeeded.