spring-cloud / spring-cloud/spring-cloud-config

Design Discussion: Scalable Spring Cloud Gateway Route Refresh Strategy in Kubernetes

Open
#2,918 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement for team discussion
Dominant language
Java
Stars
2k
Forks
1.3k
Avg merge
2d 59m
Merged PRs (30d)
16

Description

Context:

We are running Spring Cloud Gateway (SCG) as a stateless service inside Kubernetes across multiple pods.
We have plan :- That the SCG pods load dynamic routing configurations via Spring Cloud Config Server, which pulls YAML route definitions from GitLab repositories.
Currently, route changes require triggering /actuator/refresh individually on each SCG pod to reload updated route definitions.
Design Problem Statement:

We are exploring options to automate and scale this refresh mechanism while considering:
Minimized operational complexity.
No additional messaging infrastructure unless necessary.
Refresh scope limited only to SCG pods — avoiding refresh on other microservices running within the same namespace/cluster.
Future-proofing for potential increase in route configurations (large YAML files).

Approaches Evaluated:
Option 1 — Spring Cloud Bus (Kafka-based):
Use /actuator/busrefresh to propagate refresh events across pods.
Requires introducing and managing Kafka (or RabbitMQ) cluster inside the Kubernetes environment.
Adds infra operational overhead and non-trivial maintenance burden.

Option 2 — Kubernetes-native refresh via Job/Script:
Run a Kubernetes Job post-deployment (or via GitLab CI/CD pipeline) that:
Selects SCG pods via label selectors.
Executes /actuator/refresh per pod via kubectl exec or pod IP/Service.

Risks:
Label-based targeting requires strict enforcement to avoid unintentionally refreshing non-Gateway pods.
Becomes harder to maintain if pod labeling consistency is not strictly enforced across all deployments.

Option 3 — ConfigMap-based route storage with Spring Cloud Kubernetes Config Watcher:
Migrate route definitions to Kubernetes ConfigMaps.
Use Spring Cloud Kubernetes native config reload capabilities.
Benefit: automatic refresh without explicit actuator calls.

Limitation: ConfigMap size limit (1MB total), which may become a bottleneck as routes grow across products/environments.

Open Questions for Review:
Is there a widely adopted pattern or reference architecture to scope config refreshes strictly to a subset of pods (i.e., SCG only) within Kubernetes?
Are there any additional Kubernetes-native event-driven solutions we can leverage (e.g., K8s informers, CRDs, operators)?
Would a hybrid approach (Config Server + GitLab + limited Bus implementation dedicated only for SCG namespace) make sense?
Has anyone implemented per-pod scoped refresh orchestration via Kubernetes controllers/operators successfully?

Constraints:
We are intentionally avoiding full platform-wide Spring Cloud Bus adoption to minimize broker management overhead.
Multi-tenant Kubernetes cluster hosting multiple microservices alongside SCG.
Fully GitLab-based GitOps workflow is already in place for deployment pipelines.

Looking for inputs / experiences / suggestions on:
Standard patterns
Long-term maintainability
Scalability at higher route volumes
Simplification vs added infra complexity trade-offs

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the /actuator/refresh and /actuator/busrefresh entry points, the Spring Cloud Kubernetes Config Watcher option, and the GitLab CI/CD workflow described in the issue. The issue has no named files, tests, implementation entry point, or acceptance criteria; done would require choosing and documenting a maintainable, scalable refresh strategy scoped to SCG pods.

Written by the indexing model from the issue text.

Assessment

Tech stack
gitlab, java, kubernetes, spring, spring-boot
Domain
backend, cloud, distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.