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 Documentation below is step by step tutorial and assumes an understanding of PXE
  16 boot and `Ansible <https://www.ansible.com/>`_ and managing physical hardware
  17 via CIMC or IPMI.
  18
  19 This process is not specific for Linux Foundation lab, but associated files and
  20 code, is based on the assumption that it runs in Linux Foundation environment.
  21 If run elsewhere, changes will be required in following files:
  22
  23 #. Inventory directory: `ansible/inventories/sample_inventory/`
  24 #. Inventory files: `ansible/inventories/sample_inventory/hosts`
  25
  26 The process below assumes that there is a host used for bootstrapping (referred
  27 to as a "Cobbler provision host" below), with reachable DHCP service.
  28
  29 Ansible host
  30 ------------
  31
  32 Prerequisities for running Ansible
  33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  34
  35 - CIMC/IPMI address, username, password are set in BIOS.
  36 - Ansible can be invoked on any host that has direct SSH connectivity to
  37   the remote hosts that will be provisioned (does not need to be Cobbler
  38   provision host). This may require installed ssh_keys `ssh-copy-id` on remote
  39   host or disabled StrictHostChecking on host running Ansible:
  40
  41   ::
  42
  43   Host <host_ip or host subnet_ip>
  44         StrictHostKeyChecking no
  45         UserKnownHostsFile=/dev/null
  46
  47 - Ansible version 2.7+ is installed via PIP or via standard package
  48   distribution (apt, yum, dnf).
  49 - User `testuser` with password `Csit1234` is created with home folder
  50   initialized on all remote machines that will be provisioned.
  51 - Inventory directory is created with same or similar content as
  52   `inventories/lf_inventory` in `inventories/` directory (`sample_inventory`
  53   can be used).
  54 - Group variables in `ansible/inventories/<inventory>/group_vars/all.yaml` are
  55   adjusted per environment with special attention to `proxy_env` variable.
  56 - Host variables in `ansible/inventories/<inventory>/host_vars/x.x.x.x.yaml` are
  57   defined.
  58
  59 Ansible structure
  60 ~~~~~~~~~~~~~~~~~
  61
  62 Ansible is defining roles `tg` (Traffic Generator), `sut` (System Under Test),
  63 `vpp_device` (vpp_device host for functional device testing), `common`
  64 (Applicable for all hosts in inventory) and `cobbler` (Cobbler provision host).
  65
  66 Each host has corresponding Ansible role mapped and is applied only if a host
  67 with that role is present in inventory file. As a part of optimization the role
  68 `common` contains Ansible tasks applied for all hosts.
  69
  70 .. note::
  71
  72    You may see `[WARNING]: Could not match supplied host pattern, ignoring:
  73    <role>` in case you have not define hosts for that particular role.
  74
  75 Ansible structure is described below:
  76
  77 .. code-block:: bash
  78
  79    .
  80    ├── inventories                     # Contains all inventories.
  81    │   ├── sample_inventory            # Sample, free for edits outside of LF.
  82    │   │   ├── group_vars              # Variables applied for all hosts.
  83    │   │   │   └── all.yaml
  84    │   │   ├── hosts                   # Inventory list with sample hosts.
  85    │   │   └── host_vars               # Variables applied for single host only.
  86    │   │       └── 1.1.1.1.yaml        # Sample host with IP 1.1.1.1
  87    │   └── lf_inventory                # Linux Foundation inventory.
  88    │       ├── group_vars
  89    │       │   └── all.yaml
  90    │       ├── hosts
  91    │       └── host_vars
  92    ├── roles                           # CSIT roles.
  93    │   ├── cobbler                     # Role applied for Cobbler host only.
  94    │   ├── common                      # Role applied for all hosts.
  95    │   ├── sut                         # Role applied for all SUTs only.
  96    │   ├── tg                          # Role applied for all TGs only.
  97    │   ├── tg_sut                      # Role applied for TGs and SUTs only.
  98    │   └── vpp_device                  # Role applied for vpp_device only.
  99    ├── site.yaml                       # Main playbook.
 100    ├── sut.yaml                        # SUT playbook.
 101    ├── tg.yaml                         # TG playbook.
 102    ├── vault_pass                      # Main password for vault.
 103    ├── vault.yml                       # Ansible vault storage.
 104    └── vpp_device.yaml                 # vpp_device playbook.
 105
 106 Tagging
 107 ~~~~~~~
 108
 109 Every task, handler, role or playbook is tagged with self-explanatory tag(s)
 110 that could be used to limit which Ansible objects are applied to target systems.
 111
 112 You can see what tags are applied to tasks, roles, and static imports by
 113 running `ansible-playbook` with the `--list-tasks` option. You can display all
 114 tags applied to the tasks with the `--list-tags` option.
 115
 116 Running Ansible
 117 ~~~~~~~~~~~~~~~
 118
 119 #. Go to ansible directory: `$ cd csit/resources/tools/testbed-setup/ansible`
 120 #. Run ansible on selected hosts:
 121    `$ ansible-playbook --vault-password-file=vault_pass --extra-vars
 122    '@vault.yml' --inventory <inventory_file> site.yaml --limit <host_ip>`
 123 #. (Optional) Run ansible on selected hosts with selected tags:
 124    `$ ansible-playbook --vault-password-file=vault_pass --extra-vars
 125    '@vault.yml' --inventory <inventory_file> site.yaml --limit <host_ip>
 126    --tags 'copy-90-csit'`
 127
 128 .. note::
 129
 130    In case you want to provision only particular role. You can use tags: `tg`,
 131    `sut`, `vpp_device`.
 132
 133 Baremetal provisioning of host via Ansible Cobbler module
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 Baremetal provisioning of the host with Ansible is done via `Cobbler
 137 <https://cobbler.github.io/>`_. Ansible contains a role `cobbler` that includes
 138 a set of tasks for deploying Cobbler in a container on dedicated host.
 139 Container is built during Ansible run of `cobbler` role and it provides DHCPD,
 140 TFTPD, HTTTP and Cobbler services.
 141
 142 There is a special set of tasks and handlers in `common` role that does include
 143 a system into Cobbler and reboots provisioned host.
 144
 145 #. Go to Ansible directory: `$ cd csit/resources/tools/testbed-setup/ansible`
 146 #. Prepare Cobbler provision host via Ansible on dedicated hosts:
 147    `$ ansible-playbook --vault-password-file=vault_pass --extra-vars
 148    '@vault.yml' --inventory <inventory_file> site.yaml --limit <cobbler_ip>`
 149 #. Run Ansible on selected hosts with selected tags:
 150    `$ ansible-playbook --vault-password-file=vault_pass --extra-vars
 151    '@vault.yml' --inventory <inventory_file> site.yaml --limit <host_ip>
 152    --tags 'provision'`