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 - Inventory directory is created with same or similar content as
 177   `inventories/lf_inventory` in `inventories/` directory (`sample_inventory`
 178   can be used).
 179 - Group variables in `ansible/inventories/<inventory>/group_vars/all.yaml` are
 180   adjusted per environment. Special attention to `proxy_env` variable.
 181 - Host variables in `ansible/inventories/<inventory>/host_vars/x.x.x.x.yaml` are
 182   defined.
 183
 184 Ansible structure
 185 .................
 186
 187 Ansible is defining roles `TG` (Traffic Generator), `SUT` (System Under Test),
 188 `VPP_DEVICE` (vpp_device host for functional testing). `COMMON` (Applicable
 189 for all servers in inventory).
 190
 191 Each Host has corresponding Ansible role mapped and is applied only if Host
 192 with that role is present in inventory file. As a part of optimization the role
 193 `common` contains Ansible tasks applied for all Hosts.
 194
 195 .. note::
 196
 197    You may see `[WARNING]: Could not match supplied host pattern, ignoring:
 198    <role>` in case you have not define hosts for that particular role.
 199
 200 Ansible structure is described below:
 201
 202 .. code-block:: bash
 203
 204    .
 205    ├── inventories                     # Contains all inventories.
 206    │   ├── sample_inventory            # Sample, free for edits outside of LF.
 207    │   │   ├── group_vars              # Variables applied for all hosts.
 208    │   │   │   └── all.yaml
 209    │   │   ├── hosts                   # Inventory list with sample hosts.
 210    │   │   └── host_vars               # Variables applied for single host only.
 211    │   │       └── 1.1.1.1.yaml        # Sample host with IP 1.1.1.1
 212    │   └── lf_inventory                # Linux Foundation inventory.
 213    │       ├── group_vars
 214    │       │   └── all.yaml
 215    │       ├── hosts
 216    │       └── host_vars
 217    ├── roles                           # CSIT roles.
 218    │   ├── common                      # Role applied for all hosts.
 219    │   ├── sut                         # Role applied for all SUTs only.
 220    │   ├── tg                          # Role applied for all TGs only.
 221    │   ├── tg_sut                      # Role applied for TGs and SUTs only.
 222    │   └── vpp_device                  # Role applied for vpp_device only.
 223    ├── site.yaml                       # Main playbook.
 224    ├── sut.yaml                        # SUT playbook.
 225    ├── tg.yaml                         # TG playbook.
 226    ├── vault_pass                      # Main password for vualt.
 227    ├── vault.yml                       # Ansible vualt storage.
 228    └── vpp_device.yaml                 # vpp_device playbook.
 229
 230 Tagging
 231 .......
 232
 233 Every task, handler, role, playbook is tagged with self-explanatory tags that
 234 could be used to limit which objects are applied to target systems.
 235
 236 You can see which tags are applied to tasks, roles, and static imports by
 237 running `ansible-playbook` with the `--list-tasks` option. You can display all
 238 tags applied to the tasks with the `--list-tags` option.
 239
 240 Running Ansible
 241 ...............
 242
 243 #. Go to ansible directory: `cd csit/resources/tools/testbed-setup/ansible`
 244 #. Run ansible on selected hosts:
 245    `ansible-playbook --vault-password-file=vault_pass --extra-vars '@vault.yml'
 246    --inventory <inventory_file> site.yaml --limit x.x.x.x`
 247
 248 .. note::
 249
 250    In case you want to provision only particular role. You can use tags: `tg`,
 251    `sut`, `vpp_device`.
 252
 253 Reboot hosts
 254 ------------
 255
 256 Manually reboot hosts after Ansible provisioning succeeded.