Skip to main content

ADR 024 – Use of Linkerd as Service Mesh for CIVITAS/CORE

Date: 2026-01-13

Status: Reviewed

Decision Makers: Architecture Board

Context​

CIVITAS/CORE is designed as a modular, cloud-native Smart City platform composed of multiple loosely coupled services. As the number of services and integrations grows, the platform requires a consistent and secure mechanism for service-to-service communication, including:

  • Mutual TLS (mTLS)
  • Traffic observability
  • Resilience features such as retries and timeouts
  • Minimal operational overhead

A service mesh provides these capabilities transparently at the infrastructure layer without requiring changes to application code.

This ADR evaluates the adoption of Linkerd as the recommended service mesh for CIVITAS/CORE deployments, compared to the alternatives Istio and Consul Connect.

Checked Architecture Principles​

  • [none] Model-centric data flow: this ADR does not influence this principle
  • [full] Distributed architecture with unified user experience
  • [full] Modular design
  • [full] Integration capability through defined interfaces
  • [full] Open source as the default
  • [full] Cloud-native architecture
  • [full] Prefer standard solutions over custom development
  • [partial] Self-contained deployment: service mesh needs full cluster rights
  • [full] Technological consistency to ensure maintainability
  • [full] Multi-tenancy: this ADR does not influence this principle
  • [full] Security by design

Decision​

CIVITAS/CORE recommends the use of Linkerd as the default service mesh for deployments that require service mesh functionality.

Linkerd is selected due to its:

  • Simplicity and low operational complexity
  • Strong focus on security-by-default (automatic mTLS)
  • Lightweight resource footprint
  • Clear separation of concerns between platform and applications
  • Mature CNCF ecosystem alignment

The use of a service mesh remains optional for CIVITAS/CORE deployments. However, when a service mesh is required (e.g. to fulfill TR-03187), Linkerd is the preferred and documented choice.

Linkerd is intentionally adopted in a way that ensures it remains easily replaceable by alternative service mesh implementations (e.g. Istio), as CIVITAS/CORE does not rely on mesh-specific APIs or proprietary features and limits service mesh usage to standardized, infrastructure-level capabilities such as mTLS, basic traffic observability, and resilience mechanisms.

Consequences​

  • CIVITAS/CORE documentation will include:
    • Reference architecture for Linkerd-based service mesh integration
    • Guidelines for mTLS, traffic observability, and failure handling
  • CIVITAS/CORE components must be compatible with:
    • Sidecar-based proxy injection
    • Transparent mTLS without application changes
  • Advanced traffic management (e.g. L7 routing, canary releases) remains intentionally limited to avoid overlap with API gateway responsibilities.
  • Deployments that do not require a service mesh (e.g. shared cluster with limited access) are not forced to adopt one.

Alternatives​

  • Istio: Discarded due to higher operational complexity, steeper learning curve, and broader feature set that exceeds CIVITAS/CORE requirements. While powerful, Istio introduces significant cognitive and operational overhead for platform operators.

  • Consul Connect: Discarded due to stronger coupling to the HashiCorp ecosystem and additional dependencies. While offering solid service mesh capabilities, it is less aligned with the Kubernetes-native and fully open-source direction.

See also​