devel/BuildbotLinuxBuilder.mdwn

   1 Buildbot Linux RC builder for OpenAFS
   2 =====================================
   3
   4 OpenAFS source code changes are frequently required to keep up with changes in
   5 the Linux VFS. Most releases of Linux require changes to keep the OpenAFS port
   6 to build and function with Linux, since OpenAFS is out of tree due to licensing
   7 incompatibilities between GPL and the IBM public license.  In order to catch
   8 build errors as the Linux and OpenAFS code changes, a nightly builder on the
   9 OpenAFS buildbot has been created to automatically build the various git
  10 branches of OpenAFS on the most recent Linux kernel release candidate every
  11 day.  The builder spins up a virtual machine guest, installs the most recent
  12 Linux release candidate image and headers, reboots the guest, then attempts to
  13 build and run OpenAFS on the release candidate.
  14
  15 Linux KVM and `libvirt` commands are used for virtualization.  The builder
  16 downloads pre-build Linux release candidates published by the Ubuntu Kernel
  17 Team.
  18
  19 The components of this system are:
  20
  21 * A Linux KVM host system (`kvm`, `qemu`, and `libvirt`)
  22 * An Ubuntu base image to be cloned
  23 * A script called `kernel-ppa` to find and download the most recent Linux kernels
  24   from the Ubuntu Kernel Team's site.
  25 * A script called `virt-run` to clone the base image, run commands on the clone,
  26   then destroy the clone
  27 * A buildbot worker which is always running
  28 * The buildbot master configuration
  29
  30 Linux KVM host system
  31 ---------------------
  32
  33 The host system is currently configured to use Linux KVM to create ephemeral
  34 virtual machines to run the build and tests.  The host system must have cpu
  35 virtualization extensions (Intel VT-x or AMD-V) to run KVM.
  36
  37 See your distribution specific documentation for KVM and libvirt installation
  38 instructions.
  39
  40 Ubuntu base image
  41 -----------------
  42
  43 Create a base image to be cloned by the buildbot worker. The base image can be
  44 created with the libvirt-manager GUI program. The OpenAFS buildbot is currently
  45 using an Ubuntu 18.04 LTS release image.
  46
  47 Install the `afsutil` package from python pip. This command is used to install
  48 the built binaries and create a test cell on ephemeral guests.
  49
  50     sudo pip install afsutil
  51
  52 Install the build tool chain needed to build OpenAFS from source using `sudo
  53 afsutil getdeps` or by running apt-get install of the packages needed.  At this
  54 point it is best to verify the OpenAFS binaries can be built from a git
  55 checkout on a running base image.
  56
  57 The `kernel-ppa` script is used to find and install the most recent Linux
  58 kernel image and headers from the Ubuntu Kernel Team's site. Download
  59 `kernel-ppa` from github and copy to a location in the path on the base image.
  60
  61     git clone https://github.com/meffie/virt-utils.git
  62     cd virt-utils
  63     git checkout virt-run
  64     sudo cp kernel-ppa /usr/local/bin/
  65
  66 Allow the buildbot user on the guest to run `kernel-ppa` and `afsutil` as sudo,
  67 without a password, in order to change the kernel on ephemeral guests.
  68
  69     $ cat /etc/sudoers.d/buildbot
  70     buildbot ALL=(ALL) NOPASSWD: /usr/local/bin/afsutil
  71     buildbot ALL=(ALL) NOPASSWD: /usr/local/bin/kernel-ppa
  72
  73 Keep the base image guest running until the buildbot worker's ssh public key is
  74 installed (see the next section). After which, the base image guest should be
  75 shutdown, otherwise libvirt will not be able to clone the base image when a
  76 build is scheduled.
  77
  78 Buildbot worker
  79 ---------------
  80
  81 The buildbot worker should be running on the host system or in a long-running
  82 virtual machine.
  83
  84 Create a 'buildbot' service account on the worker system and create an ssh
  85 key-pair for the communication from the buildbot worker to the ephemeral
  86 virtual machines.  The ssh-key should be password-less for the automation.
  87 Copy the public ssh key to the buildbot user's authorized keys file on the
  88 running base image guest.  After the key is in place and verified to work,
  89 shutdown the base image guest so it can be cloned.
  90
  91 Configure the account to have access to `libvirt` commands by setting the
  92 environment variable `LIBVIRT_DEFAULT_URI`. See the KVM and libvirt
  93 documentation.
  94
  95 Install the `virt-run` command from the 'virt-utils' project on github.
  96
  97     git clone https://github.com/meffie/virt-utils.git
  98     cd virt-utils
  99     git checkout virt-run
 100     sudo make install
 101
 102 Verify the `virt-run` command is able to clone the base-image to spin up an
 103 ephemeral guest and run commands on it.  See the `examples` directory in
 104 `virt-utils` for some example usage.
 105
 106 Finally, install the buildbot worker from your distibution packages or from
 107 python pip and configure the slave to contact the buildbot master.
 108
 109 Buildbot master configuration
 110 -----------------------------
 111
 112 Changes to the buildbot master can be deployed by one of the OpenAFS buildbot
 113 admins.  The buildbot master configuration is maintained in the OpenAFS-Contrib
 114 project on [github][1].
 115
 116 Currently, the buildbot master is configured to `virt-run` to spin up a clone,
 117 install the current linux release candidate, reboot the clone, and then build
 118 OpenAFS.
 119
 120 [1]: https://github.com/openafs-contrib/afsbotcfg.git