devel/BuildbotLinuxBuilder.mdwn

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