Skip to main content
Version: 1.0

Configuration Guide

KubeOpera has no central configuration file and no kubeopera config command — every service, including the frontend, is configured entirely through environment variables, sourced from a Kubernetes ConfigMap for non-sensitive values and a Sealed Secret for anything sensitive (database credentials, signing keys, third-party API keys). This page explains the two configuration patterns you'll actually run into, and points to where each service's specific variables are documented rather than duplicating them here — the individual service pages under Backend Services are the source of truth for exactly which variables a given service reads.

The frontend: a build-time/runtime split worth understanding​

Most of the frontend's configuration is ordinary server-side environment variables, read at request time — changing one in the deployed ConfigMap and restarting the pod is enough. A handful of variables are prefixed NEXT_PUBLIC_, and those behave differently in a way that causes real confusion if you don't know it going in: Next.js inlines every NEXT_PUBLIC_* variable into the compiled JavaScript bundle at next build time, everywhere it's referenced — not just in client components. Changing a NEXT_PUBLIC_* value in a running container's environment has no effect at all until the image is rebuilt.

The clearest example is AUTH_APP_ID versus NEXT_PUBLIC_AUTH_APP_ID. The server-side AUTH_APP_ID is the one that actually matters at runtime — the auth proxy route reads it on every request and patches it into the login payload before forwarding it to auth-service, so a ConfigMap change takes effect immediately on the next pod restart, no rebuild needed. NEXT_PUBLIC_AUTH_APP_ID only sets a page's initial display value and is frozen at whatever it was when the image was last built. The two should always be kept in sync, but if you only remember one thing about this split, remember that AUTH_APP_ID (no prefix) is the source of truth.

The METRICS_SOURCE variable (kubernetes | prometheus | datadog | newrelic | mock) is a deployment-level decision, not something an end user configures in the UI — it selects which of five backing adapters the main dashboard reads metrics from, resolved once server-side in the root layout and passed down as a prop rather than fetched client-side. Regardless of which source is selected, the Observability panel's latency, network, and error-rate charts always go through Prometheus specifically, since the Kubernetes metrics API has no equivalent signal — that one exception is worth knowing if a chart looks like it's ignoring METRICS_SOURCE.

Backend services: environment variables per service​

Every Go backend service is configured the same simple way: environment variables read at startup, no config file, no live-reload. A database connection string, the shared JWT signing secret, and whichever other services it needs to call are the norm; a handful of services (nodes-manager is the one exception documented on its own page) also read a YAML file for defaults with environment variables layered on top for anything that needs to differ per environment.

Rather than repeat every variable here — they're genuinely specific to what each service does, and duplicating them risks the two copies drifting apart — each service's own page under Backend Services documents its exact environment variable contract, including which ones are required (the service refuses to start without them) versus optional with a sensible default.

Where secrets live​

Nothing sensitive is ever committed to the deployment repository in plaintext. Database passwords, JWT signing secrets, and API keys are stored as Sealed Secrets — encrypted against the target cluster's own key before being committed, decryptable only by that cluster's sealed-secrets controller. A handful of credentials are managed at runtime instead, through their own dedicated APIs rather than as static deployment secrets — see Auth Service for all three: a tenant's own AI provider key, a tenant's registry push/pull credentials, and (platform-admin-only, no tenant dimension) the cloud provider credentials Cluster Management uses to provision new infrastructure. All three are encrypted at rest and, once set, only ever exposed again as a last-4-characters display value — never re-served in plaintext.

Next Steps​

  • Setup Guide — how a KubeOpera environment is actually deployed
  • Backend Services — each service's specific environment variable reference
  • Security Guide — the platform's real authentication and authorization model