🥇Tartalom-alapú címkézés a werf gyűjtőben: miért és hogyan működik?

werf — a nyílt forráskódú GitOps CLI eszközünk az alkalmazások Kubernetesbe történő összeállításához és szállításához. Az v1.1-es kiadásban bemutattunk egy új funkciót a képkészítőben: képek címkézése a tartalom vagy tartalmi alapú címkézés. Eddig a werf címkézési sémája az volt, hogy a Docker képeket a Git címkéje, Git ága vagy Git commitja alapján címkéztük. Ennek a három sémának azonban megvannak a hátrányai, amelyeket a címkézés új stratégiája teljes mértékben megold. Részletek a következő oldalakon.

Mikroszolgáltatáscsomag kiadása egy Git tárolóból

Gyakori helyzet, amikor az alkalmazás többé-kevésbé független szolgáltatásokra van bontva. Ezeknek a szolgáltatásoknak a kiadásai függetlenül történhetnek: egyszerre egy vagy több szolgáltatás is kiadható, míg a többi szolgáltatásnak változtatás nélkül kell működnie. Kód tárolása és projektkezelés szempontjából azonban kényelmesebb, ha ezek a szolgáltatások egyetlen tárolóban találhatók.

Előfordulhat, hogy a szolgáltatások valóban függetlenek és nem kapcsolódnak egyetlen alkalmazáshoz. Ilyen esetben külön projektekben helyezkednek el, és a kiadásokat minden projektben külön CI/CD folyamatokon keresztül hajtják végre.

A valóságban azonban a fejlesztők gyakran bontják le az egyes alkalmazásokat több mikroszolgáltatásra, de mindegyikhez külön tárolót és projektet létrehozni… — nyilvánvaló overkill. Pontosan erről a helyzetről lesz szó: több ilyen mikroszolgáltatás található egyetlen projekt tárolójában, és a kiadások egyetlen CI/CD folyamaton keresztül történnek.

Címkézés Git ágon és Git címkén

Tegyük fel, hogy a legelterjedtebb címkézési stratégiát használjuk — tag-or-branch. A Git ágak esetében a képeket az ágnévvel címkézzük, egy ágon egyszerre csak egy publikált kép létezhet az ágnév alapján. A Git címkék esetében a képeket a címke nevével címkézzük.

Amikor új Git címkét hozunk létre — például egy új verzió kiadásakor — a projekt összes képéhez új Docker címke készül a Docker Registry-ben:

myregistry.org/myproject/frontend:v1.1.10
myregistry.org/myproject/myservice1:v1.1.10
myregistry.org/myproject/myservice2:v1.1.10
myregistry.org/myproject/myservice3:v1.1.10
myregistry.org/myproject/myservice4:v1.1.10
myregistry.org/myproject/myservice5:v1.1.10
myregistry.org/myproject/database:v1.1.10

Ezek az új képek nevei Helm-sablonokon keresztül kerülnek be a Kubernetes konfigurációba. A telepítés indításakor werf deploy az érintett mező frissítése megtörténik kép a Kubernetes erőforrások manifesztjeiben és az érintett erőforrások újraindítása a kép nevének megváltozása miatt.

Probléma: ha a korábbi kiadás (Git-címke) ténylegesen nem változott meg a kép tartalmával, csak a Docker-címkéje, akkor túlzott az alkalmazás újraindítása és ennek következtében esetleg némi leállás történik. Bár nem voltak valós okai ennek az újraindításnak.

Ennek következtében a jelenlegi címkézési séma miatt több külön Git-repozitóriumot kell létrehozni, és felmerül a probléma az ezeknek a repozitóriumoknak a kiadásának szervezésével. Összességében ez a séma túlterhelt és bonyolult. Jobb, ha sok szolgáltatást egyetlen repozitóriumban egyesítünk, és olyan Docker-címkéket hozunk létre, hogy elkerüljük a felesleges újraindításokat.

Címkézés Git-commit alapján

A werf-ben is létezik Git-commitokkal kapcsolatos címkézési stratégia.

A Git-commit a Git-repozitórium tartalmának azonosítója, és a Git-repozitóriumban a fájlok módosításainak történetétől függ, ezért logikusnak tűnik, hogy ezt használjuk a Docker Registry-ben lévő képek címkézésére.

Azonban a Git-commit alapján történő címkézésnek ugyanazok a hátrányai vannak, mint a Git-ágak vagy Git-címkék esetében:

Lehetett létrehozni üres commitot, amely nem változtat a fájlokon, miközben a Docker-kép címkéje megváltozik.
Lehetett létrehozni merge commitot, amely szintén nem változtat a fájlokon, de a Docker-kép címkéje megváltozik.
Lehetett létrehozni olyan commitot, amely a Git-ben olyan fájlokat változtat meg, amelyek nem kerülnek be a képbe, így a Docker-kép címkéje ismét megváltozik.

A Git-ág neve szerinti címkézés nem tükrözi a kép verzióját

Van egy másik probléma is, amely a Git-ágak szerinti címkézési stratégiához kapcsolódik.

A branch nevének szerinti címkézés addig működik, amíg a branch commitjei időrendi sorrendben összegyűjtésre kerülnek.

Ha a jelenlegi séma szerint a felhasználó egy régi commit újragyártását kezdeményezi, amely valamilyen branch-hez kapcsolódik, akkor a werf felül fogja írni a képet a régi commit újonnan összegyártott verziójával a megfelelő Docker-címke szerint. Azok a Deploymentek, amelyek ezt a címkét használják, a pod-ok újraindításakor kockázatot vállalnak, hogy másik kép verziót húznak be, ami miatt az alkalmazásunk elveszíti a kapcsolatot a CI-rendszerrel, és szinkronizálatlanná válik.

Ezenkívül, ha egymás után sok push-t hajtanak végre egy ágon kis időközönként, a régi commit később is kerülhet a feldolgozásra, mint az újabb: a régi image verzió felülírhatja az újat a Git ág címkéjén. Ezeket a problémákat egy CI/CD rendszer (például a GitLab CI az utolsó commitok sorozatánál egy pipeline-t indít) képes kezelni. Azonban ezt nem minden rendszer támogatja, így megbízhatóbb módot kell találni e radikális probléma megelőzésére.

Mi az a tartalom-alapú címkézés?

Tehát mi is az a tartalom-alapú címkézés — a képek címkézése a tartalom alapján.

A Docker címkék létrehozásához nem a Git primitívumokat (Git ágat, Git címkét…) használjuk, hanem a következőkkel összefüggő ellenőrző összeget:

a kép tartalmával. A címke azonosítója tükrözi a tartalmat. Az új verzió összeállításakor ez az azonosító nem változik, ha a képen lévő fájlok nem módosultak;
a kép létrehozásának történetével a Git-ben. A különböző Git ágakhoz és a werf által különböző építési történetekhez tartozó képek különböző címke-azonosítókat fog kapni.

Egy ilyen címke-azonosítóként funkcionál a úgynevezett stádiumok aláírása.

Minden kép egy sorozatból áll: a, before-install, git-archive, install, imports-after-install, before-setup,… git-latest-patch stb. Minden stádiumhoz van egy azonosító, ami a tartalmát tükrözi, — stádium aláírás (stage signature).

Az végleges kép, amely ezekből a stádiumokból áll, a stádiumok sorozatának aláírásával van címkézve — stages signature, — amely általánosítja az összes stádium tartalmát.

Minden képnél az konfigurációban werf.yaml általánosan van egy ilyen aláírása, és ennek megfelelően Docker címkéje is.

A stádiumok aláírása megoldja az összes említett problémát:

Ellenáll az üres Git commitoknak.
Ellenáll azoknak a Git commitoknak, amelyek fájlokat módosítanak, amelyek nem relevánsak a kép szempontjából.
Nem okoz problémát a legfrissebb kép felülírásakor, amikor a régi Git commitokhoz újraépítéseket indítanak.

Most ez az ajánlott címkézési stratégia, amely alapértelmezés szerint a werf-ben használatos minden CI-rendszerhez.

Hogyan lehet ezt aktiválni és használni a werf-ben

A kapcsolódó opció elérhető a parancsban werf publish: --tag-by-stages-signature=true|false

A CI rendszerben a címkézési stratégiát a parancs határozza meg werf ci-env. Korábban ehhez a paramétert a következőképpen határozták meg werf ci-env --tagging-strategy=tag-or-branch. Most, ha megadjuk werf ci-env --tagging-strategy=stages-signature vagy ne is adjuk meg ezt az opciót, a werf alapértelmezés szerint a címkézési stratégiát fogja használni stages-signature. A parancs werf ci-env automatikusan beállítja a szükséges zászlókat a parancs számára werf build-and-publish SysWOW64 werf publish), tehát nincs szükség további opciók megadására ezekhez a parancsokhoz.

Például a parancs:

werf publish --stages-storage :local --images-repo registry.hello.com/web/core/system --tag-by-stages-signature

…a következő képeket létrehozhatja:

registry.hello.com/web/core/system/backend:4ef339f84ca22247f01fb335bb19f46c4434014d8daa3d5d6f0e386d
registry.hello.com/web/core/system/frontend:f44206457e0a4c8a54655543f749799d10a9fe945896dab1c16996c6

Itt 4ef339f84ca22247f01fb335bb19f46c4434014d8daa3d5d6f0e386d — ez a kép fázisának aláírása backend, és f44206457e0a4c8a54655543f749799d10a9fe945896dab1c16996c6 — a kép fázisának aláírása frontend.

Speciális funkciók használata esetén werf_container_image és werf_container_env a Helm sablonokban semmit nem kell módosítani: ezek a funkciók automatikusan megfelelő képneveket generálnak.

Példa CI-rendszer konfigurációjára:

type multiwerf && source <(multiwerf use 1.1 beta)
type werf && source <(werf ci-env gitlab)
werf build-and-publish|deploy

További információ a beállításokról a dokumentációban található:

Összesen

Az új opció werf publish --tag-by-stages-signature=true|false.
Az opció új értéke werf ci-env --tagging-strategy=stages-signature|tag-or-branch (ha nem adja meg, alapértelmezés szerint stages-signature).
Ha korábban Git-commit alapú címkézési opciókat használtak (WERF_TAG_GIT_COMMIT vagy az opció werf publish --tag-git-commit COMMIT), akkor kötelező váltani a címkézési stratégiára stages-signature.
Az új projekteket a lehető leghamarabb érdemes az új címkézési rendszerre váltani.
Öreg projekteknél a werf 1.1-re való áttéréskor célszerű az új címkézési rendszerre váltani, azonban a régi tag-or-branch továbbra is támogatott.

A tartalom-alapú címkézés megoldja a cikkben felsorolt problémákat:

A Docker-címke nevének ellenállása a üres Git-commitokkal szemben.
A Docker-címke nevének ellenállása a Git-commitokkal szemben, amelyek irreleváns fájlokat módosítanak a képpel kapcsolatban.
Nem okoz problémát a legfrissebb kép felülírása a régi Git-commitok újraépítése során a Git-ágakhoz.

Használja! És ne felejtsen el benézni hozzánk a GitHub, hogy létrehozzon egy issue-t, vagy megtalálja a már meglévőt, lájkolja, hozzon létre PR-t, vagy csak figyelje a projekt fejlődését.