Configuration

KubeStellar Console can be configured via environment variables or Helm values.

Environment Variables

kc-agent Configuration

The local agent (kc-agent) runs on your machine and bridges the browser-based console to your kubeconfig. It supports CLI flags and environment variables.

CLI Flags

Agent Environment Variables

Default Allowed Origins

The agent allows connections from these origins by default:

• http://localhost, https://localhost
• http://127.0.0.1, https://127.0.0.1
• https://console.kubestellar.io
• https://*.ibm.com

Adding Custom Origins

Use the --allowed-origins CLI flag or KC_ALLOWED_ORIGINS environment variable to allow additional origins. Both are additive — they merge on top of the defaults.

# Via CLI flag
kc-agent --allowed-origins "https://my-console.example.com"
 
# Via environment variable
KC_ALLOWED_ORIGINS="https://my-console.example.com" kc-agent
 
# Both together (all origins are merged)
KC_ALLOWED_ORIGINS="https://env-origin.example.com" kc-agent --allowed-origins "https://flag-origin.example.com"

Wildcard subdomains are supported (e.g., https://*.example.com).

Helm Values

Basic Configuration

# values.yaml
replicaCount: 1
 
image:
  repository: ghcr.io/kubestellar/console
  tag: latest
 
service:
  type: ClusterIP
  port: 8080
 
# GitHub OAuth
github:
  existingSecret: ksc-secrets
  existingSecretKeys:
    clientId: github-client-id
    clientSecret: github-client-secret

AI Configuration

# AI Mode settings
ai:
  defaultMode: "medium"  # low | medium | high
  tokenLimits:
    enabled: true
    monthlyLimit: 100000
    warningThreshold: 80   # Show warning at 80%
    criticalThreshold: 95  # Restrict features at 95%
 
# Claude API (optional)
claude:
  apiKey: ""
  model: "claude-sonnet-4-20250514"
  existingSecret: ""

Persistence

persistence:
  enabled: true
  size: 1Gi
  storageClass: ""

OpenShift Route

route:
  enabled: true
  host: ksc.apps.your-cluster.com
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect

Ingress (non-OpenShift)

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  hosts:
    - host: ksc.your-domain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: ksc-tls
      hosts:
        - ksc.your-domain.com

AI Mode Configuration

Low Mode

• Minimal token usage (~10%)
• Direct kubectl/API calls for all data
• AI responds to explicit requests
• Best for cost control

Medium Mode (Default)

• Balanced token usage (~50%)
• AI analyzes and summarizes data on request
• Natural language card configuration
• Contextual help enabled

High Mode

• Full AI assistance (~100%)
• Proactive card swap suggestions
• Automatic issue analysis
• Real-time recommendations based on cluster activity

Dashboard Filtering

Use ENABLED_DASHBOARDS to control which dashboards appear in the sidebar for a given deployment. This is useful for per-team or per-environment customization.

# Show only GPU, AI/ML, and Benchmarks dashboards
ENABLED_DASHBOARDS=gpu-reservations,ai-ml,llm-d-benchmarks
 
# Show only operations-focused dashboards
ENABLED_DASHBOARDS=clusters,workloads,events,security,alerts

When set, the listed dashboard routes will appear in the sidebar navigation. All other dashboards are hidden but still accessible via direct URL.

Analytics Configuration

The console includes optional Google Analytics 4 telemetry for product usage insights.

Enabling Analytics

Set the GA4 measurement ID:

VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX

User Opt-Out

Users can opt out of analytics in Settings > Analytics. The toggle is off by default on self-hosted installations.

What Is Collected

• Page views and navigation patterns (prefixed with ksc_)
• Card interactions (add, remove, expand, configure)
• No personally identifiable information (PII) is ever collected

GitHub Enterprise OAuth

The console supports GitHub Enterprise Server (GHE) as an OAuth provider in addition to github.com.

Setup

1. On your GHE instance, create an OAuth App under Settings > Developer settings > OAuth Apps
2. Set the callback URL to https://your-console-url/api/auth/callback
3. Configure the console with:

GITHUB_URL=https://github.mycompany.com
GITHUB_CLIENT_ID=your-ghe-client-id
GITHUB_CLIENT_SECRET=your-ghe-client-secret

The console automatically adjusts OAuth and API endpoints based on GITHUB_URL. The public_repo scope is not requested — basic user profile data is needed.

kc-agent Background Daemon

When using start.sh, the kc-agent automatically runs as a background daemon process. This means:

• The agent starts automatically with the console
• It runs in the background without occupying a terminal
• Logs are written to the console’s log output
• The agent is stopped when the console shuts down

To run kc-agent independently:

# Run as foreground process
./kc-agent --port 8585
 
# Or with custom origins
./kc-agent --allowed-origins "https://my-console.example.com"

Performance Optimizations

The console includes several performance optimizations for faster load times:

• Vendor chunk splitting — JavaScript bundles are split into vendor chunks for better caching. Framework code (React, Recharts) is separated from application code.
• Gzip compression — All responses are gzip-compressed, reducing transfer sizes by ~70%.
• Two-phase OPA loading — The OPA Policies card renders instantly with cached data, then updates in the background. Cluster checks run in parallel rather than sequentially.
• Progressive card loading — Mission Browser cards appear-by-one as they load rather than waiting for all data.

Security Considerations

1. GitHub OAuth: Create a dedicated OAuth app for production
2. Secrets: Use Kubernetes secrets, not plain values
3. Network: Use TLS termination at ingress/route level
4. RBAC: The service account needs read access to target clusters