docs/ci/docker.rst

   1 Docker CI
   2 =========
   3
   4 For llvmpipe and swrast CI, we run tests in a container containing
   5 VK-GL-CTS, on the shared gitlab runners provided by `freedesktop
   6 <http://freedesktop.org>`_
   7
   8 Software architecture
   9 ---------------------
  10
  11 The docker containers are rebuilt from the debian-install.sh script
  12 when DEBIAN\_TAG is changed in .gitlab-ci.yml, and
  13 debian-test-install.sh when DEBIAN\_ARM64\_TAG is changed in
  14 .gitlab-ci.yml.  The resulting images are around 500MB, and are
  15 expected to change approximately weekly (though an individual
  16 developer working on them may produce many more images while trying to
  17 come up with a working MR!).
  18
  19 gitlab-runner is a client that polls gitlab.freedesktop.org for
  20 available jobs, with no inbound networking requirements.  Jobs can
  21 have tags, so we can have DUT-specific jobs that only run on runners
  22 with that tag marked in the gitlab UI.
  23
  24 Since dEQP takes a long time to run, we mark the job as "parallel" at
  25 some level, which spawns multiple jobs from one definition, and then
  26 deqp-runner.sh takes the corresponding fraction of the test list for
  27 that job.
  28
  29 To reduce dEQP runtime (or avoid tests with unreliable results), a
  30 deqp-runner.sh invocation can provide a list of tests to skip.  If
  31 your driver is not yet conformant, you can pass a list of expected
  32 failures, and the job will only fail on tests that aren't listed (look
  33 at the job's log for which specific tests failed).
  34
  35 DUT requirements
  36 ----------------
  37
  38 In addition to the general :ref:`CI-farm-expectations`, using
  39 docker requires:
  40
  41 * DUTs must have a stable kernel and GPU reset (if applicable).
  42
  43 If the system goes down during a test run, that job will eventually
  44 time out and fail (default 1 hour).  However, if the kernel can't
  45 reliably reset the GPU on failure, bugs in one MR may leak into
  46 spurious failures in another MR.  This would be an unacceptable impact
  47 on Mesa developers working on other drivers.
  48
  49 * DUTs must be able to run docker
  50
  51 The Mesa gitlab-runner based test architecture is built around docker,
  52 so that we can cache the debian package installation and CTS build
  53 step across multiple test runs.  Since the images are large and change
  54 approximately weekly, the DUTs also need to be running some script to
  55 prune stale docker images periodically in order to not run out of disk
  56 space as we rev those containers (perhaps `this script
  57 <https://gitlab.com/gitlab-org/gitlab-runner/issues/2980#note_169233611>`_).
  58
  59 Note that docker doesn't allow containers to be stored on NFS, and
  60 doesn't allow multiple docker daemons to interact with the same
  61 network block device, so you will probably need some sort of physical
  62 storage on your DUTs.
  63
  64 * DUTs must be public
  65
  66 By including your device in .gitlab-ci.yml, you're effectively letting
  67 anyone on the internet run code on your device.  docker containers may
  68 provide some limited protection, but how much you trust that and what
  69 you do to mitigate hostile access is up to you.
  70
  71 * DUTs must expose the dri device nodes to the containers.
  72
  73 Obviously, to get access to the HW, we need to pass the render node
  74 through.  This is done by adding ``devices = ["/dev/dri"]`` to the
  75 ``runners.docker`` section of /etc/gitlab-runner/config.toml.