🥇Inhaltsbasierte Tagging im werf-Builder: Warum und wie funktioniert das?

werf — unser GitOps-CLI-Tool mit offenem Quellcode zur Erstellung und Bereitstellung von Anwendungen in Kubernetes. In der Version v1.1 wurde eine neue Funktion im Image-Building vorgestellt: das Tagging von Images basierend auf dem Inhalt oder content-based tagging. Bisher war das typische Tagging-Schema in werf, dass Docker-Images anhand des Git-Tags, des Git-Zweigs oder des Git-Commits getaggt wurden. Doch alle diese Schemata haben Nachteile, die durch die neue Tagging-Strategie vollständig gelöst werden. Details dazu und was sie so gut macht, finden Sie darunter.

Die Bereitstellung eines Satzes von Mikroservices aus einem einzelnen Git-Repository

Es gibt häufig Situationen, in denen eine Anwendung in mehrere mehr oder weniger unabhängige Dienste aufgeteilt ist. Die Bereitstellungen dieser Dienste können unabhängig voneinander erfolgen: auf einmal kann ein oder mehrere Dienste bereitgestellt werden, während die anderen weiterhin ohne Änderungen arbeiten müssen. Aus der Sicht der Codeverwaltung und des Projektmanagements ist es jedoch praktischer, solche Dienste in einem einzigen Repository zu halten.

Es gibt Situationen, in denen die Dienste tatsächlich unabhängig sind und nicht zu einer einzigen Anwendung gehören. In diesem Fall befinden sie sich in separaten Projekten, und die Bereitstellung erfolgt über separate CI/CD-Prozesse in jedem dieser Projekte.

In der Realität jedoch zerlegen Entwickler oft eine einheitliche Anwendung in mehrere Mikroservices, aber für jeden einen separaten Repository und ein Projekt anzulegen, wäre ... ein offensichtlicher Overkill. Genau über diese Situation wird im Folgenden gesprochen: mehrere solche Mikroservices liegen in einem einzigen Repository des Projekts und die Bereitstellungen erfolgen über einen einzigen CI/CD-Prozess.

Tagging nach Git-Zweig und Git-Tag

Angenommen, es wird die am weitesten verbreitete Tagging-Strategie verwendet — tag-or-branch. Für Git-Zweige werden Images mit dem Namen des Zweigs getaggt, für einen Zweig existiert zu einem Zeitpunkt nur ein veröffentlichtes Image mit dem Namen dieses Zweigs. Für Git-Tags werden die Images entsprechend dem Tag-Namen getaggt.

Bei der Erstellung eines neuen Git-Tags — zum Beispiel bei der Veröffentlichung einer neuen Version — wird für alle Images des Projekts im Docker-Registry ein neuer Docker-Tag erstellt:

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

Diese neuen Bildnamen gelangen über Helm-Templates in die Kubernetes-Konfiguration. Bei der Ausführung des Deployments mit dem Befehl werf deploy erfolgt eine Aktualisierung des Feldes Image in den Manifesten der Kubernetes-Ressourcen und ein Neustart der entsprechenden Ressourcen aufgrund des geänderten Bildnamens.

Problem: falls sich der Inhalt des Images seit dem letzten Rollout (Git-Tag) tatsächlich nicht geändert hat, sondern nur dessen Docker-Tag, findet ein überflüssiger Neustart dieser Anwendung statt, wodurch möglicherweise eine Unterbrechung entsteht. Obwohl es keine wirklichen Gründe gab, für diesen Neustart.

Folglich muss bei dem aktuellen Taggingschema mehrere separate Git-Repositorys erstellt werden, und es entsteht das Problem, diese mehreren Repositorys auszuspielen. Insgesamt führt ein solches Schema zu einer Überlastung und Komplexität. Es ist besser, viele Dienste in einem einzigen Repository zu bündeln und Docker-Tags so zu setzen, dass überflüssige Neustarts vermieden werden.

Tagging nach Git-Commit

In werf gibt es auch eine Tagging-Strategie, die mit Git-Commits verbunden ist.

Ein Git-Commit ist der Identifier für den Inhalt des Git-Repositorys und hängt von der Änderungs-Historie der Dateien im Git-Repository ab, daher erscheint es logisch, ihn für das Tagging von Bildern im Docker-Registry zu verwenden.

Allerdings hat das Tagging nach Git-Commit die gleichen Nachteile wie das Tagging nach Git-Branches oder Git-Tags:

Es könnte ein leerer Commit erstellt worden sein, der keine Dateien ändert, während der Docker-Tag des Bildes geändert wird.
Es könnte ein Merge-Commit erstellt worden sein, der keine Dateien ändert, während der Docker-Tag des Bildes geändert wird.
Es könnte ein Commit erstellt worden sein, der die Dateien in Git ändert, die nicht im Image importiert werden, und der Docker-Tag des Bildes wird erneut geändert.

Tagging nach dem Namen des Git-Branches spiegelt nicht die Version des Images wider

Es gibt noch ein weiteres Problem, das mit der Tagging-Strategie nach Git-Branches verbunden ist.

Tagging nach dem Namen des Branches funktioniert, solange die Commits dieses Branches chronologisch aufeinanderfolgend gesammelt werden.

Wenn der Benutzer im aktuellen Schema eine Neubau des alten Commits, der mit einem bestimmten Branch verbunden ist, startet, wird werf das Image gemäß dem entsprechenden Docker-Tag mit der neu gebauten Version des Images für den alten Commit überschreiben. Die Deployments, die dieses Tag verwenden, laufen ab diesem Moment Gefahr, beim Neustart der Pods eine andere Version des Images zu ziehen, was dazu führen kann, dass unsere Anwendung die Verbindung zum CI-System verliert und desynchronisiert wird.

Darüber hinaus kann bei aufeinanderfolgenden Pushes in einen Branch mit geringen Zeitabständen zwischen ihnen der alte Commit später gebaut werden als der neuere: Die alte Version des Images überschreibt die neue nach dem Git-Branch-Tag. Solche Probleme können von einem CI/CD-System (z. B. wird in GitLab CI für eine Reihe von Commits das Pipeline des letzten Commits gestartet) gelöst werden. Allerdings unterstützen nicht alle Systeme dies, und es sollte eine zuverlässigere Methode zur Vermeidung eines so fundamentalen Problems geben.

Was ist Content-based Tagging?

Also, was ist Content-based Tagging – das Tagging von Images basierend auf deren Inhalt.

Zur Erstellung von Docker-Tags werden nicht die primitiven Git-Elemente (Git-Branch, Git-Tag…) verwendet, sondern eine Prüfziffer, die verbunden ist mit:

dem Inhalt des Images. Die Tag-ID des Images spiegelt dessen Inhalt wider. Bei der Erstellung einer neuen Version wird diese ID nicht verändert, sofern sich die Dateien im Image nicht geändert haben;
der Historie der Erstellung dieses Images in Git. Images, die mit verschiedenen Git-Branches und unterschiedlichen Bauhistorien über werf verbunden sind, haben unterschiedliche Tag-IDs.

So eine Tag-ID ist die sogenannte Stufensignatur des Images.

Jedes Image besteht aus einer Reihe von Stufen: from, before-install, git-archive, install, imports-after-install, before-setup,… git-latest-patch usw. Jede Stufe hat eine ID, die ihren Inhalt widerspiegelt, — Stufensignatur (stage signature).

Das endgültige Bild, das aus diesen Stufen besteht, wird mit der sogenannten Signatur der Stufensammlung getaggt — stages signature, — die verallgemeinernd für alle Stufen des Images ist.

Jedes Image aus der Konfiguration werf.yaml wird im Allgemeinen eine solche Signatur und damit einen entsprechenden Docker-Tag haben.

Die Stufensignatur löst alle genannten Probleme:

Ist resistent gegen leere Git-Commits.
Ist resistent gegen Git-Commits, die Dateien verändern, die nicht relevant für das Image sind.
Führt nicht zu einem Problem mit der Überschreibung der aktuellen Version des Images beim Neustart von Builds für alte Git-Commits des Branches.

Dies ist jetzt die empfohlene Tagging-Strategie und wird standardmäßig in werf für alle CI-Systeme verwendet.

Wie man es in werf aktiviert und verwendet

Die entsprechende Option wurde im Befehl hinzugefügt werf publish: --tag-by-stages-signature=true|false

In der CI-System wird die Tagging-Strategie durch den Befehl festgelegt werf ci-env. Zuvor wurde dafür der Parameter definiert werf ci-env --tagging-strategy=tag-or-branch. Wenn nun werf ci-env --tagging-strategy=stages-signature oder diese Option weggelassen wird, verwendet werf standardmäßig die Tagging-Strategie stages-signature. Der Befehl werf ci-env stellt automatisch die erforderlichen Flags für den Befehl ein werf build-and-publish (oder werf publish), daher müssen für diese Befehle keine zusätzlichen Optionen angegeben werden.

Beispielsweise der Befehl:

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

… kann die folgenden Images erstellen:

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

Hier 4ef339f84ca22247f01fb335bb19f46c4434014d8daa3d5d6f0e386d — das ist die Signatur der Stufen des Images backend, und f44206457e0a4c8a54655543f749799d10a9fe945896dab1c16996c6 — Signatur der Stufen des Images frontend.

Bei der Verwendung spezieller Funktionen werf_container_image und werf_container_env muss im Helm-Template nichts geändert werden: diese Funktionen generieren automatisch die korrekten Image-Namen.

Beispielkonfiguration im CI-System:

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

Weitere Informationen zur Konfiguration finden Sie in der Dokumentation:

Insgesamt

Neue Option werf publish --tag-by-stages-signature=true|false.
Neuer Wert der Option werf ci-env --tagging-strategy=stages-signature|tag-or-branch (wenn nicht angegeben, wird standardmäßig stages-signature).
Wenn zuvor Tags nach Git-Commits verwendet wurden (WERF_TAG_GIT_COMMIT oder die Option werf publish --tag-git-commit COMMIT), muss unbedingt auf die Tagging-Strategie umgestellt werden. stages-signature.
Neue Projekte sollten sofort auf das neue Tagging-System umgestellt werden.
Alte Projekte sollten beim Übergang zu werf 1.1 idealerweise auf das neue Tagging-System umgestellt werden, jedoch wird die alte tag-or-branch weiterhin unterstützt.

Content-basiertes Tagging löst alle im Artikel angesprochenen Probleme:

Widerstandsvermögen des Docker-Tag-Namens gegen leere Git-Commits.
Widerstandsvermögen des Docker-Tag-Namens gegen Git-Commits, die irrelevante Dateien für das Image ändern.
Führt nicht zu Problemen beim Überschreiben der aktuellen Version des Images bei einem Neustart von Builds für alte Git-Commits in Git-Zweigen.

Nutzen Sie es! Und vergessen Sie nicht, uns auf GitHub, um ein Issue zu erstellen oder ein bereits bestehendes zu finden, einen Daumen hoch zu geben, einen PR zu erstellen oder einfach den Fortschritt des Projekts zu beobachten.