Configuration Guide
Every KubeOpera component — the dashboard and each backend service — is configured the same way: environment variables, supplied from a Kubernetes ConfigMap for ordinary settings and a Sealed Secret for sensitive ones. There's no central config file to keep in sync.
This guide shows you how to change configuration safely, explains the dashboard's settings, and tells you where to find each service's options.
Changing a setting
Because every environment is managed with GitOps, configuration changes are commits:
- Find the service's overlay for your environment:
fluxcd/apps/<service>/overlays/<env>/. - Edit its ConfigMap patch (or re-seal its Secret — see Setup: secrets).
- Commit and push. Flux applies the change, and the service restarts with the new configuration.
# fluxcd/apps/analysis-agent-srv/overlays/production/config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: analysis-agent-srv-config
data:
ANOMALY_Z_THRESHOLD_HIGH: "2.8"
INSIGHT_PUBLISH_MIN_RISK_SCORE: "10"
Keep differences between environments in their overlays. If production needs a larger connection pool than development, that difference should be visible in Git — not set by hand on a running cluster.
Configuring the dashboard
The dashboard (kubeopera-frontend) reads two kinds of variable:
- Server-side variables are read when a request is handled. Change them and restart the pod.
NEXT_PUBLIC_*variables are compiled into the browser bundle when the image is built. Changing them requires a rebuild.
AUTH_APP_ID (server-side, authoritative) and NEXT_PUBLIC_AUTH_APP_ID (initial value shown in the browser) must match — set both, and rebuild after changing the public one.
Service URLs
| Variable | Default | Service |
|---|---|---|
NEXT_PUBLIC_AUTH_API_URL | http://localhost:8082 | auth-service |
KUBEOPERA_API_BASE_URL | http://kubeopera-api:8090 | kubeopera-api |
K8S_MONITOR_BASE_URL | http://k8s-monitor:8085 | k8s-monitor |
SECURITY_API_BASE_URL | http://security-api:8086 | security-api |
CICD_GATEWAY_BASE_URL | http://cicd-gateway:8087 | cicd-gateway |
ANOMALY_DETECTOR_BASE_URL | http://anomaly-detector:8088 | anomaly-detector |
PREDICTIVE_SCALER_BASE_URL | http://predictive-scaler:8089 | predictive-scaler |
INCIDENT_MANAGER_BASE_URL | http://incident-manager:8090 | incident-manager |
OBSERVABILITY_AGENT_SRV_BASE_URL | http://observability-agent-srv:8092 | observability-agent |
ANALYSIS_AGENT_SRV_BASE_URL | http://analysis-agent-srv:8093 | analysis-agent |
ACTION_AGENT_SRV_BASE_URL | http://action-agent-srv:8094 | action-agent |
FEEDBACK_AGENT_SRV_BASE_URL | http://feedback-agent-srv:8095 | feedback-agent |
RECOMMENDATION_AGENT_SRV_BASE_URL | http://recommendation-agent-srv:8096 | recommendation-agent |
AGENT_RUNTIME_BASE_URL | http://agent-runtime:8111 | agent-runtime |
K8S_OPTIMIZER_BASE_URL | http://k8s-optimizer:8097 | k8s-optimizer |
APP_INTERNAL_URL | http://localhost:3000 | The dashboard itself, for server-side calls between its own routes. |
Each service's hostname must also be on the dashboard's upstream allowlist. The defaults above are allowed out of the box; if you run a service under a different hostname, add it with ALLOWED_UPSTREAM_HOSTS (comma-separated).
Metrics and observability
| Variable | Default | Description |
|---|---|---|
METRICS_SOURCE | kubernetes | Where the Dashboard's cluster metrics come from: kubernetes, prometheus, datadog, newrelic or mock. |
PROMETHEUS_URL | http://kube-prometheus-stack-prometheus.monitoring:9090 | Prometheus, used when METRICS_SOURCE=prometheus and always for latency, network and error-rate charts. |
METRICS_SOURCE is an environment-wide choice made by operators, not a per-user setting.
AI
| Variable | Description |
|---|---|
AI_CREDENTIAL_INTERNAL_API_KEY | Lets the dashboard's AI Chat resolve the caller's AI credential from auth-service. |
The AI Chat uses the same credential resolution as the agents: a tenant's own provider key if configured, otherwise the platform key. Configure the platform key under Settings → AI Provider Key.
Configuring backend services
Each Go service reads its environment at startup. Most need:
| Variable | Purpose |
|---|---|
DATABASE_URL | Its PostgreSQL schema. |
RABBITMQ_URL | The message bus, for services that publish or consume events. |
AUTH_JWT_ACCESS_SECRET | Validates user access tokens. |
<SERVICE>_BASE_URL | The address of each service it calls. |
PORT | Its HTTP port. |
Services fail fast with a clear error if a required variable is missing, so misconfiguration shows up at deploy time rather than later. Each service's page under Core Services lists every variable it reads, its default and whether it's required.
Where secrets live
| Secret | Where it's stored | Who manages it |
|---|---|---|
| Database passwords, signing keys, service API keys | Sealed Secrets in Git | Operators, through GitOps. |
| Platform AI provider key | auth-service (encrypted) | Platform administrators, in Settings → AI Provider Key. |
| A tenant's own AI provider key | auth-service (encrypted) | Tenant administrators, in their settings. |
| Registry credentials | auth-service (encrypted) | Tenants, when deploying private images. |
| Cloud credentials for provisioning | auth-service (encrypted) | Platform administrators, in Cluster Management. |
| Personal access tokens | auth-service (hashed) | Each user, in Settings → Access Tokens. |
Credentials managed through the dashboard are encrypted at rest and never shown again after they're saved — only a label and the last four characters are displayed.
Next steps
- Advanced configuration — resources, disruption budgets and overlays.
- Security — authentication, authorization and hardening.
- Core Services — every service's configuration reference.