Gitlab runners toevoegen

Voeg GitLab Runners toe aan de PHX referentie-implementatie, inclusief een optionele air-gapped simulatie.
Categories:
Tags:

Projects:  c2platform/phx/ansible ,  c2platform.mgmt.gitlab-runner

Overzicht

Deze handleiding beschrijft hoe je GitLab Runners kunt aanmaken op nodes pxd-runner1 en pxd-runner2 met behulp van de Ansible GitLab Runner play. Beide nodes zijn vergelijkbaar geconfigureerd, maar pxd-runner2 simuleert een air-gapped installatie op basis van een handmatige installatievariant. Dit maakt het mogelijk om scenario’s te testen waarin internettoegang beperkt is, zoals het offline downloaden van packages.

GitLab Runners voeren CI/CD-pipelines uit voor je GitLab-projecten. In deze setup voorzien we runners met verschillende executors (bijv. Docker en Shell) om diverse jobtypen veilig en efficiënt af te handelen.

Randvoorwaarden

  • Uitrol van GitLab CE: Deze handleiding beschrijft hoe een GitLab Community Edition-instance in de PHX-referentie-implementatie te provisionen en configureren.
  • Zorg ervoor dat de nodes pxd-rproxy1, pxd-ad en pxd-gitlab actief en draaiend zijn.

Uitrol

Om de runner op de pxd-runner1 node aan te maken en te registreren, voer je het volgende commando uit. Dit duurt ongeveer 4 minuten:

vagrant up pxd-runner1

Air-gapped installatie (optionieel)

Om een installatie uit te voeren die een air-gapped omgeving simuleert (op basis van de handmatige installatievariant), maak je de pxd-runner2 node aan. Dit duurt ongeveer 15 minuten:

vagrant up pxd-runner2

Verificatie

Runners

Navigeer naar Groepen → C2 Platform → Bouwen → Runners  . Afhankelijk van of je pxd-runner2 hebt voorzien, zie je 4 of 8 geregistreerde runners. Zonder pxd-runner2 zijn er 4 runners (één voor elk van de Docker- en Shell-executors in VM- en containermodus). Met pxd-runner2 wordt dit verdubbeld tot 8 runners. De afbeelding hieronder toont een voorbeeld met 4 runners.

Git LFS en GitLab Pages

Navigeer naar Groepen → C2 Platform → C2 Platform → Voorbeelden → Git LFS en GitLab Pages → Bouwen → Pipelines  en start een nieuwe pipeline.

Zodra de pipeline is voltooid, navigeer je naar Deploy → Pages  . Deze pagina toont de URL naar de GitLab Pages-website die door de pipeline is aangemaakt.

Klik op de URL om de landingspagina voor de Ansible Software Repository te openen.

Als je op de link voor apache-tomcat-10.1.19.tar.gz klikt, zou de tarball moeten worden gedownload. Dit demonstreert dat de GitLab Runner de pipeline succesvol heeft uitgevoerd, inclusief het publiceren van een GitLab Pages-website die een software repository implementeert met behulp van Git LFS en GitLab Pages.

GitLab Runner CLI

SSH naar pxd-runner1:

vagrant ssh pxd-runner1

Schakel over naar root:

sudo su -

Je kunt nu de GitLab Runner CLI gebruiken om verschillende taken uit te voeren. Voor hulp:

gitlab-runner --help
Show me
root@pxd-runner1:~# gitlab-runner --help
NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   18.9.0 (07e534ba)

AUTHOR:
   GitLab Inc. <support@gitlab.com>

COMMANDS:
   list                  List all configured runners
   register              register a new runner
   reset-token           reset a runner's token
   run                   run multi runner service
   run-single            start single runner
   wrapper               start multi runner service wrapped with gRPC manager server
   unregister            unregister specific runner
   verify                verify all registered runners
   fleeting              manage fleeting plugins
   artifacts-downloader  download and extract build artifacts (internal)
   artifacts-uploader    create and upload build artifacts (internal)
   cache-archiver        create and upload cache artifacts (internal)
   cache-extractor       download and extract cache artifacts (internal)
   cache-init            changed permissions for cache paths (internal)
   health-check          check health for a specific address
   proxy-exec            execute internal commands (internal)
   read-logs             reads job logs from a file, used by kubernetes executor (internal)
   install               install service
   uninstall             uninstall service
   start                 start service
   stop                  stop service
   restart               restart service
   status                get status of a service
   help, h               Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --cpuprofile value           write cpu profile to file [$CPU_PROFILE]
   --debug                      debug mode [$RUNNER_DEBUG]
   --log-format value           Choose log format (options: runner, text, json) [$LOG_FORMAT]
   --log-level value, -l value  Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
   --help, -h                   show help
   --version, -v                print the version

Bijvoorbeeld, lijst de runners op deze node op:

gitlab-runner list

root@pxd-runner1:~# gitlab-runner list
Runtime platform                                    arch=amd64 os=linux pid=4060 revision=dcfb4b66 version=15.10.1
Listing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
pxd-runner1                                   Executor=shell Token=btPy-VV2HF2DxVxh1xzM URL=https://gitlab.com/
root@pxd-runner1:~#

Review

Vagrant boxes

De Vagrant-configuratie definieert twee runner-nodes: pxd-runner1 en pxd-runner2. pxd-runner2 bevat een extra label voor air-gapped simulatie. Deze boxes gebruiken Ubuntu 24 LXD en passen de mgmt/gitlab_runner play toe.

Box-definitie in Vagrantfile.yml:

 Vagrantfile.yml

253  - name: runner1
254    short_description: Gitlab Runner
255    description: Gitlab Runner
256    box: ubuntu24-lxd
257    ip-address: 192.168.60.13
258    plays:
259      - mgmt/gitlab_runner
260    labels:
261      - gitlab_runner
262  - name: runner2
263    short_description: Gitlab Runner
264    description: Gitlab Runner
265    box: ubuntu24-lxd
266    ip-address: 192.168.60.15
267    plays:
268      - mgmt/gitlab_runner
269    labels:
270      - gitlab_runner
271      - gitlab_runner_air_gapped

Play

De Ansible play richt zich op hosts met label gitlab_runner of gitlab_runner_air_gapped. Het past core Linux-roles toe en de c2platform.mgmt.gitlab_runner role om de runners in te stellen.

 plays/mgmt/gitlab_runner.yml

---
- name: GitLab Runner
  hosts: gitlab_runner:gitlab_runner_air_gapped
  become: true

  roles:
    - c2platform.core.linux
    - c2platform.mgmt.gitlab_runner

Hoofdconfiguratie

De hoofdconfiguratie voor de GitLab Runner bevindt zich in group_vars/gitlab_runner/main.yml. Het definieert de runner-versie, coordinator URL, authenticatietoken, te installeren packages, groep-ID, omgevingsvariabelen (voor certificaatvertrouwen), en schakelt de standaard runner-creatie uit. Het stelt ook aangepaste resources in zoals gebruikersgroepen en configuratiebestanden voor concurrency en logging.

 group_vars/gitlab_runner/main.yml

---
px_gitlab_runner_version: 18.9.0-1
gitlab_runner_coordinator_url: "https://{{ px_gitlab_domain }}"
gitlab_runner_token: "{{ px_gitlab_root_pat }}"
gitlab_runner_package:
  - "gitlab-runner-helper-images={{ px_gitlab_runner_version }}"
  - "gitlab-runner={{ px_gitlab_runner_version }}"
gitlab_runner_group: 2  # group: c2platform  # TODO PHX-548

gitlab_runner_environment:
  REQUESTS_CA_BUNDLE: "{{ px_linux_cert_dir }}/c2.crt.crt"

# Disable default runner creation
gitlab_runner_resource_groups_disabled: [default]

gitlab_runner_resources:
  0_config:
    - name: gitlab-runner  # required for vm-runner and shell-exe
      module: user
      groups: docker
      append: true
    - name: config.toml & config_template.toml
      module: copy
      defaults:
        mode: '644'
      resources:
        - dest: /etc/gitlab-runner/config.toml
          content: |
            concurrent = 1
            check_interval = 0
            shutdown_timeout = 0
            log_format = "text"
          force: false
        - dest: /etc/gitlab-runner/config_template.toml
          content: |
            [[runners]]
              [runners.docker]
                host = "unix:///var/run/docker.sock"
                volumes = ["/var/run/docker.sock:/var/run/docker.sock"]
                privileged = false

Aangepaste GitLab Runner image

Deze configuratie bouwt een aangepaste Docker-image voor de GitLab Runner die C2-certificaten vertrouwt. Het creëert een directory, kopieert certificaten en configs, werkt de Dockerfile bij met de daadwerkelijke Docker GID, en bouwt de image (gitlab/c2-gitlab-runner:latest). Dit zorgt ervoor dat runners in containermodus Docker-operaties veilig kunnen uitvoeren met het juiste certificaatvertrouwen.

 group_vars/gitlab_runner/image.yml

---
# GitLab Runner config and GitLab Runner image that trusts C2 certificates
gitlab_runner_resources:
  0_gitlab_runner_image:
    - name: /opt/gitlab-runner
      module: file
      path: /opt/gitlab-runner
      mode: '755'
      state: directory
    - name: /opt/gitlab-runner/Dockerfile
      module: copy
      defaults:
        mode: '644'
      resources:
        - dest: /opt/gitlab-runner/c2.crt
          src: "{{ px_linux_cert_dir }}/c2.crt.crt"
          remote_src: true
        - dest: /opt/gitlab-runner/config.toml
          src: /etc/gitlab-runner/config.toml
          remote_src: true
        - dest: /opt/gitlab-runner/config_template.toml
          src: /etc/gitlab-runner/config_template.toml
          remote_src: true
        - dest: /opt/gitlab-runner/Dockerfile.tpl
          content: |
            # for container-runner with shell-exe:
            # - docker.io package required
            # - gitlab-runner in docker group
            FROM gitlab/gitlab-runner:latest
            ARG DOCKER_GID=999
            COPY c2.crt /usr/local/share/ca-certificates/c2.crt
            COPY config.toml /etc/gitlab-runner/config.toml
            COPY config_template.toml /etc/gitlab-runner/config_template.toml
            RUN update-ca-certificates \
              && apt update \
              && apt install docker.io -y \
              && apt clean
            RUN if ! getent group docker; then \
                  groupadd -g ${DOCKER_GID} docker; \
                else \
                  groupmod -g ${DOCKER_GID} docker; \
                fi
            RUN usermod -a -G docker gitlab-runner
    - name: Update Dockerfile with actual Docker GID
      module: shell
      cmd: |
        cat /opt/gitlab-runner/Dockerfile.tpl > /opt/gitlab-runner/Dockerfile
        DOCKER_GID=$(getent group docker | cut -d: -f3)
        sed -i "s/ARG DOCKER_GID=999/ARG DOCKER_GID=${DOCKER_GID}/" \
          /opt/gitlab-runner/Dockerfile
    - name: gitlab/c2-gitlab-runner
      module: docker_image
      tag: latest
      build:
        path: /opt/gitlab-runner
        dockerfile: Dockerfile
        pull: true
      source: build
      state: present

Runners configuratie

Deze configuratie registreert meerdere runners met specifieke tags, executors en instellingen. Het definieert tags op basis van de omgeving (bijv. hostname, OS), en registreert runners voor Docker- en Shell-executors in zowel VM- als containermodus. De gemeenschappelijke registratieflags zorgen voor een non-interactieve setup met de coordinator URL.

 group_vars/gitlab_runner/runners.yml

---
gitlab_runner_tag_list:
  - px
  - pxd
  - "{{ ansible_fqdn }}"
  - "{{ ansible_distribution | lower }}"
  - "{{ ansible_os_family | lower }}"
  - "{{ ansible_distribution_version }}"

gitlab_runner_resources:
  1_runners:
    - name: Register runners
      module: gitlab_runner
      defaults:
        api_url: "{{ gitlab_runner_coordinator_url }}"
        api_token: "{{ gitlab_runner_token }}"
        environment: "{{ gitlab_runner_environment }}"
        active: true
        run_untagged: true
        locked: false
        group: "{{ gitlab_runner_group }}"
      resources:
        - description: "{{ inventory_hostname }}-docker"
          tag_list: "{{ gitlab_runner_tag_list + ['vm-runner', 'docker-exe'] }}"
          register: >-
            {{ px_gitlab_runner_register_common }}
            --executor "docker"
            --docker-image alpine:latest
            --template-config /etc/gitlab-runner/config_template.toml
        - description: "{{ inventory_hostname }}-shell"
          tag_list: "{{ gitlab_runner_tag_list + ['vm-runner', 'shell-exe'] }}"
          register: >-
            {{ px_gitlab_runner_register_common }}
            --executor "shell"
        - description: "{{ inventory_hostname }}-dind"
          tag_list: "{{ gitlab_runner_tag_list + ['container-runner', 'docker-exe'] }}"
          container:
            name: "gitlab-runner-{{ inventory_hostname }}-docker"
            image: gitlab/c2-gitlab-runner:latest
          register: >-
            {{ px_gitlab_runner_register_common }}
            --executor "docker"
            --docker-image alpine:latest
            --template-config /etc/gitlab-runner/config_template.toml
        - description: "{{ inventory_hostname }}-sind"
          tag_list: "{{ gitlab_runner_tag_list + ['container-runner', 'shell-exe'] }}"
          container:
            name: "gitlab-runner-{{ inventory_hostname }}-shell"
            image: gitlab/c2-gitlab-runner:latest
          register: >-
            {{ px_gitlab_runner_register_common }}
            --executor "shell"

px_gitlab_runner_register_common: >-
  --non-interactive
  --url "{{ gitlab_runner_coordinator_url }}"

Air-gapped installatie

De air-gapped configuratie voor pxd-runner2 schakelt de standaard installatie van de GitLab Runner role uit en vervangt deze door een aangepaste installatiemethode geschikt voor omgevingen zonder internettoegang. Dit is gedefinieerd in group_vars/gitlab_runner_air_gapped/main.yml. Het schakelt de 1_install resource group uit en introduceert 1_install_air_gapped, die DEB-packages installeert vanuit een lokale repository, de service activeert, en de versie en repository-URL’s dienovereenkomstig instelt. Dit demonstreert de flexibiliteit van de Ansible role in het ondersteunen van aangepaste, offline installatievarianten.

 group_vars/gitlab_runner_air_gapped/main.yml

---
# Disable default install from GitLab Runner role
gitlab_runner_bootstrap_resource_groups_disabled: [1_install]

# Configure custom install
gitlab_runner_bootstrap_resources:
  1_install_air_gapped:
    - name: gitlab-runner-helper-images.deb
      module: apt
      deb: "{{ px_gitlab_runner_repo }}/gitlab-runner-helper-images.deb"
    - name: gitlab-runner_amd64.deb
      module: apt
      deb: "{{ px_gitlab_runner_repo }}/gitlab-runner_amd64.deb"
    - name: gitlab-runner
      module: service
      enabled: true

gitlab_runner_package_urls:
  Debian: "{{ px_gitlab_runner_repo }}/gitlab-runner_amd64.deb"

# https://gitlab.com/gitlab-org/gitlab-runner/-/releases
px_gitlab_runner_version: v18.9.0
# px_gitlab_runner_version: latest
px_gitlab_runner_repo: >-
  {{ "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/"
  ~ px_gitlab_runner_version ~ "/deb"
  }}

Zie ook de standaard installatie in roles/gitlab_runner/defaults/main.yml in GitLab Runner role c2platform.mgmt.gitlab_runner:

 roles/gitlab_runner/defaults/main.yml

37  1_install:
38    - name: Download GitLab Runner repository installation script
39      module: get_url
40      url: "{{ gitlab_runner_repository_installation_script_url }}"
41      dest: "{{ gitlab_runner_repo_script_path }}"
42    - name: Install GitLab Runner repository
43      module: command
44      cmd: "bash {{ gitlab_runner_repo_script_path }}"
45      changed_when: true
46      # creates TODO
47    - name: "{{ gitlab_runner_package }}"
48      module: package
49      state: present
50    - name: gitlab-runner
51      module: service
52      enabled: true

Aanvullende informatie

Voor verdere referentie, bekijk de volgende informatie:


Laatst gewijzigd 2026.03.31: howto phx gitlab runners pxd-gitlab pxd-runner1 pxd-runner2 PHX-540 (01b3402)