Control Plane Configuration

The Control Plane is configured through the gateway-stack values of the platform chart, under gateway-stack.controlPlane. 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 LLM Gateway uses.
• Registration token secret and issuer, plus agent registration turned on in the LLM Gateway with a credential signer. Once registration is on, the chart gives the gateway the same secret and issuer, so it accepts the tokens the Control Plane mints. Without it, the gateway answers a valid token with 404 registration_unavailable. Outside the chart, set LLM_GATEWAY_AGENT_REGISTRATION_ENABLED, LLM_GATEWAY_REGISTRATION_TOKEN_SECRET, LLM_GATEWAY_REGISTRATION_TOKEN_ISSUER, and LLM_GATEWAY_CREDENTIAL_SIGNER_SEED on the gateway.
• Authentication with Auth Service bearer mode, so Guardian users and API keys are accepted.
• Guardian adapter connections to Auth Service and Integrity Service, for the project-scoped routes Guardian uses.
• Plugin artifact storage, plugin signer keys, and the plugin secrets key, before publishing plugins.

Chart Values

The platform chart already turns on the Guardian adapter and bearer authentication in Auth Service mode, and points the adapter at the release’s Auth Service and Integrity Service. Set authentication on yourself: with bearer authentication on and authentication off, the Control Plane refuses to start.

gateway-stack:
  enabled: true
  llmGateway:
    registration:
      enabled: true
      credentialSigner:
        existingSecret: "guardian-gateway-credential-signer" # holds seed
  controlPlane:
    apiBasePath: "/api"
    auth:
      enabled: true
      existingSecret: "guardian-control-plane-auth" # holds registrationTokenSecret
  ingress:
    enabled: true
    controlPlanePath: "/api"
    hosts:
      controlPlane: "control-plane.example.com"

Environment Variables

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

Lists such as email domains, scopes, and issuer DIDs are comma-separated; their command-line flags are singular and repeatable, and VT_API_KEY has no flag. PLUGIN_TRUSTED_SIGNER_KEYS is a comma-separated list of key_id=public_key pairs, where the public key may be a did:key.

ADAPTER_TRUSTED_COMPLIANCE_ISSUER_DIDS lists the issuers whose project compliance credentials and agent certifications the Control Plane trusts. Setting it replaces the fallback to ADAPTER_TRUSTED_MEMBERSHIP_ISSUER_DIDS, so keep every issuer you trust in it. For agent certification it must include the platform signing DID; see Agent Certification.

PLUGIN_ARTIFACT_STORAGE_PROVIDER accepts gcs, s3, azure, or file. Leave it unset and plugin artifacts cannot be uploaded. With file, the bucket is a folder path that both the Control Plane and the gateway can reach. Azure needs exactly one of a connection string, an account key, or managed identity, and an endpoint override cannot be combined with a connection string.

The LLM Gateway must use the same artifact storage and Auth Service URL as the Control Plane, and the same registration token secret and issuer, plugin trusted signer keys, and plugin secrets key; see LLM Gateway Configuration. Outside the chart, set these four on both services:

When the publisher signer is configured, the Control Plane signs the plugin artifacts and configurations an admin uploads unsigned, and adds its own key to the trusted signer keys. The gateway must trust the same public key. Without a publisher signer, uploads must carry their own signature, which guardian-plugin publish does not add. The plugin secrets key is 32 bytes in base64, base64url, or hex.

VirusTotal scanning runs only when VT_ENABLED is true and VT_API_KEY is set.

API Base Path

With a base path such as /api, the spec at /api/openapi.json and the API explorer at /api/docs/ are served only under the prefix. Every other route, including /health, answers both with and without it. A base path must start with /.

Startup Validation

The Control Plane refuses to start when its configuration is inconsistent, and logs invalid config: followed by the setting at fault, in flag form:

• Bearer authentication requires authentication, and authentication requires bearer authentication and a registration token secret.
• Auth Service mode requires an Auth Service URL, from either AUTH_BEARER_AUTH_SERVICE_BASE_URL or ADAPTER_AUTH_SERVICE_BASE_URL. OIDC mode requires an issuer URL, a client ID, and at least one scope.
• The Guardian adapter requires the Auth Service URL.
• Timeouts and the maximum upload size must be above zero.
• Artifact storage needs a bucket once a provider is set, a region and credentials for s3, and an account name for Azure unless a connection string is set.
• The publisher signer needs both its key ID and its seed file.

An unknown storage provider, an unreadable signer seed, or an unreachable database also stops startup, with its own log line.

Keep secrets such as the registration token secret, 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 Authentication and RBAC — what each bearer mode accepts
• Policy as Code — publishing plugins once artifact storage and signing are configured
• Control Plane Operations — checks to run once the service is configured
• Air-Gapped Install — mirroring the gateway stack images