Skip to main content

ADR 006: Exposing publicly available services in kubernetes (GatewayAPI vs. Std Ingress)

Date: 2025-09-04 Status: Proposed

Decision Makers: @JulianSobott @PatersonKopp

Context​

As a DevOps engineer I want to have a best practice on how to expose the APIs and component UIs in our deployment definition, in order to keep the deployment compatible with different operators and highly maintainable.

Issue: https://gitlab.com/civitas-connect/civitas-core/civitas-core-v2/civitas-core-deployment/-/issues/11

Checked Architecture Principles​

  • [none] Model-centric data flow
  • [partial] Distributed architecture with unified user experience - Apps are decoupled from network logic. UI Depends on the used implementation.
  • [full] Modular design - gateway class, gateway and route
  • [full] Integration capability through defined interfaces - native kubernetes API
  • [full] Open source as the default
  • [full] Cloud-native architecture
  • [partial] Prefer standard solutions over custom development - Requires custom routes for most tools, becuase most only support ingress
  • [full] Self-contained deployment
  • [full] Technological consistency to ensure maintainability - All services use routes instead of ingress
  • [full] Multi-tenancy - mutliple domains, gateways and LB are possible
  • [full] Security by design - Allows fine-grained RBAC

Decision​

Chosen option: "Use Gateway API", because it is more modular and prevents vendor lock-in

Consequences​

  • Helm Charts need to be adjusted/supplemented with Routes
  • Existing Ingresses from v1 need to be rewritten
  • GatewayClasses need to be selected

Alternatives​

Use Gateway API (Selected solution)​

Docs: https://gateway-api.sigs.k8s.io/

  • Good, because mostly independent of implementations
    • No more implementation specific annotations
    • Civitas can be deployed independent of which implementation is used in a data center
  • Good, because has a modular (role oriented) architecture (cluster operators, app developers, it sec)
  • Good, because official part of kubernetes -> Explanation from developer
  • Bad, because CRDs need to be installed manually
  • Bad, because not all data centers might support this
  • Bad, because (nearly?) no helm chart supports this -> github discussion
  • Bad, because more complex than ingress

Although this should be independent of the implementation we might need to decide on one implementation to use. It may also may be a good idea to choose multiple to ensure, we don't create a vendor lock-in and keep compability to "all" implementations.

Use Ingress with ingress-nginx​

Project Status: https://github.com/kubernetes/ingress-nginx/issues/13002

  • Good, because proven to work in civitas v1
  • Good, because many data centers already support this
  • Neutral, because project is still maintained, just no new features are added (feature complete)
  • Bad, because not all data centers have the same ingress class (nginx.org vs ingress-nginx)

Use Ingress with other ingress controller​

e.g. InGate (successor of ingress-nginx), traefik, HAProxy, Envoy, ...

  • Good, because ingress is known to most developers and operators
  • Bad, because vendor lock-in
  • Bad, because it depends on the data centers to provide this exact ingress class

Use a mixture of Gateway API and Ingress​

e.g. InGate (successor of ingress-nginx)

  • Good, because we can choose per tool which fits best
  • Good, because we can slowly transition towards Gateway API
  • Neutral, because one project (e.g. InGate) can be used for both
  • Neutral, because InGate's stable version is planned for mid 2026
  • Bad, because we need to decide what to use every time
  • Bad, because still use ingress with all its disadvantages

See also​

  • Final decision depends if data centers will support this. This is tracked in this issue
  • Ticket #11