MODULE 13 · LESSON 13.3
Manage configuration as a versioned resource
Publish versioned settings, explain named code overrides, and preview desired/resolved/applied values before changing a host.
Lesson 78 of 88 · FabrCore 2.0
Overview
A Cloud Server serves a versioned effective document to each Host. Separate the document's publication, the Host's download and each setting consumer's application timing.
The Host consumes an envelope, not an editor form
GET /fabrcore-cloud/v1/configuration returns the effective model configuration plus optional settings and blueprints. A Cloud Server may merge base/environment documents, but layering policy is server-owned; the Host receives the final result. The version/ETag must change whenever that result changes. If unchanged, 304 lets the Host retain its current snapshot.
Published and applied are different states
Cloud settings sit above appsettings files but below environment variables and command-line overrides. Some consumers can apply changes live; startup-only settings require restart. The server cannot make a consumer reload simply by saving a value. Insights-style history/rollback can publish an earlier body under a new version; a custom implementation should define its own equally clear version policy.
Observe consumers rather than schema examples
GET /fabrcoreapi/admin/v1/settings/state reports desired, resolved and observed applied values for this process. The settings catalog describes configuration only. Reports include boot identity, sequence, observation time, revisions, source ownership and pending restarts. Secrets are redacted; unobserved consumers remain unverified.
Snapshot consumers retain consumed values after refresh. Monitored options record successful consumer access or change callbacks. An arbitrary post-configuration callback may be identified as code-or-consumer, but preview never replays it. Reports do not claim every downstream operation succeeded.
Declare rules and preview a complete draft
ConfigureRuntime registers a named pure rule before AddFabrCoreServer. Default fills an absent key, Override owns a key even when its value equals cloud intent, and Require checks final values including operator overrides. Competing rule owners are rejected. Rules run at registration, cloud refresh and explicit preview; ordinary file reloads and late providers do not rerun them.
POST /fabrcoreapi/admin/v1/settings/preview accepts the complete merged candidate cloud settings map, not a partial patch. It evaluates rules and infrastructure defaults without installing values or firing change notifications. Cloud runtime settings must be enabled. A changed draft invalidates its prior preview.
Adopt eligible applied values into a separate draft, preserving code ownership. Exclude secrets, unverified values, derived/runtime facts and instance identities. Publish using the server revision policy; rule rejection leaves the installed configuration intact, while consumer failure after installation does not imply rollback.
Publish an effective configuration version
- Construct the effective envelope for the target cluster/environment. The example below shows a supported settings map; retain the required model configuration for your enabled features.
- Publish through your Cloud Server's own authenticated storage/editor and change configurationVersion/ETag when the effective resource changes.
- Inspect the Host-reported version and apply/restart state. Roll back by publishing a compatible prior effective body as a new version, rather than pretending a version string resets the running process.
{
"schemaVersion": 1,
"configurationVersion": "ops-development-2",
"configuration": {
"modelConfigurations": [
{
"name": "default",
"provider": "OpenAI",
"model": "<your-model>",
"apiKeyAlias": "model-key"
}
],
"apiKeys": [
{
"alias": "model-key",
"value": "<resolved-secret>"
}
]
},
"settings": {
"FabrCore:Host:WebSocketPath": "/ws"
}
}
GET /fabrcore-cloud/v1/configuration
Authorization: Bearer <cluster-key>
X-FabrCore-Cluster-Id: operations-desk
X-FabrCore-Environment: Development
If-None-Match: "ops-development-2"
GET /fabrcoreapi/admin/v1/settings/state
Authorization: Bearer <administration-credential>
POST /fabrcoreapi/admin/v1/settings/preview
Authorization: Bearer <administration-credential>
Content-Type: application/json
{
"FabrCore:Host:WebSocketPath": "/ws"
}
var options = new FabrCore.Host.FabrCoreServerOptions()
.ConfigureRuntime("OperationsDesk.Endpoint", context =>
{
context.Default("FabrCore:Host:WebSocketPath", "/ws",
"Use the standard endpoint when no value was supplied.");
context.Require("FabrCore:Host:WebSocketPath",
value => value is not null && value.StartsWith("/"),
"The WebSocket path must begin with a slash.");
});
builder.AddFabrCoreServer(options);
Compare served, effective and applied values
- Publish a harmless supported setting/model change with a new effective version. Request the configuration endpoint using the Host's cluster/environment and inspect the returned envelope/ETag.
- Observe the Host's next reported version and apply status. If a local environment override wins or the consumer needs restart, explain that state rather than displaying “applied” from the publish response.
- Request again with the current If-None-Match. Expect 304 when unchanged. Change the effective document and verify the next request receives 200 with a new version.
- Preview the complete draft before publishing. Confirm current applied observations stay unchanged; unsupported keys or failed rules reject the candidate.
- Compare reports after publishing with an operator override in place. Explain why desired and resolved differ and whether a known consumer actually needs restart. Never infer application from the catalog alone.
This verifies configuration delivery and its application boundary. The open Host-facing protocol does not prescribe a universal POST /publish API for every Cloud Server editor.
If the result is different
Publishing never restarts an instance automatically. A persisted new value is not evidence that a singleton/startup consumer has reloaded it.
Go deeper
Explore the related documentation.