API¶
The API is a FastAPI application, versioned under /api/v1. Every data route
requires authentication; /healthz and GET /api/v1/setup are public by
design.
Authentication¶
- HTTP Basic:
GSLB_API_USER/GSLB_API_PASSWORD. - Static Bearer:
GSLB_API_TOKEN(also used by the DNS nodes). - Read-only token:
GSLB_API_RO_TOKENauthenticates every read and is refused on every write (403 read-only credential). When it is the only credential configured, reads work, the token holder's writes answer403 read-only credentialand an anonymous write answers403 writes are disabled. - OIDC session cookie (optional, since 0.11.3):
gslb_session, signed, set by/auth/callback. It carries a role —reader,operatororadmin— and a write made with it must also carryX-Requested-With: gslb-consoleand a matchingOrigin. WithoutGSLB_OIDC_ISSUERnothing changes. See OIDC. - Roles:
readerreads and computes;operatoralso tests a probe and checks the VIP;adminwrites. Basic and the tokens areadmin, the read-only token isreader. - Fail closed: with nothing configured, every data route answers
503. - A credential over plain HTTP is refused (
403, actionable message). The precedence is:GSLB_REQUIRE_TLS=1refuses and wins over everything;GSLB_REQUIRE_TLS=0allows (deprecated alias);GSLB_ALLOW_PLAINTEXT_AUTH=1allows (lab switch); otherwise refuse./healthzis never affected. GSLB_TRUST_PROXY=1is the only way the transport (X-Forwarded-Proto) and the source address (X-Real-IP, else the lastX-Forwarded-Forhop) are read from headers; without it only the connection itself counts. The hop into the console's nginx must be HTTPS for that header to sayhttps.
The lot 2 prefix /api remains an alias, hidden from the OpenAPI schema. It is
removed only when /api/v2 lands, never before. /auth/* has no alias: a
callback URL is registered once at the provider, and a second spelling of it is
a second way to be wrong.
Routes¶
Every route below is relative to /api/v1, except /healthz, which stays at the
root. Methods in parentheses are the second verb on the same path.
| Route | Method | Purpose |
|---|---|---|
/healthz |
GET | Liveness, unauthenticated |
/auth/methods |
GET | What the sign-in page may offer: oidc, basic, token, display_name, preset, logout_url (public) |
/auth/login |
GET | Start the OIDC flow; ?next=/... is a local path only |
/auth/callback |
GET | Finish it: state, code exchange, ID token, session cookie |
/auth/logout |
POST | Erase the session cookie (CSRF header required) |
/auth/me |
GET | authenticated, actor, role, auth, can_read/operate/write/admin; 401 when anonymous |
/settings/identity |
GET, PUT, DELETE | Identity provider: effective settings, where each value comes from, callback URL, secret flags, recent changes. PUT stores console overrides (admin), DELETE erases them (admin) |
/settings/identity/test |
POST | Reach the effective or drafted provider once: {ok, checks: [{name, ok, detail}]}. Stores nothing, opens no session |
/setup |
GET, PUT | First start: needed?, then write the first configuration |
/about |
GET | Version, database schema, environment, server time zone, start time, auth, role |
/config |
GET, PUT | Structured form, canonical YAML, hash, last reload, drift; PUT validates, writes, acknowledges and rolls back on refusal |
/config/raw |
GET | Exact YAML and hash, for DNS nodes |
/config/validate |
POST | Dry run, diff, no write |
/config/versions |
GET | Configuration history |
/config/versions.csv |
GET | History export |
/config/versions/{id} |
GET | One version |
/config/versions/{id}/diff |
GET | Diff against the current file or another version |
/config/versions/{id}/restore |
POST | Restore through the normal save path |
/stats |
GET | Snapshot, counters, pools, drift, not-routed split |
/stats/history |
GET | Answers/fallbacks/failures per bucket |
/stats/clients |
GET | Query counts per client /24 |
/health |
GET | Snapshot age and health transitions |
/health/availability |
GET | Availability strip per backend |
/health/availability.csv |
GET | Availability export for the selected window |
/events |
GET | Paginated routing journal: events and the filtered total |
/events/filters |
GET | The values the journal accepts: pool labels and reasons |
/events.csv |
GET | Journal export with the same filters, 10 000 rows at most |
/suggestions |
GET | Unregistered subnets, imbalance, flapping |
/instances |
GET | Fleet view: one row per node (addresses, port, version, workers, configuration state), the two disagreement lists, and the declared vip/vip_port |
/instances/vip-check |
POST | Query the VIP for heartbeat.<zone>; names the node that answered |
/instances/{id}/snapshot |
POST | DNS node pushes its snapshot |
/instances/{id}/events |
POST | DNS node pushes a batch of events |
/instances/{id}/reload |
POST | DNS node acknowledges a configuration |
/metrics |
GET | Prometheus exposition, text format 0.0.4 (also at the root, /metrics) |
/probes/validate |
POST | Validate a probe block without saving it |
/probes/test |
POST | Run one probe once (5 s at most), return the verdict and its reason |
/templates |
GET, POST | Probe template library |
/templates/export |
GET | Templates as JSON, never the links |
/templates/import |
POST | Import a JSON export |
/templates/relink |
POST | Follow a rename performed in the editor |
/templates/{id} |
GET, PUT, DELETE | One template; DELETE is refused (409) while a backend follows it |
/templates/{id}/preview |
POST | Impact of a draft: diff, backends rewritten, diverged, orphaned |
/templates/{id}/apply |
POST | Write the draft into the followers, then update the library |
/templates/{id}/links |
POST, DELETE | Attach or detach a backend |
Windows are 1h, 24h or 7d.
The identity settings live under /api/v1 only, like /auth/*: they configure
the callback those routes use, and a second spelling of that contract would be a
second way to be wrong. Reading them is a reader action; writing, erasing and
testing are admin actions — an operator is refused like a reader.
Refusals are the usual ones: 401 anonymous, 403 when the role is too low (a
read-only token gets 403 read-only credential), 400 with an actionable
sentence when the payload would leave nobody able to sign in, and 503 on
/auth/login when OIDC is enabled without GSLB_SESSION_SECRET. No secret is
ever in a response: GSLB_OIDC_CLIENT_SECRET and GSLB_SESSION_SECRET are
reported as secret_configured and session_secret_configured only, with the
name of the variable to set. The redirect URI is computed (GSLB_PUBLIC_ORIGIN
plus /api/v1/auth/callback, or GSLB_OIDC_REDIRECT_URI) and never editable.
/stats also returns not_routed and not_routed_reasons: the queries that
reached no backend (REFUSED, NXDOMAIN, an empty answer, SERVFAIL, a liveness
check). They stay in by_pool as none for the contract; the console draws the
pools alone and states this volume underneath, because one health check every
two seconds would otherwise dwarf a small site's traffic.
/instances is empty in the single-host file mode: there is no fleet to show.
In HA mode a node is a host (GSLB_INSTANCE) and each row carries the
processes it runs, so one machine with eight workers stays one row.
Examples¶
# Basic
curl -u admin:secret http://gslb:8080/api/v1/stats
# Bearer
curl -H "Authorization: Bearer $GSLB_API_TOKEN" \
http://gslb:8080/api/v1/instances
# Validate a form without writing it
curl -u admin:secret -X POST http://gslb:8080/api/v1/config/validate \
-H 'Content-Type: application/json' -d @form.json
# Which node holds the VIP, and what it runs
curl -u admin:secret -X POST http://gslb:8080/api/v1/instances/vip-check \
-H 'Content-Type: application/json' -d '{}'
# The scrape, with the read-only token: the same series at /metrics
curl -H "Authorization: Bearer $GSLB_API_RO_TOKEN" \
http://gslb:8080/api/v1/metrics
curl -u admin:secret http://gslb:8080/api/v1/config returns
{"form": ..., "yaml": ..., "sha256": ..., "reload": ..., "drift": ...}.
Configuration history¶
/config/versions returns one entry per save, restore, setup or template
application:
{"id": 42, "ts": 1763556000.0, "sha256": "…", "trigger": "api",
"actor": "admin", "source_ip": "203.0.113.9", "applied": true, "error": null}
source_ip is the administrator's address, recorded since 0.11 (schema 7);
it is NULL for older rows and whenever nothing trustworthy could be read. With
GSLB_TRUST_PROXY=1 it comes from X-Real-IP, else from the last hop of
X-Forwarded-For, validated as an address; otherwise it is the socket peer. The
CSV export carries the same column between actor and applied. See
Who changed the DNS.
Errors¶
| Code | Meaning |
|---|---|
400 |
Invalid configuration or probe (validation message in the detail) |
401 |
Missing or wrong credentials; an ID token that is not ours; the provider refused the code |
403 |
Read-only credential on a write, a role too low for the route, writes disabled, a bad CSRF header or origin, no mapped OIDC group, or a credential over plain HTTP (TLS required by default since 0.11) |
404 |
Unknown version, template, instance, or a link whose backend is gone |
409 |
Setup already done, or a template still followed |
500 |
The configuration file cannot be read |
503 |
No credential configured, the API is closed; OIDC half-configured or GSLB_SESSION_SECRET missing |
502 |
The identity provider is unreachable, or its documents are inconsistent |
A save that the DNS refuses returns 200 with applied: false, the error and
the per-instance acknowledgements; the file is rolled back.
OpenAPI¶
FastAPI serves the schema at /openapi.json and Swagger UI at /docs on the
API port. In the HA compose the API publishes no port: read it from the
management host (127.0.0.1:8000) or add a proxy location if you need it
remotely. The bodies are not described by response models yet: the console
carries the shapes by hand in web/src/api/types.ts.