A modern szoftverfejlesztés egyik alappillére a Folyamatos Integráció és Folyamatos Szállítás (CI/CD). Ez a módszertan lehetővé teszi a fejlesztők számára, hogy gyorsabban, megbízhatóbban és hatékonyabban szállítsanak kódot. A GitLab egy rendkívül népszerű platform, amely beépített CI/CD funkciókat kínál, és a kulcsfontosságú eleme ennek a rendszernek a GitLab Runner. Bár a GitLab.com biztosít megosztott Runner-eket, sok esetben előnyösebb, ha saját, dedikált Runner-t állítunk be. Különösen igaz ez, ha specifikus erőforrásokra, egyedi szoftverekre vagy szigorúbb biztonsági kontrollra van szükségünk. Ebben a részletes útmutatóban lépésről lépésre bemutatjuk, hogyan állíthatod be a saját GitLab Runner-edet Dockerrel, hogy maximális kontrollt és rugalmasságot élvezhess.
Mi az a GitLab Runner és miért van rá szükséged?
A GitLab CI/CD lényege, hogy a projekt gyökérkönyvtárában található .gitlab-ci.yml fájlban definiált utasításokat futtatja a kód változásai (pl. push, merge request) alapján. Ezek az utasítások lehetnek tesztek, fordítások, csomagolás, telepítés és sok más. Ahhoz, hogy ezek a feladatok végrehajtódjanak, egy végrehajtó környezetre van szükség: ez a GitLab Runner.
A Runner egy könnyűsúlyú, elosztott alkalmazás, amely a GitLab példányokkal kommunikál, lekérdezi a futtatandó feladatokat, végrehajtja azokat, majd visszaküldi az eredményeket. Lehet telepítve egy szerverre, egy virtuális gépre, vagy akár egy konténerbe is. Amikor saját Runner-t állítunk be, az alábbi előnyöket élvezhetjük:
- Erőforrás-kontroll: Teljesen irányíthatod a Runner rendelkezésére álló CPU, memória és lemezterület mennyiségét.
- Testreszabott környezet: Telepíthetsz rá bármilyen szoftvert, könyvtárat vagy eszközt, amire a CI/CD feladataidnak szüksége van.
- Gyorsabb build-ek: Nincs várakozás a megosztott Runner-ekre, és a lokális cache-elés is gyorsíthatja a folyamatokat.
- Biztonság: Különösen érzékeny projektek esetén a saját infrastruktúrán futó Runner fokozott biztonságot nyújt.
- Hálózati hozzáférés: Hozzáférhet olyan belső erőforrásokhoz (adatbázisok, API-k), amelyekhez egy publikus Runner nem férne hozzá.
Miért éppen Dockerrel?
A Docker egy konténerizációs platform, amely lehetővé teszi alkalmazások és azok függőségeinek csomagolását izolált konténerekbe. A GitLab Runner Docker executor használata számtalan előnnyel jár:
- Izoláció: Minden CI/CD feladat egy különálló Docker konténerben fut, ami garantálja, hogy a feladatok nem befolyásolják egymást és tiszta környezetben indulnak.
- Reprodukálhatóság: A build-ek mindig ugyanabban a környezetben futnak, csökkentve az „az én gépemen működik” típusú problémákat.
- Egyszerűség: A Runner telepítése és kezelése lényegesen egyszerűbb Dockerrel, mivel nem kell aggódni a rendszerfüggőségekért.
- Rugalmasság: Könnyedén válthatunk különböző Docker image-ek között a feladatokhoz, például különböző nyelvi verziókhoz (Python 3.8, Node.js 16).
- Skálázhatóság: Könnyen indítható több Runner példány vagy akár autoscaling megoldás is kiépíthető.
Előfeltételek
Mielőtt belevágnánk a konfigurációba, győződj meg róla, hogy a következőkre rendelkezel:
- GitLab Fiók és Projekt: Rendelkezz egy aktív GitLab fiókkal és egy projekttel, amelyhez hozzá szeretnéd adni a Runner-t.
- Fizikai vagy Virtuális Gép: Egy Linux, Windows vagy macOS alapú gép, ahol a Docker futni fog. Javasolt egy dedikált szerver vagy virtuális gép, megfelelő CPU-val és memóriával.
- Telepített Docker: Győződj meg róla, hogy a Docker telepítve van a gépeden, és a felhasználód jogosult a Docker parancsok futtatására (általában a felhasználó hozzáadása a
dockercsoporthoz). A telepítési útmutatókért látogass el a Docker hivatalos weboldalára.
Lépésről lépésre: Saját GitLab Runner beállítása Dockerrel
Most pedig térjünk rá a lényegre: a GitLab Runner beállítására Dockerrel.
1. Készítsünk egy konfigurációs mappát
A Runner konfigurációs fájljaihoz és a cache-hez szükségünk lesz egy állandó tárolóhelyre. Hozzunk létre egy mappát a host gépen, amit majd a Docker konténerbe csatolunk:
sudo mkdir -p /srv/gitlab-runner/configEzzel biztosítjuk, hogy a Runner beállításai és adatai fennmaradjanak, még akkor is, ha a Docker konténer újraindul vagy törlődik.
2. GitLab Runner Docker image letöltése
Töltsük le a hivatalos GitLab Runner Docker image-et. Ajánlott a latest címke használata, vagy egy konkrét verzió, ha ragaszkodunk hozzá:
docker pull gitlab/gitlab-runner:latest3. GitLab Runner regisztrálása
Ez a legfontosabb lépés. A regisztráció során összekapcsoljuk a Runner-t a GitLab példányunkkal. Ehhez szükségünk lesz a GitLab URL-re és egy regisztrációs tokenre. A token a GitLab projektedben (vagy csoportodban/példányodban) található a Settings > CI/CD > Runners menüpont alatt.
Futtassuk a következő Docker parancsot a regisztrációs folyamat elindításához. A --rm flag biztosítja, hogy a regisztráció után a konténer automatikusan törlődjön, hiszen ez csak egy egyszeri művelet.
docker run --rm -it
-v /srv/gitlab-runner/config:/etc/gitlab-runner
gitlab/gitlab-runner:latest registerA parancs futtatása után a Runner interaktívan kérdéseket fog feltenni:
- Enter the GitLab instance URL (e.g. https://gitlab.com/):
Add meg a GitLab példányod URL-jét, pl.
https://gitlab.com/vagy a saját privát GitLab szervered címét. - Enter the registration token:
Illeszd be a GitLab felületén (Settings > CI/CD > Runners) található token-t.
- Enter a description for the runner:
Adj egy könnyen azonosítható nevet a Runner-ednek, pl.
my-docker-runner-on-server-1. - Enter tags for the runner (comma-separated):
Ez egy nagyon fontos lépés! Itt adhatsz meg címkéket, amikkel később a
.gitlab-ci.ymlfájlban hivatkozhatsz erre a Runner-re. Például:docker, linux, my-private-runner. Ezekkel a tag-ekkel tudod majd irányítani, hogy melyik Runner futtassa az adott feladatot. - Enter an executor: docker, ssh, virtualbox, kubernetes, custom, parallels, shell, instance:
Válaszd a
dockeropciót. Ez a Runner motorja, amely a feladatokat Docker konténerekben fogja futtatni. - Enter the default Docker image (e.g. ruby:2.7):
Add meg az alapértelmezett Docker image-et, amit a Runner használni fog, ha a
.gitlab-ci.ymlfájlban nem specifikálsz másikat. Egy jó kiindulópont lehet:ubuntu:latest,alpine/git, vagy egy specifikus nyelv image-e, pl.python:3.9-slim.
Ha a regisztráció sikeres volt, a /srv/gitlab-runner/config/config.toml fájl létrejön a host gépen, és tartalmazni fogja a Runner beállításait. Ezt a fájlt később kézzel is szerkesztheted, ha szükséges.
4. GitLab Runner elindítása szolgáltatásként
Miután regisztráltad a Runner-t, elindíthatod azt egy háttérfolyamatként. Ez a konténer folyamatosan futni fog, és várja a GitLab-tól érkező feladatokat.
docker run -d --name gitlab-runner --restart always
-v /srv/gitlab-runner/config:/etc/gitlab-runner
-v /var/run/docker.sock:/var/run/docker.sock
gitlab/gitlab-runner:latestNézzük meg a parancs paramétereit:
-d: A konténert háttérben indítja (detached mode).--name gitlab-runner: Nevet ad a konténernek, így könnyebben hivatkozhatunk rá.--restart always: Biztosítja, hogy a konténer automatikusan újrainduljon, ha a host gép újraindul, vagy a konténer bármilyen okból leáll.-v /srv/gitlab-runner/config:/etc/gitlab-runner: Csatolja a korábban létrehozott konfigurációs mappát a konténerbe. Ez tartalmazza aconfig.tomlfájlt.-v /var/run/docker.sock:/var/run/docker.sock: Ez egy kulcsfontosságú paraméter! Ez teszi lehetővé, hogy a GitLab Runner a host gép Docker démonját használja a CI/CD feladatok konténereinek indításához. Ez az úgynevezett „Docker in Docker” (DinD) megközelítés egyszerűsített változata.
5. A Runner állapotának ellenőrzése
Ellenőrizd, hogy a Runner fut-e és megfelelően működik-e:
docker ps -a | grep gitlab-runnerLátnod kell a gitlab-runner nevű konténert Up státuszban.
Nézd meg a logokat is, ha bármilyen problémát tapasztalsz:
docker logs gitlab-runnerMost, ha visszalátogatsz a GitLab projekted Settings > CI/CD > Runners menüpontjához, látnod kell a frissen regisztrált Runner-edet, valószínűleg zöld jelzéssel, ami azt jelenti, hogy aktív és készen áll a feladatokra.
A .gitlab-ci.yml fájl konfigurálása
Most, hogy van egy saját Runner-ed, használnod kell azt a CI/CD pipeline-jaidban. A .gitlab-ci.yml fájlban a tags kulcsszóval hivatkozhatsz a Runner-edre. Emlékszel a regisztráció során megadott címkékre? Most jönnek jól!
stages:
- build
- test
build-job:
stage: build
image: node:16-alpine # Egyedi Docker image ehhez a jobhoz
script:
- echo "Building the project..."
- npm install
- npm run build
tags:
- docker # Ezzel hivatkozunk a saját Runner-ünkre
- my-private-runner
test-job:
stage: test
image: python:3.9-slim
script:
- echo "Running tests..."
- pip install -r requirements.txt
- pytest
tags:
- docker
- my-private-runner
A fenti példában a build-job és a test-job is a docker és my-private-runner címkével ellátott Runner-t fogja használni. Emellett minden job saját image-et is megadhat, így maximális rugalmasságot kapsz a futtatási környezetek terén.
Haladó beállítások és tippek
Saját Docker Image-ek használata
Létrehozhatsz és használhatsz saját Docker image-eket, amelyek előre telepített függőségeket tartalmaznak a projektjeidhez. Ezeket feltöltheted a GitLab Container Registry-be vagy bármely más Docker registry-be, és hivatkozhatsz rájuk a .gitlab-ci.yml fájlban.
Cache beállítása
A cache használatával jelentősen felgyorsíthatod a build-eket, mivel nem kell minden alkalommal újra letölteni a függőségeket (pl. node_modules, Maven repository). Ezt a .gitlab-ci.yml fájlban konfigurálhatod:
cache:
paths:
- node_modules/
- .gradle/
key: "$CI_COMMIT_REF_SLUG" # Gyakran használják a branch nevére, hogy branch-specifikus cache legyen
Service konténerek
A tesztek futtatásához gyakran szükség van adatbázisokra (pl. PostgreSQL, MySQL) vagy más szolgáltatásokra. Ezeket „service konténerekként” indíthatod a CI/CD job-ok mellett:
test-database:
stage: test
image: python:3.9-slim
services:
- postgres:latest # Futtat egy PostgreSQL konténert a job mellett
variables:
POSTGRES_DB: test_db
POSTGRES_USER: runner
POSTGRES_PASSWORD: password
script:
- pip install -r requirements.txt
- python manage.py migrate
- pytest
A services szekcióban megadott konténerek a job konténeréhez kapcsolódnak, és a szolgáltatás nevével (pl. postgres) érhetők el a job konténeréből.
Karbantartás és frissítés
A Runner konténert rendszeresen frissítened kell a legújabb verzióra a biztonsági javítások és új funkciók érdekében. Ehhez egyszerűen állítsd le, töröld, majd indítsd újra az image letöltésével együtt:
docker stop gitlab-runner
docker rm gitlab-runner
docker pull gitlab/gitlab-runner:latest
docker run -d --name gitlab-runner --restart always
-v /srv/gitlab-runner/config:/etc/gitlab-runner
-v /var/run/docker.sock:/var/run/docker.sock
gitlab/gitlab-runner:latestA konfigurációs fájl megmarad a host gépen, így nem kell újraregisztrálnod.
Biztonsági megfontolások
A /var/run/docker.sock megosztása a Runner konténerrel nagy hatalmat ad a konténernek (gyakorlatilag a host gépen is futtathat Docker parancsokat). Ügyelj rá, hogy a Runner-t megbízható környezetben futtasd, és csak olyan projektekhez add hozzá, amelyekben megbízol. Fontos, hogy a host gépedet rendszeresen frissítsd, és csak a szükséges portokat nyisd meg.
Gyakori hibák és elhárításuk
- „permission denied while trying to connect to the Docker daemon socket”: Ez általában azt jelenti, hogy a felhasználód nem tagja a
dockercsoportnak, vagy adocker.socknincs megfelelően csatolva. Ellenőrizd a felhasználó jogosultságait és a Docker parancsot. - „job stuck” (a job beragadt):
- Ellenőrizd, hogy a Runner fut-e (
docker ps). - Ellenőrizd, hogy a Runner elérhető-e a GitLab számára (Settings > CI/CD > Runners).
- Győződj meg róla, hogy a job-ban megadott
tagsmegegyezik a Runner regisztrációjakor megadott címkékkel. - Nézd meg a Runner logjait (
docker logs gitlab-runner).
- Ellenőrizd, hogy a Runner fut-e (
- „image not found” (image nem található): Ellenőrizd az image nevét a
.gitlab-ci.yml-ben vagy a Runner alapértelmezett image beállításában. Lehet, hogy elírtad, vagy az image privát és nincs hitelesítve a Runner. - Hálózati problémák: Ha a Runner-nek hálózati erőforrásokra van szüksége, győződj meg róla, hogy a host gép tűzfala engedélyezi a kimenő és bejövő forgalmat a szükséges portokon.
Összefoglalás
A saját GitLab Runner beállítása Dockerrel egy rendkívül hasznos lépés a CI/CD automatizálásod fejlesztésében. Növeli a projekted rugalmasságát, sebességét és biztonságát, miközben teljes kontrollt biztosít a build környezet felett. Bár a kezdeti beállítás igényel némi figyelmet, a hosszú távú előnyei messze felülmúlják ezt az erőfeszítést.
Reméljük, hogy ez az útmutató segített abban, hogy magabiztosan vágj bele a saját GitLab Runner-ed konfigurálásába. Ne félj kísérletezni a különböző Docker image-ekkel, cache beállításokkal és service konténerekkel, hogy optimalizáld a pipeline-jaidat a projekted specifikus igényei szerint. Sok sikert a CI/CD utazásodhoz!
Leave a Reply