Documentation for v2.11.0. Read the latest, v2.12.0.

Operator

Configuration

Everything the service takes from its environment is in one table below, one row per variable. What an administrator changes at runtime (cleanup ages, the cache size, the authentication mode, the webhook allow-list) lives in the database instead and is listed at the end.

Environment variables#

A variable that is unset takes its default. A variable set to something the service cannot use stops the start (below); the service never falls back silently.

There is no variable for the metrics path or the session length: metrics are always at /metrics, a session always lasts 7 days.

Invalid values#

A numeric variable that is not a number, or a fixed-vocabulary variable (LOG_FORMAT, OTEL_ENABLED, MCP_ENABLED, WEBHOOKS_ENABLED) with an unrecognised value, makes the service exit before it binds, with the variable named on stderr:

CONFIGURATION ERROR: LOG_BUFFER_SIZE="1OO" is not a valid number. Correct it or unset it to use the default (100).
CONFIGURATION ERROR: LOG_FORMAT="yaml" is not recognised. Valid values: json, text. Unset it to use the default (text).

The same for values that would make the service useless: MAX_SPEC_BODY_BYTES=0, MCP_CALLS_PER_MINUTE=0, MCP_MAX_RESULT_BYTES=0, WEBHOOK_WORKER_INTERVAL_SECS=0, WEBHOOK_DELIVERY_TIMEOUT_SECS=0, CLEANUP_INTERVAL_SECS=0, a PUBLIC_BASE_URL without a scheme, and an unparsable BIND_ADDRESS or DATABASE_URL. Two variables are the exception and fall back quietly: LDAP_OPERATION_TIMEOUT_SECS and SANSHAIN_DIRECTORY_GROUP_TTL_SECS use their default when the value is not a whole number (and, for the LDAP timeout, when it is zero). Boolean-like variables read with a plain comparison (ALLOW_INSECURE_DEV_MODE) are true only for the exact string true.

Root users#

SANSHAIN_ROOT_USERS names the accounts that hold every permission, including ones a later release adds. Root is deliberately not stored: its authority comes from configuration, so no UI action, role change, migration or SQL update can revoke it. That makes it the recovery path when an administrator locks themselves out.

The list is read once at startup; changing it means a restart. Unset or empty, it falls back to INITIAL_ADMIN_USERNAME, then to root, so an existing deployment keeps a root account without being reconfigured. The resolved set is logged: Root users (configuration-held, cannot be revoked in-app): root.

Naming an account grants full authority whether or not it exists, is approved or holds a role, so keep the list short. Because the grant is a pure username match, an unclaimed root name would be a standing invitation: startup therefore creates a placeholder account for every configured name that has none, and registration refuses reserved names with 409 This username is reserved. The placeholder has no usable local password; the first LDAP or OIDC login under that name signs in as it, and it becomes that directory user's shadow account. The log says so: Claimed root username 'breakglass' with a placeholder account: ….

SANSHAIN_ROOT_USERS=root,breakglass

Directory group caching#

With LDAP, a user's group membership is read from the directory through the configured service account on every authorisation check and cached for SANSHAIN_DIRECTORY_GROUP_TTL_SECS. Sanshain stores which roles a directory group confers, never who is in it. The TTL is the dial between load on the directory and how long a revocation takes to bite; 0 disables caching, so every check reads the directory.

When the directory is unreachable, directory-derived roles are omitted, and the empty answer is cached for the TTL too, so an outage does not cost a directory timeout per request. Directory roles are purely additive, so leaving them out can only remove privilege. An outage degrades a directory-backed administrator to whatever Sanshain itself granted them; SANSHAIN_ROOT_USERS, held in configuration, still works. The alternative, a stale answer for the duration of the outage, would keep a revoked administrator in exactly that long.

The data cache#

Every data cache (resolved endpoints, endpoint lists per version, spec content, reports, Producer and Consumer lists, version metadata) holds an entry for at most 10 seconds. The value is fixed. A write invalidates the caches at once, and Sanshain runs as one instance, so the limit is never noticed; it is also why a second instance would serve stale data. See Scaling.

CACHE_MEMORY_MB is the initial memory bound. The admin page's In-Memory Cache section shows hit rate, entries and memory used, changes the bound at runtime (POST /admin/settings/cache, which rebuilds the caches) and clears them (POST /admin/cache/clear). The runtime value is not persisted; a restart returns to the variable.

Additional CA certificates#

Set EXTRA_CA_CERTS_DIR to a directory of PEM files when Sanshain must trust a private or corporate certificate authority, typically for LDAPS against an internal directory. Every *.pem, *.crt and *.cer file in the directory is read at startup and added to the platform trust store, never substituted for it. A file may hold one certificate or a chain; .crt is accepted because a Kubernetes Secret is conventionally keyed ca.crt. Files with any other name are ignored, so the entries a projected volume creates (..data and friends) do not interfere.

Startup fails rather than continuing with an incomplete store when:

• CA certificate directory '…' does not exist
• Could not read CA certificate directory '…': …
• Could not read CA certificate file '…': …: the file cannot be parsed, or holds no certificate at all, which means something other than a bundle was mounted.

On success the log says Trusting N additional CA certificate(s) from M file(s) in …; certificate contents are never logged. Certificates are read once, so rotating them means a restart. Unset, nothing changes: the platform bundle, which the image ships, is used.

This applies to LDAP connections. The database and the OTLP exporter have their own TLS configuration and do not consult this directory. Sanshain builds the LDAP trust store itself in every case, configured or not: left to its own, the LDAP library substitutes an empty root store when reading the platform certificates fails, which rejects every certificate and reports nothing.

Logging#

Two filters, two sinks. RUST_LOG governs stdout (LOG_FORMAT=json for machine-readable lines); CAPTURE_LOG_FILTER governs the in-memory buffer of LOG_BUFFER_SIZE lines per level that the observability page shows, so the buffer can hold debug lines while stdout stays at info. Two debug flags (business logic, admin/user activity) widen the buffer further at runtime without a restart. Secrets, tokens and passwords are never logged.

Settings in the database#

These are changed on the admin page or through /admin/settings/* and survive a restart. Each route needs a signed-in session; API tokens are not accepted on administrative routes.

Every *_max_age_days accepts at most 36500 days; a larger value answers 400 days must be at most 36500.

Checked against v2.6.1.