LLM Gateway Configuration

The LLM Gateway is configured through the gateway-stack values of the platform chart, under gateway-stack.llmGateway. This page describes the chart values operators set, the environment variables the service reads outside the chart, and the checks it runs at startup.

Required Configuration Areas

• Gateway database connection, the same PostgreSQL database the Control Plane uses. The platform chart supplies it from the gateway-dsn key of the platform database Secret.
• Agent registration turned on, with a credential signer seed. The chart gives the gateway the Control Plane’s registration token secret and issuer, so set those once, in Control Plane Configuration.
• The Auth Service URL, for agents that register with an API key.
• The plugin runtime, with the same trusted signer keys, artifact storage, and plugin secrets key as the Control Plane, before you configure policies.
• Project context, so project configurations and memberships apply.

Chart Values

The platform chart already points the gateway at the platform database and sets deploymentEnvironment to production. Set the rest yourself. <release> is your platform release name, such as guardian-platform.

gateway-stack:
  enabled: true
  llmGateway:
    registration:
      enabled: true
      credentialSigner:
        existingSecret: "guardian-gateway-credential-signer" # holds seed
    authServiceBaseURL: "http://<release>-auth-service:8080"
    plugins:
      enabled: true
      artifactStorage:
        provider: "gcs"
        bucket: "guardian-plugins"
      trustedSignerKeys:
        signer-v1: "did:key:z6Mk..."
      secrets:
        resolutionOrder: ["store"]
        encryptionKey:
          existingSecret: "guardian-plugin-secrets-key" # holds encryption-key
    projectContext:
      mode: "enforce"
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      llmGateway: "gateway.example.com"

Project Context

Project context is off unless you turn it on with projectContext.mode. While it is off, the gateway ignores the project an agent presents: project configurations, project membership, and project trust do not apply, and every request runs under the global configuration only. Set it to enforce (or observe, which currently behaves the same) once plugins are on; the chart refuses to render with project context on and plugins off. The gateway’s mode denies nothing itself: with either value, a request that presents a project is denied when no project membership entry can admit it, and otherwise the Project Membership entry’s own mode decides whether a failed membership check denies it; see Gateway Policies.

Environment Variables

Outside the chart, the gateway reads these variables. Every name starts with LLM_GATEWAY_, left out below. The service also reads a TOML file named by -config or LLM_GATEWAY_CONFIG_FILE, and accepts a command-line flag for most settings. A flag overrides its environment variable, which overrides the file.

PLUGIN_TRUSTED_SIGNER_KEYS is a comma-separated list of key_id=public_key pairs, where the public key may be a did:key; its flag, -plugin-trusted-signer-key, takes one pair and repeats. TRUSTED_YUBIKEY_ROOT_CERTS is a comma-separated list of PEM file paths. PLUGIN_SECRETS_RESOLUTION_ORDER is a comma-separated list of store and env: store reads the secrets stored through the Control Plane, and env reads environment variables named with PLUGIN_SECRETS_ENV_PREFIX, for local development. The credential signer seed and the plugin secrets key are base64, base64url, or hex; the seed may also be a path to a file that holds it.

PLUGIN_REDACT_HEADERS is a comma-separated list of extra header names, matched case-insensitively, whose values the gateway masks before request.end plugins and their on-disk queue see them. Headers whose names contain auth, token, secret, password, session, cookie, api-key or apikey, or end in -key, are always masked; use this setting for other upstream credential headers.

PLUGIN_WASM_INTERPRETER has no flag: true interprets plugin WebAssembly instead of compiling it to native code.

DEPLOYMENT_ENVIRONMENT is also reported to OpenTelemetry as deployment.environment unless OTEL_RESOURCE_ATTRIBUTES sets it. The service reads a few variables that are not listed here: REGISTRY_BACKEND, which accepts only postgres; the EXT_REGISTRY_* external registry settings, which are not supported in production; and PROJECT_CONTEXT_REQUIRE_MEMBERSHIP and PROJECT_TRUSTED_ISSUER_DIDS, which are deprecated and have no effect.

The Control Plane must use the same registration token secret and issuer, trusted signer keys, and plugin secrets key as the gateway, listed in Control Plane Configuration, as well as the same artifact storage and Auth Service URL.

Startup Validation

The gateway refuses to start when its configuration is inconsistent, and logs LLM Gateway failed: invalid config: followed by the setting at fault, usually in flag form. The checks include:

• A database DSN is required.
• The upstream URLs and the signature label must be set, and the upstream URLs must be http or https URLs with a host.
• The request body and blob size limits must be above zero.
• Registration requires a registration token secret.
• An Auth Service identity issuer requires an Auth Service URL, the URL must be valid, and its timeout and cache TTL must be above zero.
• Audit capture requires an audit DSN and a queue directory, and its queue size, batch size, flush interval, and retention must be above zero.
• Plugins require at least one trusted signer key, a positive poll interval, their queue and cache directories, and a queue size above zero.
• Project context must be disabled, observe, or enforce, and any mode other than disabled requires plugins.
• Artifact storage needs a bucket once a provider is set, a region and credentials for s3, and exactly one of a connection string, an account key, or managed identity for Azure.

These also stop startup, with LLM Gateway failed: and the reason:

• a missing credential signer seed while registration is on, or an unreadable seed
• a store secret resolver without the plugin secrets key, or a resolver other than store or env
• a trusted signer key that is not a valid public key
• unreadable YubiKey root certificates
• an active plugin configuration that cannot be loaded, such as one whose artifact is unreachable or signed by an untrusted key
• an unreachable database

Keep secrets such as the credential signer seed, the plugin secrets key, and storage credentials in the deployment’s secret management system, not in values files.

Related

• Chart Values — where the gateway stack settings live in values.yaml
• Control Plane Configuration — the registration token secret and the plugin settings the gateway shares
• Register Agents — the registration paths these settings turn on
• LLM Gateway Operations — checks to run once the service is configured
• Observability — metrics and OpenTelemetry settings