From nobody Sun Feb 8 23:05:39 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1657629903; cv=none; d=zohomail.com; s=zohoarc; b=B6wCKdRK1bquxqnDaiw7bsKz0n8v/l2RQ/nqLwjo0d35SsseRDj/QDnp/bCyXVi5qES/5c2dEsL71HioUWtupHEdZovIXWibi7UgPbqE941mPfySTQlh3ovtgqTEyub2Sxtbh72uzVZsnuf8hOba0LoY6oAbImOQX9hzOVt9pVE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1657629903; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=u59quVNYgeGGBOAwBHzh8nJRWclUThboAOIHOrAkB2M=; b=OaUgfMdydxTJkzAVodE1IhhivvYRZ3eJ1DT8A97sTRSMXcfBPG4CIsCcg6cC2Mh2LxI9AdWBO2/mx4us7c+hkkR+fTNy20jsILyauCRMioNuTPsJgjH9KEmeYZ2k91EEwXIhd5u+TrzildW5p6ViRVRq2uP8a5p6hiOkrorQTp0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1657629903812130.0044220976298; Tue, 12 Jul 2022 05:45:03 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-314-zQEIUzaXMGeOR2tNj7bPhQ-1; Tue, 12 Jul 2022 08:44:54 -0400 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6E611102F03A; Tue, 12 Jul 2022 12:44:48 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (unknown [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1FD33403163; Tue, 12 Jul 2022 12:44:48 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id CBFCA194705F; Tue, 12 Jul 2022 12:44:47 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 53E8B1947B87 for ; Tue, 12 Jul 2022 12:44:46 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 468B2492CA5; Tue, 12 Jul 2022 12:44:46 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.193.6]) by smtp.corp.redhat.com (Postfix) with ESMTP id BEB2A492C3B; Tue, 12 Jul 2022 12:44:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1657629902; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=u59quVNYgeGGBOAwBHzh8nJRWclUThboAOIHOrAkB2M=; b=iTglcW9sIXFAIq86T7nN+HZx19vEEMx8vnXzo9opxXOTKQVPQJmWJJUBJbV/nsrYLGSHff 1k/FO/RTwbaQq9UgmwO68Vr1NMql74k1VBFe2+PlHlGYTKTb/206eT8p17xVWdWNWgNvzY S+u2I3d4DiDG2rifVLt1dammRR0n9B0= X-MC-Unique: zQEIUzaXMGeOR2tNj7bPhQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 03/10] docs: Provide an article on how to add a custom runner to the project Date: Tue, 12 Jul 2022 14:44:35 +0200 Message-Id: <0bccf4deff93ffb630da626060b74d116e71b665.1657629865.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.9 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: eskultet@redhat.com Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1657629905487100005 Content-Type: text/plain; charset="utf-8"; x-default="true" Since running our functional test suite in GitLab cannot make use of the shared resources it makes sense to document the process of adding own HW to run the custom libvirt executor that powers the integration suite. This article will likely make even more sense in the future with GitLab severely cutting down on shared CI resources. Signed-off-by: Erik Skultety Reviewed-by: Daniel P. Berrang=C3=A9 --- docs/ci-runners.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 1 + 2 files changed, 87 insertions(+) create mode 100644 docs/ci-runners.rst diff --git a/docs/ci-runners.rst b/docs/ci-runners.rst new file mode 100644 index 0000000000..fd5fdd121a --- /dev/null +++ b/docs/ci-runners.rst @@ -0,0 +1,86 @@ +GitLab CI Custom (Specific) Runners +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +GitLab's CI allows additional machines to be added to the project's or gro= up's +pool of runners (a runner is a machine running the GitLab's +`gitlab-runner `__ agent ser= vice). +Upon registering the runner the runner will then be ready accepting CI jobs +depending on the pipeline configuration. Unlike the shared runners provided +directly by GitLab's hosted SaaS specific runners are only used within the +project/group which they were registered to, so you don't need to worry ab= out +forks burning CPU cycles on your precious HW resources. + +Understandably, we respect your decision to keep your runners only visible= to +your fork, but for the sake of the community we'd appreciate if you decide= d to +register your runner with the upstream libvirt project instead. As we're o= nly +interested in running upstream test workloads (which you can even help +defining) maintenance and security of the HW is your own responsibility an= d so +we can promise to never ask for physical or remote access to the machine. + +Machine Setup Howto +------------------- + +The following sections will guide you through the necessary setup of your +specific GitLab runners. + +gitlab-runner setup and registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The gitlab-runner agent needs to be installed on each machine that is supp= osed +to run jobs. The association between a machine and a GitLab project +happens with a registration token. To find the registration token for +your repository/project, navigate on GitLab's web UI to: + + * Settings (the gears-like icon at the bottom of the left hand side + vertical toolbar), then + * CI/CD, then + * Runners, and click on the *Expand* button, then + * Under *Set up a specific Runner manually*, look for the value under + *And this registration token:* + +Note that in order to register a runner with the upstream libvirt project +you'll need to work with the project maintainers to successfully register = your +machine. + +Following the `registration `__ +process, it's necessary to configure the runner tags, and optionally other +configurations on the GitLab UI. Navigate to: + + * Settings (the gears like icon), then + * CI/CD, then + * Runners, and click on the *Expand* button, then + * *Runners activated for this project*, then + * Click on the *Edit* icon (next to the *Lock* Icon) + +Don't forget to add a tag to your runner as these are used to route specif= ic +jobs to specific runners, e.g. if a job in ``ci/integration.yml`` looked l= ike +this :: + + centos-stream-9-tests: + ... + variables: + # needed by libvirt-gitlab-executor + DISTRO: centos-stream-9 + # can be overridden in forks to set a different runner tag + LIBVIRT_CI_INTEGRATION_RUNNER_TAG: my-vm-host + tags: + - $LIBVIRT_CI_INTEGRATION_RUNNER_TAG + +it would mean that the CentOS Stream 9 job would only be scheduled on runn= ers +bearing the 'my-vm-host' tag. + +Running integration tests +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Libvirt's integration tests run in a nested virtualization environment. So= , if +you wish to run integration tests on your bare-metal machine, you'll have = to +make use of GitLab's +`custom executor `__ +feature which allows you to provision any kind of environment for a worklo= ad to +run - in libvirt's case - a virtual machine. If you need any help with cre= ating +VM template images ready to run libvirt's integration test suite, have a l= ook +at the `libvirt-gitlab-executor `__ +project which encapsulates provisioning, execution, and teardown of the +virtualized environments in a single tool. diff --git a/docs/meson.build b/docs/meson.build index fd9df047cb..0c7c54a75f 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -35,6 +35,7 @@ docs_rst_files =3D [ 'cgroups', 'ci', 'ci-dashboard', + 'ci-runners', 'coding-style', 'committer-guidelines', 'compiling', --=20 2.36.1