Skip to content

docs: document Git backend unavailability behaviour and stale-cache fallback #3246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
won-seoop wants to merge 1 commit into
base: main
Choose a base branch
from
+40 −0
Open

docs: document Git backend unavailability behaviour and stale-cache fallback #3246

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions docs/modules/ROOT/pages/server/environment-repository/git-backend.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,46 @@ value of this property is specified in seconds. By default the value is 0, mean
the config server will fetch updated configuration from the Git repo every time it
is requested. If the value is a negative number the refresh will not occur.

[[git-backend-unavailability]]
== Behavior When the Git Backend Is Unavailable

Spring Cloud Config Server clones the remote Git repository to a local working directory (the _basedir_ cache) when configuration is first requested (or at startup when `cloneOnStart: true`).
This local clone is used as a read-only cache so that the Config Server can continue serving configuration even if the remote Git backend becomes temporarily unreachable.

The following table summarises the behaviour under various failure scenarios:

[cols="3,4", options="header"]
|===
| Scenario | Behaviour

| Config Server starts without a prior local clone, and Git is unreachable
| The initial clone fails.
The Config Server logs an error and returns an HTTP `500` to the requesting client.
No stale data is available.

| Git becomes unreachable after at least one successful clone or fetch
| The `fetch` step fails silently (a `WARN`-level log entry is emitted).
The Config Server falls back to the last successfully fetched local working copy and serves the stale (but valid) configuration.
Clients receive an HTTP `200` with potentially outdated values.

| `force-pull: true` and Git is unreachable
| `force-pull` instructs the server to reset the local working copy before merging from the remote.
When the subsequent fetch fails, the reset has already been applied.
No stale data is available and the Config Server returns an HTTP `500`.

| `cloneOnStart: true` and Git is unreachable at startup
| The Config Server fails to start.
This surfaces misconfiguration early rather than at the first client request.

|===

[NOTE]
====
Because the fallback to stale configuration is silent (only a log warning), clients may receive outdated values without any indication that the backend is unavailable.
Monitor the Config Server's `WARN` log output and, in production, enable the
xref:server/health-indicator.adoc[Health Indicator] (or configure a dedicated alerting rule on it) so that backend connectivity problems are surfaced promptly.
====

[[default-label]]
== Default Label

Expand Down