meldestelle/docs/99_Journal/2026-04-16_Consul-Port-Hardening.md

Journal: Consul Healthcheck & Port Hardening

Datum: 16. April 2026 Badge: 🏗️ [Lead Architect] & 👷 [Backend Developer]

Problemstellung

Der masterdata-service wurde im Consul als critical markiert, da der Healthcheck einen 404-Fehler lieferte. Die Analyse ergab, dass Consul versuchte, den /actuator/health Endpoint auf dem Ktor-Port (8091) statt auf dem Spring-Management-Port (8086) zu erreichen. Trotz der Konfiguration health-check-port: ${server.port} kam es zu Fehlinterpretationen, möglicherweise aufgrund der doppelten Port-Registrierung (Ktor als Service-Port, Spring als Management-Port).

Durchgeführte Maßnahmen

1. Port-Explizitheit (Hardening)

Um jegliche Mehrdeutigkeit bei der Port-Auflösung durch Spring Cloud Consul zu vermeiden, wurden in allen 11 Backend-Services die dynamischen Variablen (${server.port}) in der Consul-Konfiguration durch literale Werte ersetzt.

2. Ktor/Spring Separation (SCS)

Für Services mit hybrider Architektur (Spring + Ktor, z.B. masterdata-service):

• Service Port (Consul): 8091 (Ktor API) -> Ziel für das Gateway.
• Healthcheck Port: 8086 (Spring Tomcat) -> Ziel für Consul Healthchecks.
• Konfiguration: health-check-port: 8086 wurde explizit gesetzt.

3. Port-Bereinigung & Vereinheitlichung

Einige Services hatten uneindeutige Port-Zuweisungen oder Standardwerte, die mit anderen Services kollidierten oder von der Dokumentation abwichen. Alle Ports wurden nun fest gezurrt:

Service	Port (Spring/Health)	API (Ktor)	Status
gateway	8081	-	Fixiert
ping-service	8082	-	Fixiert
entries-service	8083	-	Fixiert
events-service	8085	-	Fixiert
masterdata-service	8086	8091	Health-Fix
identity-service	8087	-	Vereinheitlicht
results-service	8088	-	Vereinheitlicht
billing-service	8089	-	Vereinheitlicht
mail-service	8092	-	Vereinheitlicht
series-service	8093	-	Vereinheitlicht
scheduling-service	8094	-	Vereinheitlicht
zns-import-service	8095	-	Fixiert

Ergebnis

Durch die explizite Angabe der Healthcheck-Ports kann Consul nun zuverlässig den Spring Boot Actuator erreichen, unabhängig davon, welcher Port als primärer Service-Port (z.B. für Ktor) registriert ist. Dies stabilisiert die Service-Discovery und das Routing über das API-Gateway.

---

🏗️ [Lead Architect]: Architektur-Entscheidung: Wir bevorzugen ab sofort literale Ports in der application.yml für Docker-Deployments, um Komplexität in der Variablen-Auflösung zu reduzieren. **,filename: