Logo der codecentric AG, einem in Deutschland führenden IT-Consulting Unternehmen

Logo der codecentric AG einem in Deutschland führenden IT-Consulting Unternehmen

Data Effectiveness

Digitale Produkte & Lösungen

Digitale Souveränität

IT-Security

Künstliche Intelligenz

Software-Modernisierung

Leistungen von A bis Z ...

Leistungen

Arbeitsweise

Referenzen

Berlin

Bielefeld

Dortmund

Erfurt

Frankfurt am Main

Hamburg

Karlsruhe

Leipzig

München

Münster

Nürnberg

Solingen

Stuttgart

Standorte

Blog

Events

Fachmedien

Softwerker

Webinare

Wissens-Hub

Jobs

Unsere Kultur

Karriere

Über uns

Aktuelles

Kontakt

Alle Standorte

Du hast Fragen oder möchtest dich mit mir austauschen? Gern – trag einfach deine Kontaktdaten ein.

Contact Us | Sub-Navi-Kontakt oder Zero Search Hits

Kontakt aufnehmen

Marketing & Community Management

Konntest du keine Einträge zu deinem Thema finden?  

STANDORT-TEAM

Unser codecentric Team am Standort Erfurt stellt sich vor

codecentric Team Erfurt

Willkommen im Team Erfurt

Consultant & Developer

Senior IT Consultant

In diesem Artikel gehen wir darauf ein, wie mithilfe des Spring-Webflux-Projekts eine reaktive Anwendung erstellt werden kann und welche Herausforderungen dieser Ansatz mit sich bringt. Wir erläutern kurz, was Kotlin Coroutines sind und zeigen, wie die Herausforderungen des Reactive Programmings mit Spring Webflux mit einer Implementierung in Kotlin Coroutines umgangen oder zumindest abgefedert werden können.

## Reactive Programming mit Spring Webflux
In einem [vorangegangenen Artikel](https://www.codecentric.de/wissens-hub/blog/reactive-programming-spring-webflux) haben wir eine Einführung ins Reactive Programming und das Spring-Webflux-Projekt gegeben. Den in diesem Artikel genutzten Beispiel-Controller wollen wir hier nochmal aufgreifen. Dieser wurde vollständig reaktiv mit Java, der Reactive Streams API und Spring Webflux implementiert:

```java
@RestController
class CustomerController {

   private final CustomerRepository repository;

   CustomerController(final CustomerRepository repository) {
       this.repository = repository;
   }

   @PostMapping("/customer")
   Mono<Customer> createNewCustomer(@RequestBody Mono<CustomerCreationRequest> request) {
      return request.flatMap( dto -> 
            repository.save(new Customer(dto.firstName(), dto.lastName()))
      );
   }
}

record CustomerCreationRequest(String firstName, String lastName) {}

@Repository
interface CustomerRepository extends ReactiveCrudRepository<Customer, Long> {

   Flux<Customer> findByFirstNameAndLastName(String firstName, String lastName);
}
```

Durch ein HTTP POST gegen die URL `/customer` kann hier ein neues `Customer`-Objekt erzeugt und in der Datenbank persistiert werden. Das Ganze passiert reaktiv, da in der Methode `createNewCustomer()` das `Mono` für den Eingangsparameter `request` mithilfe der `flatMap()`-Methode mit dem reaktiven Repository und dessen `save()`-Methode verknüpft wird. Dadurch kann Spring Webflux dann einen HTTP Request ohne jegliche Blocking IO verarbeiten. 

Es wird in diesem Beispiel jedoch auch deutlich, welche Nachteile das Reactive Programming mit sich bringt. Der Code ist für viele Entwickler komplizierter zu schreiben und zu verstehen. Im Gegensatz zu einem klassischen, imperativen Ansatz, bei dem der Code von oben nach unten ausgeführt wird, muss der Entwickler hier in Verkettungen von Streams denken. Und diese Verkettungen können deutlich komplexer werden als in diesem einfachen Beispiel, wie wir am Ende dieses Artikels zeigen werden. Diese Art des Denkens ist für viele Entwickler ungewohnt und stellt damit zunächst eine Hürde für die Nutzung von Reactive Programming dar. Wir werden im Folgenden zeigen, wie man mithilfe von Kotlin Coroutines das gewohnte imperative Programmiermodell auch für die Implementierung reaktiver Anwendungen nutzen kann.

## Kotlin und Coroutines
Das zentrale Element für die Implementierung von Nebenläufigkeit in Kotlin sind die sog. *Coroutines*. Dabei handelt es sich, ähnlich wie bei Threads, um Programmabläufe, die parallel zueinander ausgeführt werden können. Im Gegensatz zu Threads sind Coroutines aber sehr leichtgewichtig und können zu Tausenden nebeneinander gestartet werden. Das ist möglich, weil Coroutines mithilfe sog. *Worker-Threads* implementiert werden. Dabei gibt es einen festen Pool von Threads, der sich um die Ausführung aller Coroutines im Hintergrund kümmert. Eine Coroutine kann an bestimmten Punkten während der Ausführung unterbrochen werden und zu einem späteren Zeitpunkt von einem anderen Thread weiter bearbeitet werden. Wann diese Thread-Wechsel passieren ist für den Entwickler transparent und wird von der Kotlin Runtime entschieden. Für einen tiefergehenden Einblick in Coroutines verweisen wir auf den Einführungsartikel [hier](https://www.codecentric.de/wissens-hub/blog/einfuehrung-in-kotlin-coroutines) im Blog.

### Controller mit Suspend Function
Fest verbunden mit Coroutines sind in Kotlin die sog. *suspend functions*. Diese Funktionen werden innerhalb einer Coroutine ausgeführt und erlauben es, unterbrochen zu werden (deshalb *suspend*). Die zugehörige Coroutine wird dabei dann auch unterbrochen, was letztendlich bedeutet, dass sie keinem Thread aus dem Thread-Pool mehr zugeordnet wird. Diesen Mechanismus können wir uns zunutze machen, um Reactive Programming mit einem imperativen Programmiermodell umzusetzen. Betrachten wir dazu die Implementierung unseres Beispiel-Controllers mit Kotlin:

```kotlin
@RestController
class CustomerController(
   private val repository: CustomerRepository
) {

   @PostMapping("/customer")
   suspend fun createNewCustomer(@RequestBody request: Flow<CustomerCreationRequest>): Customer {
      val dto = request.single()
      return repository.save(Customer(dto.firstName, dto.lastName))
   }
}

data class CustomerCreationRequest(val firstName: String, val lastName: String)

@Repository
interface CustomerRepository : CoroutineCrudRepository<Customer, Long>{

   fun findByFirstNameAndLastName(firstName: String, lastName: String): Flow<Customer>
}
```

Neben der etwas kompakteren Schreibweise, die uns Kotlin erlaubt, fällt gleich auf, dass die beiden Monos verschwunden sind. Außerdem wird auch die `flatMap()`-Methode nicht mehr verwendet. Die Methode `createNewCustomer()` gibt direkt das `Customer`-Objekt zurück. Trotz dieser Änderungen ist der Controller vollständig non-blocking. Der Trick ist hier das Schlüsselwort `suspend`. Dadurch kann diese Methode immer dann unterbrochen werden, wenn sie eine andere *suspend function* aufruft. Und das wiederum erlaubt es Spring Webflux (genauer, der *InvocableHandlerMethod*), den Aufruf dieser Methode in einem `Mono` zu verpacken. Das resultierende `Mono` emittiert also genau dann das `Customer`-Objekt, wenn obige *suspend function* von der Coroutine abgearbeitet wurde. Dadurch können wir als Entwickler uns das `Mono` als Rückgabetyp ersparen. 

Eine weitere Auffälligkeit ist der Typ des Parameters `request`. Dieser hat sich von `Mono` zu `Flow` geändert. Dabei handelt es sich um eine Abstraktion von Kotlin, die als eine Vereinigung der Reactive Streams Publisher `Mono` und `Flux` betrachtet werden kann. Anders als in der Reactive Streams API wurde `Flow` aber vor allem deshalb eingeführt, um zu erlauben, dass Coroutines asynchron einen Stream von Objekten austauschen können (siehe auch <a href="https://kotlinlang.org/docs/flow.html" target="_blank">hier</a> in der Kotlin-Dokumentation). In unserem Fall möchten wir in der Methode `createNewCustomer()` darauf warten, dass ein `CustomerCreationRequest` verfügbar wird. Der Aufruf der `single()`-Methode (ebenfalls eine *suspend function*) wird die Ausführung daher so lange unterbrechen, bis ein Request-Objekt (durch Spring Webflux) verfügbar wird. Anschließend wird die Ausführung innerhalb der Coroutine fortgesetzt, ein `Customer`-Objekt erzeugt und die suspend function `save()` des Repositorys aufgerufen. Auch dieser Aufruf wird wieder zu einer Unterbrechung führen, bis die Persistierung in der Datenbank abgeschlossen ist. Erst dann wird die Coroutine weiterlaufen und das persistierte `Customer`-Objekt als Ergebnis zurückliefern. Der Sourcecode sieht fast wie in einem klassischen imperativen Programmiermodell aus, durch die Möglichkeit der Unterbrechung der Methode ist aber eine Ausführung wie in einem Reactive-Ansatz möglich. Der Entwickler muss sich damit aber gedanklich kaum beschäftigen, was die Komplexität deutlich reduziert.

### Komplexeres Beispiel
Um die mögliche Reduktion der Komplexität nochmal deutlicher zu zeigen, möchten wir abschließend unser Beispiel durch eine komplexere Abfrage ergänzen. Dabei sollen alle `Customer`-Objekte anhand ihrer Kundengruppe abgefragt werden. Der reaktive Java-Code dieser Abfrage sieht wie folgt aus:

```java
@GetMapping("/search/customerGroup/{customerGroup}")
Flux<Customer> findByCustomerGroup(@PathVariable final String customerGroup) {
   return webClient.getCustomerGroup(customerGroup)
           .flatMapMany(group ->
                   Flux.concat(
                           group.entries()
                                   .stream()
                                   .map(entry -> repository.findByFirstNameAndLastName(entry.firstName(), entry.lastName()))
                                   .toList()
                   )
           );
}
```

Zunächst wird mithilfe eines Webclients eine REST-API eines anderen Services aufgerufen, um den Namen der Kundengruppe zu einer Liste von Kundennamen aufzulösen. Diese Liste kann dann anschließend benutzt werden, um aus dem oben bereits genutzten Repository die tatsächlichen `Customer`-Objekte auszulesen. Sowohl der Aufruf der REST-API als auch der Aufruf des Repositorys sind dabei non-blocking und nutzten `Mono` bzw. `Flux` als Rückgabewert. Diese müssen dann wieder miteinander verkettet werden (diesmal mit den `flatMapMany()`- und `Flux.concat()`-Methoden). Der ungeübte Entwickler wird hier einen Augenblick brauchen, um genau zu verstehen, wie die einzelnen Aufrufe zusammenhängen. Und selbst viele geübte Entwickler werden diesen Code nicht ohne Weiteres runterschreiben können. Die Kotlin-Implementierung dieses Beispiels ist nicht nur einfacher zu verstehen, sondern einer klassischen imperativen Implementierung auch deutlich ähnlicher:

```kotlin
@GetMapping("/search/customerGroup/{customerGroup}")
suspend fun findByCustomerGroup(@PathVariable customerGroup: String): Flow<Customer> {
   val group = webClient.getCustomerGroup(customerGroup)
   return group
       .entries
       .map { repository.findByFirstNameAndLastName(it.firstName, it.lastName) }
       .merge()
}
```

Hier gibt es noch eine Besonderheit. In Kotlin hat es sich als Best Practice etabliert, dass eine Methode mit Rückgabewert `Flow` keine *suspend function* sein sollte, sondern stattdessen unmittelbar den `Flow` zurückgibt. Eventuelle Aufrufe von blockierenden oder *suspending functions* innerhalb dieser Methode werden dabei in die Ausführung des `Flow` selbst verschoben. Dies lässt sich in obiger Methode leicht erreichen, indem man den Methodenkörper in einen `flow { ... }` Builder einbettet und die `return`-Anweisung durch ein `emitAll()` ersetzt. Durch Kotlins ausdrucksstarke Syntax fällt diese Änderung kaum auf, ist für einen Entwickler des klassischen, imperativen Ansatzes dennoch weniger vertraut. Aus unserer Sicht sind für eine Controller-Methode beide Varianten akzeptable Lösungen:

```kotlin
@GetMapping("/search/customerGroup/{customerGroup}")
fun findByCustomerGroup(@PathVariable customerGroup: String) = flow {
   val group = webClient.getCustomerGroup(customerGroup)
   emitAll(group
      .entries
      .map { repository.findByFirstNameAndLastName(it.firstName, it.lastName) }
      .merge())
}
```

## Fazit
Wir hoffen, wir konnten mit den obigen Beispielen zeigen, dass in Java ein Reactive-Ansatz wie Spring Webflux eine kognitive Belastung für die Entwickler mitbringen kann und dass es möglich ist, diese durch die Benutzung von Kotlin Coroutines bzw. *suspend functions* zu reduzieren. Gerade Entwicklern, die bisher eher im Blocking-IO-Umfeld Erfahrung gesammelt haben (z. B. mit Spring MVC), kann der Umstieg in die Non-blocking-Welt vereinfacht werden, wenn man dabei die von Kotlin angebotenen Konzepte nutzt.

Ein tolles Paar: Spring Webflux und Kotlin Coroutines

Reactive Programming mit Spring Webflux

> ## TL;DR
Unkontrolliertes Agentic Coding („Vibe Coding“) liefert schnell Code – und oft Sicherheits- und Wartungsprobleme, sobald Software produktiv gehen soll. EXACT Coding (Example-guided AI-Collaborative Test-driven Coding) bündelt bewährte Praktiken: zuerst Beispiele und Klarheit, dann Tests als Steuerung, dann Implementierung – mit dem Menschen an definierten Stellen im Loop. So bleibt die KI ein kollaborativer Partner, kein Blackbox-Generator. 
> 
> Vertiefung zu Begründungen, Fallstricken, Tooling (Rule-Files, Skills, SubAgents) und einer durchgespielten TDD-Session gibt es im 👉[Buch “EXACT Coding” auf Leanpub](https://leanpub.com/exact-coding). Teams, die den Workflow gemeinsam üben wollen, können den ganztägigen EXACT-Workshop direkt bei uns anfragen. Mehr Infos siehe [unten](#workshop).

## Vibe Coding vs. Engineering-Disziplin

KI-unterstützte Softwareentwicklung ist längst Normalität: Agenten schreiben Code, refaktorisieren, iterieren. Der viel zitierte Begriff Vibe Coding (Andrej Karpathy) beschreibt die extreme Variante: sich von der KI treiben lassen und den eigenen Code fast nicht mehr lesen – für ein Wochenend-Experiment mag das reichen, für produktive Software wird es schnell riskant. 
Sobald Zahlungslogik, Datenhaltung oder Sicherheitsgrenzen im Spiel sind, zählen Nachvollziehbarkeit, Tests und klare Anforderungen – nicht nur Geschwindigkeit.

## Wofür sich die Einordnung lohnt

In vielen Organisationen reden Fachbereich, Management und Entwicklung über „KI beim Programmieren“ – und meinen damit völlig verschiedene Stufen der Unterstützung. Ohne gemeinsames Bild entstehen falsche Erwartungen: Mal wird die KI als Wundermittel verkauft, mal als Risiko verteufelt.

Auf dem codecentric-Blog findet sich dazu unter anderem ein [Fünf-Level-Modell der KI-gestützten Softwareentwicklung](https://www.codecentric.de/wissens-hub/blog/die-fuenf-level-der-ki-gestuetzten-softwareentwicklung): von einfachem Chat über IDE-Assistenz und Agenten bis zu spec-getriebener Arbeit mit starkem Agenten-Einsatz. 

**EXACT Coding** ist kein Ersatz für dieses Modell, sondern ein konkreter Workflow dort, wo du Agenten sinnvoll nutzt – typischerweise im Bereich von Level 3 und 4: 
**Du bleibst im Agentic-Kontext, entscheidest aber bewusst, wie Spezifikation, Tests und menschliche Kontrolle aussehen.**

## Sweet Spot: Autonomie und Qualität

Ein anschauliches Bild ist der Autonomy Slider (ebenfalls von Karpathy popularisiert): ganz links streng handgeschriebener Code, ganz rechts maximale KI-Autonomie mit oft fragiler Qualität. Die Kurve ist keine Gerade: Mit gezielten Praktiken lässt sich bei hoher KI-Nutzung trotzdem Qualität sichern – die Frage ist weniger „weniger KI“, sondern welche Leitplanken du setzt.

*![autonomy_slider.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/cmo88rgaby5tk06uumu2kc802) Der Slider spannt das Feld zwischen klassischer, disziplinierter Entwicklung und maximal „vibe-getriebener“ KI-Nutzung – EXACT Coding zielt auf einen bewusst gewählten Bereich dazwischen (Abb. 1).*

Wer nur auf Vibes setzt, läuft Gefahr, typische Fehlmuster zu verstärken: Hardcoded Secrets, Sicherheitslogik am falschen Ort, halluzinierte Dependencies, fehlende Eingabevalidierung, Überengineering und uneinheitliche Lösungen in derselben Codebase. Dazu kommt Verification Debt: Der generierte Code sieht überzeugend aus, Reviews werden oberflächlich – bis es im Betrieb knallt. 
Mehr Hintergrund und Einordnung liefert unter anderem der Artikel ["Vibe Coding – was nun?"](https://www.codecentric.de/wissens-hub/blog/vibe-coding-was-nun). Zur Rolle von Tests und Refactoring im KI-Alltag passt auch der Artikel ["Bugs, Refactoring, Tests: Wo Chatbots beim Coden glänzen und wo sie scheitern"](https://www.codecentric.de/wissens-hub/blog/bugs-refactoring-tests-wo-chatbots-beim-coden-glaenzen-und-wo-sie-scheitern).

## Was ist EXACT Coding?

EXACT Coding steht für **Ex**ample-guided **A**I-**C**ollaborative **T**est-driven Coding. Es ist kein neues Framework, sondern ein Workflow aus bewährten Ideen aus Software Craft und kollaborativer Modellierung (Behavior-Driven Development, Domain-Driven Design). Eine konkrete Ausprägung davon ist Example Mapping: In einem kurzen Workshop klären Beteiligte gemeinsam Story, Regeln, Beispiele und offene Fragen – sichtbar und strukturiert, bevor die erste Zeile Code oder der erste Prompt entsteht. Der Workflow ist so zusammengesetzt, dass er mit modernen Large Language Models und Agenten gut funktioniert. Die KI ist kollaborativ eingebunden, nicht als Ersatz für Nachdenken und Verantwortung.

> Um die Theorie in die Praxis zu übersetzen, enthält das [Buch](https://leanpub.com/exact-coding) eine vollständig dokumentierte TDD-Session. Als Beispiel dient das Kartenspiel Overlords: The Card Game. Da dieses Spiel kaum in den Trainingsdaten der LLMs vorkommt, lässt sich dort live beobachten, wie die KI echte Logik-Probleme löst, statt nur aus dem Gedächtnis zu zitieren.

Kern von EXACT Coding ist ein Dreiklang, den du dir merken kannst:

* **Beispiele vor Code** – Mehrdeutigkeit in natürlicher Sprache wird durch konkrete Beispiele reduziert, bevor das erste Token fließt; dazu liefert Example Mapping typischerweise das gemeinsame Raster (Story, Regeln, Beispiele, offene Fragen).  
* **Tests als Steuerung** – Ein fehlgeschlagener Test (Rot) definiert einen kleinen, klaren nächsten Schritt und hält den Kontext für das Modell beherrschbar.  
* **Mensch als Korrektiv** – An definierten Punkten (z. B. nach Rot, Grün, Refactor) bleibt der Mensch die Instanz für Design, Sicherheit und Kontext – Human in the Loop, nicht als Bremse, sondern als Qualitätssicherung.

### Der Ablauf in sieben Schritten (Kurzfassung)

Von Example Mapping und Spezifikation in natürlicher Sprache geht es in den TDD-Kreislauf (Test, Implementierung, Refactoring) – mit klaren Rollen für Mensch und KI.

*![exact_coding_workflow.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/cmo88tz80yqul07t5zadbn9ei) Der Workflow verbindet kollaborative Anforderungsklärung mit dem Rot–Grün-Refactor-Zyklus; die Grafik fasst den Ablauf kompakt zusammen (Abb. 2).*

1. **Scope abstecken** – Feature klein genug wählen, damit der LLM-Kontext nicht explodiert (Story-Slicing, vertikale Schnitte).  
2. **Example Mapping** – Kurz-Workshop mit Story, Regeln, Beispielen und offenen Fragen (z. B. farbige Karten oder digitales Board).  
3. **Test-Liste** – Aus den Beispielen eine geordnete Liste von Testfällen; von Mensch oder KI erstellt, vom Menschen geprüft.  
4. **Rot** – Ein Test aus der Liste wird konkret und schlägt fehl; der Scope bleibt minimal.  
5. **Grün** – Minimale Implementierung, bis der Test grün ist – hier sind Agenten oft stark.  
6. **Refactor** – Struktur und Lesbarkeit verbessern, ohne Semantik zu ändern; hier ist menschliche Erfahrung gefragt.  
7. **Wiederholen** – Bis die Liste abgearbeitet ist; neue Erkenntnisse fließen als neue Einträge in die Liste ein.

So bleibt die Arbeit in kleinen, überprüfbaren Schritten – genau das adressiert typische LLM-Schwächen wie Kontextverlust in langen Prompts („Lost in the Middle“) und vage Anforderungen.

### Autonomie-Stufen: den Slider bewusst setzen

Praktisch kannst du den Grad der KI-Autonomie abstufen. Damit sich das nicht mit den Schritten des EXACT-Workflows überschneidet, sind die typischen Einstellungen hier als Option A–C benannt:

* **Stufe A:**  Der Agent arbeitet die Testliste weitgehend allein ab; Review am Ende. Schnell, aber riskant, wenn früh etwas fundamental falsch läuft.  
* **Stufe B:** Pause nach jedem vollständigen Rot–Grün-Refactor-Zyklus – gute Balance aus Tempo und Kontrolle.  
* **Stufe C:** Pause nach jeder Phase (Rot, Grün, Refactor) – maximal kontrolliert, langsamer.

**Empfehlung:** Bei Unklarheit oder seltsamem Testverhalten sofort stoppen und klären – frühes Eingreifen ist günstiger als großflächiges Aufräumen.

Rule-Files, Commands, Skills und SubAgents (z. B. in Cursor oder Claude Code) helfen, TDD-Disziplin und Stopppunkte stabil zu halten, ohne jeden Prompt neu zu erfinden – die Details und Beispiele dazu sind im Buch ausgeführt.

## Deep Dive: Buch auf Leanpub lesen

Der Blogartikel liefert die Landkarte. Wer Begründungstiefe, typische Fehlermuster der Agenten, eine durchgespielte TDD-Session (inklusive Beispiel-Domäne) und praktische Konfiguration (Rules, Skills, Agenten) nachvollziehen will, findet das im Buch “[EXACT Coding](https://leanpub.com/exact-coding)” auf Leanpub. Dort ist der Workflow so beschrieben, dass du ihn in echten Projekten adaptieren kannst – inklusive Verweis auf das begleitende Übungs-Repository [EXACT-Coding-Exercises](https://github.com/marcoemrich/EXACT-Coding-Exercises) mit Beispiel-Regeln und \-Strukturen.

<a name="workshop"></a>
## Workshop: EXACT Coding gemeinsam erproben

Theorie und Blog reichen nicht immer – manche Teams wollen den Ablauf einmal gemeinsam durchspielen. Dafür bieten wir einen thematisch eng am Buch ausgerichteten, [ganztägigen Workshop](https://www.codecentric.de/leistungen/kuenstliche-intelligenz/training-exact-coding) an: Prinzipien aus dem Buch, konkrete Übungen und Beispiele aus dem Projektalltag. Teilnehmende arbeiten in Paaren und kleinen Mobs (Driver plus Navigatoren) und durchlaufen den EXACT-Workflow Schritt für Schritt – von Example Mapping über TDD bis zum Refactoring mit KI-Unterstützung.
Kontakt: 
Sprecht uns über die üblichen codecentric-Kanäle oder direkt an (z. B. über unsere LinkedIn-Profile: [Marco](https://www.linkedin.com/in/marco-emrich) und [Ferdi](https://www.linkedin.com/in/ferdinand-ade-5011a78b/) – siehe Buch und Impressum auf Leanpub). 

## Fazit

EXACT Coding zielt auf den Sweet Spot: spürbar mehr Produktivität durch KI, ohne Qualität und Kontrolle zu opfern. Es ersetzt weder verantwortungsvolle Architektur noch Security-Reviews – und es behauptet nicht, „Level 5“ (vollautonome Produktentwicklung ohne menschliche Prüfung) sei erreicht. Es liefert aber einen nachvollziehbaren, wiederholbaren Weg, wie Teams Agenten produktiv einsetzen können, ohne im Vibe-Chaos zu landen.

EXACT Coding: KI-gestützte Entwicklung mit Qualität statt Vibe-Chaos

> ## TL;DR
Uncontrolled agentic coding (“vibe coding”) delivers code quickly—and often leads to security and maintenance issues as soon as the software goes live. EXACT Coding (Example-guided AI-Collaborative Test-driven Coding) combines best practices: first examples and clarity, then tests as guidance, then implementation—with humans involved at defined points in the loop. This way, AI remains a collaborative partner, not a black-box generator. 
> 
> For a deeper dive into the rationale, pitfalls, tooling (rule files, skills, subagents), and a walkthrough of a TDD session, see the 👉[book “EXACT Coding” on Leanpub](https://leanpub.com/exact-coding). Teams that want to practice the workflow together can request the full-day EXACT workshop directly from us. See [below](#workshop) for more information.

## Vibe Coding vs. Engineering Discipline

AI-assisted software development has long been the norm: agents write code, refactor, and iterate. The much-cited term “Vibe Coding” (Andrej Karpathy) describes the extreme variant: letting yourself be driven by AI and barely reading your own code anymore—this might be enough for a weekend experiment, but it quickly becomes risky for productive software. 
As soon as payment logic, data management, or security boundaries come into play, traceability, testing, and clear requirements matter—not just speed.

## Why this classification matters

In many organizations, business units, management, and development teams talk about “AI in programming”—but they mean completely different levels of support. Without a shared understanding, false expectations arise: sometimes AI is touted as a miracle cure, other times it’s demonized as a risk.

The codecentric blog features, among other things, a [five-level model of AI-assisted software development](https://www.codecentric.de/wissens-hub/blog/die-fuenf-level-der-ki-gestuetzten-softwareentwicklung) (article is written in German): ranging from simple chat to IDE assistance and agents, all the way to spec-driven work with heavy agent usage. 

**EXACT Coding** is not a replacement for this model, but rather a concrete workflow for situations where you use agents effectively—typically at Levels 3 and 4: 
**You remain within the agentic context, but consciously decide what specifications, tests, and human oversight look like.**

## Sweet Spot: Autonomy and Quality

A helpful illustration is the Autonomy Slider (also popularized by Karpathy): strictly hand-written code on the far left, maximum AI autonomy with often fragile quality on the far right. The curve is not a straight line: With targeted practices, quality can still be ensured even with high AI usage—the question is less “less AI” and more about what guardrails you set.

*![autonomy_slider.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/cmo896ds6zi2s07t567kmhfb3) The slider spans the spectrum between classic, disciplined development and maximally “vibe-driven” AI usage – EXACT Coding targets a deliberately chosen area in between (Fig. 1).*

Those who rely solely on vibes run the risk of reinforcing typical patterns of error: hardcoded secrets, security logic in the wrong place, hallucinated dependencies, missing input validation, overengineering, and inconsistent solutions within the same codebase. Added to this is verification debt: the generated code looks convincing, reviews become superficial—until things go wrong in production. For more background and context, see, among other sources, the article ["Vibe Coding – What Now?"](https://www.codecentric.de/wissens-hub/blog/vibe-coding-was-nun). The article ["Bugs, Refactoring, Tests: Where chatbots shine in coding and where they fail"](https://www.codecentric.de/wissens-hub/blog/bugs-refactoring-tests-wo-chatbots-beim-coden-glaenzen-und-wo-sie-scheitern) also addresses the role of testing and refactoring in everyday AI work (articles are written in German).

## What is EXACT Coding?

EXACT Coding stands for **Ex**ample-guided **A**I-**C**ollaborative **T**est-driven Coding. It is not a new framework, but rather a workflow based on proven ideas from software craftsmanship and collaborative modeling (Behavior-Driven Development, Domain-Driven Design). One concrete manifestation of this is Example Mapping: In a short workshop, participants jointly clarify the story, rules, examples, and open questions—visibly and in a structured way—before the first line of code or the first prompt is written. The workflow is designed to work well with modern large language models and agents. The AI is integrated collaboratively, not as a substitute for thinking and responsibility.

> To put theory into practice, the [book](https://leanpub.com/exact-coding) includes a fully documented TDD session. The card game Overlords: The Card Game serves as an example. Since this game rarely appears in the training data of LLMs, you can observe live how the AI solves real logic problems rather than just reciting from memory.
The core of EXACT coding is a three-part principle you can keep in mind:

* **Examples Before Code** – Ambiguity in natural language is reduced through concrete examples before the first line of code is written; Example Mapping typically provides the common framework for this (story, rules, examples, open questions).  
* **Tests as Guidance** – A failed test (Red) defines a small, clear next step and keeps the context manageable for the model.  
* **Humans as a corrective** – At defined points (e.g., after Red, Green, Refactor), humans remain the authority for design, safety, and context – Human in the Loop, not as a brake, but as quality assurance.

### The Process in Seven Steps (Summary)

From Example Mapping and natural language specifications, the process moves into the TDD cycle (Test, Implementation, Refactoring)—with clear roles for humans and AI.

*![exact_coding_workflow.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/cmo894y2myzxi06uuh883x8b8) The workflow combines collaborative requirements clarification with the Red–Green–Refactor cycle; the diagram provides a concise summary of the process (Fig. 2).*

1. **Define scope** – Choose a feature small enough so that the LLM context does not explode (story slicing, vertical slices).  
2. **Example mapping** – Short workshop with story, rules, examples, and open questions (e.g., colored cards or digital board).  
3. **Test list** – Create an organized list of test cases from the examples; generated by humans or AI, verified by humans.  
4. **Red** – A test from the list is run and fails; the scope remains minimal.  
5. **Green** – Minimal implementation until the test passes – agents often excel here.  
6. **Refactor** – Improve structure and readability without changing semantics; human experience is essential here.  
7. Repeat – Until the list is worked through; new insights are incorporated into the list as new entries.

This keeps the work in small, verifiable steps – which is exactly what addresses typical LLM weaknesses such as context loss in long prompts (“Lost in the Middle”) and vague requirements.

### Autonomy Levels: Setting the Slider Consciously

In practice, you can adjust the degree of AI autonomy. To avoid overlap with the steps of the EXACT workflow, the typical settings are labeled here as Options A–C:

* **Level A:**  The agent works through the test list largely on its own; review at the end. Fast, but risky if something goes fundamentally wrong early on.  
* **Level B:** Pause after every complete Red–Green–Refactor cycle – good balance of speed and control.  
* **Level C:** Pause after every phase (Red, Green, Refactor) – maximum control, slower.

**Recommendation:** If anything is unclear or test behavior seems strange, stop immediately and clarify—early intervention is better than a major cleanup later.

Rule files, commands, skills, and subagents (e.g., in Cursor or Claude Code) help maintain TDD discipline and stopping points without having to reinvent every prompt—the details and examples are covered in the book.

## Deep Dive: Book on Leanpub 

The blog post provides the roadmap. If you want to understand the depth of reasoning, typical agent error patterns, a walkthrough of a TDD session (including an example domain), and practical configuration (rules, skills, agents), you’ll find it in the book “[EXACT Coding](https://leanpub.com/exact-coding)” on Leanpub (in German). There, the workflow is described in a way that allows you to adapt it to real projects—including a reference to the accompanying exercise repository [EXACT-Coding-Exercises](https://github.com/marcoemrich/EXACT-Coding-Exercises) with sample rules and structures.

<a name="workshop"></a>
## Workshop: Trying out EXACT Coding Together

Theory and the blog aren’t always enough—some teams want to walk through the process together. For this, we offer a full-day workshop closely aligned with the book’s themes: principles from the book, concrete exercises, and examples from everyday project work. Participants work in pairs and small mobs (drivers plus navigators) and go through the EXACT workflow step by step—from example mapping to TDD to refactoring with AI support.
Contact: 
Reach out to us via the usual codecentric channels or directly (e.g., via our LinkedIn profiles: [Marco](https://www.linkedin.com/in/marco-emrich) und [Ferdi](https://www.linkedin.com/in/ferdinand-ade-5011a78b/) – see the book and imprint on Leanpub). 

## Conclusion

EXACT Coding aims for the sweet spot: noticeably higher productivity through AI, without sacrificing quality or control. It does not replace responsible architecture or security reviews—and it does not claim that “Level 5” (fully autonomous product development without human review) has been achieved. However, it provides a transparent, repeatable approach for teams to use agents productively without ending up in a state of chaos.

EXACT Coding: AI-powered development that prioritizes quality over chaotic experimentation

Senior Consultant, Developer & Trainer

Spring Boot & Apache CXF – Logging & Monitoring mit Logback, Elasticsearch, Logstash & Kibana

Ansible zaubert Spring Boot Apps auch auf Windows

Spring Boot & Apache CXF – SOAP ohne XML?

Spring Boot & Apache CXF – SOAP-Webservices testen

Spring Boot & Apache CXF – XML-Validierung und Custom SOAP Faults

Spring Boot & Apache CXF – Von 0 auf SOAP mit dem cxf-spring-boot-starter

Simplifying Spring Boot GraalVM Native Image builds with the native-image-maven-plugin

Spring Boot & Apache CXF – Logging & Monitoring with Logback, Elasticsearch, Logstash & Kibana

Running Spring Boot apps as GraalVM Native Images

Taming the Hybrid Swarm: Initializing a Mixed OS Docker Swarm Cluster Running Windows & Linux Native Containers with Vagrant & Ansible

Running Spring Boot Apps on Docker Windows Containers with Ansible: A Complete Guide incl Packer, Vagrant & Powershell

Running Spring Boot Apps on Windows with Ansible

Running Spring Boot GraalVM Native Images with Docker & Heroku

Continuous cloud infrastructure with Ansible, Molecule & TravisCI on AWS

Continuous Infrastructure with Ansible, Molecule & TravisCI

Spring Boot on Heroku with Docker, JDK 11 & Maven 3.5.x

Test-driven infrastructure development with Ansible & Molecule

<p>The Pipeline-as-Code pattern is implemented by most CI/CD platforms today. So what could be the next evolutionary step? Based on GitHub Actions, the article outlines why open-source Pipeline-as-Code Building Blocks will take your pipelines to the next level.</p><h2>GitHub Actions – blog series</h2><p>Part 1: <a href="/en/knowledge-hub/blog/github-actions-pipeline">GitHub Actions CI pipeline: GitHub Packages, Codecov, release to Maven Central & GitHub</a> <br /> Part 2: <a href="/en/knowledge-hub/blog/github-container-registry">Publishing Docker images to GitHub Container Registry with GitHub Actions</a> <br /> Part 3: Stop re-writing pipelines! Why GitHub Actions drive the future of CI/CD</p><h2>Isn’t it just another CI/CD tool?</h2><p>While migrating many of my open-source projects to GitHub Actions, one thought gradually came to my mind over the last few months: I realized I was working with a kind of next-generation CI/CD platform. Which I didn’t get at first <strong>since GitHub Actions is just another CI/CD tool right?</strong> Only a different syntax for our pipeline, which shouldn’t be considered a really big step …</p><p>But then it slowly became clear to me: <strong>it’s all about this “Actions” thing!</strong> And I started to think about what I experienced in my professional career using CI/CD tooling as a key piece of my toolbelt. But to really explain what my thoughts are all about, I need to go back in time more than 10 years. 🙂 Please excuse me if I leave out a lot of great tools on this journey. I only wanted to sketch out an idea rather than provide <a href="https://github.com/ligurio/awesome-ci" target="_blank">a comprehensive overview of all CI/CD platforms available</a> . So I will focus on the ones that have been most popular in my life as a software engineer.</p><h2>Going back over a decade in time: the first wave of CI/CD platforms</h2><p>Let’s start with some time in 2007 when I was in the middle of my higher-education studies. Since I was doing a work-study course, I was thrown into practical application really early. And I’m still honored that I was able take part in the so-called “Frameworks Team” as a student already. On this team, <strong>I was able to watch the introduction of the first CI server quite closely</strong>: back then, my colleague Xavier reported about the first installation of a Hudson server, his eyes shining with delight.</p><p><img width="1024" height="768" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mQ6cKHqlSa6kPWFmVhQ4" alt="the 3 waves of CICD platforms that lead to the Pipeline-as-Code Building Blocks pattern" /></p><p>Logo sources: <a href="https://www.jenkins.io/" target="_blank">Jenkins logo</a> , <a href="https://travis-ci.com/" target="_blank">TravisCI logo</a> , <a href="https://about.gitlab.com/press/press-kit/" target="_blank">GitLab logo</a> , <a href="https://github.com/" target="_blank">GitHub Actions logo</a> </p><p>This thing was so popular, <a href="https://medium.com/swlh/hudson-is-retiring-the-end-of-a-jenkins-story-9cee866135ab" target="_blank">it even received the Duke’s Choice Award at JavaOne 2008</a> . Forced to fork the project because of Oracle’s purchase of Sun Microsystems, the project was renamed to “<a href="https://www.jenkins.io/" target="_blank">Jenkins</a> ” in January 2011. And <strong>I guess we all know Jenkins in some form</strong>. It is by far the most widely used CI/CD platform, I guess. And there are good reasons for that! I was in the role of a software architect in a project back in 2013, where my soon-to-be colleague <a href="https://twitter.com/denschu" target="_blank">Dennis Schulte</a>  showed us how to use <a href="https://github.com/jenkinsci/job-dsl-plugin" target="_blank">the Jenkins Job DSL plugin</a>  to circumvent the maintainance hell brought about by hundreds of manually created Jenkins jobs.</p><h2>Pipeline-as-Code: the second wave of CI/CD platforms</h2><p>When referring to the time before the release of the Job DSL plugin, I think it’s fair to speak of the <em>“first wave of CI/CD platforms”</em>. The Job DSL plugin – and later the <a href="https://www.jenkins.io/blog/2016/02/29/jenkins2-alphas/" target="_blank">Jenkins 2.0 pipelines project in 2016</a>  – are part of the second wave of CI/CD platforms. But Jenkins wasn’t the driver behind this next wave, really. Released as early as 2013, the <a href="https://en.wikipedia.org/wiki/Travis_CI" target="_blank">TravisCI project</a>  aimed to provide CI/CD services free for open source projects. This was a huge step! <strong>Bringing together TravisCI with GitHub, the resulting setup could be seen as a forerunner of modern software development processes.</strong> And they didn’t stop there. I first realized how elegant and simple CI/CD pipelines could be when I joined codecentric in 2015. Encouraged to use our off-project time to build and play with open source projects, I started to create my first projects incorporating this setup. And using Travis felt like a revelation to me! I only had to write a few lines of code and had my pipelines test and build my application.</p><p>Back then I always considered the software development process inside enterprise companies to be separate from the one used in open-source projects. My “reasoning” was: <em>Well, Travis is so simple and easy to use because they don’t need to deal with “all that enterprisey stuff”</em>. But soon something began to work in the back of my head. And finally in 2018 I realized that <strong><a href="https://docs.gitlab.com/ee/ci/" target="_blank">GitLab CI</a>  brought the power & elegance of CI/CD pipelines to the enterprise that I only knew from TravisCI</strong>. I was really disillusioned by the implementation of the Pipeline-as-Code pattern by Jenkins 2.0 in 2017. Back then we tried to implemend it at a customer project (<a href="https://twitter.com/m_p_dus" target="_blank">Marco</a> , I hear you 🙂 ). But GitLab made me realize what this might look like. I also assume that it’s not an easy task to introduce a big application like Jenkins to a new pattern like Pipeline-as-Code. Especially when you’re striving to be completely downward-compatible, as Jenkins 2.0 was aiming to be. I was so convinced by the solution GitLab brought into the game, I wrote lots of articles about it (e.g. <a href="/en/knowledge-hub/blog/gitlab-ci-pipeline">this one</a>  and <a href="https://www.heise.de/select/ix/2018/8/1533431466220024" target="_blank">this one</a> ). And I recommended this great platform to my customers.</p><h2>GitLab CI brought Pipeline-as-Code to the enterprise</h2><p>GitLab CI also solved an issue I had with most Pipeline-as-Code platforms. Released in <a href="https://about.gitlab.com/2019/01/22/gitlab-11-7-released/" target="_blank">version 11.7 at the beginning of 2019</a> , GitLab CI made a huge step forward again. They introduced <a href="https://docs.gitlab.com/ee/ci/yaml/#include" target="_blank">the include keyword</a>  into their pipeline syntax. With this great addition, <strong>it was possible to write re-usable pipeline templates</strong> (I know by the time also Jenkins pipelines made this possible, but I didn’t find their solution as elegant).</p><p>I remember being inside a customer project in 2019 where we faced a migration of several hundred projects to GitLab. Having a set of tested and high-quality pipeline templates at hand was a key success factor in the project. And I guess it is in many companies, because we all love DevOps. And we all want to do Microservices. But many customers <a href="https://www.ufried.com/blog/microservices_fallacy_10_microliths/" target="_blank">aren’t able to fill their projects with Fullstack DevOps superstars only</a> . <strong>So having some people focussing on writing really good CI/CD templates is not a bad idea</strong>.</p><p>To sum up, I would say that roughly the time from 2013 to 2019 could be seen as <em>the second wave of CI/CD platforms</em>. All platforms began to focus on the Pipeline-as-Code pattern and some implemented it better than others (as we’re accustomed to in IT history 🙂 ).</p><h2>GitHub Actions kick off the third wave of CI/CD platforms</h2><p>At the end of 2019 <a href="https://github.blog/2019-08-08-github-actions-now-supports-ci-cd/" target="_blank">GitHub announced the availability of GitHub Actions</a>  I didn’t really have the time back then to dig into it deeper. One thing that also kept me from doing so was the thought: <strong>“Oh, just another CI/CD platform. So who cares?”</strong> I already wrote about the fact I was forced to look into it at the end of 2020. This was <a href="https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing" target="_blank">when TravisCI stopped broad support for open-source projects</a> . I needed (and still need) to move all my open-source repositories to GitHub Actions. See the <a href="/en/knowledge-hub/blog/github-actions-pipeline">“The problem with TravisCI” paragraph in one of my last articles</a> . This migration also forced me to really take a closer look at the platform. I realized that GitHub Actions easily adapted everything that was already great in other platforms. <strong>But it adds one piece that sets it apart from the others.</strong> And it’s right there in the name: Actions! But wait. What are those Actions?</p><p><img loading="lazy" width="1024" height="1158" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/aDjuZzEuQZGqaZufsWFD" alt="Open Source Pipeline-as-Code Building Blocks pattern idea outlined" /></p><p>To get a first understanding, you may want to have a look at <a href="https://github.com/marketplace?type=actions" target="_blank">the GitHub Actions Marketplace</a> . The Actions listed there are either provided by GitHub itself, or they are developed by other companies and the community. In both cases they are available as open-source projects on GitHub. These Actions help you solve common problems that occur while writing CI/CD pipelines. And <strong>they are assemblable like the famous Lego blocks and finally form your CI/CD pipelines.</strong> Read that once again! As already said, for me it was the first thought when I heard about the Pipeline-as-Code pattern: How are we supposed to reuse stuff we write here? Do we need to write this release pipeline over and over again? How was this Sonar analysis supposed to be written again? And finally: how can we deploy our app to this shiny new cloud service using Infrastructure-as-Code? <strong>Many aspects of such questions are already covered by an Action available.</strong> And they ultimately reduce the lines of code needed inside our CI/CD pipelines drastically. Especially when compared to other tools.</p><h2>It’s all about the Actions</h2><p>Just insert these few lines describing the chosen Action and go for it. Let’s assume you need a changelog for your artifact releases. Simply use the <a href="https://github.com/metcalfc/changelog-generator" target="_blank">metcalfc/changelog-generator</a>  Action in your GitHub Actions workflow (or another of the dozens of available changelog Actions):</p><div>

```yaml
      - name: Generate changelog
        uses: metcalfc/changelog-generator@v0.4.4
        with:
          myToken: ${{ secrets.GITHUB_TOKEN }}
```

</div><p>Maybe you need to<a href="/en/knowledge-hub/blog/github-actions-pipeline"> set up a JDK to build and deploy to Maven Central</a>  (configuring a pre-defined <code>settings.xml</code> under the hood also). Just use <a href="https://github.com/actions/setup-java" target="_blank">GitHub’s setup-java Action</a> :</p><div>

```yaml
      - name: Set up settings.xml for Maven Central Repository
        uses: actions/setup-java@v1
        with:
          java-version: 11
          server-id: oss.sonatype.org
          server-username: MAVEN_USERNAME
          server-password: MAVEN_PASSWORD
          gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }}
          gpg-passphrase: MAVEN_GPG_PASSPHRASE
```

</div><p>And what about said shiny cloud provider and some Infrastructure-as-Code tooling? Let’s say we use <a href="https://www.pulumi.com/" target="_blank">Pulumi</a>  to provision our infrastructure in <a href="https://azure.microsoft.com/en-us/" target="_blank">Azure</a> . There’s a great <a href="https://github.com/pulumi/actions" target="_blank">Pulumi Action</a>  available:</p><div>

```yaml
      - uses: pulumi/actions@v1
        with:
          command: up
        env:
          ARM_SUBSCRIPTION_ID: ${{ secrets.ARM_SUBSCRIPTION_ID }}
          ARM_CLIENT_ID: ${{ secrets.ARM_CLIENT_ID }}
          ARM_CLIENT_SECRET: ${{ secrets.ARM_CLIENT_SECRET }}
          ARM_TENANT_ID: ${{ secrets.ARM_TENANT_ID }}
          PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
```

</div><p>You also don’t need to worry that your pipelines will spontaneously start to behave completely differently. As you may have noticed, <strong>every action has a specific version number</strong>. So upgrades are made explicit (and should be also automated with a tool like <a href="https://github.com/renovatebot/renovate" target="_blank">renovate</a>  🙂 ). I guess this outlines the idea behind Actions aka Pipeline-as-Code Building Blocks 🙂 And in the rare event that there’s no Action for your use case: You can write and publish your own Actions, of course.</p><h2>Open-source Pipeline-as-Code Building Blocks</h2><p>OK, maybe I’m overly enthusiastic here. But for me the “Actions” in GitHub Actions kick off the next level (or wave) in the evolution of CI/CD platforms! Finally <strong>we’re able to really reduce boilerplate code in our pipelines</strong>. And we don’t have to establish a new team to write re-usable templates for us. We can simply pick the ones needed. Additionally these building blocks aren’t only used by our own company. There’s even a big community of people using the Actions, reporting issues, pushing the development of it further, in other words: bringing <strong>all the benefits of open-source software into the creation of CI/CD pipelines</strong>. A logical step after the introduction of Pipeline-as-Code. Since I see it as a kind of pattern, I would like to name it: “Pipeline-as-Code Building Blocks”.</p><p>This is maybe an unusual post of mine: nearly no example code! But as I’ve already written about GitHub Actions (and will continue to write about them in the future), I hope you’ll forgive me. <strong>I simply needed to put an emphasis on the huge step this tooling represents for the CI/CD world.</strong> I don’t think that GitHub will be the only one that’s adopting the pattern of “Pipeline-as-Code Building Blocks” in the future, though. But so far only GitHub really implements it this broadly. So if you haven’t done so already: take a look at GitHub Actions for your next project. And then stop re-writing your CI/CD pipelines. 🙂</p>

Stop re-writing pipelines! Why GitHub Actions drive the future of CI/CD

GitHub Actions CI pipeline: GitHub Packages, Codecov, release to Maven Central & GitHub

<p>You may have heard about all the benefits of Cloud Native Buildpacks?! But Paketo’s pack CLI depends on Docker. So what about our Kubernetes-based CI systems, where we might not have a Docker daemon available?</p><h2>Cloud Native Buildpacks – blog series</h2><p>Part 1: <a href="/en/knowledge-hub/blog/buildpacks-spring-boot"> Goodbye Dockerfile: Cloud Native Buildpacks with Paketo.io & layered jars for Spring Boot</a> <br /> Part 2: Cloud Native Buildpacks / Paketo.io in GitLab CI without Docker & pack CLI <br />
Part 3: <a href="/en/knowledge-hub/blog/cloud-native-buildpacks-lifecycle-environment-variables">Using Environment Variables with the Cloud Native Buildpacks lifecycle</a></p><p>I was recently thrown into a customer project in which everything is based on <a href="https://docs.gitlab.com/ee/ci/" target="_blank">GitLab CI</a> . Which is a great tool, although I tend to favour GitHub Actions right now <a href="/en/knowledge-hub/blog/github-actions-nextgen-cicd" target="_blank">because of their great reusable Pipeline-as-Code Building Blocks</a> . But I was keen to work with the latest GitLab CI version to see how it has progressen since the last time I had used it intensively. And really <strong>the first thing we wanted to do in GitLab was to use Cloud Native Buildpacks / Paketo.io to build our container images!</strong> Remember <a href="/en/knowledge-hub/blog/buildpacks-spring-boot" target="_blank">that the Dockerfile is dead</a>  – so today, we shouldn’t need to write and maintain them anymore.</p><p>Well, hasn’t this cool Auto DevOps feature been introduced by GitLab CI? And <a href="https://buildpacks.io/docs/tools/gitlab/" target="_blank">there’s already a Buildpacks integration ready!</a>  As stated in the docs our <code>.gitlab-ci.yml</code> only needs to look like this:</p><div>

```javascript
include:
  - template: Auto-DevOps.gitlab-ci.yml
 
variables:
  AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED: "true"
```

</div><p>But soon we looked stupidly at this build log:</p><div>

```javascript
Building Cloud Native Buildpack-based application with builder heroku/buildpacks:18...
ERROR: failed to build: failed to fetch builder image 'index.docker.io/heroku/buildpacks:18': Cannot connect to the Docker daemon at tcp://localhost:2375. Is the docker daemon running?
```

</div><p>What was this all about?</p><h2>GitLab CI with unprivileged Kubernetes Runners – and no Docker socket!</h2><p>GitLab has been setup by the great folks over at <a href="/en/services/managed-services" target="_blank">codecentric cloud</a> , where our customers just rent it as a managed service. In a state-of-the-art setup this GitLab uses <a href="https://aws.amazon.com/eks/" target="_blank">Amazon EKS</a>  to run its <strong>builds on Kubernetes-based Runners</strong>. Quite early in the process, Daniel from codecentric cloud made one thing clear: in the default setup <strong>we wouldn’t be able to access the Docker daemon socket inside our containers</strong> running inside the Kubernetes cluster. And we also wouldn’t have any containers in privileged mode (aka Docker in Docker or <code>docker:dind</code>). And that should be the case, if we take a look at all the security risks being introduced otherwise.</p><p>As this could be seen as a common setup, <strong>it shouldn’t be a big deal to use Paketo.io & Cloud Native Buildpacks in this scenario right?!</strong> Therefore we should lift our gaze from the <a href="https://docs.gitlab.com/ee/topics/autodevops/" target="_blank">Auto DevOps feature</a>  and get our hands dirty! Let’s write our own GitLab CI yaml files! Commonly the basic ingredient of using Paketo.io and Cloud Native Buildpacks is to utilize <a href="https://buildpacks.io/docs/tools/pack/" target="_blank">pack CLI</a> . Here’s an example command which is usually everything you need in order to build and publish an OCI container image:</p><div>

```javascript
pack build microservice-api-spring-boot:latest \
    --builder paketobuildpacks/builder:base \
    --path .
```

</div><p><a href="https://buildpacks.io/docs/tools/pack/#install" target="_blank">Installing pack CLI</a>  inside our .gitlab-ci.yml and simply using it to build our container images plunged us into an already known trap:</p><div>

```javascript
$ pack build $CI_REGISTRY_IMAGE:latest --builder paketobuildpacks/builder:base --path .
ERROR: failed to build: failed to fetch builder image 'index.docker.io/paketobuildpacks/builder:base': Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
```

</div><p>These errors finally reminded me of my colleague <a href="https://twitter.com/omegapolice" target="_blank">Raphael</a> . Right after writing about <a href="/en/knowledge-hub/blog/buildpacks-spring-boot" target="_blank">all those merits of Cloud Native Buildpacks</a>  he tore me out of my reveries:</p><blockquote><p>“Hey Jonas, that’s really cool stuff! I love it. But do we really need to have Docker installed in order to use Paketo with its nice and shiny pack CLI? What about my CI systems? I love Kubernetes and <a href="https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds" target="_blank">don’t want to introduce all those security risks</a>  to my pipelines…”</p></blockquote><p>But stepping back and refraining from using Cloud Native Buildpacks wasn’t an option to us! I also thought about <a href="https://docs.gitlab.com/runner/executors/kubernetes.html#using-kaniko" target="_blank">using kaniko as stated in the GitLab CI docs</a> . But <a href="https://github.com/GoogleContainerTools/kaniko" target="_blank">kaniko</a>  needs <code>Dockerfiles</code>. And not needing to write and maintain them anymore is the whole point here…</p><h2>Directly using Paketo’s lifecycle instead of Docker</h2><p>But finally it came to me. <strong>I had already read about this issue with pack CLI.</strong> I came across it writing the first article of this blog series: <a href="https://github.com/buildpacks/pack/issues/564" target="_blank">github.com/buildpacks/pack/issues/564</a> . The initial question nails it:</p><blockquote><p>There are many users who are starting to not have Docker installed on their systems because there are other alternatives that let them create containers in a secure way <strong>as they typically run these containers on remote systems (e.g. kubernetes clusters)</strong>. […] Pack, although not depending on docker build […] does require Docker to be running on your container.</p></blockquote><p>Followed by a big discussion there was <a href="https://github.com/buildpacks/pack/issues/413#issuecomment-565165832" target="_blank">only one comment</a>  that included a hint on how to deal with the issue:</p><blockquote><p>If you’re looking to build images in CI (not locally), I’d encourage you to <strong>use the lifecycle directly for that</strong>, so that you don’t need Docker. <a href="https://github.com/tektoncd/catalog/blob/main/task/buildpacks/0.3/buildpacks.yaml" target="_blank">Here’s an example</a> </p></blockquote><p>The comment refers to the <a href="https://tekton.dev/" target="_blank">Tekton</a>  implementation on <a href="https://github.com/tektoncd/catalog/blob/main/task/buildpacks/0.3/buildpacks.yaml" target="_blank">how to use buildpacks in a Kubernetes environment</a> . And that brought us onto the right path. Here we can get a first clue about what is referred to as <em>“to use the lifecycle directly”</em>. The crucial point there is the usage of the <code>command: ["/cnb/lifecycle/creator"]</code>. We finally found the lifecycle mentioned above. And there’s also a good documentation about this command which can be found <a href="https://github.com/buildpacks/rfcs/blob/main/text/0026-lifecycle-all.md#usage" target="_blank">in this Cloud Native Buildpacks RFC</a> .</p><h2>A good base image: paketobuildpacks/builder:base</h2><p>So how can we get closer to a working <code>.gitlab-ci.yml</code>?<br /> <strong>It’s always a good way to start as simple as possible.</strong> Digging <a href="https://github.com/tektoncd/catalog/blob/main/task/buildpacks/0.3/buildpacks.yaml" target="_blank">into the Tekton implementation,</a>  you’ll see that the lifecycle command is executed inside an environment defined in <code>BUILDER_IMAGE</code>. This variable is defined as <em>The image on which builds will run (must include lifecycle and compatible buildpacks)</em>.</p><p>Maybe that sounds familiar?!<br /> <strong>Can’t we simply pick the builder image <a href="https://hub.docker.com/r/paketobuildpacks/builder" target="_blank">paketobuildpacks/builder:base</a>  from our pack CLI command?</strong> Let’s try this locally on our workstation before committing too much noise into our GitLab. Before running the build, we need to choose an application project we want to turn into a container image. I created an example Spring Boot app on <a href="https://gitlab.com/jonashackt/microservice-api-spring-boot" target="_blank">gitlab.com/jonashackt/microservice-api-spring-boot</a>  which you can clone. Or use your own app, if you’d like. Having the application project available locally, we can simply spin up a container based on the Paketo builder image <code>paketobuildpacks/builder</code>:</p><div>

```javascript
docker run --rm -it -v "$PWD":/usr/src/app -w /usr/src/app paketobuildpacks/builder bash
```

</div><p>With this command we mount the application’s source code into the container in order to have it available for the Paketo lifecycle. Now, inside the container we can <strong>try to run the Paketo lifecycle directly</strong> with:</p><div>

```javascript
/cnb/lifecycle/creator -app=. microservice-api-spring-boot:latest
```

</div><p>I only used the <code>-app</code> parameter of <a href="https://github.com/buildpacks/rfcs/blob/main/text/0026-lifecycle-all.md#usage" target="_blank">the <code>creator</code> command’s</a>  many possible parameters. That should be okay for many cases since most of them have quite good defaults. I configured the app path as the default one at <code>/workspace</code> doesn’t hold our application source. Instead it’s the current directory. Also we need to define an <code>image-name</code> at the end, which will be used as the resulting container image name.</p><p>The execution of the lifecycle should trigger a normal Paketo build using Cloud Native Buildpacks! <strong>But this time we did not need pack CLI</strong> 🙂</p><h2>The first .gitlab-ci.yml</h2><p>As now we know how to run the Paketo lifecycle directly, we can craft our <code>.gitlab-ci.yml</code>. Using some <a href="https://docs.gitlab.com/ee/ci/variables/predefined_variables.html" target="_blank">GitLab CI predefined variables</a>  the command could look like this:</p><div>

```yaml
/cnb/lifecycle/creator -app=. $CI_REGISTRY_IMAGE:latest
```

</div><p>Choosing the wrong image name could lead to a breaking Buildpack process analyser step and no image gets pushed to the GitLab Container Registry!<br /> So let’s craft our first <code>.gitlab-ci.yml</code> like this:</p><div>

```yaml
image: paketobuildpacks/builder

stages:
  - build

build-image:
  stage: build
  script:
    - /cnb/lifecycle/creator -app=. $CI_REGISTRY_IMAGE:latest
```

</div><p>Commiting this to our repository in GitLab <strong>should already start a GitLab CI build using Buildpacks!</strong> Yay! 🙂<br /> The only problem is that it might run into an error like this:</p><div>

```yaml
    ===> ANALYZING
    ERROR: failed to get previous image: connect to repo store "gitlab.yourcompanyhere.cloud:4567/yourgroup/microservice-api-spring-boot:latest": GET https://gitlab.yourcompanyhere.cloud/jwt/auth?scope=repository%3Ayourgroup%2Fmicroservice-api-spring-boot%3Apull&service=container_registry: DENIED: access forbidden
    Cleaning up project directory and file based variables 00:01
    ERROR: Job failed: command terminated with exit code 1
```

</div><h2><em>docker login</em> without Docker</h2><p>Using the build image <code>paketobuildpacks/builder:base</code> we don’t have the command <code>docker</code> available inside our Kubernetes Runners. So we can’t <a href="https://docs.gitlab.com/ee/user/packages/container_registry/#authenticate-by-using-gitlab-cicd" target="_blank">login to GitLab Container Registry as described in the official docs</a> . That’s why we run into the <code>DENIED: access forbidden</code> error, because our pipeline has no access to the GitLab Container Registry.</p><p>Luckily my colleague <a href="https://twitter.com/m_p_dus" target="_blank">Marco</a>  gave me the hint that there’s the approach <a href="https://stackoverflow.com/a/46422186/4964553" target="_blank">described in this stackoverflow answer</a> . <strong>Instead of using <code>docker login</code> we can create the Docker configuration file <code>~/.docker/config.json</code> ourselves.</strong> So let’s create it containing our GitLab Container Registry’s login information. This way <a href="https://github.com/buildpacks/spec/blob/main/platform.md#registry-authentication" target="_blank">the Paketo build will pick them up as stated in the docs</a> :</p><blockquote><p>If <code>CNB_REGISTRY_AUTH</code> is unset and a docker config.json file is present, the lifecycle SHOULD use the contents of this file to authenticate with any matching registry.</p></blockquote><p>Inside our <code>.gitlab-ci.yml</code> creating a correct <code>~/.docker/config.json</code> could look like this:</p><div>

```yaml
    before_script:
      - mkdir ~/.docker
      - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_JOB_TOKEN\"}}}" >> ~/.docker/config.json
```

</div><p>Again be sure to use the handy <a href="https://docs.gitlab.com/ee/ci/variables/predefined_variables.html" target="_blank">GitLab CI predefined variables</a>  like <code>$CI_REGISTRY</code> (the GitLab Container Registry url) and the variables <code>$CI_REGISTRY_USER</code> & <code>$CI_JOB_TOKEN</code>, which contain the credentials.</p><h2>Our final .gitlab-ci.yml</h2><p>So bringing it all together, our <code>.gitlab-ci.yml</code> finally looks like this:</p><div>

```yaml
image: paketobuildpacks/builder

stages:
  - build
 
# We somehow need to access GitLab Container Registry with the Paketo lifecycle
# So we simply create ~/.docker/config.json as stated in https://stackoverflow.com/a/41710291/4964553
before_script:
  - mkdir ~/.docker
  - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_JOB_TOKEN\"}}}" >> ~/.docker/config.json

build-image:
  stage: build
  script:
    - /cnb/lifecycle/creator -app=. $CI_REGISTRY_IMAGE:latest
```

</div><p>Here’s the example project’s <a href="https://gitlab.com/jonashackt/microservice-api-spring-boot/-/blob/main/.gitlab-ci.yml" target="_blank">fully working <code>.gitlab-ci.yml</code></a> .<br /> <strong>Our builds should now run successfully, using Paketo/Buildpacks without pack CLI and Docker</strong>:</p><p><img width="1024" height="911" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/PILwGSBhTNSLxiY0Lln5" alt="GitLab CI running Paketo Buildpack build without pack CLI unprivileged" /></p><p>The example project also has <a href="https://gitlab.com/jonashackt/microservice-api-spring-boot/-/jobs/1679213328" target="_blank">the full build log available here</a> , if you’re interested.</p><h2>Great to see Cloud Native Buildpacks / Paketo.io working in GitLab CI without Docker & pack CLI!</h2><p>I’m absolutely glad to see <a href="/en/knowledge-hub/blog/buildpacks-spring-boot" target="_blank">my favourite container build solution</a>  working together with a state-of-the-art CI/CD setup like GitLab featuring Kubernetes runners! Being able to use Cloud Native Buildpacks / Paketo.io without the Docker daemon or pack CLI, <strong>enables a much broader usage of this absolutely great technology.</strong> It’s no problem to stay with pack CLI locally, if you have Docker installed. But you now know what it means to <strong>use the lifecycle directly</strong>! Besides Tekton there’s also another gread CI/CD tooling using this trick: <a href="https://github.com/pivotal/kpack" target="_blank">kpack</a> .<br /> Hopefully, I will find the time to write about it in the near future 🙂<br /> <a href="/en/careers?utm_campaign=PeSo%20Blog%20to%20Job&utm_source=cc_blog&utm_medium=display&utm_content=cloud_native_developer_und_consultant" target="_blank"><img loading="lazy" width="660" height="220" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/2mSd0KsrS96mi0kzeeEg" alt="Mitglieder für unsere Gilde gesucht! Jetzt der Gilde als Cloud Native Developer und Consultant (w/d/m) beitreten" /></a> </p><p> </p>

Cloud Native Buildpacks / Paketo.io in GitLab CI without Docker & pack CLI

Goodbye Dockerfile: Cloud Native Buildpacks with Paketo.io & layered jars for Spring Boot

<p>Tired of bumping into Docker Hub’s rate limiting? Why not give the GitHub Container Registry a try? Right now it’s in public beta but it already looks great, especially in combination with GitHub Actions.</p><h2>GitHub Actions – blog series</h2><p>Part 1: <a href="/en/knowledge-hub/blog/github-actions-pipeline">GitHub Actions CI pipeline: GitHub Packages, Codecov, release to Maven Central & GitHub</a> <br /> Part 2: Publishing Docker images to GitHub Container Registry with GitHub Actions<br /> Part 3: <a href="/en/knowledge-hub/blog/github-actions-nextgen-cicd">Stop re-writing pipelines! Why GitHub Actions drive the future of CI/CD</a> </p><h2>What’s the problem with Docker Hub?</h2><p>Recently I’ve been running into <a href="https://www.docker.com/increase-rate-limit" target="_blank">Docker Hub’s new rate limiting</a>  more and more often. So regardless which CI system I use, I find myself looking into a log file at something like this:</p><div>

```bash
Unable to find image 'hello...
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit.\nSee 'docker run --help'.\n"
```

</div><p>or this</p><div>

```bash
ERROR: toomanyrequests: Too Many Requests.
```

</div><p>So <strong>I thought of using an alternative container registry</strong> that doesn’t expose such a limit. Coincidentally I was updating my example project, which shows <a href="https://github.com/jonashackt/spring-boot-graalvm" target="_blank">how to use GraalVM with Spring</a> . I learned that Oracle moved their GraalVM Docker image from <code>oracle/graalvm-ce</code> (already producing a 404) from <a href="https://hub.docker.com" target="_blank">hub.docker.com</a>  to a place at <a href="https://github.com/graalvm/container/pkgs/container/graalvm-ce" target="_blank">github.com/graalvm/container/pkgs/container/graalvm-ce</a> . The resulting image has the coordinates <code>ghcr.io/graalvm/graalvm-ce</code> and is served by the <em>GitHub Container Registry</em>. Wow, <strong>I didn’t even know that GitHub had a registry!</strong> But <a href="https://github.blog/2020-09-01-introducing-github-container-registry/" target="_blank">in late 2020 they introduced it</a>  as part of their GitHub Packages offering (if you want to see the “normal” Packages in action, you can take a sneak peek <a href="/en/knowledge-hub/blog/github-actions-pipeline" target="_blank">here where I show how to publish Maven artifacts</a> ).</p><p><img width="1024" height="407" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/03cH3SDmS2KC76q7dxBc" alt /></p><p>Logo sources: <a href="https://github.com/" target="_blank">GitHub & GitHub Actions & GitHub Packages logo</a> , <a href="https://www.docker.com/" target="_blank">Docker logo</a> </p><p>Soon I realized that <a href="https://medium.com/faun/migrating-my-docker-images-to-the-github-container-registry-9f304ccf0aaa" target="_blank">more people started to migrate their Docker images</a>  to <a href="https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images" target="_blank">the new GitHub Container Registry</a> :</p><blockquote><p>GitHub Container Registry is currently in public beta and subject to change. During the beta, storage and bandwidth are free. To use GitHub Container Registry, you must enable the feature preview.</p></blockquote><p>The GitHub Container Registry <a href="https://stackoverflow.com/a/66368787/4964553" target="_blank">will ultimately supersede the already existing Packages Docker Registry</a> .</p><h2>All I wanted was: docker run hello-world</h2><p>I hadn’t touched <a href="https://github.com/jonashackt/molecule-ansible-docker-aws" target="_blank">my beloved molecule showcase project</a>  for a while (wow, my blog about <a href="/en/knowledge-hub/blog/ansible-molecule-travisci-aws" target="_blank">Continuous cloud infrastructure with Ansible, Molecule & TravisCI on AWS</a>  is already older than two years). So I finally needed to upgrade to the latest <a href="https://github.com/ansible-community/molecule" target="_blank">molecule</a>  module system with separate drivers not being shipped inside the core anymore. The upgrade really went super smoothly. Right until I hit the Docker Hub rate limiting problem in the final testinfra test case . 🙁 It was really all about a failing <code>docker run hello-world</code>!! <strong>What the hell?!</strong></p><p>So I thought about publishing my own hello-world image to the GitHub Container Registry. Maybe even others would bump into the same problem. And this would give me the chance to get to know this new registry. 🙂 In the end all I wanted was something I could simply use like this:</p><div>

```java
docker run ghcr.io/jonashackt/hello-world
```

</div><h2>A simple Go-based executable</h2><p>The <a href="https://github.com/docker-library/hello-world" target="_blank">original hello-world image from Docker Hub</a>  uses a small executable to print a text. I decided to leverage <a href="https://golang.org/" target="_blank">Go</a>  in order to create a reasonably small executable myself. Every piece of code I use throughout this post <a href="https://github.com/jonashackt/docker-hello-world" target="_blank">is also available on GitHub</a> .</p><p>So let’s start with a ultra simple <a href="https://github.com/jonashackt/docker-hello-world/blob/main/hello-world.go" target="_blank">hello-world.go</a> :</p><div>

```golang
package main
 
import "fmt"
 
func main() {
	fmt.Println("Hello from Docker on GitHub Container Registry!\nThis message shows that your installation appears to be working correctly.")
}
```

</div><p>Building and running a Go program is easy. You only need to have <a href="https://golang.org/doc/install" target="_blank">the Go compiler installed</a>  on your machine. On my Mac I used homebrew and did a <code>brew install go</code>. Now we can build the program with</p><div>

```golang
go build hello-world.go
```

</div><p>This will produce a <code>hello-world</code> executable that we can run with <code>./hello world</code>.</p><h2>A multi-stage build for our GO program</h2><p>As we only need to have the Go compiler present to build the binary, we should implement a Docker multi-stage build. The <a href="https://hub.docker.com/_/golang" target="_blank">official Go image</a>  is quite huge:</p><div>

```bash
$ docker images
golang     latest     861b1afd1d13   7 days ago     862MB
```

</div><p>Therefore we should leverage <a href="https://docs.docker.com/develop/develop-images/multistage-build/" target="_blank">a multi-stage build</a>  inside of our <a href="https://github.com/jonashackt/docker-hello-world/blob/main/Dockerfile" target="_blank">Dockerfile</a> :</p><div>

```java
# We need a golang build environment first
FROM golang:1.16.0-alpine3.13
 
WORKDIR /go/src/app
ADD hello-world.go /go/src/app
 
RUN go build hello-world.go
 
# We use a Docker multi-stage build here in order that we only take the compiled go executable
FROM alpine:3.13
 
COPY --from=0 "/go/src/app/hello-world" hello-world
 
ENTRYPOINT ./hello-world
```

</div><p>The second “run” image is based on <a href="https://hub.docker.com/_/alpine" target="_blank">the same alpine image</a>  as the builder image containing the Go compiler. So let’s now simply build and run our image:</p><div>

```bash
$ docker build . --tag hello-world
$ docker run hello-world
Hello from Docker on GitHub Container Registry!
This message shows that your installation appears to be working correctly.
```

</div><p>The resulting image is around <code>7.55MB</code> which should be small enough for our use cases.</p><h2>List of steps how to publish to GitHub Container Registry with GitHub Actions</h2><p>In order <a href="https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images" target="_blank">to publish a container image on GitHub Container Registry</a>  using GitHub Actions, we have to do the following steps:</p><p><strong>1. Activate improved container support</strong><br /> <strong>2. Create a personal access token (PAT) and a repository secret</strong><br /> <strong>3. Create GitHub Actions workflow and login to GitHub Container Registry using the PAT</strong><br /> <strong>4. Publish (push) Container image to GitHub Container Registry & link it to our repository</strong><br /> <strong>5. Optional: Make your image publicly accessible</strong></p><h2>1. Activating improved container support</h2><p>This step is only needed while the GitHub Container Registry is in beta phase. In order to use the new Container Registry feature, <a href="https://docs.github.com/en/packages/guides/enabling-improved-container-support" target="_blank">we need to activate it in our account first</a> . Therefore head to your GitHub account’s settings menu und click on <code>Feature preview</code>:</p><p><img loading="lazy" width="1024" height="428" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/d143IpnPQNaKFZgUYaKV" alt="Feature preview GitHub profile settings" /></p><p>In my account there was only one feature I could choose from: the <strong>improved container support feature</strong> we need to enable to have GitHub Container Registry ready:</p><p><img loading="lazy" width="1024" height="367" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/NDIe8FOsQIuwtW4zXopZ" alt="Activate improved container support" /></p><h2>2. Creating a personal access token (PAT) and a repository secret</h2><p>Right now (in beta) <a href="https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images#authenticating-to-github-container-registry" target="_blank">we can’t use the <code>GITHUB_TOKEN</code> in GitHub Actions to authenticate to the GitHub Container Registry</a> . So we need to create a personal access token (PAT). But keep in mind <a href="https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token" target="_blank">what the docs state</a> :</p><blockquote><p>PATs can grant broad access to your account. We recommend selecting only the necessary read, write, or delete package scope when creating a PAT to authenticate to the container registry.</p></blockquote><p>Create a PAT in <code>Settings/Developer settings</code> <code>Personal access tokens</code> and click on <code>Generate new token</code>. Here you need to select <code>read:packages</code>, <code>write:packages</code> and <code>delete:packages</code> scopes like this:</p><p><img loading="lazy" width="1024" height="707" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/tnp0PBw1TGlhmJc2KGtI" alt="Create a personal access token in GitHub" /></p><p>Having created the PAT, we can move on to create a new repository secret inside our GitHub repository that contains our Go program and <code>Dockerfile</code>. To create a repository secret, head to your repository’s settings tab and click on <code>Secrets</code>. There you should be able to create a new repository secret:</p><p><img loading="lazy" width="1024" height="626" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/j34Zc4ErTrKMxpnMRdya" alt="Create a new repository secret containing the PAT" /></p><h2>3. Creating GitHub Actions workflow and logging into GitHub Container Registry using the PAT</h2><p>With both PAT and repository secret set up, we can now create a new (or choose an existing) GitHub Actions workflow. After the usual checkout action, we should set our secret as an environment variable. The example project’s workflow file <a href="https://github.com/jonashackt/docker-hello-world/blob/main/.github/workflows/publish.yml" target="_blank">.github/workflow/publish.yml</a>  looks like this:</p><div>

```yaml
name: publish

on: [push]

jobs:
  publish-hello-world-image:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Build the hello-world Docker image
      run: |
        echo $CR_PAT | docker login ghcr.io -u YourAccountOrGHOrgaNameHere --password-stdin
      env:
        CR_PAT: ${{ secrets.CR_PAT }}
```

</div><p>Be sure to use your account or GitHub organization name instead of <code>YourAccountOrGHOrgaNameHere</code>. This should successfully do the login to the GitHub Container Registry.</p><h2>4. Publishing (Pushing) Container image to GitHub Container Registry & linking it to our repository</h2><p>So we’re already approaching the final steps. Now we should have everything in place to push our container image to the GitHub Container Registry. Therefore we need to tag our image correctly while building it. The tag’s pattern must adhere to <code>ghcr.io/OWNER/IMAGE_NAME:latest</code>. Inside the example project’s <a href="https://github.com/jonashackt/docker-hello-world/blob/main/.github/workflows/publish.yml" target="_blank">.github/workflow/publish.yml</a>  it looks like this:</p><div>

```yaml
        docker build . --tag ghcr.io/jonashackt/hello-world:latest
        docker run ghcr.io/jonashackt/hello-world:latest
        docker push ghcr.io/jonashackt/hello-world:latest
```

</div><p>This is already enough to push our image!</p><p>As the image is published as a GitHub account global package, it isn’t linked with our repository and thus won’t be displayed there, nor will it use the <code>README.md</code> as description. In order to automatically link our image to our GitHub repository, we need to add a specific <code>LABEL</code> into our <a href="https://github.com/jonashackt/docker-hello-world/blob/main/Dockerfile" target="_blank">Dockerfile</a> . It should contain the URL to our repository like this:</p><div>

```java
LABEL org.opencontainers.image.source="https://github.com/jonashackt/docker-hello-world"
```

</div><p>Having added this label to our <code>Dockerfile</code>, the image package automatically gets linked to our repository:</p><p><img loading="lazy" width="1024" height="754" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mdbqELJR9KTpyp44D4Ow" alt="The image gets linked to the repository using the LABEL" /></p><p>Also, the image becomes visible on our repository’s main page:</p><p><img loading="lazy" width="1024" height="597" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/9Jty5hcIQtOGT09GqDIS" alt="The image gets visible on the repositories main page" /></p><h2>5. Optional: Making your image publicly accessible</h2><p>By default <a href="https://docs.github.com/en/packages/guides/configuring-access-control-and-visibility-for-container-images" target="_blank">, our container image is private on the GitHub Container Registry</a> . To make it publicly accessible, we need to move to our user account or GitHub organization page. For my account, this is <a href="https://github.com/jonashackt?tab=packages" target="_blank">https://github.com/jonashackt?tab=packages</a> :</p><p><img loading="lazy" width="1024" height="414" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/ExAO5dcQlGhGgeC9vEgM" alt="images are shown as packages on the account level" /></p><p>Click on the container image published (which looks the same as a normal GitHub package) and then go to <code>Package Settings</code>. In the <code>Danger Zone</code>, click on <code>change visibility</code> and choose <code>Public</code>:</p><p><img loading="lazy" width="1024" height="698" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/ZedLoXURVmbxKImy3V8Q" alt="package settings for public visibility" /></p><p>Now we should finally be able to pull and run our image! Simply run <code>docker run ghcr.io/jonashackt/hello-world</code>:</p><div>

```java
$ docker run ghcr.io/jonashackt/hello-world
Unable to find image 'ghcr.io/jonashackt/hello-world:latest' locally
latest: Pulling from jonashackt/hello-world
ba3557a56b15: Already exists
8d624a13b642: Pull complete
Digest: sha256:c88996d21c33ed08a76decc2b53e109bbc601d0fa1e444f24682250c5d406aa1
Status: Downloaded newer image for ghcr.io/jonashackt/hello-world:latest
Hello from Docker on GitHub Container Registry!
This message shows that your installation appears to be working correctly.
```

</div><h2>Give the GitHub Container Registry a try!</h2><p>I didn’t really want to create a <code>hello-world</code> image myself in the first place. But hey! Working with the GitHub Container Registry is fun and you should consider it for your next project. In this article we have seen how to create a small example program and build it using a Docker multi-stage build. The activation of the new feature and the creation of a personal access token (PAT) are the prerequisites to using the Container Registry right now in beta phase. I guess both won’t be necessary anymore soon.</p><p>Using GitHub Actions, we only need to log in using our PAT which we can store in a repository secret. The <code>LABEL org.opencontainers.image.source</code> links our image to our repository after we pushed it using a GitHub Actions workflow of choice. Finally we define our image as publicly accessible if we want it to be. That’s it already! Now it’s time to move your images from Docker Hub to GitHub Container Registry I guess. 🙂 And if you ever need a <code>hello-world</code> image, you know where to find it …</p>

Publishing Docker images to GitHub Container Registry with GitHub Actions

Spring Boot & Apache CXF – How to SOAP in 2016

Spring Boot & Apache CXF – Testing SOAP Web Services

Spring Boot & Apache CXF – XML validation and custom SOAP faults

Spring Boot & Apache CXF – SOAP on steroids fueled by cxf-spring-boot-starter

Senior Solution Architect

<p><span>In this blog post, I will demonstrate how you can deploy an application to AWS Fargate using the AWS CDK. The WordPress software is used, which introduces some requirements. So Elastic File System and Aurora Serverless database will be deployed, too.</span></p><p><span>As an example, think of a website for an event that allows for registration at a specific time. Or there are thousands of people trying to register for a very limited course that many want to attend. Everyone knows the registration likely is available during a 10 minute time frame twice a year as it is instantly fully booked. Now they are hitting the page reload button. An approach to counter such situations is a service named AWS Fargate, which provides computing resources. You don’t have to choose instance types or any other unit in advance. Amazon provides resources as needed by the workload. This is very useful if the usage pattern of the deployed application is extremely volatile and you don’t want to spend time evaluating the best amount of computing resources to handle the load. Maybe there is a database that has to be scaled with your workload.</span></p><h2>Overview</h2><p>To get an idea about the moving parts we need to create, I will provide an image showing the amazon products involved, more details will follow.</p><p><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/1xJHJoqCQFWqqkcwMb1o" alt="overview AWS fargate" width="708" height="341" /></p><h2><h2>Bootstrap</h2><p>Before we start, you have to create the project files. For your convenience, the AWS CDK provides a command to generate some boilerplate code. Install the CDK and create an empty directory. After that, initialize your project.</p>

```
npm install -g aws-cdk
mkdir project && cd project
cdk init --language=python --generate-only
```

<h2><h2>Docker build and push</h2><p>First, we build the Fargate task in the private section. The task serving the WordPress site needs an image, from which the container can be created from. <a href="https://hub.docker.com/_/wordpress" target="_blank"><span>Prebuilt images</span></a> <span> are available for download from the official docker hub. That image will be used to spin up a container in an ECS cluster.</span></p><p><span>You will notice that the <strong>default</strong> images have a maximum HTTP post size of <strong>2 MB</strong> configured, which is not enough if you want to upload larger plugins or media files. To configure the parameters affecting that limit, you have to create or modify some files inside the image. If you do this in local docker or in Kubernetes, you simply mount a file or a config to the container. Fargate does not have such a mechanism. It would be quite nice to mount a file from s3. Amazon is currently <a href="https://github.com/aws/containers-roadmap/issues/56">working on it</a> , but the feature is not completed yet. Another option would be to place a file in an EFS volume. But the AWS CDK <a href="https://github.com/aws/aws-cdk/issues/9496">lacks an upload feature</a>  as known from s3. A different approach is to build your own images, based on the official ones. They can be uploaded to ECR for later usage. To build an image in AWS CDK, you need the context path and a dockerfile:</span></p>

```
# docker context directory
docker_context_path = os.path.dirname(__file__) + "../../src"

# upload images to ecr
nginx_image = ecr_assets.DockerImageAsset(
    self, "Nginx",
    directory=docker_context_path,
    file="Docker.nginx",
)

wordpress_image = ecr_assets.DockerImageAsset(
    self, "Php",
    directory=docker_context_path,
    file="Docker.wordpress",
)
```

<p>That’s it! The AWS CDK detects whether a build is needed and will upload the resulting image to <a href="https://aws.amazon.com/ecr/">ECR</a> . To configure PHP to allow more than the 2 MB limit for file upload, create a file containing</p>

```
file_uploads = On
memory_limit = 64M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 600
```

<p>and include the path in your dockerfile.</p><p>As you can see in the CDK code above, there are two docker images. I prefer to have a single process per container as this is a cleaner approach. The downside is greater complexity when it comes to communication between the processes.</p><p>To allow Nginx to send messages to the PHP process, it needs a network address and port. To allow some local test, you can configure the endpoint at build time:</p>

```
ARG upstream_wordpress_php=localhost

COPY ./nginx/conf.d/http.conf /etc/nginx/conf.d/default.conf

RUN echo -e "upstream wordpress_php {\n  server $upstream_wordpress_php:9000;\n}\n" \
    > /etc/nginx/conf.d/upstream.conf
```

<p>This allows the usage of a local <a href="https://github.com/dhenne/aws-cdk-fargate-aurora-wordpress-example/blob/main/src/docker-compose.yml">docker-compose.yml</a> , to enable a local spin-up of a WordPress site. In Fargate all containers of a task are reachable through the loopback device. Amazon uses a network mode called <a href="https://aws.amazon.com/blogs/compute/task-networking-in-aws-fargate/">awsvpc</a> . Now that we have an image, we are able to define our Fargate task. The image object can be passed directly to the task definition. The AWS CDK takes care of all tasks needed to have the correct image used.</p><h2><h2>Fargate task definition</h2>

```
event_task = ecs.FargateTaskDefinition(self, "WordpressTask")

app_container = event_task.add_container(
    "Php",
    image=ecs.ContainerImage.from_docker_image_asset(wordpress_image)
)
nginx_container = event_task.add_container(
    "Nginx",
    image=ecs.ContainerImage.from_docker_image_asset(nginx_image)
)
```

<p><strong>Note:</strong> The strings to name the resources are meaningless. In AWS, a common pattern is to name your resources with capitalized letters.</p><p>Now you can create an ECS cluster and place your task definition on it. At this point, it is very important to specify the Fargate version to <strong>1.4</strong>. People at AWS have decided that the “latest” platform version <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/platform_versions.html">in fact means the “penultimate” version</a> .</p>

```
cluster = ecs.Cluster(
    self, 'ComputeResourceProvider',
    vpc=properties.vpc
)

wordpress_service = ecs.FargateService(
    self, "InternalService",
    task_definition=event_task,
    platform_version=ecs.FargatePlatformVersion.VERSION1_4,
    cluster=cluster,
)
```

<p>Now you would be able to start a task. There’s one thing more to do. We have to specify a <a href="https://github.com/aws/aws-cdk/issues/10113">port mapping for each container</a> , even though we may not need it. This can be done using the following.</p>

```
nginx_container.add_port_mappings(
    ecs.PortMapping(container_port=80)
)
```



```
app_container.add_port_mappings(
    ecs.PortMapping(container_port=9000)
)
```

<h2><h2>Database</h2><p><span>You can now start a task, but there are still some parts missing. We do need some persistence for files and structured data (SQL). As stated before, an Aurora Serverless database provides the SQL service for our task. The definition is straight forward:</span></p>

```
database = rds.ServerlessCluster(
    self, "WordpressServerless",
    engine=rds.DatabaseClusterEngine.AURORA_MYSQL,
    default_database_name="WordpressDatabase",
    vpc=properties.vpc,
    scaling=rds.ServerlessScalingOptions(
        auto_pause=core.Duration.seconds(0)
    ),
    deletion_protection=False,
    backup_retention=core.Duration.days(7),
    removal_policy=core.RemovalPolicy.DESTROY,
)
```

<p>A secret and a database are automatically created. To pass the values to the WordPress container, you can reference them directly. The AWS CDK creates appropriate roles and permissions to apply to the task that allows the retrieval of secret values.</p>

```
app_container = event_task.add_container(
    "Php",
    environment={
        'WORDPRESS_DB_HOST': database.cluster_endpoint.hostname,
        'WORDPRESS_TABLE_PREFIX': 'wp_'
    },
    secrets={
        'WORDPRESS_DB_USER':
            ecs.Secret.from_secrets_manager(database.secret, field="username"),
        'WORDPRESS_DB_PASSWORD':
            ecs.Secret.from_secrets_manager(database.secret, field="password"),
        'WORDPRESS_DB_NAME':
            ecs.Secret.from_secrets_manager(database.secret, field="dbname"),
    },
    image=ecs.ContainerImage.from_docker_image_asset(wordpress_image)
)
```

<h2><h2>Elastic File System</h2><p><span>WordPress is an application written in PHP and extendable by plugins. All that functionality is relying on a writable filesystem, where the PHP user can place its files, so everything can be done through the web interface. Therefore you need a shared filesystem that can be mounted to the container running the PHP process. Since </span><a href="https://aws.amazon.com/de/about-aws/whats-new/2020/04/amazon-ecs-aws-fargate-support-amazon-efs-filesystems-generally-available/" target="_blank"><span>last year</span></a> <span>, attaching an EFS to Fargate task definitions has generally been available. More details about persistent storage in amazon ECS is available in the <a href="https://aws.amazon.com/blogs/compute/task-networking-in-aws-fargate/">aws documentation</a> . Create your EFS storage and define a volume.</span></p>

```
file_system = efs.FileSystem(
    self, "WebRoot",
    vpc=properties.vpc,
    performance_mode=efs.PerformanceMode.GENERAL_PURPOSE,
    throughput_mode=efs.ThroughputMode.BURSTING,
)
```



```
wordpress_volume = ecs.Volume(
    name="WebRoot",
    efs_volume_configuration=ecs.EfsVolumeConfiguration(
        file_system_id=file_system.file_system_id
    )
)
```

<p>Later that volume can be used to extend your task definition.</p>

```
event_task = ecs.FargateTaskDefinition(
    self, "WordpressTask",
    volumes=[wordpress_volume]
)
```

<p>Now, this volume is available to container mounts in your task definition. WordPress needs write access to that volume. Read permissions are sufficient for Nginx.</p>

```
nginx_container_volume_mount_point = ecs.MountPoint(
    read_only=True,
    container_path="/var/www/html",
    source_volume=wordpress_volume.name
)
nginx_container.add_mount_points(nginx_container_volume_mount_point)
```



```
container_volume_mount_point = ecs.MountPoint(
    read_only=False,
    container_path="/var/www/html",
    source_volume=wordpress_volume.name
)
app_container.add_mount_points(container_volume_mount_point)


```

<h2><h2>Networking</h2><p>The final part of the deployment is about network connectivity. You may have noticed the VPC parameter before. We can create this VPC or use a preexisting one. In my example repository you have the whole network-related resources, separated in a different stack, to be reusable by several other stacks. You can have a look at the <a href="https://github.com/dhenne/aws-cdk-fargate-aurora-wordpress-example/blob/main/cdk_stacks/network.py">file</a> . There are two different network types created and endpoints of a load balancer are placed in the public subnet. The result looks like the following picture.</p><p><img loading="lazy" width="738" height="701" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/7aaZ1hC5SzGa9yuHewiR" alt="context path and docker file" /></p><p>The VPC and the load balancer are then passed to the WordPress stack as property objects. You can also create a parent stack around the constructs, but I think you get the point. Note that there is an upper limit of stacks per account. If you have too many, you can use nested stacks.</p><p> </p><p>To allow the Fargate tasks to connect to the elastic filesystem and the Aurora Serverless database, add them to the appropriate security groups:</p>

```
database.connections.allow_default_port_from(wordpress_service)
file_system.connections.allow_default_port_from(wordpress_service)
```

<p>In this blog post, an application load balancer is used to provide an endpoint to which the outside users can connect. The Fargate tasks are automatically added to the targets of this load balancer as they are created. You simply have to define a listener and configure your load balancer watch for the WordPress service. You also can apply some rules to the listener affecting request routing. But there is only one site delivered at the moment. If the WordPress site is not initialized yet, then it is redirecting requests to an installation page. Therefore the load balancer health checks have to accept that redirect as successful. To achieve that, the HTTP Code 302 can be added to the list of acceptable return codes.</p>

```
http_listener = properties.load_balancer.add_listener(
    "HttpListener",
    port=80,
)

http_listener.add_targets(
    "HttpServiceTarget",
    protocol=elbv2.ApplicationProtocol.HTTP,
    targets=[wordpress_service],
    health_check=elbv2.HealthCheck(healthy_http_codes="200,301,302")
)
```

<h2><h2>Deploy</h2><p>When you are done defining your stacks, all resources can be deployed using the deploy command. This takes a few minutes and outputs information about created instances. You can read about the whole process <a href="https://docs.aws.amazon.com/cdk/latest/guide/apps.html">here</a> . In short, the CDK command synthesizes the code to cloud assemblies, which contain the images and cloudformation templates. After creation, the artifacts are uploaded to AWS.</p>

```
cdk deploy --require-approval never --all
```

<p>I have stripped out the progress bar and other elements of less relevance. You can see the ExternalDNSName the deployed WordPress instance is reachable at. In production scenarios, you should use HTTPS certificates and a suitable name for your users. Both can be done using the AWS CDK.<br /> <img loading="lazy" width="1024" height="101" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/uYZfnpvoReCMXQIx08bC" alt="configure file" /></p><h2><h2>Tests</h2><p>As you define your infrastructure as code, this code can be tested and validated. You can write simple unit tests using your favorite test suite and scan the generated AWS cloud formation templates. This can be checked against what you expect. As I am using python, there are already testing frameworks available.</p><p>To get a reusable snippet of code, which synthesizes your template, add a fixture:</p>

```
@pytest.fixture()
def template():
    app = core.App()
    NetworkStack(app, "NetworkStackTest")
    return json.dumps(app.synth().get_stack("NetworkStackTest").template)
```

<p>Later this can be used to get a template and check the content using asserts. As an example, you can check that a VPC is defined.</p>

```
def test_vpc_created(template):
    assert("AWS::EC2::VPC" in template)
```

<h2><h2>Conclusion</h2><p>AWS CDK is a very convenient tool for deploying resources to AWS. There are many native AWS mechanisms used so that constructs are easily integrated into existing environments. With a few lines of source code you can define a lot of functionality, as you don’t have to define all resources needed by yourself. The complete code of this blog post is available in the example <a href="https://github.com/dhenne/aws-cdk-fargate-aurora-wordpress-example">Github repository</a> . Give it a try!</p></h2></h2></h2></h2></h2></h2></h2></h2></h2>

Fargate with EFS and Aurora Serverless using AWS CDK

In this post you will learn what GitOps is about and see the steps to create a setup on your laptop to gain some experience with ArgoCD. Using an industry standard container orchestrator such as Kubernetes, this enables developers to continuously deploy their applications.

There is a huge number of options available to deploy artifacts. A widely adopted 
approach uses the <a href='https://github.com/opencontainers/image-spec' target='_blank'>OCI image format</a> to ship your software. A continuous integration pipeline builds the software and creates an artifact. The image can then be deployed by a container orchestrator, i.e. Kubernetes. 

Furthermore, development teams are responsible for the entirety of their applications. Defining the infrastructure and the process as code is crucial
to not reducing efficiency and velocity while keeping all actions reproducible and tackling complexity. Tools such as Terraform and Helm can read a definition and be executed as part of a pipeline to push changes to achieve the desired state.

## The GitOps principles

While traditional pipelines and the tools within such as GitHub Actions or GitLab CI/CD are executed whenever a specific event like a *git push* happens, the GitOps principle works the other way around.
The largest difference is that the desired state is continuously pulled from a source such as a VCS repository to drive the infrastructure. This pattern is called a *reconciliation loop* and matches with the Kubernetes <a href='https://kubernetes.io/docs/concepts/extend-kubernetes/operator/' target='_blank'>operator pattern</a>. 

There are many tools out there that leverage the Kubernetes CRDs as input to define the desired state and apply them by operators.

The elements of GitOps can be described by four principles. 

* Declarative infrastructure
* Desired state is stored versioned and immutable
* Pulled automatically from source code
* Continuously reconciled by software agents

The CNCF hosts the project <a href='https://opengitops.dev/' target='_blank'>OpenGitOps</a> which is an attempt to define an open standard.

## ArgoCD

As stated before, in this blog post we will take a closer look at ArgoCD. This tool focuses on Continuous Delivery of applications to Kubernetes.  

For this purpose, ArgoCD monitors a source and creates the API objects out of its definitions files. A lot of options are available starting from plain YAML files to Helm Charts and Kustomize. Even custom <a href='https://argo-cd.readthedocs.io/en/stable/user-guide/config-management-plugins/' target='_blank'>plugins</a> are possible, which is very handy in migration scenarios or if the need for any custom integrations are a usual pattern in your organization. The core concepts of ArgoCD can be found at <a href='https://argo-cd.readthedocs.io/en/stable/core_concepts' target='_blank'>https://argo-cd.readthedocs.io/en/stable/core_concepts</a>. 

ArgoCD is an excellent fit in our mission to deliver our high-value applications at best-in-class velocity to users.

### Installation

Now it is time to take our first steps into our GitOps journey and try out ArgoCD. First, we need
a Kubernetes cluster to deploy to. I will use Minikube here, but every other distribution will do the job. Simply install <a href='https://minikube.sigs.k8s.io/docs/start/' target='_blank'>Minikube</a> and start your local cluster:

```
minikube start --driver=docker
```

After your kubectl tool is configured and you can access your cluster, clone the demo repository and install ArgoCD.

```
git clone git@github.com:dhenne/minikube-argocd-traefik-example.git
```

There is a `bootstrap-argo-cd` chart in the folder `charts/`, which can be used to bootstrap your ArgoCD installation using the helm CLI tool. Later we will use this instance of ArgoCD to manage itself. 


```
cd minikube-argocd-traefik-example/charts/bootstrap-argo-cd/
helm dependency build
helm install argo-cd .
```


After all images are downloaded and the pods are started, you should see a few pods running:

*kubectl get pods*
```
NAME                                                       READY   STATUS    RESTARTS   AGE
argo-cd-argocd-application-controller-0                    1/1     Running   0          52s
argo-cd-argocd-applicationset-controller-bf44c7bc9-2k4w9   1/1     Running   0          53s
argo-cd-argocd-dex-server-8676995c89-7pb5x                 1/1     Running   0          53s
argo-cd-argocd-notifications-controller-7d9d94f45d-rk5kh   1/1     Running   0          53s
argo-cd-argocd-redis-6749667d89-7prsk                      1/1     Running   0          53s
argo-cd-argocd-repo-server-58b8864fc7-kvtln                1/1     Running   0          53s
argo-cd-argocd-server-78fd54c49d-dvv7d                     1/1     Running   0          53s
```

Nice! To interact with the installation and check out what is going on, we can use the UI. The password can be found inside a secret which is automatically created if not disabled by a configuration parameter. Get yours with `kubectl -n default get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d` forwarding a port to your workspace using the command `kubectl port-forward service/argo-cd-argocd-server -n default 8080:443 &` and browse to http://localhost:8080.

After login with the user `admin` you can see there are no applications deployed yet.

![no-applications-yet.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/qRtVD5jDTyXSKRcVe8gF)

Congratulations, now we can start delivering!

### Apps-of-apps pattern

ArgoCD introduces an <a href='https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/#app-of-apps-pattern' target='_blank'>app-of-apps pattern</a>. As applications can be defined in CRDs, applications can be part of an application. This can be used as a starting point to define which applications have to be deployed.

To demonstrate this, there is a root application defined inside the example repository. The definition contains the path pointing to the demo repository:

*charts/root/templates/root.yaml*
```
...
  source:
    repoURL: https://github.com/dhenne/minikube-argocd-traefik-example.git
    path: charts/root
    targetRevision: HEAD
...
```

The root application of the demo project includes another definition for ArgoCD. Unlike before, the source is a Helm repository. This definition causes ArgoCD to match the previously installed instance and therefore to manage itself. Now you are enabled to get <a href='https://docs.renovatebot.com/modules/manager/argocd/' target='_blank'>automated updates using Renovate</a> to update your installation!  

*<a href='https://github.com/dhenne/minikube-argocd-traefik-example/blob/main/charts/root/templates/argo-cd.yaml' target='_blank'>charts/root/tempaltes/argo-cd.yaml</a>*
```
...
  source:
    repoURL: https://argoproj.github.io/argo-helm
    chart: argo-cd
    targetRevision: 5.4.3
...
```

Use *kubectl apply* to instruct pulling the state from GitHub and apply the defined state:

```
kubectl apply -f charts/root/templates/root.yaml
```

Now watch the state changing until there are some apps including Root and ArgoCD: 

![root-and-argocd.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/IfjtNg9SyeUNvY4jweIw)

NOTE: To keep your namespace clean, unlink the ArgoCD instance from your local Helm CLI: `kubectl delete secret -l owner=helm,name=argo-cd` 

Now you can explore the great UI from ArgoCD. Everything is clean and focused on purpose. As mentioned in the core concepts before, there are buttons labeled *refresh* and *sync*. Refreshing causes to poll the source repositories and their state. After that, a sync applies the changes needed to ensure the defined state is in place. If auto sync is enabled, then a sync is done immediately after a refresh causing an out-of-sync state. 

Another very helpful use case is to explore your deployment and get an idea of all parts and their state. If we drill down the `argo-cd` app, there are a lot of resources deployed. It's a lot of work to get an idea of all parts. But within the ArgoCD UI, everything is well organized and it's easy to check out all parts in detail. In fact, there are 47 resources. All relations definitions states, logs, and events are a few clicks away. Even parts that are paid less attention to such as replica sets or endpoints fit nicely into the big picture.

## Application gitopsified

![gitopsify-all-the-things.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/a2QZLvT8RrqBpVWl0uTx)

It's time for additional proof of the ability to deploy our apps. The <a href='https://github.com/dhenne/minikube-argocd-traefik-example/' target='_blank'>demo repository</a> mentioned before can be seen as a widely used pattern of a GitOps repository. There you can find definitions of the desired state, but the source code can be found in a separate repository. In this article, I will demonstrate a slightly different approach. We only define which applications will be deployed and the desired state is placed in your application's source code repositories. Developers then have to do all their changes inside one repository, without the need to keep an eye on the GitOps repository. Of course, you can achieve that using custom pipelines and other tools, but we want a GitOps-style approach here that polls information instead of pushing it to the GitOps repo. On top of that, ArgoCD is our tool of choice here, and it can achieve that. Why should we bother with custom self-made approaches? Be aware that configuration in source code repositories can be considered a violation of <a href='https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/#best-practices' target='_blank'>best practices</a>, so prepare yourself for a good discussion (maybe with this article). 

While there's a <a href='https://github.com/argoproj/argo-cd/blob/master/docs/proposals/multiple-sources-for-applications.md' target=_blank>proposal</a>, which aims at first-class support of multiple sources for our definitions, we have to use ArgoCD <a href='https://argocd-applicationset.readthedocs.io/en/stable/Generators/' target='_blank'>generators</a> to use multiple sources to define our state. Generators are included within the ApplicationsSet feature, which has been fully <a href='https://github.com/argoproj/applicationset/releases/tag/v0.4.0' target=''>integrated into the ArgoCD installation</a> since 2022. ApplicationSets are a great option to template your application definitions without Helm or anything else. Therefore, using the <a href='https://argocd-applicationset.readthedocs.io/en/stable/Generators-Git/' target='_blank'>Git Generator</a> can be considered as a first-class approach, too.

There are two options available for the Git Generator. While the *directories* key scans a directory and creates an application for every folder found, the *files* key does the same thing for a file-matching pattern.

![argo-multisource.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/hx4GsjLORIqFkKBTxXAU)

The demo repository contains another application in the root app named `spring-boot-apps`, which references a Helm Chart consisting of ApplicationSet definitions to demonstrate the two options. Exploring them in the UI can be done in the root app using a link in the application representation. This shortcut is quite handy to move around while using the app-of-apps pattern.

![link-app-of-apps.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/4pGAq7Qxq7N8Yf8uIsdw)

Following the link, you can see two ApplicationSets, which consist of two applications each for a test and production stage. Let's have a look at both sets.


![spring-boot-apps.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8YDMaHsMQemUTUrMieyT)


### Git Generator: Directories

In my opinion, the Directories Generator is the best approach. It generates applications from a pattern that matches folders. Inside the folders, everything that is <a href='https://argo-cd.readthedocs.io/en/stable/user-guide/application_sources/' target='_blank'>supported</a> can be placed. This provides superior flexibility for developers, which encourages people to strive towards a DevOps culture. In the demo repository, you'll find Helm Charts, but it doesn't matter for the application definition and can be swapped to other options in different stages without redefining the ApplicationSet itself. Another advantage worth mentioning is the avoidance of ArgoCD or organization-specific schema of your definitions inside the source code repository. Developers can use their knowledge of existing standards. Below you can find the definition which points to a Spring Boot application.

<a href='https://github.com/dhenne/minikube-argocd-traefik-example/blob/main/charts/spring-boot-apps/templates/springboot-appset-git-directories.yaml' target='_blank'>charts/spring-boot-apps/templates/springboot-appset-git-directories.yaml</a>

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: springboot-appset-git-directories
spec:
  generators:
    - git:
        repoURL: https://github.com/dhenne/spring-boot-service
        revision: HEAD
        directories:
          - path: "deployment/helm/*"
  template:
    metadata:
      name: '{{`{{path.basename}}`}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/dhenne/spring-boot-service
        path: '{{`{{path}}`}}'
        targetRevision: HEAD
      destination:
        server: https://kubernetes.default.svc
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

NOTE: Unlike the files generator, using paths inside hidden folders is not supported, as the folders are <a href='https://github.com/argoproj/argo-cd/blob/02bf903dd9b25c141d073bab3c7588d190145eb3/applicationset/services/repo_service.go#L109' target='_blank'>skipped</a>. 

### Git Generator: Files

Another generator that can be used is the Files Generator that looks for files matching the provided pattern. Each file can then define keys and values in JSON or YAML format. When ArgoCD is generating the applications, values can be used in a template spec to define applications. Think of Helm Charts, then you got the concept. In the demo repository, we use Helm Charts, so we have to exclude ArgoCD templating from the Helm templating engine using Go strings. 

<a href='https://github.com/dhenne/minikube-argocd-traefik-example/blob/main/charts/spring-boot-apps/templates/springboot-appset-git-files.yaml' target='_blank'>charts/spring-boot-apps/templates/springboot-appset-git-files.yaml</a>
```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: springboot-appset-git-files
spec:
  generators:
    - git:
        repoURL: https://github.com/dhenne/spring-boot-service
        revision: HEAD
        files:
          - path: "deployment/multisource-files/**.yaml"
  template:
    metadata:
      name: '{{`{{name}}`}}'
    spec:
      project: default
      source:
        repoURL: https://dhenne.github.io/helm-charts/
        chart: spring-boot-helm-demo
        targetRevision: 0.1.6
        helm:
          values: |-
            {{`{{values}}`}}
      destination:
        server: https://kubernetes.default.svc
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

## Developer Workflow

The workflow for developers to deploy new versions consists of a single commit to the application repository. To instruct ArgoCD to deploy a new version, developers only need to adjust the version number inside the configuration file of the correct environment. For example, the test environment of the directories example can be found in the <a href="https://github.com/dhenne/spring-boot-service/blob/main/deployment/helm/springboot-helm-test/values.yaml" target="_blank">values.yaml</a> in the application repository. There is a GitHub workflow to demonstrate an automated version bump, release, and deployment of the <a href="https://github.com/dhenne/spring-boot-service/" target="_blank">spring-boot-service</a> to test environments. The production environments are requiring manual confirmation to allow the workflow to proceed. All information defining the application and the corresponding environments can be found in one place, which is a big advantage of this approach.

## Conclusion

ArgoCD <a href='https://argo-cd.readthedocs.io/en/stable/#why-argo-cd' target='_blank'>promises</a> to provide an easy-to-understand GitOps tool. As we have seen, this is perfectly true. There is a lot of flexibility while keeping things aligned on purpose. The UI is very helpful to drill down into the complexity of large deployments and developers can still use their favorite standard tooling for defining applications in Kubernetes. If you consider digging deeper into the topic, the <a href='https://github.com/terrytangyuan/awesome-argo' target='_blank'>awesome-argo</a> list might be a good start.

Argonauts, to the moon!

### Links

<a href='https://github.com/argoproj/argo-cd' target='_blank'>https://github.com/argoproj/argo-cd</a>

<a href='https://github.com/dhenne/minikube-argocd-traefik-example' target='_target'>https://github.com/dhenne/minikube-argocd-traefik-example</a>





Introduction to GitOps with ArgoCD

Senior IT Consultant & Developer

Stellt euch eine Insel namens "Alistair Island" vor. Diese Insel ist ein lebendiger Ort mit Häusern, fruchtbaren Böden und einer eingespielten Gemeinschaft von Bewohnern, die nach klaren Abläufen leben. Jedes Geschehen auf der Insel ist von Bedeutung und dient einem bestimmten Zweck. Die täglichen Aufgaben und Rituale sind festgelegt, und die Insel funktioniert wie ein gut koordiniertes Ensemble.

Die Insel ist von einem Festland umgeben, auf dem verschiedene Länder mit unterschiedlichen Industrien und Bevölkerungsgruppen existieren. Diese produzieren unterschiedliche Waren, bieten diverse Dienstleistungen an und sprechen verschiedene Sprachen. Die Bewohner des Festlands sind vielfältig und umfassen Handwerker, Händler, Postboten und viele andere Berufe.

Nicht nur variieren die Sprachen und Waren der verschiedenen Gebiete des Festlands. Auch die Bewohner der Insel haben ihre eigene Sprache und eine einzigartige Kultur, die sich von allem auf dem Festland Bekannten unterscheidet.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wtcM9pkyTcezHMl9uucT)


Obwohl die Insel isoliert ist, gibt es zahlreiche Verbindungen zur Außenwelt. An verschiedenen Küstenpunkten befinden sich Häfen, die Handel und Kommunikation mit dem Festland ermöglichen. Für den Transport von Nachrichten, Gütern und weiteren legen Schiffe an den Häfen des Festlands und der Insel an.

Um den Handel geordnet abzuwickeln, existiert ein Handelsabkommen. Es legt fest, dass Schiffe, die Waren von der Insel zum Festland transportieren oder umgekehrt, bestimmte Handelsrouten nutzen müssen. Schiffe, die vom Festland zur Insel fahren, nutzen die Routen, welche westlich der Insel liegen, während Schiffe, die von der Insel zum Festland fahren, die östlichen Routen befahren.

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/B8LsrUXQQ6W1gNYjodYg)

Es gibt verschiedene Arten von Schiffen. Große Frachtschiffe sind beladen mit Lebensmitteln und Vorräten. Passagierschiffe bringen Besucher zur Insel. Kleinere Boote dienen dazu, spezielle Nachrichten und Aufträge zu überbringen.

Jedes Schiff hat einen Heimathafen. Schiffe, die auf den westlichen Handelsrouten fahren und vom Festland aus entsandt werden, legen an einem festgelegten Hafen am Festland an. Die Schiffe von der Insel warten an den Häfen der Insel, um ihre Reise anzutreten.

Entscheidend ist also nicht, in welche Richtung Waren oder Nachrichten übermittelt werden, sondern wer den Auftrag dazu gegeben hat. Betrachten wir das Ganze stets aus Sicht der Insel, so sind Schiffe, welche vom Festland aus kommen, eingehende Schiffe. Schiffe, die von der Insel entsandt werden, sind ausgehende Schiffe. Egal ob sie Waren liefern oder eine Anfrage senden  um Waren zu bekommen. Ein ausgehendes Schiff kann also durchaus die Intention haben, Waren vom Festland zur Insel zu transportieren. Dennoch gilt es als ausgehend, da die Intention von der Insel ausgeht.

Aufgrund der unterschiedlichen Sprachen der Inselbewohner und des Festlands müssen die Schiffe mit Übersetzern ausgestattet sein, um die Nachrichten des Festlands für die Inselbewohner verständlich zu machen. Auch die Güter müssen möglicherweise umverpackt werden, da auf dem Festland z. B. große Kräne zum Verladen genutzt werden, während auf der Insel alles händisch transportiert wird. Eine Qualitätsprüfung ist ebenfalls sinnvoll, um sicherzustellen, dass die Waren den Bedürfnissen der Insel entsprechen. Falls nicht, gibt das Schiff direkt Rückmeldung an das Festland. Das Ganze gilt selbstverständlich auch andersherum. Die ausgehenden Schiffe packen um, übersetzen und prüfen, ob die Waren für das Festland korrekt sind.

Die Schiffe sind die einzigen, die sowohl die Sprache der Insel als auch die des Festlands beherrschen und wissen, wie die Waren entsprechend umverpackt werden müssen. Sie sind jedoch nur für ihre jeweilige Handelsroute spezialisiert. Wenn neue Handelsrouten entstehen, kommt ein anderes Schiff zum Einsatz.

Ein weiterer wichtiger Aspekt dieser Welt ist die Stabilität der Insel. Die Stabilität der Insel bleibt, unabhängig von Änderungen der Güter oder des Baus neuer Häfen, erhalten. Lediglich die Art des Schiffes und dessen Besatzung müssen sich anpassen oder eine neue Handelsroute eingeführt werden. Die Bewohner der Insel erhalten ihre Waren und Nachrichten jedoch immer in der für sie gewohnten Art und Sprache.

So existiert Alistair Island, sicher und stabil, inmitten des weiten Ozeans. Ungeachtet neuer Schiffe oder Veränderungen auf dem Festland bleibt die Insel das, was sie ist: ein Ort voller Leben, Struktur und mit einer besonderen Verbindung zur Welt um sie herum.

<aside>

### 💡 Zusammenfassung

- Alistair Island ist eine isolierte Insel mit einer eigenen Kultur und klaren Abläufen.
- Die Insel steht in Verbindung mit einem Festland, das vielfältige Waren und Dienstleistungen bietet.
- Handelsabkommen regeln die Handelsrouten zwischen Insel und Festland.
- Schiffe, die vom Festland entsandt werden, gelten (aus Sicht der Insel) als eingehende Schiffe. Sie sind an den Häfen des Festlands stationiert und fahren immer auf den westlichen Handelsrouten.
- Schiffe, die von der Insel entsandt werden, gelten als ausgehende Schiffe. Sie sind an den Häfen der Insel stationiert und fahren immer auf den östlichen Handelsrouten.
- Es gibt verschiedene Schiffstypen, die jeweils spezifische Aufgaben übernehmen (Frachtschiffe, Passagierschiffe, kleine Boote).
- Übersetzer und Qualitätsprüfungen sind notwendig, um die Unterschiede zwischen Insel und Festland zu überwinden. Die spezialisierten Schiffe übernehmen diese Aufgabe.
- Die Stabilität der Insel bleibt gewahrt, unabhängig von äußeren Veränderungen oder neuen Handelsrouten.

</aside>

## Übertragung der Analogie in die Hexagonale Architektur

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mOt9dAJRMSHBA2o8wJdY)


Lasst uns nun die Analogie der Insel, Häfen und Schiffe in die Begriffe der hexagonalen Architektur übertragen, um ihre Zusammenhänge zu verdeutlichen.

### Insel - Domäne

![Finale Insel_komplett.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/I1eM0DTnS5S9rWiTKldh)


Die Insel in unserer Analogie repräsentiert die Domäne – den Kern der Geschäftslogik. Die Insel ist das Zentrum, in dem alle wichtigen Prozesse und Abläufe stattfinden, genauso wie die Domäne der Ort ist, an dem die Geschäftslogik verwaltet und verarbeitet wird.

### **Schiffe - Adapter** 

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vUKzCLWiRDHG9DKfKjNQ)


Die Schiffe in der Analogie stehen für die Adapter in der hexagonalen Architektur. Sie sorgen dafür, dass die Kommunikation zwischen der Außenwelt und der Domäne tatsächlich stattfinden kann. Sie sind spezialisierte Übersetzer, welche die Sprache zwischen der Domäne und der Außenwelt (in beide Richtungen) übersetzen.

Adapter sind also maßgeblich dafür verantwortlich, dass die Anforderungen von außen in eine Form gebracht werden, die im Inneren der Domäne verarbeitet werden kann. Zudem bringen sie auch die Anforderungen nach außen in eine Form, die von der Außenwelt verstanden werden kann. Zum Beispiel könnte ein eingehender Adapter eine REST-API-Anfrage in ein Domänenobjekt übersetzen, während ein ausgehender Adapter die Domänenobjekte in eine für Datenbankabfragen oder externe API-Aufrufe verständliche Form bringt.

Wir unterscheiden also zwischen eingehenden und ausgehenden Adaptern:

- **Eingehende Adapter** nehmen Aufträge von externen Systemen oder Aktoren (Festland) entgegen, übersetzen sie und stellen sie der Domäne bereit. Die eingehenden Adapter entsprechen den eingehenden Schiffen, die von den Häfen des Festlands starten, um auf die Insel zu gelangen.
- **Ausgehende Adapter** hingegen nehmen die Antworten oder Daten der Domäne und bereiten sie für externe Systeme oder Aktoren (Festland) auf, damit sie verständlich und nutzbar sind. Die ausgehenden Adapter sind die ausgehenden Schiffe, die an den Häfen der Insel bereitstehen, um Informationen von der Domäne zurück an das Festland zu transportieren.

Ob ein Adapter nun ein eingehender oder ausgehender ist, entscheidet maßgeblich, wer den Auftrag initial gegeben hat. Dabei schauen wir immer aus der Sicht der Domäne (Insel).

### **Häfen - Ports**

  ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/5B96iNZeQXmyC6FPzJv4)


Die Häfen, die wir in der Analogie verwendet haben, entsprechen in der hexagonalen Architektur den sogenannten Ports. Ports sind die klar definierten Schnittstellen, über die die Domäne, also der Kern der Geschäftslogik, sich von der Außenwelt abgrenzt. Dabei wird zwischen eingehenden und ausgehenden Ports unterschieden. Wir haben in der Analogie schon einmal erwähnt, dass die Schiffe ebenfalls in eingehende und ausgehende unterteilt werden. Dabei war wichtig, wer den Auftrag erteilt  und somit das Schiff entsendet hat. Die Ports (Häfen) bilden dies ebenfalls ab.

Zum Beispiel kann ein eingehender Port eine Bestellung aus einem Webshop entgegennehmen, während ein ausgehender Port Zahlungsinformationen an einen externen Zahlungsdienstleister übermittelt.

## Wie ist die Domäne aufgebaut?

Interessanterweise haben wir uns bisher kaum mit dem Innenleben der Insel selbst beschäftigt – also damit, wie die Bewohner agieren, welche Strukturen und Rituale sie pflegen. Beispielsweise könnte man sich fragen, wie sie Güter effizient verteilen, Entscheidungen im Konsens treffen oder Regeln für ein harmonisches Zusammenleben festlegen. Was machen sie mit den Gütern und Nachrichten? Wie sind die Wege in der Stadt, welche Regeln gibt es und wie werden diese eingehalten? Das liegt daran, dass die eigentliche Gestaltung der Domäne – also der Kern der Geschäftslogik – kein Bestandteil der hexagonalen Architektur ist.

Die hexagonale Architektur konzentriert sich ausschließlich auf die Gestaltung der Schnittstellen (Ports) und den zugehörigen Adaptern. Diese Fokussierung ist zentral, da sie sicherstellt, dass die Domäne unabhängig bleibt und flexibel auf Änderungen in der Außenwelt reagieren kann, ohne ihre interne Logik zu gefährden. Wie die Menschen auf der Insel miteinander interagieren, welche Regeln sie befolgen und wie die alltäglichen Prozesse ablaufen, wird durch andere Architekturprinzipien geregelt. Ein Konzept wie Domain-Driven Design (DDD) kann unter anderem dafür verantwortlich sein, wie die Domäne strukturiert wird. Ihr könnt euch auch eigene Prinzipien ausdenken oder einfach drauf los bauen – all das hat keinen direkten Einfluss auf die hexagonale Architektur und wird auch nicht von ihr vorgeschrieben.

Die wichtigste Regel der hexagonalen Architektur ist: Trennt die Domäne von der Außenwelt. Lasst die Bewohner der Insel autark arbeiten und leben, keine Änderung der Außenwelt darf direkten Einfluss auf die Bewohner der Insel haben.

# **Warum eigentlich ein Hexagon?**

Eine Frage, die bei Einsteigern in die hexagonale Architektur häufig aufkommt, ist: Warum ist es ein Hexagon? Braucht es immer sechs Elemente? Haben die gegenüberliegenden Seiten des Hexagons eine besondere Beziehung?

Die einfache, wenn auch etwas ernüchternde Antwort lautet: Es gibt keine tiefere Bedeutung hinter der Form des Hexagons. Alistair Cockburn, der diese Architektur konzipiert hat, fand die Form des Hexagons einfach spannend und wollte eine anschaulichere Bezeichnung für die Architektur als nur "Ports und Adapter". Tatsächlich ist "Ports und Adapter" der eigentlich korrekte Name für diese Architektur, aber er ist zu generisch und nicht besonders einprägsam.

Wie wir an dem Beispiel der Insel gesehen haben, funktioniert das Ganze auch mit komplett organischen Formen und braucht keine spezielle Geometrie. Das Hexagon ist nur ein symbolisches Mittel, um die unterschiedlichen Schnittstellen und Beziehungen anschaulicher darzustellen.

# **Vom Hafen zum Java Interface**

Ein kleiner Hinweis vorweg: Wer Sprachen wie JavaScript, Python und Co. nutzt, wird die Interfaces vergebens suchen. In solchen Sprachen gibt es diese Schnittstellen nur als implizite Signatur. Das Prinzip bleibt jedoch gleich, auch wenn dort die Schnittstellen nicht explizit als Interface erzeugt werden.

Nun wollen wir uns aber anschauen, wie wir das Ganze im Code umsetzen. Dazu schauen wir uns einmal das folgende Diagramm an.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vTwf2booQtmqkTNLN2B3)

Wie wir sehen, haben wir hier zwischen eingehenden und ausgehenden Adaptern unterschieden. Das sind unsere Schiffe, die zwischen dem Festland und der Insel hin- und herfahren.

Die Insel ist auch in Form der Domäne vorhanden. Diese beinhaltet die Services und die Ports. Anhand der Pfeile könnt ihr nun gut erkennen, wer wen nur nutzt und wer wen implementiert. Wichtig ist hierbei noch, dass der Outbound-Port zwingend notwendig ist, da er dafür sorgt, dass die Dependency umgedreht wird. Dies folgt dem **Dependency Inversion Principle**. Der Inbound-Port ist technisch nicht zwingend notwendig. Der Adapter kann ohne Weiteres direkt auf den Service zugreifen. Durch die Einführung von Interfaces erhaltet ihr jedoch eine losere Kopplung. Außerdem leidet die Testbarkeit ein wenig, wenn ihr direkt von dem Adapter auf den Service zugreift. In der Regel solltet ihr also auch auf der eingehenden Seite einen Port vorsehen.

Nun schauen wir uns noch kurz an, wie das Ganze im Code aussieht.

Wir gehen einmal davon aus, dass wir ein Framework nutzen, welches die Dependency Injection für uns übernimmt. Spring wäre hier ein gutes Beispiel. Dann ist das alles ganz einfach: Wenn eine Klasse ein Interface nutzt, dann gebt ihr es als Übergabeparameter in den Klassenkonstruktor mit.

```kotlin
//uses
@Service
class SomeService(private val forUsingPort: ForUsingPort){
	// what ever your service does
}

```

Implementiert eine Klasse nun ein Interface, dann tut ihr das, was der Name schon sagt. Ihr lasst die Klasse den Port (ForImplementingPort) implementieren. Das sieht dann so aus:

```kotlin
// implements
@Service
class SomeService(): ForImplementingPort{
	 override fun functionOfPort(){
		 // what ever you should do here
	 }
}
```

Und das ist es im Grunde auch schon.

# **Fazit**

Die hexagonale Architektur wird häufig als überladenes Konzept wahrgenommen, doch sie beruht auf wenigen klaren Prinzipien, die ihre Anwendung überraschend einfach machen.

- Trenne die Domäne von der Außenwelt. Die Geschäftslogik und Datenverarbeitung sollten  unabhängig von der Datenbank oder Webframeworks gestaltet werden. Damit sie leichter ausgetauscht oder erweitert werden können.
- Alles, was Technologie betrifft, sollte nicht in der Domäne sein.
- Füge Ports rund um deine Domäne hinzu, um die beiden anderen Punkte sicherzustellen.

Wenn diese Grundsätze einmal verstanden sind, lässt sich die hexagonale Architektur fast immer anwenden. Selbst in kleinen Projekten ist es sinnvoll, die Domäne frei von technischen Details zu halten, um sie einfacher testen zu können. Zum Beispiel kann eine Geschäftslogik, die keine direkte Abhängigkeit zu einer spezifischen Datenbank hat, leicht in isolierten Unit-Tests überprüft werden. Die hexagonale Architektur hilft dabei und eignet sich hervorragend zur Unterstützung dieser Trennung.

Ein Tipp zum Einstieg: Ein Tool wie ArchUnit kann euch helfen, eure Umsetzung mit Tests zu überprüfen. Falls ihr darüber mehr wissen möchtet, schaut bei meinem Blogbeitrag zu ArchUnit vorbei: [ArchUnit in der Praxis: Architektur sauber halten und optimieren](/wissens-hub/blog/archunit-in-der-praxis-architektur-sauber-halten-und-optimieren)

Hexagonale Architektur ist auch nur eine Insel

# Modularisierung leicht gemacht: Spring Modulith mit Kotlin und Hexagonale Architektur

Modularisierung ist ein Schlüsselkonzept in der modernen Softwareentwicklung, um Anwendungen wartbar, testbar und flexibel zu gestalten. In diesem Artikel zeigen wir, wie Spring Modulith in Verbindung mit der hexagonalen Architektur und Kotlin eine solide Grundlage für die Modularisierung schaffen kann. Wir betrachten die Herausforderungen bestehender monolithischer Anwendungen und wie durch klar definierte Module eine schrittweise Entkopplung gelingt.

## Was ist ein Modulith?

Der Name deutet es schon an. Ein Modulith bezeichnet eine Architektur, bei der ein Monolith in klar abgegrenzte Module unterteilt wird. Diese Module sind so gestaltet, dass sie möglichst stark voneinander entkoppelt sind und interne Abhängigkeiten minimiert werden. Ihr könnt es euch so vorstellen, als ob ihr mehrere Microservices in ein Repository packt und unter einer Anwendung handhabt. Zum Beispiel könnte ein Modul die Benutzerdaten und ein anderes Modul die Rechnungsstellung verwalten, wobei beide Module klar voneinander getrennt sind, aber in derselben Anwendung laufen. Der Vorteil liegt auf der Hand: Es sind keine aufwendigen HTTP-Schnittstellen oder Kafka-Broker notwendig. Keine Authentifizierungen, um zwischen den Modulen zu kommunizieren, und dennoch ist der Vorteil einer losen Kopplung gegeben.

Modularisierung kann also als ein sanfter Einstieg in die Microservice-Welt gesehen werden.

## Was macht Spring Modulith

Um eine Anwendung in Module zu unterteilen gibt es verschiedene Optionen. Zum einen kann man einfach den Code in verschiedene Packages packen. Zum anderen bieten Maven bzw Gradle die Option Module mit eigenen Dependencies und eigenem Build-Script zu erzeugen. Und auch die Aufteilung in Microservices ist eine Art Modularisierung.

Schaut man sich die drei Optionen an, fällt auf, dass deren Umsetzung geordnet in ihrem Aufwand steigt. Während Pakete noch sehr einfach anzulegen sind, braucht es für Maven/Gradle-Module schon jeweils separate Dependency-Definitionen. Der Aufwand, Microservices in die Welt zu senden und deren Kommunikation untereinander zu ermöglichen, legt den anderen beiden noch einmal eine ganze Schippe oben drauf.

Wir wollen also eigentlich erst einmal nur mit Paketen starten. Aber hier bekommen wir schnell ein Problem. Stellt euch vor, ihr habt eine Legacy-Anwendung, bei der ein Domain-Modell auf das andere zugreift und das wiederum auf das nächste. Packt ihr nun alle eure passend zusammenhängenden Klassen in die jeweiligen Pakete, sieht es zwar nach verschiedenen Modulen aus, aber in Wirklichkeit ist dem nicht so.

Wir wollen eine lose Kopplung erreichen. Vom Prinzip her wollen wir vielleicht später mal in der Lage sein, eines der Module herauszulösen und als Microservice zu deployen. Dann wollen wir natürlich so wenig wie möglich Kopplung haben. Somit wird der Refactoring-Aufwand reduziert.

Leider sieht man diese Kopplung nur sehr schwer, da sie oft erst bei einer detaillierten Analyse des Quellcodes oder bei der Beobachtung von unerwartetem Verhalten in der Anwendung deutlich wird. Im Zweifel fällt es erst auf, wenn versucht wird, das Modul herauszulösen und als eigenen Microservice zu deployen. Häufig verbirgt sich diese Kopplung in subtilen Abhängigkeiten zwischen Modulen, die durch direkte Zugriffe entstehen. Selbst wenn ihr anfangt aufzuräumen und in einer großen Hauruck-Aktion die Klassen voneinander entkoppelt, werdet ihr spätestens in der weiteren Entwicklung wieder Kopplungen erhalten.

Und genau hier hilft Spring Modulith. Es prüft, ob ihr Dependencies von einem Modul auf ein anderes habt, welche nicht erlaubt sind.

## Grundlagen

Stellen wir uns vor, wir haben folgende Struktur:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── ModuleTwoService.kt

```

In unserem `src`-Package liegt also eine `Application.kt` und daneben zwei Pakete: `module-1` und `module-2`. In den beiden Modulen befindet sich zum einen ein Interface und ein Service, welcher die Implementierung des Interfaces darstellt.

Das Erste, was Spring Modulith macht, ist, alle Pakete, welche auf der gleichen Ebene liegen wie die `Application.kt`, als Modul zu definieren. Das passiert von ganz alleine, und ihr müsst dafür nichts weiter tun. Alle sich darin befindlichen Klassen und Interfaces werden von Spring Modulith standardmäßig als public angesehen. Es ist also erlaubt, von allen anderen Modulen auf diese Klassen zuzugreifen.

Nun wollen wir aber nicht, dass der `ModuleOneService` direkt auf den `ModuleTwoService` und vice versa zugreifen kann, sondern das Ganze soll nur über die Interfaces möglich sein. Um das zu erreichen, packen wir die Services einfach in ein Sub-Package:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── services
│       └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── services
        └── ModuleTwoService.kt

```

Greifen wir nun von einem der Services auf den anderen Service zu, wird der Spring Modulith-Test fehlschlagen.

## Spring Modulith Test

Da wir nun schon den Test erwähnt haben, möchte ich hier noch einmal kurz aufzeigen, wie diese Tests aussehen. Im Grunde stellt euch Spring Modulith drei "Test"-Funktionalitäten zur Verfügung. Zum einen haben wir den eigentlichen Test, der unsere Module analysiert und verifiziert, ob wir die lose Kopplung, die wir haben wollen, einhalten.

```kotlin
@Test
fun `verifies modular structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.verify()
}

```

Als Nächstes haben wir die Option, uns einmal die Module mit deren Definitionen anzuschauen. Hierin werden alle wesentlichen Inhalte eines Moduls wie zum Beispiel die `NamedInterfaces`, auf die wir gleich noch zu sprechen kommen, ausgegeben.

``` kotlin
@Test
fun `print module structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.forEach(Consumer { module: ApplicationModule? -> println(module) })
}

```

Und als Letztes bietet Spring Modulith die Möglichkeit, euch eine Doku zu generieren. Diese beinhaltet verschiedene PlantUML-Diagramme der Module und deren Beziehungen zueinander. Aber auch eine AsciiDoc-Dokumentation mit den Diagrammen und allen Klassen sowie Interfaces, welche nach außen öffentlich gemacht sind.

```kotlin
@Test
fun `create module documentation`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    Documenter(modules)
        .writeDocumentation()
        .writeIndividualModulesAsPlantUml()
}

```

## Hexagonale Architektur

Selten werden wir so einfache Strukturen in unseren Modulen haben, wie in dem Beispiel weiter oben zu sehen. Gerade wenn wir mit Strukturen wie der hexagonalen Architektur arbeiten, entstehen viele Sub-Packages. Einige von ihnen wollen wir ggf. nach außen hin zugänglich machen. Eine solche Struktur könnte dann so aussehen:

```toml
src
├── Application.kt
├── module-1
│   ├── adapter
│   │   ├── inbound
│   │   └── outbound
│   ├── domain
│   │   ├── services
│   │   │   └── ModuleOneService.kt
│   │   ├── model
│   │   └── ports
│   │       ├── inbound
│   │       │   └── ModuleOneInterface.kt
│   │       └── outbound
│   └── services
└── module-2
    ├── adapter
    │   ├── inbound
    │   └── outbound
    └── domain
        ├── services
        │   └── ModuleTwoService.kt
        ├── model
        └── ports
            ├── inbound
            │   └── ModuleTwoInterface.kt
            └── outbound

```

Nun können die Services weiterhin nicht auf andere Services zugreifen, da sie in einem Sub-Package liegen. Jedoch können die Services nun auch nicht mehr auf die Interfaces zugreifen, da diese nun ebenfalls in einem Sub-Package liegen. Wir müssen an dieser Stelle also klar definieren, dass wir zum Beispiel das Package `module-1.domain.ports.inbound` nach außen öffnen wollen. Dazu legt man in Java eine `package-info.java` in das Package und kann hier sein Package definieren.

In Kotlin funktioniert dieser Weg nicht. Hier müssen wir eine Klasse erstellen und dieser gewisse Annotationen mitgeben. Wir erzeugen uns also die `ModuleMetadata.kt` und legen sie in den zu definierenden Ordner. Der Name der Klasse ist dabei nicht von Bedeutung. Ihr könnt die Klasse auch `Drotbohm.kt` oder `Weihnachtsmann.kt` nennen. Viel wichtiger ist der Inhalt.

```toml
└── ports
    ├── inbound
    │   ├── ModuleOneInterface.kt
    │   └── ModuleMetadata.kt

```

Hier sind zwei Annotationen zu sehen: Zum einen `@PackageInfo` und `@NamedInterface`.

```kotlin
@PackageInfo
@NamedInterface(name = ["inbound-port"])
class ModuleMetadata

```

`@PackageInfo` ist in der Java-Variante nicht nötig, da dies durch den Dateityp bereits gegeben ist. In Kotlin wird dies benötigt, damit Spring Modulith weiß, dass es sich um die PackageInfo-Datei handelt und hier die Deklaration für das Package zu finden ist.

`@NamedInterface` definiert den Namen, unter dem das Package später von Spring Modulith gefunden werden kann. Auch diese Annotation ist nötig, ihr müsst jedoch keinen Namen angeben. Lasst ihr den Parameter weg, wird der Name des Packages genutzt. Wollt ihr einen expliziten Namen angeben, müsst ihr in Kotlin mit Named-Parametern arbeiten und das Ganze als Array definieren.

Der Name ist gerade in der hexagonalen Architektur nicht ganz unwichtig. Schaut ihr euch ein wenig weiter oben den Projektbaum an, werdet ihr feststellen, dass wir zwei Packages haben, welche `inbound` heißen. Einmal in der Domain und einmal in den Adaptern. Lasst ihr den Namen weg, werden beide Packages öffentlich gemacht, da sie den gleichen Namen besitzen.

## Explizite Zugriffe auf Module

Stellt euch vor, wir haben einige Module in unserer Anwendung. Wir haben in jedem dieser Module einige Packages öffentlich für andere Module gemacht.

Nun kann jedoch jedes Modul auf alle der geöffneten Packages aus allen anderen Modulen zugreifen. Das wollen wir aber nicht. Wir öffnen ein Package ja ggf. nur für ein spezifisches Modul. Auch hier kann man eine Definition vornehmen, um dies sicherzustellen.

Nehmen wir an, wir haben neben unseren `module-1` und dem `module-2` auch noch ein `module-3`. In allen drei Modulen haben wir gewisse Packages öffentlich gemacht. Nun wollen wir, dass `module-1` ausschließlich auf Packages von `module-2` zugreifen darf. Und innerhalb von `module-2` soll es auch nur auf das `inbound-port`-Package zugreifen dürfen.

Um das zu tun, erstellen wir wieder eine Module-Metadata in der obersten Ebene von `module-1`:

```toml
└── module-1
    ├── ModuleMetadata.kt
    ├── adapter
    │   ├── ...
    ├── domain
        ├── ...

```

In der `ModuleMetadata.kt` fügen wir nun die `@ApplicationModule`-Annotation hinzu. Hierin können wir dann über `allowedDependencies` die Module und Packages deklarieren, auf die das Modul Zugriff haben darf. Das Ganze erfolgt nach dem Schema: `Module :: Package`. Der Paketname ist entweder der Name des Packages, in dem eure `ModuleMetadata.kt` des anderen Moduls liegt, oder derjenige, den ihr in der `ModuleMetadata.kt` als NamedInterface deklariert habt.

```kotlin
@ApplicationModule(
    allowedDependencies = ["module-2 :: inbound-port"]
)
class ModuleMetadata

```

Wenn ihr weitere Module und/oder NamedInterfaces erlauben wollt, könnt ihr dies hier einfach kommasepariert angeben. Solltet ihr zwar ein Modul erlauben, aber keine Einschränkungen der einzelnen Packages wollen, könnt ihr dies mit dem Sternchen (`*`) ausdrücken: `allowedDependencies = ["module-2 :: *"]`.

## Legacy Anwendung

Nun wissen wir, wie wir einzelne Packages freigeben und den Zugriff auf diese für andere Module explizit angeben können. Setzen wir das Ganze in einer Legacy-Anwendung um, wird die Liste an Fehlern im Spring Modulith-Test sehr lang. Das alles mit einem Mal zu beheben, ist oft sehr aufwändig.

Aber auch hierfür bietet Spring Modulith eine Option, um euch auch beim Modularisieren von Legacy-Anwendungen zu unterstützen.

Ihr könnt in der Moduldefinition, in der ihr die `allowedDependencies` eingefügt habt, noch einen weiteren Parameter ergänzen. Und zwar den `type`. Mit diesem könnt ihr das gesamte Modul auf öffentlich setzen. Das heißt, alle Packages sind ab dann für alle anderen Module verfügbar, auch wenn ihr darin keine Module-Metadata definiert habt.

```kotlin
@ApplicationModule(
    type = ApplicationModule.Type.OPEN,
    allowedDependencies = ["module-1 :: inbound-port"]
)
class ModuleMetadata

```

Es ist also möglich, zunächst die Module mit ihrer Paketstruktur zu erstellen und die bis dato starke Kopplung noch zu behalten. Eure Tests bleiben weiterhin grün, ihr könnt andere Änderungen committen und eure Pipeline läuft sauber durch. Das ermöglicht euch, eure Module nacheinander zu entkoppeln. Die Öffnung eines Moduls sollte aber nur so lange Bestand haben, wie ihr euer Modul entkoppelt. Sobald das Modul entkoppelt ist, kann man den Typ entweder auf CLOSED setzen oder einfach aus der `@ApplicationModule`-Annotation entfernen.

## Fazit

Ein Modulith ist ein Monolith, der in klar abgegrenzte Module unterteilt wird, um lose Kopplung und bessere Wartbarkeit zu erreichen. Diese Module laufen zwar in einer gemeinsamen Anwendung, sind aber so strukturiert, dass sie weitgehend voneinander getrennt funktionieren. Gerade bei Legacy-Anwendungen, die viele unübersichtliche Abhängigkeiten aufweisen, bietet das modulare Konzept einen schrittweisen Übergang zu einer entkoppelten Architektur.

Spring Modulith unterstützt diesen Ansatz, indem es auf Packagings in einer Spring-Anwendung aufsetzt und automatisch Module erkennt. Im Default-Zustand sind alle Pakete eines Moduls öffentlich, doch über spezielle „Metadata“-Dateien können unerwünschte Abhängigkeiten blockiert oder nur bestimmte Bereiche (z.B. Interfaces) öffentlich gemacht werden. Das sorgt dafür, dass Zugriffe zwischen Modulen nur explizit erlaubt erfolgen.

Zur Überprüfung der modularen Struktur stellt Spring Modulith drei zentrale Test-Funktionen bereit:

1. **Verifikation**: Ein Test, der prüft, ob alle definierten Modulgrenzen eingehalten werden.
2. **Modul-Übersicht**: Eine Ausgabe der erkannten Module und deren Abhängigkeiten.
3. **Dokumentation**: Eine automatisierte Erzeugung von AsciiDoc-Dateien und PlantUML-Diagrammen.

Gerade bei komplexen Strukturen wie in der hexagonalen Architektur (Ports & Adapters) legen sich Services, Interfaces und Adapterschichten häufig in mehreren Sub-Packages ab. In Kotlin kennzeichnet man die öffentlichen Bereiche dann mit einer speziellen Klasse (z.B. `ModuleMetadata.kt`), die Spring Modulith mit den Annotationen `@PackageInfo` und `@NamedInterface` eindeutig identifiziert. Außerdem lässt sich der Zugriff anderer Module auf genau diese Bereiche durch `@ApplicationModule(allowedDependencies = […])` explizit steuern.

Für Legacy-Systeme, die sofortige Trennung in „saubere“ Module nicht erlauben, können einzelne Module auch offen deklariert werden (`type = ApplicationModule.Type.OPEN`). Dadurch bleiben vorhandene Abhängigkeiten vorerst bestehen. So lässt sich Schritt für Schritt vorgehen: Zuerst werden Module nur grob definiert, später werden einzelne Teile geschlossen, bis eine solide Modularisierung erreicht ist.

Mit diesen Bausteinen habt ihr alles an der Hand, um einen guten Einstieg in die Modularisierung mit Spring Modulith zu schaffen. 

Spring Modulith bietet neben den genannten Dingen auch noch weitere Funktionalitäten, wie Application Events, welche einen weiteren spannenden Aspekt darstellen. Da solltet ihr ebenfalls einen Blick hineinwerfen.

Eine kleine Anwendung, in der wir einige der Aspekte umgesetzt habe, findet ihr hier: [https://github.com/darthkali/spring-modulith-hex-test](https://github.com/darthkali/spring-modulith-hex-test)

##

Modularisierung leicht gemacht: Spring Modulith mit Kotlin und Hexagonale Architektur

ArchUnit in der Praxis: Architektur sauber halten und optimieren

<div><div><p>Mit Kotlin Multiplatform Mobile (KMM) steht ein weiteres Cross-Platform Framework in den Startlöchern. Diesmal geht JetBrains ins Rennen und versucht natürlich alles besser zu machen als alle anderen. Die Frage ist aber: Brauchen wir das wirklich? Ist es einfach nur eine weitere Kopie in neuem Gewand?<br /> Um das herauszufinden, habe ich eine kleine App gebaut und wir schauen uns gemeinsam an, wie das Ganze funktioniert. <a href="https://github.com/darthkali/kmmbikeshare" target="_blank">Hier findet ihr</a>  die Beispiel-App, auf die ich mich im Beitrag beziehe.</p><div><h2><strong>Grundlegender Aufbau von Kotlin Multiplatform Mobile</strong></h2><div><div><p>Starten wir zunächst mit dem Aufbau einer Kotlin Multiplatform Mobile-App. Ein KMM-Projekt basiert in erster Linie auf Modularisierung. Folgt man dem Standardweg von Kotlin, erhält man folgende Struktur:</p></div><div><div><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wZx4FYH6TZikCTxgemlf" alt="Bild zeigt wie die Struktur einer KMM App ist." /></div></div><div><p>Wir haben also ein Android-Modul, ein iOS-Modul und ein shared-Modul. In den Android- bzw. IOS-User-Interface-Modulen implementieren wir hauptsächlich Elemente für das User Interface, während wir die Business- und Datenlogik im shared-Modul umsetzen. Eine strikte Regel für die Abgrenzung gibt es jedoch nicht. Erscheint es für den Anwendungsfall sinnvoll, einen Teil der Businesslogik in die UI-Module zu ziehen, ist das mit Kotlin Multiplatform Mobile ohne Weiteres möglich. Die Implementierungen werden dann nicht zwischen den Systemen geteilt. Diese Flexibilität ist ein großer Vorteil von Kotlin Multiplatform Mobile.</p></div><div><p>Innerhalb des shared-Moduls erfolgt eine Aufteilung in common, iOS und Android Packages. Der größte Teil der Entwicklung findet im common Package statt. Hier liegt in der Regel die komplette Implementierung der Business- und Datenlogik. Also alles von der Implementierung der Datenbank, über die Remoteschnittstelle, bis hin zur Domänenlogik. In die beiden systemspezifischen Packages innerhalb des shared-Moduls kommen nur die Implementierungen, die wir für die jeweiligen Systeme separat entwickeln müssen. Das sind meist nur Treiberimplementierungen oder Ähnliches.</p></div><div><p>Neben den oben genannten Modulen gibt es dann auch das passende Pendant für die Tests. Auch hier erfolgt der Hauptteil im CommonTest Package während wir in den systemspezifischen Packages nur das Setup und die Treiber implementieren.</p></div><div><p>Damit wissen wir nun, wie der ganz grobe Aufbau der App ist. Wie das Ganze im Detail funktioniert, schauen wir uns in den kommenden Abschnitten an.</p></div></div></div><div><h2><strong>expect / actual – was ist das?</strong></h2><div><div><p>Bevor wir uns auf konkrete Implementierungen stürzen, müssen wir vorher noch eine wichtige Funktionalität betrachten. Ich habe im letzten Abschnitt erwähnt, dass wir für manche Anwendungsfälle separate Implementierungen benötigen. Wir brauchen also einen Mechanismus, der eine Weiche darstellt, um jeweils die spezifische Implementierung für die passende Plattform zu kompilieren.<br /> Hierzu kommt das Feature <em>expect / actual</em> zum Einsatz.</p></div><div><div>expect / actual</div><div>

```rouge highlight
// Common
expect fun sharedFunction(parameter: String): String


// iOS
actual fun sharedFunction(parameter: String): String {
    return “this is the iOS implementation”
}


// Android
actual fun sharedFunction(parameter: String): String {
    return “this is the Android implementation”
}
```

</div></div><div><p>Im common Package definieren wir, was implementiert werden soll, ohne jedoch eine direkte Implementierung an dieser Stelle zu erstellen. Das Keyword <em>expect</em> sorgt dafür, dass der Compiler eine Implementierung erwartet. Sie muss den gleichen Namen aufweisen und den gleichen Package-Pfad besitzen. Danach können wir die Methode oder Klasse in dem jeweiligen plattformspezifischen Package implementieren.</p></div></div></div><div><h2><strong>Codesharing zwischen iOS und Android</strong></h2><div><div><p>Kommen wir mal zu den harten Fakten. Was lässt sich denn jetzt wirklich alles teilen? Wie viel müssen wir ggf. doch parallel implementieren?</p></div><div><h3><strong>User Interface</strong></h3><div><p>Wie schon etwas weiter oben beschrieben sind wir absolut frei, was wir teilen wollen. Ob wir nur eine einzige Methode teilen oder die kompletten Daten und Domänenlogik ist uns komplett frei gestellt. Was wir jedoch nicht teilen sollten, ist das User Interface und seine Komponenten. Demzufolge müssen wir auch die UI-Tests jeweils plattformspezifisch entwickeln, was durchaus Sinn ergibt.</p></div></div><div><h3><strong>UI-State</strong></h3><div><p>Da der State in der Beispielanwendung lediglich eine Dataclass ist, kann man ihn durchaus teilen. Aber auch hier merkt man schon, dass wir für die jeweilige Plattform kleine Abweichungen einbauen müssen. Für iOS benötigen wir einen eigenen Konstruktor. So muss man es zwar dennoch doppelt schreiben, hat es aber zumindest in einer Datei, was sicherlich Geschmackssache ist.</p></div><div><div>UI-State</div><div>

```rouge highlight
data class BicycleSharingSystemListState(
    val isLoading: Boolean = false,
    val country: String = "",
    val bicycleSharingSystems: List<BicycleSharingSystem> = listOf(),
) {
    // Need secondary constructor to initialize with no args in SwiftUI
    constructor() : this(
        isLoading = false,
        country = "",
        bicycleSharingSystems = listOf(),
    )
}
```

</div></div></div><div><h3><strong>Remote-Zugriff</strong></h3><div><p>Für die Umsetzung der Remote-Schnittstelle haben wir Ktor als Framework verwendet, was auch JetBrains offiziell als Lösung vorgeschlägt.</p></div><div><p>Hierfür benötigen wir für iOS und Android zunächst eine separate Implementierung des Treibers. Es existieren also in der <em>commonMain</em> eine <em>KtorClientFactory</em>-Klasse, die wir als <em>expect</em> deklarieren, sowie jeweils eine <em>actual</em>-Klasse für Android und iOS. Deren Implementierungen sehen dann wie folgt aus:</p></div><div><div>KtorClientFactory</div><div>

```rouge highlight
expect class KtorClientFactory() {
    fun build(): HttpClient
}


iOS
actual class KtorClientFactory {
    actual fun build(): HttpClient {
        return HttpClient(Ios) {
            install(JsonFeature) {
                serializer = KotlinxSerializer(
                    kotlinx.serialization.json.Json {
                        ignoreUnknownKeys = true
                        useAlternativeNames = false

Android
actual class KtorClientFactory {
    actual fun build(): HttpClient {
        return HttpClient(Android) {
            install(JsonFeature) {
                serializer = KotlinxSerializer(
                    kotlinx.serialization.json.Json {
                        ignoreUnknownKeys = true
```

</div></div><div><p>Hier ist zu erkennen, dass die Implementierungen jeweils recht ähnlich sind. Der wichtigste Unterschied ist, dass bei der jeweiligen Plattform die passende Client-Engine (iOS respektive Android) an den <em>HttpClient</em> übergeben wird. Zur Serialisierung der Klassen nutzt KMM in beiden Fällen die KotlinX Serialization.</p></div><div><p>Mit der Implementierung der <em>KtorClientFactory</em> ist die Grundlage für die Remote-Anbindung bereits eingearbeitet. Das ist gleichzeitig die einzige Stelle, an der wir zwischen iOS und Android unterscheiden müssen. Die restliche Implementierung erfolgt wieder als komplett geteilte Codebasis.</p></div></div><div><h3><strong>Asynchronität</strong></h3><div><p>Neben vielen Klassen und Methoden, die problemlos zwischen iOS und Android teilbar sind, gibt es auch solche, bei denen das nicht ohne Weiteres machbar ist. Ein Beispiel ist die Verwendung von Coroutines. Um Asynchronität zu implementieren, bietet Kotlin für Android die <em>kotlinx.coroutines</em>-Bibliothek an. Das ist unter anderem für die Implementierung der Remote-Anbindung nötig. iOS kann diese Funktionalität jedoch nicht nutzen.</p></div><div><p>Zur Lösung dieses Problems gibt es verschiedene Ansätze:</p></div><div><h4><strong>KMP Beta</strong></h4><div><p>Zum einen kann man ganz entspannt einen Kaffee trinken und warten, bis KMM <a href="https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/" target="_blank">in die Beta kommt</a> . Hier wird laut JetBrains ein neuer Kotlin/Native-Memory-Manager zum Einsatz kommen. Damit sollen die Differenzen zwischen den beiden System begradigt werden und das Arbeiten mit Asynchronität deutlich vereinfacht werden.</p></div></div><div><h4><strong>FlowHelper</strong></h4><div><p>Wer nicht warten kann, hat auch jetzt schon Möglichkeiten. In unserer Beispiel-App haben wir das ganze mit einem Wrapper gelöst. Der FlowHelper kann unterscheiden, ob es eine iOS-App oder eine Android-App ist.</p></div><div><div>Flow Helper</div><div>

```rouge highlight
fun <T> Flow<T>.asCommonFlow(): CommonFlow<T> = CommonFlow(this)

class CommonFlow<T>(private val origin: Flow<T>) : Flow<T> by origin {
    fun collectCommon(
        coroutineScope: CoroutineScope? = null, // 'viewModelScope' on Android and 'nil' on iOS
        callback: (T) -> Unit, // callback on each emission
    ) {
        onEach {
            callback(it)
        }.launchIn(coroutineScope ?: CoroutineScope(Dispatchers.Main))
    }
}
```

</div></div><div><p>Für Android gibt man dem FlowHelper einfach den <em>Coroutinescope</em> mit und setzt den Callback auf <em>null</em>. Der Rest funktioniert dann wie gewohnt mit der <em>coroutinex.flow dependency</em>.</p></div><div><div>collectCommon Implementierung Android</div><div>

```rouge highlight
searchBicycleSharingSystems.execute(
    country = state.value.country,
).collectCommon(viewModelScope) { dataState ->
    state.value = state.value.copy(isLoading = dataState.isLoading)

    dataState.data?.let { bicycleSharingSystems ->
        appendBicycleSharingSystem(bicycleSharingSystems)
        saveAllBicycleSharingSystems(bicycleSharingSystems)
    }
}
```

</div></div><div><p>Bei iOS gibt man einen Callback mit. Man implementiert hier eine Funktion, die KMM dann anstelle der Couroutines ausführt.</p></div><div><div>collectCommon Implementierung iOS</div><div>

```rouge highlight
searchBicycleSharingSystems.execute(
    country: currentState.country
).collectCommon(
    coroutineScope: nil,
    callback: {
        >>> Here you can write your code
    })
```

</div></div></div></div><div><h3><strong>Datenbankzugriff</strong></h3><div><p>Für die Datenbankanbindung haben wir SQLDelight genommen. Das war zum Zeitpunkt der Erstellung das einzige Framework, das sowohl für Android wie auch für iOS eine Implementierung zur Verfügung stellte. Neben SQL Delight gibt es inzwischen auch die Möglichkeit, Realm als Datenbank zu nutzen.</p></div><div><h4><strong>Grundlegende Implementierung</strong></h4><div><p>Ähnlich der Remote-Schnittstelle mit Ktor bedarf es hier ebenfalls einer plattformspezifischen Implementierung der Treiber. Das haben wir ähnlich der Implementierung der PeopleInSpace App von John O’Reilly umgesetzt.</p></div><div><div>Platform Module für die Datenbank</div><div>

```rouge highlight
expect fun platformModule(): Module
```

</div></div><div><p>In den jeweiligen plattformspezifischen Modulen wird der passende Treiber genutzt und das Datenbankschema wie auch der Datenbankname übergeben.</p></div><div><div>Platform Module für die Datenbank – iOS</div><div>

```rouge highlight
actual fun platformModule() = module {
    single {
        val driver = NativeSqliteDriver(KmmBikeShareDatabase.Schema, "BikeShareDb.db")
        KmmBikeShareDatabaseWrapper(KmmBikeShareDatabase(driver))
    }
}
```

</div></div><div><div>Platform Module für die Datenbank – Android</div><div>

```rouge highlight
actual fun platformModule() = module {
    single {
        val driver =
            AndroidSqliteDriver(KmmBikeShareDatabase.Schema, get(), "BikeShareDb.db")
        KmmBikeShareDatabaseWrapper(KmmBikeShareDatabase(driver))
    }
}
```

</div></div><div><p>Das Datenbankschema wird zunächst in SQLDelight-Dateien definiert. Hier wird klassisch erst die Tabelle mit den Attributen und deren Eigenschaften definiert. Danach erfolgen die konkreten Datenbankabfragen (CRUD-Methoden), die später für die App zum Einsatz kommen. Innerhalb der <em>build.gradle.kts</em> wird die SQLDelight-Erweiterung definiert und sowohl der Datenbankname, als auch das Verzeichnis zu den oben beschriebenen Datenbankschemata hinterlegt. Um das anschließend nutzen zu können, müssen wir diesen Abschnitt zunächst kompilieren. Erfolgt eine Änderung an dem Schema, muss ein Rebuild erfolgen, damit die Änderungen wirksam werden.</p></div><div><p>SQLDelight erzeugt aus den Dateien einige neue Dateien, darunter die Implementierung der Datenbank, die die notwendigen Methoden und Verknüpfungen für die Entitäten und die Queries enthält. Außerdem sind hier weitere grundlegende Methoden inbegriffen, zum Beispiel <em>getLastInsertRowId</em>, die die zuletzt eingefügte ID zurückgibt. Das ist später sehr nützlich, um bei einem <em>Insert</em>-Befehl die ID zurückzugeben, um damit weiterzuarbeiten.</p></div><div><p>Die eigentliche Implementierung besteht aus dem Mapper, dem Datenbankmodell und den jeweiligen Repositories.</p></div></div></div><div><h3><strong>Test</strong></h3><div><p>Ein großer Vorteil der geteilten Codebasis ist, dass die Tests ebenfalls geteilt werden können.</p></div><div><p>In der App haben wir Tests für die lokalen Datenbankimplementierungen und für die Interactors erstellt. In diesem Abschnitt geht es also nur um die Tests, die sich innerhalb der geteilten Codebasis befinden.</p></div><div><p>Als Grundlage für die Tests haben wir den <em>BaseTest</em> eingebaut. Er ist im commonMain Package ebenfalls als <em>expect</em> deklariert, da es hier nötig ist, eine Unterscheidung zwischen Android und iOS zu treffen. Der <em>BaseTest</em> ist grundlegend so aufgebaut, dass es möglich ist, darin eine Suspend Function aufzurufen. Dazu muss er in einem <em>CoroutineScope</em> laufen. Außerdem müssen die Module für die Dependency Injection angelegt werden. Diese beiden Aufgaben sorgen dafür, dass die Basisklasse separat für Android und iOS gehandhabt werden muss. Eine weitere wichtige Aufgabe in Bezug auf Koin und den <em>CoroutineScope</em> ist es, diese zu starten und vor allem auch wieder zu stoppen.</p></div><div><div>BaseTest expect im Common Main</div><div>

```rouge highlight
expect abstract class BaseTest() : KoinTest {
    fun <T> runTest(block: suspend CoroutineScope.() -> T)
}
```

</div></div><div><h4><strong>Android</strong></h4><div><p>Unter Android gestaltet sich das unkompliziert. Hier können wir eine <em>KoinTestRule</em> erzeugen, die eine <em>ﬁnished</em>– und eine <em>starting</em>-Methode beinhaltet, die KMM dann automatisch ausführt. Der Coroutine Scope wird ebenfalls selbstständig gestartet und anschließend auch wieder beendet.</p></div><div><div>BaseTest unter Android</div><div>

```rouge highlight
@RunWith(AndroidJUnit4::class)
actual abstract class BaseTest : KoinTest {
    @get:Rule
    val koinTestRule = KoinTestRule.create {
        androidContext(ApplicationProvider.getApplicationContext())
        modules(
            network,
            ...
        )
    }
    actual fun <T> runTest(
        block: suspend CoroutineScope.() -> T
    ) { runBlocking { block(
}
```

</div></div></div><div><h4><strong>iOS</strong></h4><div><p>Für iOS müssen wir die gleiche Funktionalität erzeugen. Aktuell gib es hierfür noch keine spezielle Bibliothek, die das gewährleistet. Um die Funktionalität dennoch zu erzeugen, wurde eine Implementierung benutzt, die aus dem <em>touchlab/KaMPkit</em>-Repository stammt.</p></div><div><p>Für iOS wird der Dispatcher händisch in die <em>BaseTest</em>-Klasse eingebracht und erzeugt ebenfalls eine Methode, mit der die Tests ausführbar sind. Auch hier ist zu sehen, dass Koin zunächst gestartet wurde und später wieder beendet wird. Ebenfalls wird ein <em>CFRunLoop</em> gestartet, der eine Basisimplementierung unter iOS ist. Dieser wird zum Ende hin ebenfalls beendet.</p></div><div><div>BaseTest unter iOS</div><div>

```rouge highlight
actual abstract class BaseTest : KoinTest {

    @OptIn(DelicateCoroutinesApi::class)
    actual fun <T> runTest(block: suspend CoroutineScope.() -> T) {
        var error: Throwable? = null

        GlobalScope.launch(Dispatchers.Main) {
            try {
                initKoin()
                block()
            } catch (t: Throwable) {
                error = t
            } finally {
                stopKoin()
                CFRunLoopStop(CFRunLoopGetCurrent())
            }
        }
        CFRunLoopRun()
        error?.also { throw it }
    }
}
```

</div></div><div><p>Die Testklassen erben nun vom <em>BaseTest</em>. Innerhalb der Testklasse erzeugen wir zunächst eine Methode, die vor jedem Test läuft und einen Basissatz an Daten in der Datenbank implementiert. Sie ist mit <em>@BeforeTest</em> annotiert und nutzt die <em>runTest</em>-Methode aus dem <em>BaseTest</em>.</p></div><div><p>An den Tests wird nun noch die Annotation <em>@Test</em> notiert. Ebenso wird hier die <em>runTest</em>-Methode aus der <em>BaseTest</em>-Klasse wieder verwendet. Die Daten, die die <em>Setup</em>-Methode erzeugt, stehen anschließend vor jedem der Tests zur Verfügung. Die restliche Testimplementierung erfolgt wiederum nach dem Aufbau, wie er von der klassischen Android-Entwicklung bekannt ist.</p></div></div></div></div></div><div><h2><strong>Conclusion</strong></h2><div><div><p>Damit sind die wichtigsten Aspekte von Kotlin Multiplatform Mobile aufgezeigt. Wenn wir einmal auf die Ausgangsfrage zurückkommen, ob JetBrains nur eine weitere Kopie eines bestehenden Crossplatform Frameworks gebaut hat, kann man das ganz klar verneinen.<br /> KMM verfolgt einen deutlich anderen und vor allem freieren Weg, der auch jetzt schon viel Anklang in der Welt der Mobile-App-Entwicklung erhält.<br /> Es gibt bereits jetzt für alle wichtigen Teilbereiche, die in der App-Entwicklung nötig sind, einsatzbereite Frameworks. Wir können von der Businesslogik, über die Remoteanbindung bis zu den Tests alles teilen.</p></div><div><p>Dennoch gibt es auch Hürden, die man nehmen muss. Die Ersteinrichtung vor allem auf iOS-Seite ist mitunter schwierig. Auch sind die externen Bibliotheken mitunter noch nicht für KMM ausgelegt. Und auch die kleinen Schwierigkeiten mit dem Memory-Modell lassen noch Raum für Verbesserung.</p></div><div><p>Alles in allem sollte man dieses Framework nicht aus dem Blick verlieren. Für den entsprechenden Use Case kann und wird sich KMM durchaus relevant einsetzen lassen.</p></div></div></div></div></div>

Kotlin Multiplatform Mobile – Ein praktischer Einstieg

Vor drei Monaten konnte ich zum ersten Mal mit GitHub Copilot von Microsoft auf die Startbahn gehen. Ob der Flug erfolgreich war oder ob ich es gar nicht in die Luft geschafft habe, möchte ich euch einmal berichten.

## Was ist GitHub Copilot?
Der Copilot ist ein intelligenter Assistent, der euch beim Programmieren helfen soll. Dies erfolgt in der Form von Vorschlägen, die euch Copilot in Echtzeit während der Eingabe anzeigt.
Beim Copilot handelt es sich um eine Künstliche Intelligenz, die auf <a href="https://openai.com/blog/openai-codex/" target="_blank">OpenAI Codex </a> basiert. 


## Registrieren und Installieren  
Zunächst werfen wir einen Blick in den Registrierungs- und Installationsprozess. Als Erstes müsst ihr euch bei GitHub registrieren und dort eine Lizenz erwerben. Der Copilot ist leider nicht kostenlos. Es besteht aber die Möglichkeit das Tool zunächst 60 Tage lang zu testen. Danach kostet es 10 $ pro Monat oder 100 $ pro Jahr. 

Studierende haben die Möglichkeit, sich über die <a href="https://education.github.com/" target="_blank">GitHub-Education-Seite</a> zu registrieren und sich den GitHub-Pro-Account zu sichern. Darin sind einige Tools enthalten. Unter anderem <a href="https://docs.github.com/en/copilot/overview-of-github-copilot/about-github-copilot#about-billing-for-github-copilot" target="_blank">GitHub Copilot</a>, aber auch der Azure-Edu-Account mit 100 $ Startbonus (kann man sich durchaus mal anschauen). 

Nach der Registrierung müsst Ihr Copilot in eurer IDE als Plugin installieren.
Ich habe das ganze ausschließlich in IntelliJ und Android Studio genutzt, weshalb hier nur dieser Weg aufgezeigt wird. Neben den <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-a-jetbrains-ide" target="_blank">JetBrain IDEs </a>     steht euch Copilot auch noch in
<a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio-code" target="_blank">Visual Studio Code</a>, <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio" target="_blank">Visual Studio</a> und <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-neovim" target="_blank">Neovim</a> zur Verfügung.


GitHub stellt Copilot als Plugin bereit und ihr könnt ihn mit wenigen Klicks innerhalb der IDE im Pluginfenster installieren. 

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/yndDfMvaT5GtXHbwo03Q)

Ist das abgeschlossen, müsst ihr noch euren GitHub-Account mit der IDE verbinden! Hierdurch wird geprüft, ob ihr eine gültige Lizenz besitzt. Das Login-Fenster findet ihr (in IntelliJ) ganz unten rechts in der Taskbar. 

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/4csRilxRauicu6YEEO55" width="200" />

Danach könnt ihr direkt mit Programmieren anfangen und Copilot wird euch ab sofort Vorschläge geben.


## Wie funktioniert es in der IDE?

Nachdem Copilot eingerichtet ist, könnt Ihr mit der Benutzung starten. Der zunächst intuitive Anwendungsfall ist die Inline-Vervollständigung. Ihr habt eine bereits implementierte Funktion und wollt diese nun im Code aufrufen. Fangt ihr an, diese Funktion einzutippen, erscheint ein ausgegrauter Vorschlag. Das Besondere dabei ist, dass auch die Übergabeparameter mit syntaktisch korrekten Parametern vorgeschlagen werden.

**Du tippst:**
``` Kotlin
sumOf
```

**Vorschlag vom Copilot:**
``` Kotlin
sumOfTwoNumbers(2, 5)
```

Gefällt euch der Vorschlag nicht, habt ihr drei Möglichkeiten, damit umzugehen. 
Zum einen könnt Ihr mit der Tastenkombination `Option + [` bzw. `Option + ]` durch weitere Vorschläge iterieren. Natürlich nur sofern diese vorhanden sind. Zum anderen könnt Ihr den Vorschlag mit `Esc` ablehnen. 

Das Schönste an Copilot ist aber die Möglichkeit, weiterzuschreiben und ihn einfach zu ignorieren. Im Gegensatz zu anderen solcher Tools stört er fast nie. Warum fast nie? Weil es hin und wieder vorkommt, dass er mehrere Zeilen an Vorschlägen macht und sich somit der eigentliche Code nach unten bewegt. Will man aktuell gar nicht mit ihm arbeiten, glitscht es dann ein wenig. Aber das ist selten und stört in Summe nicht. 
Wollt ihr dennoch mal Ruhe von Copilot haben, könnt ihr ihn mit zwei Klicks leicht deaktivieren. Entweder komplett oder für einen bestimmen Dateityp. Das findet ihr am gleichen Ort wie für die Authentifizierung mit GitHub (in IntelliJ).

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8SawieNyROinyPIZE1Mn" width="200"/>


**Hier noch einmal die Shortcuts in der Zusammenfassung:**

| Aktion                | Windows / Linux | macOS       |
| --------------------- | --------------- | ----------- |
| Inline-Vorschläge     | Alt + \         | Option + \  |
| nächster Vorschlag    | Alt + ]         | Option + ]  |
| vorheriger Vorschlag  | Alt + \[        | Option + \[ |
| Vorschlag akzeptieren | Tab             | Tab         |
| Vorschlag ablehnen    | Esc             | Esc         |
 *In anderen IDEs können die Shortcuts abweichen


### Beispiele
Besonders positiv ist mir Copilot bei der Verwendung von Methoden mit vielen Parametern aufgefallen. Gerade beim Nutzen von Datenklassen, die dann in Mocks genutzt wurden, musste ich mir keine Dummy-Daten ausdenken – zum Beispiel beim Verwenden eines Personenobjekts.

``` Kotlin
data class Person(  
	val name: String,  
	val age: Int,  
	val isMarried: Boolean,  
	val children: List<Person>  
)
```
Jetzt gibt man nur  `Person` ein und Copilot schlägt dann etwas wie das folgende vor:
``` Kotlin
Person(  
	name = "John", age = 30, isMarried = true, children = listOf(  
		Person(  
			name = "Mary", age = 15, isMarried = false, children = listOf()  
		),   
		Person(  
			name = "Bob", age = 20, isMarried = false, children = listOf()  
		)  
	)  
)
```
Ok zugegeben, dass John mit 10 Jahren schon den Bob als Kind bekam, scheint nicht ganz realistisch. Hieran erkennt man aber auch die Grenze der KI.

Eine weitere Möglichkeit zur Generierung von Code ist das Schreiben von Kommentaren. Ihr könnt einfach beschreiben, was ihr haben möchtet und Copilot liefert euch einen oft ganz guten Ansatz. 

**Beispiel:**
``` Kotlin
// write a function, that can calculate the sum of 2 float values
```

**Copilot schlägt dann folgendes vor:**
``` Kotlin
fun sum(a: Float, b: Float): Float {  
	return a + b  
}
```

Ihr könnt auch auf anderen Sprachen als Englisch schreiben. Hier zum Beispiel mal zum Vergleich auf Englisch und Deutsch.
``` Kotlin
class Test(){  
//write a function, that takes a string and returns the first character of the string  
//if the string is empty, return null    

fun firstChar(str: String): Char? {  
    if (str.isEmpty()) {  
        return null  
    }  
    return str[0]  
}  
```
  
``` Kotlin
// schreibe eine Funktion, die einen string übergeben bekommt und den ersten Buchstaben des Strings zurückgibt  
// wenn der String leer ist, gib 5 zurück    

fun firstChar2(str: String): Char? {  
	if (str.isEmpty()) {  
		return '5'  
	}  
	return str[0]  
}  
```
*Den Return habe ich geändert, damit man erkennt, dass es unterschiedliche Vorschläge sind.

Copilot kann durchaus noch mehr. Hier sind vor allem auch kreative Ideen gefragt. Eine kleine Auflistung liefert GitHub im Artikel <a href="https://github.blog/2022-09-14-8-things-you-didnt-know-you-could-do-with-github-copilot/" target="_blank">8 things you didn’t know you could do with GitHub Copilot</a>.

## Copilot!
Das ganze wirkt durchaus beeindruckend und funktioniert erstaunlich vernünftig sowie stressfrei. Dennoch ist es nur eine Hilfe. Der Name Copilot ist Programm und sollte auch so verstanden werden. Im Kontext der Programmierung steuert der Pilot (das seid ihr) das Flugzeug (das Programm). Er entscheidet, wo es hingeht und er hält das Flugzeug auf Kurs. 

Copilot gibt dabei wertvolle Unterstützung beim Start, der Landung und dem Flug, ist aber nicht entscheidend für den Erfolg dieses Fluges. Verlasst euch niemals nur auf den Vorschlag von Copilot. Überprüft, was er vorschlägt und ob das ganze wirklich passt.

## Ein Blick hinter die Kulissen
Nach dem ersten positiven Hype, den ich beim Ausprobieren entwickelt habe, stellte ich mir die Frage, woher die Vorschläge eigentlich kommen. 

Zum einen stammen viele Vorschläge vom aktuelle Repository, in dem ich gerade arbeite. Es werden zum Beispiel bereits implementierte Klassen und Methoden erkannt und die Übergabeparameter "sinnvoll" vorgeschlagen. Soweit ist das nichts Neues und das gleiche Vorgehen wie auch bei anderen solcher Tools.

Jedoch werden auch Vorschläge für ganze Codeblöcke gemacht, die keineswegs von meinem Code stammen können. Ein Blick auf die Funktionsbeschreibung von Copilot verrät, dass die Quelle andere Repositories auf GitHub sind. Laut GitHub handelt es sich dabei um öffentlichen Repositories, anhand derer die KI trainiert wird. 

Codex versucht Strukturen und Pattern von existierendem Code zu finden und erzeugt daraus unter anderem diese Vorschläge.  Darin liegt die *Macht* von Github Copilot. 


##  Die Dunkle Seite der Macht
Neben all dem positiven gibt es auch eine Schattenseite. Wie schon erwähnt, generiert der Copilot seine Vorschläge anhand von öffentlichen Repositories. 

Und das ist der große Knackpunkt. Darf Microsoft einfach den Code von anderen Repositories nutzen und damit Profit generieren? Viele der auf GitHub gehosteten Projekte wurden unter einer <a href="https://de.wikipedia.org/wiki/Copyleft" target="_blank">Copyleft-Lizenz</a> lizenziert. Damit sind diese Projekte nicht gemeinfrei, sondern stehen unter der <a href="https://de.wikipedia.org/wiki/Free/Libre_Open_Source_Software" target="_blank">"Free and Open Source Software"-Lizenz (FOSS)</a>.

Nutzt man diese Projekte, muss man den oder die Autoren nennen. Außerdem gibt es die Option, dass Software, die auf Grundlage dieser Open-Source-Software basiert, ebenfalls unter einer Copyleft-Lizenz lizenziert werden muss. Das ganze geschieht bei der Nutzung von GitHub Copilot nicht. Rein rechtlich ist Microsoft hier wohl auf der sicheren Seite, aber einen faden Beigeschmack hat das Ganze dennoch.

Das ist ein komplexes Thema, welches schon <a href="https://www.heise.de/meinung/Edit-Policy-GitHubs-KI-Copilot-ist-keine-Urheberrechtsverletzung-6128502.html" target="_blank">in anderen Artikeln</a> gut beleuchtet wurde. Dieses Thema wird in den kommenden Jahren noch für viel Gesprächsstoff sorgen. Nicht nur GitHub Copilot stößt an Grenzen der Ethik und des Rechts. Auch anderer solcher Tools werden diese Probleme bekommen. Denn eine KI, die gut funktionieren soll, muss auch gut trainiert werden. Das bedeutet, dass es viele Daten braucht. Die Grenzen werden sich wohl Stück für Stück verschieben und ggf. müssen neue Regelungen geschaffen werden, damit der Open-Source-Gedanke weiter bestehen kann.


## Fun Fact
Ich schreibe den Blogbeitrag aktuell im IntelliJ mit Markdown. Und während ich diese Zeilen schreibe, schlägt mir der Copilot meine Satzvervollständigung vor.  
Wir probieren mal, was passiert, wenn ich ab jetzt nur noch das nehme, was Copilot vorschlägt. Ich markiere alles, was ich getippt habe, dick. Und Los gehts:  
  
> **Ha**llo, ich bin ein neuer Entwickler. GitHub ist ein tolles Tool. **Da**s ist ein COPILOT-Tool.  
> **Zum Ab**schluss: **sei nochmal gesa**gt, dass ich ein COPILOT-Tool bin.  
  
Naja, wie sinnvoll das in Textanwendungen ist, sei mal dahingestellt.  :) 

GitHub Copilot – Pair Programming mit der KI

P5.JS: Zeichnen mit der Open-Source-JavaScript-Bibliothek

Imagine an island called "Alistair Island." This island is a vibrant place with houses, fertile soil, and a well-coordinated community of residents who live by well-defined routines. Every activity on the island has significance and serves a specific purpose. Daily tasks and rituals are established, and the island functions like a well-coordinated ensemble.

The island is surrounded by a mainland where various countries with diverse industries and populations exist. These countries produce different goods, offer a range of services and speak different languages. The inhabitants of the mainland are diverse including craftsmen, merchants, postal workers, and many other professions.

Not only do the languages and goods of the different regions of the mainland vary, but the island's residents also have their own language and a unique culture distinct from anything known on the mainland.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wtcM9pkyTcezHMl9uucT)

Although the island is isolated, there are numerous connections to the outside world. At various coastal points, harbors facilitate trade and communication with the mainland. Ships dock at the harbors of both the mainland and the island to transport messages, goods and other stuff.

To ensure organized trade, a trade agreement is in place. It specifies that ships transporting goods from the island to the mainland or vice versa must use designated trade routes. Ships traveling from the mainland to the island use the routes west of the island, while ships traveling from the island to the mainland take the eastern routes.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/B8LsrUXQQ6W1gNYjodYg)

There are various types of ships. Large cargo ships are loaded with food and supplies. Passenger ships bring visitors to the island. Smaller boats are used to deliver specific messages and fulfill special assignments.

Each ship has a home harbor. Ships traveling on the western trade routes and dispatched from the mainland dock at designated mainland harbors. Ships from the island wait at the island’s harbors to embark on their journey.

The key distinction lies not in the direction of goods or messages but in who initiated the request. Viewing everything from the island’s perspective, ships coming from the mainland are considered inbound ships. Ships dispatched from the island are outbound ships. Whether they deliver goods or make requests to get goods. An outbound ship might even intend to transport goods from the mainland to the island, yet it is classified as outbound since the intent originates from the island.

Due to the different languages spoken by the islanders and mainlanders, ships must be equipped with translators to make the mainland's messages understandable for the islanders. Goods may also need to be repackaged. For example large cranes might be used for loading on the mainland, while everything is transported manually on the island. Quality checks are also advisable to ensure the goods meet the island’s needs. If not, the ship provides immediate feedback to the mainland. This process works the other way around as well. Outbound ships repackage, translate and verify that goods destined for the mainland are appropriate.

The ships are the only ones capable of understanding both the language of the island and that of the mainland as well as how to repackage goods accordingly. However, they are specialized for their respective trade routes. When new trade routes emerge, different ships are deployed.

Another important aspect of this world is the stability of the island. The island's stability remains intact regardless of changes in goods or the construction of new harbors. Only the type of ship and its crew need to adapt, or new trade routes need to be established. The islanders continue to receive their goods and messages in the manner and language they are used to.

Thats how the Alistair Island exists secure and stable in the middle of the vast ocean. Despite the emergence of new ships or changes on the mainland the island remains what it is: a place full of life, structure and a unique connection to the world around it.

<aside>

### 💡 Summary

- Alistair Island is an isolated island with its own culture and well-defined routines.
- The island is connected to a mainland that offers a wide range of goods and services.
- Trade agreements regulate the trade routes between the island and the mainland.
- Ships dispatched from the mainland are considered inbound ships (from the island's perspective). They are stationed at mainland harbors and always use the western trade routes.
- Ships dispatched from the island are considered outbound ships. They are stationed at the island's harbors and always use the eastern trade routes.
- There are different types of ships, each taking on specific tasks (cargo ships, passenger ships, small boats).
- Translators and quality checks are necessary to bridge the differences between the island and the mainland. Specialized ships handle these tasks.
- The stability of the island remains intact, regardless of external changes or the introduction of new trade routes.

</aside>

## Transferring the Analogy to Hexagonal Architecture

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mOt9dAJRMSHBA2o8wJdY)

Let’s now transfer the analogy of the island, harbors and ships into the terms of hexagonal architecture to clarify their relationships.

### Island - Domain

![Finale Insel_komplett.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/I1eM0DTnS5S9rWiTKldh)

The island in our analogy represents the domain – the core of the business logic. The island is the center where all critical processes and routines take place, just as the domain is the place where business logic is managed and executed.

### **Ships - Adapters**

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vUKzCLWiRDHG9DKfKjNQ)

Ships in the analogy represent the adapters in hexagonal architecture. They ensure that communication between the external world and the domain can actually take place. These ships act as specialized translators that convert the "language" between the domain and the external world in both directions.

Adapters are therefore crucial in transforming external requests into a format the domain can process.  In addition they translate internal domain responses into a format the external world can understand. For example, an inbound adapter might translate a REST API request into a domain object, while an outbound adapter might convert domain objects into a format suitable for database queries or external API calls.

We distinguish between inbound and outbound adapters:

- **Inbound adapters** receive requests from external systems or actors (the mainland), translate them and pass them to the domain. These correspond to inbound ships which depart from the harbors of the mainland to reach the island.
- **Outbound adapters** on the other hand take the responses or data from the domain and prepare them for external systems or actors (the mainland) in a comprehensible and usable way. These correspond to outbound ships stationed at the island’s harbors ready to transport information from the domain back to the mainland.

Whether an adapter is inbound or outbound is determined primarily by who initiated the request. The perspective is always that of the domain (the island).

### Harbors **- Ports**

  ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/5B96iNZeQXmyC6FPzJv4)

The harbors we used in the analogy correspond to what are known as ports in hexagonal architecture. Ports are the clearly defined interfaces that separate the domain, the core of the business logic, from the external world. A distinction is made between inbound and outbound ports. As mentioned in the analogy, ships are also divided into inbound and outbound, depending on who issued the order and dispatched the ship. Ports reflect this concept as well.

For example, an inbound port might receive an order from a webshop, while an outbound port might send payment information to an external payment provider.

## How is the domain structured?

Interestingly we have so far barely touched on the inner workings of the island itself. How the residents act, what structures and rituals they maintain. For instance one might ask how they efficiently distribute goods, make decisions by consensus or establish rules for harmonious coexistence. What do they do with the goods and messages? How are the paths in the city organized, what rules exist and how are they enforced? This is because the actual design of the domain, the core business logic, is not part of hexagonal architecture.

Hexagonal architecture focuses exclusively on designing the interfaces (ports) and their corresponding adapters. This focus is essential as it ensures that the domain remains independent and can adapt flexibly to changes in the external world without compromising its internal logic. How the people on the island interact, what rules they follow and how everyday processes function are governed by other architectural principles. Concepts like Domain-Driven Design (DDD) can play a role in structuring the domain. Alternatively, you could devise your own principles or simply build as you go. None of this directly affects hexagonal architecture and is not dictated by it.

The most important rule of hexagonal architecture is: **Separate the domain from the external world.** Let the island's residents work and live autonomously. No change in the external world should directly impact the island's inhabitants.

# Why a hexagon?

A common question among beginners in hexagonal architecture is: Why a hexagon? Does it always need six elements? Do the opposite sides of the hexagon have a special relationship?

The simple, although somewhat underwhelming, answer is: there is no deeper meaning behind the hexagonal shape. Alistair Cockburn, who conceptualized this architecture, simply found the hexagon visually appealing and wanted a more illustrative name for the architecture than just "Ports and Adapters." In fact "Ports and Adapters" is the correct name for this architecture but it’s too generic and not particularly memorable.

As we’ve seen in the island analogy the concept also works with completely organic shapes and doesn’t require any specific geometry. The hexagon is merely a symbolic tool to make the different interfaces and relationships more visually comprehensible.

# From the harbor to the Java interface.

A quick note upfront: If you’re using languages like JavaScript, Python and similar you won’t find interfaces as explicit constructs. In these languages interfaces exist only as implicit signatures. However the principle remains the same even though interfaces are not explicitly defined.

Now, let’s take a look at how to implement this in code. To do so, we’ll examine the following diagram.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vTwf2booQtmqkTNLN2B3)

As we can see we have distinguished between inbound and outbound adapters. These are our ships traveling back and forth between the mainland and the island.

The island is also represented in the form of the domain. This includes the services and ports. Based on the arrows, you can clearly see who depends on whom and who implements what. It’s important to note that the outbound port is essential because it ensures the dependency is inverted. This follows the **Dependency Inversion Principle**. The inbound port however is not technically mandatory. The adapter can directly access the service without issues. But by introducing interfaces you achieve loser coupling. Additionally, testability suffers slightly if the adapter directly accesses the service. Therefore, you should typically also define a port on the inbound side.

Now let’s briefly look at how this appears in code.

Let’s assume we are using a framework that handles dependency injection for us such as Spring. This makes everything straightforward: If a class **uses** an interface, you simply pass it as a constructor parameter in the class.

```kotlin
//uses
@Service
class SomeService(private val forUsingPort: ForUsingPort){
	// what ever your service does
}
```

When a class **implements** an interface, it does exactly what the name suggests: the class implements the port (ForImplementingPort). It looks like this:

```kotlin
// implements
@Service
class SomeService(): ForImplementingPort{
	 override fun functionOfPort(){
		 // what ever you should do here
	 }
}
```

And that's it basically.

# Conclusion

Hexagonal architecture is often perceived as an overly complex concept but it is based on a few clear principles that make its application surprisingly simple:

- Separate the domain from the external world. Business logic and data processing should be designed independently of the database or web frameworks so they can be more easily replaced or extended.
- Anything related to technology should not reside within the domain.
- Add ports around your domain to ensure the first two points are upheld.

Once these principles are understood, hexagonal architecture can be applied in almost any situation. Even in small projects it is beneficial to keep the domain free of technical details to make it easier to test. For instance, business logic with no direct dependency on a specific database can be easily verified with isolated unit tests. Hexagonal architecture supports this separation and is an excellent tool for maintaining it.

**A tip for getting started:** A tool like ArchUnit can help you verify your implementation with tests. If you'd like to know more, check out my blog post on ArchUnit: [ArchUnit in practice: Keep your Architecture Clean](/en/knowledge-hub/blog/archunit-in-practice-keep-your-architecture-clean)

Hexagonal Architecture is just an island

# Modularization the easy way: Spring Modulith with Kotlin and Hexagonal Architecture

Modularization is a key concept in modern software development to make applications maintainable, testable and flexible. In this article we will see how Spring Modulith combined with hexagonal architecture and Kotlin provides a solid foundation for modularization. We will examine the challenges of existing monolithic applications and how clearly defined modules enable step-by-step decoupling.

## What is a Modulith?

The name says it all. A Modulith refers to an architecture where a monolith is divided into clearly defined modules. These modules are designed to be as decoupled from each other as possible while minimizing internal dependencies. You can think of it as bundling multiple microservices into a single repository and managing them as one application. For example one module could manage user data and another could handle invoicing. Both modules running in the same application but remaining distinctly separated. The advantage is clear: there is no need for complex HTTP interfaces or Kafka brokers, no authentication for inter-module communication and yet the benefit of loose coupling is maintained.

Modularization can therefore be seen as a gentle introduction to the microservices world.

## What Does Spring Modulith Do?

To divide an application into modules, there are various options. One approach is simply to organize the code into different packages. Another is to use Maven or Gradle to create modules with their own dependencies and build scripts. Additionally splitting an application into microservices is another form of modularization.

When comparing these three options it becomes apparent that their implementation effort increases progressively. While packages are easy to organize, Maven/Gradle modules already require separate dependency definitions. Deploying microservices and enabling their communication with each other adds even more complexity.

We actually want to start with packages initially. But here we run into a problem quickly. Imagine you have a legacy application where one domain model accesses another and vice versa. Even if you group logically related classes into packages it may look like different modules but it’s not really the case.

We aim for loose coupling. Ideally, we should ne able to extract a module  later and deploy it as a microservice. In that sense, we want minimal coupling which reduces refactoring effort.

Unfortunately, this coupling is hard to detect as it often only becomes evident through detailed code analysis or when observing unexpected application behavior. In the worst case, it only becomes apparent when trying to extract a module and deploy it as a standalone microservice. Such coupling often hides in subtle interdependencies between modules arising from direct accesses. Even if you clean up and decouple classes in one big action, coupling will creep back during further development.

This is where Spring Modulith helps. It checks whether you have dependencies between modules that are not allowed.

## Basics

Let’s assume we have the following structure:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── ModuleTwoService.kt

```

In our `src` package, there is an `Application.kt` and alongside it two packages: `module-1` and `module-2`. Each module contains an interface and a service that implements the interface.

The first thing Spring Modulith does is to define all packages at the `Application.kt` level. This happens automatically without requiring any additional configuration. All classes and interfaces in these packages are by default considered public by Spring Modulith allowing other modules to access them.

Now, we don’t want `ModuleOneService` to directly access `ModuleTwoService` and vice versa; access should only be possible through the interfaces. To achieve this, we simply place the services in a subpackage:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── services
│       └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── services
        └── ModuleTwoService.kt

```

If one service now tries to access another one, the Spring Modulith-Test will fail.

## Spring Modulith Test

Since we’ve mentioned the test let’s briefly explore what these tests look like. Spring Modulith provides three main “test”-functionalities. First, there’s the actual test that analyzes our modules and verifies if we maintain the desired level of loose coupling.

```kotlin
@Test
fun `verifies modular structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.verify()
}

```

Next we have the option to inspect the modules and their definitions. This outputs the key contents of each module such as `NamedInterfaces`, which we’ll discuss shortly.

```kotlin
@Test
fun `print module structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.forEach(Consumer { module: ApplicationModule? -> println(module) })
}

```

Also Spring Modulith can generate a documentation. This includes various PlantUML diagrams of the modules and their relationships as well as AsciiDoc documentation with diagrams and all publicly exposed classes and interfaces.

```kotlin
@Test
fun `create module documentation`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    Documenter(modules)
        .writeDocumentation()
        .writeIndividualModulesAsPlantUml()
}

```

## Hexagonal Architecture

Rarely will our modules have simple structures like the example above. Especially when working with an architectural style like hexagonal architecture. There we have many sub-packages. Some of which we may want to expose externally. Such a structure might look like this:

```toml
src
├── Application.kt
├── module-1
│   ├── adapter
│   │   ├── inbound
│   │   └── outbound
│   ├── domain
│   │   ├── services
│   │   │   └── ModuleOneService.kt
│   │   ├── model
│   │   └── ports
│   │       ├── inbound
│   │       │   └── ModuleOneInterface.kt
│   │       └── outbound
│   └── services
└── module-2
    ├── adapter
    │   ├── inbound
    │   └── outbound
    └── domain
        ├── services
        │   └── ModuleTwoService.kt
        ├── model
        └── ports
            ├── inbound
            │   └── ModuleTwoInterface.kt
            └── outbound

```

Services still cannot access other services as they are in a subpackage. However, they also cannot access the interfaces as they are now in a subpackage as well. Here, we must explicitly define that for instance, the `module-1.domain.ports.inbound` package should be externally accessible. In Java, this is done by creating a `package-info.java` file in the package.

In Kotlin this approach doesn’t work. Instead, we create a class and annotate it. For example, we create a `ModuleMetadata.kt` file and place it in the respective package. The class name is irrelevant. You could name it `Drotbohm.kt` or `SantaClaus.kt`. The content is what matters.

```toml
└── ports
    ├── inbound
    │   ├── ModuleOneInterface.kt
    │   └── ModuleMetadata.kt

```

Here are two annotations: `@PackageInfo` and `@NamedInterface`.

```kotlin
@PackageInfo
@NamedInterface(name = ["inbound-port"])
class ModuleMetadata

```

`@PackageInfo` is unnecessary in the Java version since it is implicitly provided by the file type. In Kotlin it is required for Spring Modulith to recognize it as the package declaration file.

`@NamedInterface` defines the name under which the package will be recognized by Spring Modulith. This annotation is also required but you can omit the name parameter. In this case the package name will be used. If you want to specify a name explicitly you must use named parameters and define it as an array.

The name is particularly important in hexagonal architecture. Looking at the project tree above we see two packages named `inbound`, one in the domain and one in the adapters. Without a specified name both packages are exposed as they share the same name.

## Explicit Module Access

Imagine we have several modules in our application, each exposing some packages to other modules.

Now any module can access all exposed packages from all other modules. Thats not what we want. Instead, we want to expose a package only for specific modules. This can also be defined.

Suppose we have `module-1`, `module-2`, and `module-3`. Each has some exposed packages. We want `module-1` to access only the packages from `module-2` and within `module-2` only the `inbound-port` package.

To achieve this we create a `ModuleMetadata.kt` file at the top level of `module-1`:

```kotlin
└── module-1
    ├── ModuleMetadata.kt
    ├── adapter
    │   ├── ...
    ├── domain
        ├── ...

```

In `ModuleMetadata.kt` we add the `@ApplicationModule` annotation. Here we can declare the modules and packages the module is allowed to access using `allowedDependencies`. The schema is `Module :: Package`. The package name is either the name of the package containing the `ModuleMetadata.kt` of the other module or the name defined as a NamedInterface in the `ModuleMetadata.kt`.

```kotlin
@ApplicationModule(
    allowedDependencies = ["module-2 :: inbound-port"]
)
class ModuleMetadata

```

If you want to allow additional modules and/or NamedInterfaces, you can list them separated by commas. If you wish to allow a module but impose no restrictions on individual packages, you can use an asterisk (`*`): `allowedDependencies = ["module-2 :: *"]`.

## Legacy Application

Now that we know how to expose specific packages and explicitly declare module access, let’s apply this to a legacy application. In this case the list of errors in the Spring Modulith-Test might be long. Fixing everything at once is often impractical.

However, Spring Modulith offers an option to support modularizing legacy applications.

In the module definition, where you’ve added `allowedDependencies`, you can also add a `type` parameter. This allows you to make the entire module public, meaning all packages are accessible to all other modules even without Module-Metadata definitions.

```kotlin
@ApplicationModule(
    type = ApplicationModule.Type.OPEN,
    allowedDependencies = ["module-1 :: inbound-port"]
)
class ModuleMetadata

```

This makes it possible to create modules with their package structures while maintaining strong coupling temporarily. Your tests remain green, commits can proceed and your pipeline continues to run. This enables gradual decoupling of modules. However this approach should only remain until the module is being decoupled. Once the module is decoupled the type can be set to CLOSED or removed from the `@ApplicationModule` annotation.

## Conclusion

A Modulith is a monolith that is divided into clearly defined modules to achieve loose coupling and improved maintainability. While these modules run in a single application, they are structured so that they operate largely independently. Particularly for legacy applications with many tangled dependencies, this modular concept provides a gradual transition toward a more decoupled architecture.

Spring Modulith supports this approach by building on packaging within a Spring application and automatically detecting modules. By default, all packages of a module are public, but special “metadata” files can block unwanted dependencies or make only certain areas (such as interfaces) public. This ensures that access between modules only occurs if it is explicitly allowed.

To verify the modular structure, Spring Modulith provides three key test functions:

1. **Verification**: A test that checks whether all defined module boundaries are respected.
2. **Module Overview**: An output displaying the detected modules and their dependencies.
3. **Documentation**: Automated generation of AsciiDoc files and PlantUML diagrams.

Especially in more complex structures, such as those found in hexagonal architecture (Ports & Adapters), services, interfaces and adapter layers are often split into multiple sub-packages. In Kotlin you mark the public areas with a special class (e.g., `ModuleMetadata.kt`) that Spring Modulith recognizes through the `@PackageInfo` and `@NamedInterface` annotations. Additionally, you can explicitly control how other modules access these areas by using `@ApplicationModule(allowedDependencies = […])`.

For legacy systems that do not allow an immediate separation into “clean” modules, individual modules can also be declared as open (`type = ApplicationModule.Type.OPEN`). This way existing dependencies remain in place for the time being. You can proceed step by step: first defining modules only roughly and then gradually restricting certain parts until a solid modularization is achieved.

With these building blocks, you have everything you need to get started with modularization using Spring Modulith.

Beyond these features, Spring Modulith also offers other functionalities, such as Application Events—another exciting aspect worth exploring.

A small application where we have implemented some of these aspects can be found here: [https://github.com/darthkali/spring-modulith-hex-test](https://github.com/darthkali/spring-modulith-hex-test).

Modularization the easy way: Spring Modulith with Kotlin and Hexagonal Architecture

ArchUnit in practice: Keep your Architecture Clean

IT-Consultant & Entwickler

IT-Consultant & Developer

Erste Erfahrungen mit einer explorativen, nicht spezifikationsgetriebenen Vaadin–Angular-Migration mit Claude Code Opus

Strukturierte Migration mit Claude Code - Context Engineering statt Prompt Engineering

Junior IT-Consultant

Erfurt | Team

Vielen Dank für deine Anfrage. Ich melde mich bei dir.

Vielen Dank für deine Anmeldung. Eine E-Mail zur Bestätigung ist zu dir unterwegs.

Diese Seite ist eine Vorschau. \nKlicken Sie hier\n, um den Vorschaumodus zu verlassen.

Zu deiner Suche haben wir leider keine passenden Blogartikel gefunden. 

Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.

Du hast Fragen oder möchtest dich mit mir austauschen? Gern - trag einfach deine Kontaktdaten ein.

Die \nDatenschutzerklärung\n der codecentric AG habe ich zur Kenntnis genommen und bestätige das mit der Absendung des Formulars.*

Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.

Ich möchte eure Inhalte abonnieren. Diese Einwilligung kann ich jederzeit widerrufen bzw. den Blog Newsletter abbestellen. Die Datenschutzerklärung habe ich gelesen. Ich bin damit einverstanden, dass die codecentric AG, Hochstr. 11, 42697 Solingen, mich über eigene Dienstleistungen, branchenrelevante Events, Webinare und Publikationen der codecentric AG über die von mir angegebene E-Mail-Adresse informiert. Meine Einwilligung ist freiwillig. Ich kann meine Einwilligung jederzeit mit Wirkung für die Zukunft widerrufen (z.B. über den hierfür vorgesehenen Abmeldelink in unserem Newsletter, per E-Mail an datenschutz@codecentric.de oder per Post an die oben genannte Adresse der codecentric AG) erklären. Weitere Hinweise zur Verarbeitung meiner personenbezogenen Daten und zu meinen Rechten als betroffene Person finde ich hier: \nhttps://www.codecentric.de/datenschutzerklaerung\n

Bitte wähle deine/n gewünschte/n Standort/e aus.

Wir möchten dich als Mensch kennenlernen. Erzähle uns, wer du bist, worauf du Wert legst, wie du gerne arbeitest und was du von uns als Arbeitgeber erwartest.

Bitte füge deine Bewerbungsunterlagen ​(mind. Lebenslauf, gerne auch mehr)​​ ​als eine ​PDF-​Datei ​hinzu.

Es gilt die Datenschutzerklärung der codecentric AG, abrufbar unter \nDatenschutzbestimmungen\n. Mit dem Absenden des Formulars bestätige ich, dass ich diese zur Kenntnis genommen habe.

Job application form field placeholder 10

Keine passende Rolle gefunden? Bewirb dich bitte trotzdem initiativ! Jenseits von starren Schubladen zählen für uns vielmehr Motivation, Kompetenz und der Cultural Fit.

Job application form field placeholder 11

Dies ist ein Pflichtfeld, bitte fülle es aus.

Willkommen im Team Erfurt

Jetzt für unseren Newsletter anmelden