Konfiguracja Forgejo Runner do komunikacji z VCS

Operator nie ponosi odpowiedzialności za systemy runner zapewniane przez Abonenta we własnym zakresie, w szczególności za bezpieczeństwo wykonywanych przez nie operacji i za bezpieczeństwo umieszczanych w nich kluczy oraz danych. Publikowane przez Operatora na niniejszej stronie informacje mają charakter pomocniczy, dla prostoty nie zawierają np. wartych rozważenia dalszych zabezpieczeń konteneryzacji czy ograniczeń komunikacji sieciowej a Abonent może korzystać z nich na własne ryzyko.

Aplikacja VCS bazuje na open source-owym projekcie Forgejo i pozwala na integrację z zapewnianymi przez abonenta we własnym zakresie instancjami Forgejo Runner w celu umożliwienia wykonywania procesów CI/CD (nazywanych w VCS Akcjami). Sposób korzystania z procesów CI/CD opisany jest w dokumentacji użytkownika Forgejo Actions (VCS może nie oferować wszystkich opisanych tam mechanizmów stąd zalecamy testowanie scenariuszy CI/CD w VCS przed podjęciem decyzji o ich produkcyjnym użyciu).

Uruchamianie procesów CI/CD wiąże się z ryzykami (np. możliwość dostępu do danych zgromadzonych w serwisie cybo.pl przez wykonywany w trakcie procesu CI/CD kod źródłowy pochodzący z niezaufanych źródeł), które należy uwzględnić przy planowaniu korzystania z tego mechanizmu. Dodatkowe informacje związane z bezpieczeństwem procesów CI/CD znajdują się m.in. na stronach Forgejo Actions oraz Gitea Actions.

Konfiguracja Forgejo Runner do komunikacji z VCS

Przykład instalacji i konfiguracji Forgejo Runner v11 w powłoce konta root osobnej maszyny wirtualnej z systemem Debian 13, korzystającej z jednej partycji dla wszystkich plików, w celu uruchamiania procesów CI/CD z VCS w serwisie demo:

• Zainstalować oprogramowanie potrzebne do korzystania z usług uruchamianych za pomocą docker-compose:

apt-get update && apt-get install docker-compose docker-cli docker.io

• Utworzyć katalog na dane aplikacji mitmproxy, która pozwalać będzie na dostęp do VCS za pomocą certyfikatu dla procesu Forejo Runner oraz procesów uruchamianych wewnątrz kontenerów CI/CD:

mkdir -p /etc/mitmproxy/cc
chmod 0770 /etc/mitmproxy

Poniższe dla prostoty zakłada użycie istniejącego konta i certyfikatu użytkownika demonstracyjnego z ID 439d, posiadającego wysokie uprawnienia w serwisie demo. W przypadku właściwej integracji warto rozważyć użycie w tym celu dedykowanego dostępu technicznego (użytkownika lub/i certyfikatu), posiadającego minimalne potrzebne uprawnienia, np. jedynie dostęp do VCS. Ponieważ runner w trakcie wykonywania procesu CI/CD korzysta z tymczasowego tokena uprawnień, to zwykle nie ma potrzeby osobnego nadawania uprawnień do repozytorium źródłowego procesu CI/CD dla użytkownika, którego certyfikat jest używany przez runnera.

• W pliku /etc/mitmproxy/cc/vcs.demo.cybo.pl.pem (w nazwie pliku należy umieścić pełną nazwę domenową integrowanej aplikacji VCS, tutaj vcs.demo.cybo.pl) umieścić treść niezaszyfrowanego klucza prywatnego w formacie PEM (pobraną z pliku 439d.plain.key) a następnie pod nią umieścić treść certyfikatu w formacie PEM (pobraną z pliku 439d.crt). Oba wskazane pliki znajdują się w archiwum 439d.zip. W utworzonym w ten sposób pliku znajdować się powinna treść zgodna z szablonem:

-----BEGIN PRIVATE KEY-----
[...]
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----

• Utworzyć katalog na konfigurację i dane runnera:

mkdir -p /etc/runner/data/.cache
chmod 0770 /etc/runner/data
chmod 2770 /etc/runner/data/.cache
chown -R 1001:1001 /etc/runner/data

• Utworzyć plik /etc/runner/docker-compose.yml o treści

services:
  proxy:
    image: 'mitmproxy/mitmproxy'
    container_name: 'proxy'
    restart: 'unless-stopped'
    ports:
        - '8080:8080'
    volumes:
        - '/etc/mitmproxy:/home/mitmproxy/.mitmproxy'
        - '/etc/ssl/certs:/etc/ssl/certs:ro'
        - '/usr/share/ca-certificates:/usr/share/ca-certificates:ro'
        - '/usr/local/share/ca-certificates:/usr/local/share/ca-certificates:ro'
    command: [ 'mitmdump', '--set', 'confdir=/home/mitmproxy/.mitmproxy', '--set', 'client_certs=/home/mitmproxy/.mitmproxy/cc', '--set', 'lock_list="/~d localhost|127\./400\"', '--set', 'ssl_verify_upstream_trusted_ca=/etc/ssl/certs/ca-certificates.crt' ]

  runner:
    image: 'data.forgejo.org/forgejo/runner:11'
    links:
      - proxy
    depends_on:
      proxy:
        condition: 'service_started'
    container_name: 'runner'
    environment:
      DOCKER_HOST: 'unix:///run/docker.sock'
      http_proxy: 'http://proxy:8080'
      https_proxy: 'http://proxy:8080'
      no_proxy: 'runner'
    user: '0:0'
    volumes:
      - '/run/docker.sock:/run/docker.sock'
      - '/etc/runner/data:/data'
      - '/etc/ssl/certs:/etc/ssl/certs:ro'
      - '/usr/share/ca-certificates:/usr/share/ca-certificates:ro'
      - '/usr/local/share/ca-certificates:/usr/local/share/ca-certificates:ro'
    restart: 'unless-stopped'
    command: '/bin/sh -c "while : ; do sleep 1 ; done ;"'

networks:
  default:
    name: runner

• Utworzyć plik /etc/runner/data/config.yml o treści

runner:
    file: '.runner'
    capacity: 1
    fetch_interval: '10s'
    report_interval: '5s'
    envs:
        https_proxy: 'http://proxy:8080'
        http_proxy: 'http://proxy:8080'

cache:
    enabled: true
    dir: ''
    host: 'runner'
    port: 0
    proxy_port: 0

container:
    force_pull: true
    network: 'runner'
    valid_volumes:
        - '/etc/ssl/certs'
        - '/usr/share/ca-certificates'
        - '/usr/local/share/ca-certificates'
    options: '--volume=/etc/ssl/certs:/etc/ssl/certs:ro --volume=/usr/share/ca-certificates:/usr/share/ca-certificates:ro --volume=/usr/local/share/ca-certificates:/usr/local/share/ca-certificates:ro '

host:
  workdir_parent:

• Uruchomić wstępnie kontenery aby wygenerowany został certyfikat CA mitmproxy:

cd /etc/runner
docker-compose up -d
# Po zakończeniu powyższego polecenia odczekać kilka sekund aby dać czas aplikacji mitmproxy na zainicjalizowanie swoich danych i certyfikatów.
docker-compose down

• Dodać wygenerowany certyfikat CA mitmproxy do listy zaufanych ośrodków certyfikacji w systemie Debian (z której korzystać będą również aplikacje w kontenerach):

cp /etc/mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
update-ca-certificates --fresh

• Uruchomić kontenery i wykonać rejestrację runnera w VCS korzystając z tym celu z tokena rejestracji dostępnego w Akcje > Runnery > Utwórz nowy runner > Registration token w ustawieniach aplikacji VCS lub w ustawieniach organizacji lub użytkownika lub repozytorium - w zależności od tego, który z tych obszarów ma być obsługiwany przez konfigurowany runner (poniższe zakłada token aQI7SPIIGJ1qKWkkOSXCgZfLja5oIiva0URK9Edp i rejestrację runnera w VCS pod nazwą runner1):

docker-compose up -d
docker exec -it runner /bin/sh
~ $ forgejo-runner register
INFO Registering runner, arch=amd64, os=linux, version=v11.1.1. 
WARN Runner in user-mode.                         
INFO Enter the Forgejo instance URL (for example, https://next.forgejo.org/): 
https://vcs.demo.cybo.pl/
INFO Enter the runner token:                      
aQI7SPIIGJ1qKWkkOSXCgZfLja5oIiva0URK9Edp
INFO Enter the runner name (if set empty, use hostname: ac2e36e23181): 
runner1
INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-20.04:docker://node:20-bookworm,ubuntu-18.04:docker://node:20-bookworm): 
# W tym miejscu można wpisać listę rozdzielonych przecinkami etykiet specyfikujących obsługiwane przez runnera obrazy kontenerów, które mają być dostępne dla procesów CI/CD lub pozostawić pustą wartość i wcisnąć Enter aby zaakceptować domyślne etykiety.
INFO Registering runner, name=runner1, instance=https://vcs.demo.cybo.pl/, labels=[docker:docker://data.forgejo.org/oci/node:20-bullseye]. 
DEBU Successfully pinged the Forgejo instance server 
INFO Runner registered successfully.              

~ $ exit
docker-compose down

• W pliku /etc/runner/docker-compose.yml usunąć linię

command: '/bin/sh -c "while : ; do sleep 1 ; done ;"'

i zamiast niej umieścić linię

command: '/bin/sh -c "sleep 5; forgejo-runner daemon --config /data/config.yml"'

• Uruchomić kontenery (będą one automatycznie uruchamiane również po restartach systemu):

docker-compose up -d

• Na stronie VCS z listą runnerów, z której pobierany był token rejestracji runnera, sprawdzić czy widoczny jest aktywny runner o nazwie runner1.

Uwagi:

• Warto rozważyć wprowadzenie następujących zmian w ustawieniach dedykowanego do procesów CI/CD użytkownika technicznego w aplikacji VCS:
  • zmienić wartość parametru Maksymalna ilość repozytoriów na 0 aby użytkownik ten nie mógł tworzyć własnych repozytoriów,
  • włączyć opcję Ograniczone konto jeśli użytkownik ten nie powinien mieć dostępu do repozytoriów publicznych znajdujących się w VCS,
  • wyłączyć opcję Może tworzyć organizacje aby użytkownik ten nie mógł tworzyć organizacji.
• Procesy CI/CD uruchamiane w kontenerach przez runnera w oparciu o powyższą konfigurację mogą korzystać z mitmproxy (za pomocą zmiennych środowiskowych https_proxy i http_proxy) co pozwala tym procesom (o ile potrafią korzystać z proxy) np. na sięganie do VCS z uprawnieniami klucza i certyfikatu z pliku /etc/mitmproxy/cc/vcs.demo.cybo.pl.pem.
• Po wygaśnięciu ważności certyfikatu umieszczonego w pliku /etc/mitmproxy/cc/vcs.demo.cybo.pl.pem, w celu dalszego korzystania z runnera należy zastąpić treść tego pliku treścią nowego klucza i certyfikatu w sposób analogiczny jak w trakcie opisanej wyżej instalacji a następnie zrestartować maszynę wirtualną Debian.
• Powyższa konfiguracja parametrów valid_volumes i options w pliku /etc/runner/data/config.yml zakłada, że kontenery CI/CD tworzone przez runnera będą korzystać z listy zaufanych ośrodków certyfikacji hosta Debian i w analogiczny sposób jak robi to host Debian (zgodność ścieżek zawierających pliki certyfikatów CA).

Zobacz też:

• VCS
• Forgejo Actions Basic concepts
• Forgejo Actions administrator guide