ebb5872971e72c65fcee33150a4aeefe80b4dbe1
[openafs-wiki.git] / 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