| 1 | Jobs on Custom Runners |
| 2 | ====================== |
| 3 | |
| 4 | Besides the jobs run under the various CI systems listed before, there |
| 5 | are a number additional jobs that will run before an actual merge. |
| 6 | These use the same GitLab CI's service/framework already used for all |
| 7 | other GitLab based CI jobs, but rely on additional systems, not the |
| 8 | ones provided by GitLab as "shared runners". |
| 9 | |
| 10 | The architecture of GitLab's CI service allows different machines to |
| 11 | be set up with GitLab's "agent", called gitlab-runner, which will take |
| 12 | care of running jobs created by events such as a push to a branch. |
| 13 | Here, the combination of a machine, properly configured with GitLab's |
| 14 | gitlab-runner, is called a "custom runner". |
| 15 | |
| 16 | The GitLab CI jobs definition for the custom runners are located under:: |
| 17 | |
| 18 | .gitlab-ci.d/custom-runners.yml |
| 19 | |
| 20 | Custom runners entail custom machines. To see a list of the machines |
| 21 | currently deployed in the QEMU GitLab CI and their maintainers, please |
| 22 | refer to the QEMU `wiki <https://wiki.qemu.org/AdminContacts>`__. |
| 23 | |
| 24 | Machine Setup Howto |
| 25 | ------------------- |
| 26 | |
| 27 | For all Linux based systems, the setup can be mostly automated by the |
| 28 | execution of two Ansible playbooks. Create an ``inventory`` file |
| 29 | under ``scripts/ci/setup``, such as this:: |
| 30 | |
| 31 | fully.qualified.domain |
| 32 | other.machine.hostname |
| 33 | |
| 34 | You may need to set some variables in the inventory file itself. One |
| 35 | very common need is to tell Ansible to use a Python 3 interpreter on |
| 36 | those hosts. This would look like:: |
| 37 | |
| 38 | fully.qualified.domain ansible_python_interpreter=/usr/bin/python3 |
| 39 | other.machine.hostname ansible_python_interpreter=/usr/bin/python3 |
| 40 | |
| 41 | Build environment |
| 42 | ~~~~~~~~~~~~~~~~~ |
| 43 | |
| 44 | The ``scripts/ci/setup/$DISTRO/build-environment.yml`` Ansible |
| 45 | playbook will set up machines with the environment needed to perform |
| 46 | builds and run QEMU tests. This playbook consists on the installation |
| 47 | of various required packages (and a general package update while at |
| 48 | it). |
| 49 | |
| 50 | The minimum required version of Ansible successfully tested in this |
| 51 | playbook is 2.8.0 (a version check is embedded within the playbook |
| 52 | itself). To run the playbook, execute:: |
| 53 | |
| 54 | cd scripts/ci/setup |
| 55 | ansible-playbook -i inventory $DISTRO/build-environment.yml |
| 56 | |
| 57 | Please note that most of the tasks in the playbook require superuser |
| 58 | privileges, such as those from the ``root`` account or those obtained |
| 59 | by ``sudo``. If necessary, please refer to ``ansible-playbook`` |
| 60 | options such as ``--become``, ``--become-method``, ``--become-user`` |
| 61 | and ``--ask-become-pass``. |
| 62 | |
| 63 | gitlab-runner setup and registration |
| 64 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 65 | |
| 66 | The gitlab-runner agent needs to be installed on each machine that |
| 67 | will run jobs. The association between a machine and a GitLab project |
| 68 | happens with a registration token. To find the registration token for |
| 69 | your repository/project, navigate on GitLab's web UI to: |
| 70 | |
| 71 | * Settings (the gears-like icon at the bottom of the left hand side |
| 72 | vertical toolbar), then |
| 73 | * CI/CD, then |
| 74 | * Runners, and click on the "Expand" button, then |
| 75 | * Under "Set up a specific Runner manually", look for the value under |
| 76 | "And this registration token:" |
| 77 | |
| 78 | Copy the ``scripts/ci/setup/vars.yml.template`` file to |
| 79 | ``scripts/ci/setup/vars.yml``. Then, set the |
| 80 | ``gitlab_runner_registration_token`` variable to the value obtained |
| 81 | earlier. |
| 82 | |
| 83 | To run the playbook, execute:: |
| 84 | |
| 85 | cd scripts/ci/setup |
| 86 | ansible-playbook -i inventory gitlab-runner.yml |
| 87 | |
| 88 | Following the registration, it's necessary to configure the runner tags, |
| 89 | and optionally other configurations on the GitLab UI. Navigate to: |
| 90 | |
| 91 | * Settings (the gears like icon), then |
| 92 | * CI/CD, then |
| 93 | * Runners, and click on the "Expand" button, then |
| 94 | * "Runners activated for this project", then |
| 95 | * Click on the "Edit" icon (next to the "Lock" Icon) |
| 96 | |
| 97 | Tags are very important as they are used to route specific jobs to |
| 98 | specific types of runners, so it's a good idea to double check that |
| 99 | the automatically created tags are consistent with the OS and |
| 100 | architecture. For instance, an Ubuntu 20.04 aarch64 system should |
| 101 | have tags set as:: |
| 102 | |
| 103 | ubuntu_20.04,aarch64 |
| 104 | |
| 105 | Because the job definition at ``.gitlab-ci.d/custom-runners.yml`` |
| 106 | would contain:: |
| 107 | |
| 108 | ubuntu-20.04-aarch64-all: |
| 109 | tags: |
| 110 | - ubuntu_20.04 |
| 111 | - aarch64 |
| 112 | |
| 113 | It's also recommended to: |
| 114 | |
| 115 | * increase the "Maximum job timeout" to something like ``2h`` |
| 116 | * give it a better Description |