GitLab FI
GitLab Continuous Integration
GitLab Continuous Integration (CI) slouží k automatizaci některých úkolů
při vývoji v repozitáři, nejčastěji pro automatické jednotkové testování.
Pro použití GitLab CI lze
nakonfigurovat svůj vlastní fyzický nebo virtuální stroj
(viz virtualizace Stratus.FI).
Navíc lze také použít fakultní stroj gitlab-ci.fi.muni.cz
.
Shrnutí
Fakultní gitlab-ci.fi
používá oficiální
GitLab Runner
s kontejnerovou izolací ve službě Docker.
Po spuštění nového úkolu (např. po git push
do repozitáře)
GitLab Runner požádá Docker o vytvoření nového kontejneru z obrazu, který
je deklarován v repozitáři v souboru .gitlab-ci.yml
.
Do kontejneru se naklonuje repozitář a spustí se úkoly popsané ve zmíněném souboru.
Po skončení se kontejner zruší a výsledek se vrátí GitLabu, který jej zobrazí v sekci CI/CD.
Konfigurace projektu pro gitlab-ci.fi.muni.cz
Nejdříve si přečtěte úvodní informace
pro používání GitLab CI/CD.
Dále budete potřebovat dokumentaci
ke .gitlab-ci.yml
.
Výběr obrazu
Používaný obraz se deklaruje v konfiguraci .gitlab-ci.yml
jako hodnota klíče image
.
Formát je buď REPOSITORY:TAG
nebo REPOSITORY
(výchozí značka se pak
použije latest
). Pokud nezadáte žádný obraz, použije
se alpine:latest
.
image: maven:latest
Výběr verze
Značky Docker obrazů nejsou statické, tj. X:3.0
je pouze
symbolický název pro nějakou verzi obrazu, přičemž se kdykoliv může stát,
že správce repozitáře změní obraz, na který značka ukazuje.
Verzování obrazů i význam samotných verzí závisí na správcích
jednotlivých Docker repozitářů, obecně je však vhodné dodržovat
principy sémantického verzování.
Pokud je to možné, preferujte obrazy v co nejobecnější hlavní verzi
(např. preferujte X:3
místo X:3.5.0
), aby měl váš
projekt k dispozici obraz s bezpečnostními záplatami a opravami chyb
v použitém softvéru.
Nedoporučujeme však používat latest
pro
důležité projekty. Tato symbolická značka obvykle ukazuje na
nejnovější stabilní verzi obrazu, může se však bez varování posunout
na novější verzi, která není zpětně kompatibilní.
Nastavení značky
Aby se stroj nezatěžoval úkoly z repozitářů, které mají nastavené vlastní CI,
akceptuje gitlab-ci.fi
úkoly pouze z těch projektů, které jsou označené
značkou shared-fi
, což lze nastavit následovně:
- v nastavení Settings → General → Permissions povolte možnost Pipelines, pokud ještě povolena není
-
v nastavení
.gitlab-ci.yml
přidejte značkushared-fi
do každého cíle, např.:build: tags: - shared-fi
Nastavení artefaktů
Pro projekty, které vytváří artefakty, doporučujeme nastavit CI tak, aby je GitLab automaticky uklízel, když se vytvoří novější.
Nejdřív v projektu zabezpečte, že GitLab zachová poslední artefakt:
Projekt → Settings → CI/CD → Artifacts
→ zaškrtněte Keep artifacts from most recent successful jobs
Pak do .gitlab-ci.yml
přidejte nastavení, které nastaví životnost
artefaktů na velmi malou hodnotu (méně než 2 hodiny, např. 10 minut).
Toto nastavte pro každý úkol JOB
.
Díky nastavení výše bude poslední artefakt zachován i po vypršení životnosti.
‹JOB›:
artifacts:
…
expire_in: 10 minutes
Ukázky
Ve fakultním GitLab FI se můžete podívat do projektu unix/ci-examples
, kde naleznete příklady konfigurace CI pro jednoduché projekty.
Container Registry
Služba Container Registry dává uživatelům možnost uložit si k projektu Docker obrazy, které pak lze využít v CI nebo jiných projektech.
Obrazy nemusí s obsahem projektu nijak souviset.
Pravděpodobně však budete k obrazu mít i Dockerfile
a další závislosti,
doporučujeme si tedy pro tyto soubory vytvořit repozitář, který bude zároveň
udržovat aktuální verzi obrazu.
Ke Container Registry se lze připojit na stroji gitlab.fi.muni.cz
a portu 5050
.
Nastavení služby
Zapnutí služby
V projektu, který má udržovat sestavené obrazy, zapněte
Settings → General → Visibility, project features, permissions → Container Registry.
Službu není nutno zapínat pro projekty, které mají obraz pouze používat v CI.Omezení počtu značek
Obrazy v Container Registry zabírají obvykle mnoho místa. Častá změna značek může diskový prostor rychle vyčerpat, proto zapněte pro projekt automatické čištění:
V nastavení Settings → Packages & Registries zapněte možnost Clean up image tags. Doporučujeme taky změnit nastavení Keep the most recent: na hodnotu 5 tags per image name.Přístup k obrazu
Přístup k obrazům se obecně řídí přístupovými právy k rodičovskému projektu:
- Private – Pouze členové projektu
- Internal – Pouze osoby přihlášené do GitLab FI
- Public – Bez omezení
Vytvoření obrazu
Obraz vytvořte lokálně ve vlastní instanci Dockeru (příkazy níže).
Lze nastavit i automatické sestavování obrazu pomocí CI,
musíte si však pro ni z bezpečnostních důvodů nastavit vlastní CI Runner.
Název obrazu, který se má umístit do GitLab Container Registry, musí začínat
doménou a portem ve formátu gitlab.fi.muni.cz:5050
,
a pokračovat cestou k projektu.
Například pro projekt https://gitlab.fi.muni.cz/NAMESPACE/PROJECT.git
tedy lze vytvořit obrazy s názvy tvaru
gitlab.fi.muni.cz:5050/NAMESPACE/PROJECT:TAG
gitlab.fi.muni.cz:5050/NAMESPACE/PROJECT/IMAGE:TAG
gitlab.fi.muni.cz:5050/NAMESPACE/PROJECT/NAME/IMAGE:TAG
Pokud jste s obrazem spokojeni, můžete jej nahrát do Container Registry:
docker login --username ‹LOGIN› gitlab.fi.muni.cz:5050 docker push gitlab.fi.muni.cz:5050/NAMESPACE/...
V prvním příkazu místo ‹LOGIN›
použijte svůj fakultní login.
Příkaz se po spuštění zeptá na heslo; zadejte fakultní heslo
nebo přístupový token GitLabu
(musí mít alespoň rozsahy read_registry
a write_registry
i přesto, že podle dokumentace stačí pouze to druhé – je zřejmě o
chybu).
Pro ukázku se můžete podívat na soubor Makefile
v repozitáři
https://gitlab.fi.muni.cz/xlacko1/pb173-perl-image.
Použití v GitLab CI
Nový obraz lze používat jak ve vlastní instanci Dockeru, tak i v úlohách GitLab CI/CD. Pouze v nastavení image:
uveďte celou cestu k vlastnímu obrazu.
Například, pokud v repozitáři
https://gitlab.fi.muni.cz/xlacko1/pb173-perl-image
chceme vytvořit obraz s názvem perl-5.32:1.0
, pak v adresáři
s Dockerfile
pro tento obraz vykonáme příkazy:
$ docker build -t gitlab.fi.muni.cz:5050/xlacko1/pb173-perl-image/perl-5.32:1.0 . $ docker login --username LOGIN gitlab.fi.muni.cz:5050 $ docker push gitlab.fi.muni.cz:5050/xlacko1/pb173-perl-image/perl-5.32:1.0
V projektu, ve kterém chceme vytvořený obraz použít pro CI, deklarujeme
v souboru .gitlab-ci.yml
:
image: https://gitlab.fi.muni.cz/xlacko1/pb173-perl-image:1.0
# The 'shared-fi' tag is necessary to use the faculty-wide CI
default:
tags:
- shared-fi
Automatické sestavování obrazu
GitLab CI lze použít k automatickému sestavení Docker obrazu a jeho
nahrání do Container Registry, typicky pomocí obrazu
docker:dind
(Docker-in-Docker).
Tato operace však vyžaduje povolit pro kontejner s úlohou privilegovaný režim, aby mohl kontejner zadávat Docker démonovi příkazy. Zároveň však umožní kontejneru obejít bezpečnostní mechanismy systému a převzít nad ním kontrolu. Proto je tato možnost na sdíleném GitLab CI vypnuta.
Pokud chcete sestavovat obrazy automaticky, musíte si nastavit vlastní CI Runner. Doporučujeme využít virtuální stroj ve Stratus.FI. Alternativně můžete službu spustit i na vlastním počítači, mějte však na paměti, že takto si můžete otevřít prostor na Privilege Escalation útok.
Virtuální stroj nebo počítač?
Pro tento úkol silně doporučujeme použít virtuální stroj ve službě Stratus.FI. Mělo by stačit využít předinstalovaný virtuální stroj.
Využití vlastního počítače je taky možné. Berte však na vědomí, že v případě chyby konfigurace hrozí riziko eskalace oprávnění nebo převzetí kontroly nad počítačem. Totéž hrozí i pro virtuální stroj, rozsah problému je však v tomto případě menší.Docker in Docker
Nakonfigurujte CI Runner pro sestavování Docker obrazů podle oficiálního návodu. Doporučujeme možnost Docker-in-Docker.Registrace
Zaregistrujte Runner pouze pro projekt, ve kterém se mají sestavovat obrazy, vizte Project Runners.Zabezpečení projektu
Zabezpečte, aby spuštění úlohy v CI mohli provádět pouze důvěryhodní uživatele v projektu (Owner, Maintainer). Zejména zabraňte tomu, aby nedůvěryhodní uživatelé mohli vytvořit Merge Request s vlastním kódem, pro který by se spustila úloha.
Vizte Protected Branches a Pravidla pro.gitlab-ci.yml
.Umístnění .gitlab-ci.yml
Potenciální útočník si může.gitlab-ci.yml
změnit dle libosti a obejít nastavení výše. Toto je vážný problém zejména pro veřejné a interní projekty.
Tento problém lze vyřešit nastavením projektu tak, aby.gitlab-ci.yml
hledal v jiném privátním repozitáři, kde ho mohou upravovat pouze důvěryhodní uživatelé. Lokální soubor se pak bude ignorovat. Vizte Custom CI/CD configuration file → Custom CI/CD configuration file examples.
Pozor, nastaveníCODEOWNERS
nestačí, pouze zabrání nežádanému Merge v případě, že se změnil chráněný soubor, ale úkoly pro CI se stále spustí.
Nakonec, zvažte, zda je automatické sestavování obrazu skutečně nevyhnutné. Pokud obraz sestavujete zřídka, nejbezpečnější možnost je sestavit obraz ve vlastní instanci Dockeru podle návodu výše.
Časté potíže a řešení
Zaseknuté úkoly
Pokud po konfiguraci projektu narazíte na chybu Job is stuck,
pravděpodobně jste v konfiguraci úkolu neuvedli značku shared-fi
.
Zkontrolujte si nastavení podle postupu výše.
Nelze používat Docker příkazy v úloze
Pokud narazíte na chybu typu dial tcp: lookup docker on 147.251.48.14:53: no such host
,
pravděpodobně se snažíte použít fakultní CI Runner v privilegovaném režimu.
To není z bezpečnostních důvodů povoleno, vizte
Automatické sestavování obrazu výše.